설정

마지막 업데이트: 2026-01-01

TL;DR

맞춤화는 리포지토리 외부에 있습니다: ~/.openclaw/workspace (워크스페이스) + ~/.openclaw/openclaw.json (구성).
안정적인 워크플로: macOS 앱을 설치하고, 번들된 Gateway를 실행하도록 합니다.
최첨단 워크플로: pnpm gateway:watch를 통해 Gateway를 직접 실행한 다음, macOS 앱이 Local 모드로 연결하도록 합니다.

전제 조건 (소스에서)

Node >=22
pnpm
Docker (선택 사항; 컨테이너화된 설정/e2e에만 필요 — Docker 참조)

맞춤화 전략 (업데이트가 문제를 일으키지 않도록)

"나에게 100% 맞춤화됨" 및 쉬운 업데이트를 원한다면, 다음에 맞춤화를 유지하세요:

구성: ~/.openclaw/openclaw.json (JSON/JSON5 형식)
워크스페이스: ~/.openclaw/workspace (스킬, 프롬프트, 메모리; 비공개 git 리포지토리로 만드세요)

한 번 부트스트랩:

openclaw setup

이 리포지토리 내에서 로컬 CLI 항목을 사용합니다:

openclaw setup

아직 전역 설치가 없는 경우 pnpm openclaw setup을 통해 실행합니다.

안정적인 워크플로 (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 봇 토큰: config/env 또는 channels.telegram.tokenFile
Discord 봇 토큰: config/env (토큰 파일은 아직 지원되지 않음)
Slack 토큰: config/env (channels.slack.*)
페어링 허용 목록: ~/.openclaw/credentials/<channel>-allowFrom.json
모델 인증 프로필: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
레거시 OAuth 가져오기: ~/.openclaw/credentials/oauth.json 자세한 내용: Security.

업데이트 (설정을 망가뜨리지 않고)

~/.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 runbook을 참조하세요.

설정