Setup

참고: 처음 설정하는 경우 시작하기부터 시작하세요. 마법사 관련 상세 내용은 온보딩 마법사를 참고하세요.

최종 업데이트: 2026-01-01

요약

커스터마이징은 저장소 바깥에: ~/.openclaw/workspace (워크스페이스) + ~/.openclaw/openclaw.json (설정).
안정적인 워크플로우: macOS 앱을 설치하고 번들된 Gateway를 실행합니다.
최신 개발 워크플로우: pnpm gateway:watch로 직접 Gateway를 실행한 뒤 macOS 앱을 Local 모드로 연결합니다.

사전 요구사항 (소스 빌드)

Node >=22
pnpm
Docker (선택 사항; 컨테이너 환경/e2e 테스트에서만 필요 — Docker 참고)

커스터마이징 전략 (업데이트 시 충돌 방지)

“내게 맞게 완전히 커스터마이징”하면서도 쉽게 업데이트하려면 다음 위치에 설정을 보관하세요:

설정: ~/.openclaw/openclaw.json (JSON/JSON5 형식)
워크스페이스: ~/.openclaw/workspace (스킬, 프롬프트, 메모리; 비공개 git 저장소로 관리 권장)

최초 설정:

openclaw setup

이 저장소 내에서는 로컬 CLI 엔트리를 사용합니다:

openclaw setup

글로벌 설치가 아직 없다면 pnpm openclaw setup으로 실행하세요.

이 저장소에서 Gateway 실행하기

pnpm build 후 패키지된 CLI를 직접 실행할 수 있습니다:

node openclaw.mjs gateway --port 18789 --verbose

안정적인 워크플로우 (macOS 앱 우선)

OpenClaw.app 설치 및 실행 (메뉴 바).
온보딩/권한 체크리스트 완료 (TCC 프롬프트).
Gateway가 Local이고 실행 중인지 확인 (앱이 관리).
채널 연결 (예: WhatsApp):

openclaw channels login

정상 동작 확인:

openclaw health

빌드에 온보딩이 포함되어 있지 않은 경우:

openclaw setup 실행 후 openclaw channels login, 그다음 Gateway를 수동 시작(openclaw gateway).

최신 개발 워크플로우 (터미널에서 Gateway 실행)

목표: TypeScript Gateway를 개발하면서 핫 리로드를 사용하고, macOS 앱 UI를 연결 상태로 유지하기.

0) (선택) macOS 앱도 소스에서 실행

macOS 앱도 최신 버전으로 사용하고 싶다면:

./scripts/restart-mac.sh

1) 개발 Gateway 시작

pnpm install
pnpm gateway:watch

gateway:watch는 워치 모드로 Gateway를 실행하고 TypeScript 변경 시 자동으로 리로드합니다.

2) macOS 앱을 실행 중인 Gateway에 연결

OpenClaw.app에서:

연결 모드: Local 앱이 설정된 포트의 실행 중인 Gateway에 연결됩니다.

3) 확인

앱 내 Gateway 상태가 **“Using existing gateway …”**로 표시되어야 합니다.
또는 CLI로 확인:

openclaw health

흔한 실수

포트 불일치: Gateway WS 기본값은 ws://127.0.0.1:18789입니다. 앱과 CLI가 같은 포트를 사용하도록 하세요.
상태가 저장되는 위치:
- 인증 정보: ~/.openclaw/credentials/
- 세션: ~/.openclaw/agents/<agentId>/sessions/
- 로그: /tmp/openclaw/

인증 정보 저장 위치

인증 디버깅이나 백업 대상 결정 시 참고하세요:

WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram 봇 토큰: 설정/환경 변수 또는 channels.telegram.tokenFile (일반 파일만 허용; 심볼릭 링크 거부)
Discord 봇 토큰: 설정/환경 변수 또는 SecretRef (env/file/exec 프로바이더)
Slack 토큰: 설정/환경 변수 (channels.slack.*)
페어링 허용 목록:
- ~/.openclaw/credentials/<channel>-allowFrom.json (기본 계정)
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (기본이 아닌 계정)
모델 인증 프로필: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
파일 기반 시크릿 페이로드 (선택): ~/.openclaw/secrets.json
레거시 OAuth 가져오기: ~/.openclaw/credentials/oauth.json 상세 내용: 보안.

업데이트 (설정을 망가뜨리지 않으면서)

~/.openclaw/workspace와 ~/.openclaw/를 “내 것”으로 유지하세요. 개인 프롬프트/설정을 openclaw 저장소에 넣지 마세요.
소스 업데이트: git pull + pnpm install (lockfile이 변경된 경우) + pnpm gateway:watch 계속 사용.

Linux (systemd 사용자 서비스)

Linux 설치는 systemd 사용자 서비스를 사용합니다. 기본적으로 systemd는 로그아웃/유휴 시 사용자 서비스를 중지하여 Gateway가 종료됩니다. 온보딩이 자동으로 lingering을 활성화하려고 시도하지만(sudo를 요청할 수 있음), 여전히 꺼져 있다면 다음을 실행하세요:

sudo loginctl enable-linger $USER

상시 가동 또는 다중 사용자 서버에서는 사용자 서비스 대신 시스템 서비스를 고려하세요(lingering 불필요). systemd 관련 내용은 Gateway 운영 가이드를 참고하세요.