CLI 온보딩 레퍼런스

이 페이지는 openclaw onboard의 전체 레퍼런스입니다. 간략한 가이드는 온보딩 마법사 (CLI)를 참고하세요.

마법사가 하는 일

로컬 모드(기본)에서는 다음 항목을 안내합니다:

• 모델 및 인증 설정 (OpenAI Code 구독 OAuth, Anthropic API 키 또는 setup 토큰, MiniMax, GLM, Ollama, Moonshot, AI Gateway 옵션 포함)
• 워크스페이스 위치 및 부트스트랩 파일
• Gateway 설정 (포트, 바인드, 인증, Tailscale)
• 채널 및 프로바이더 (Telegram, WhatsApp, Discord, Google Chat, Mattermost 플러그인, Signal)
• 데몬 설치 (LaunchAgent 또는 systemd 사용자 유닛)
• 헬스 체크
• 스킬 설정

원격 모드는 이 머신에서 다른 곳의 Gateway에 연결하도록 설정합니다. 원격 호스트에는 아무것도 설치하거나 수정하지 않습니다.

로컬 흐름 상세

1단계: 기존 설정 감지

- `~/.openclaw/openclaw.json`이 존재하면 유지, 수정, 또는 초기화를 선택합니다.
- 마법사를 다시 실행해도 명시적으로 초기화를 선택하거나 `--reset`을 전달하지 않는 한 기존 내용을 지우지 않습니다.
- CLI `--reset`은 기본적으로 `config+creds+sessions`를 대상으로 합니다. `--reset-scope full`을 사용하면 워크스페이스도 제거됩니다.
- 설정이 유효하지 않거나 레거시 키를 포함하고 있으면 마법사가 먼저 `openclaw doctor`를 실행하도록 안내합니다.
- 초기화는 `trash`를 사용하며 범위를 선택할 수 있습니다:
  - 설정만
  - 설정 + 인증 정보 + 세션
  - 전체 초기화 (워크스페이스도 제거)

2단계: 모델 및 인증

- 전체 옵션 목록은 [인증 및 모델 옵션](#인증-및-모델-옵션)에 있습니다.

3단계: 워크스페이스

- 기본 `~/.openclaw/workspace` (변경 가능).
- 최초 실행 부트스트랩 절차에 필요한 워크스페이스 파일을 생성합니다.
- 워크스페이스 구조: [에이전트 워크스페이스](/docs/concepts/agent-workspace).

4단계: Gateway

- 포트, 바인드, 인증 모드, Tailscale 노출을 설정합니다.
- 권장: 루프백에서도 토큰 인증을 활성화하여 로컬 WS 클라이언트가 인증하도록 하세요.
- 토큰 모드의 대화형 온보딩에서 선택 가능:
  - **평문 토큰 생성/저장** (기본)
  - **SecretRef 사용** (옵트인)
- 비밀번호 모드의 대화형 온보딩에서도 평문 또는 SecretRef 저장을 지원합니다.
- 비대화형 토큰 SecretRef 경로: `--gateway-token-ref-env <ENV_VAR>`.
  - 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다.
  - `--gateway-token`과 함께 사용할 수 없습니다.
- 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하세요.
- 비루프백 바인딩에는 여전히 인증이 필요합니다.

5단계: 채널

- [WhatsApp](/docs/channels/whatsapp): 선택적 QR 로그인
- [Telegram](/docs/channels/telegram): 봇 토큰
- [Discord](/docs/channels/discord): 봇 토큰
- [Google Chat](/docs/channels/googlechat): 서비스 계정 JSON + 웹훅 오디언스
- [Mattermost](/docs/channels/mattermost) 플러그인: 봇 토큰 + 기본 URL
- [Signal](/docs/channels/signal): 선택적 `signal-cli` 설치 + 계정 설정
- [BlueBubbles](/docs/channels/bluebubbles): iMessage에 권장; 서버 URL + 비밀번호 + 웹훅
- [iMessage](/docs/channels/imessage): 레거시 `imsg` CLI 경로 + DB 접근
- DM 보안: 기본값은 페어링입니다. 첫 DM이 코드를 보내며
  `openclaw pairing approve <channel> <code>`로 승인하거나 허용 목록을 사용합니다.

6단계: 데몬 설치

- macOS: LaunchAgent
  - 로그인된 사용자 세션이 필요합니다. 헤드리스 환경에서는 커스텀 LaunchDaemon을 사용하세요(기본 제공 아님).
- Linux 및 Windows(WSL2): systemd 사용자 유닛
  - 마법사가 `loginctl enable-linger <user>`를 시도하여 로그아웃 후에도 Gateway가 유지되도록 합니다.
  - sudo를 요청할 수 있습니다(`/var/lib/systemd/linger`에 기록). sudo 없이 먼저 시도합니다.
- 런타임 선택: Node (권장; WhatsApp과 Telegram에 필수). Bun은 권장하지 않습니다.

7단계: 헬스 체크

- Gateway를 시작(필요 시)하고 `openclaw health`를 실행합니다.
- `openclaw status --deep`는 상태 출력에 Gateway 헬스 프로브를 추가합니다.

8단계: 스킬

- 사용 가능한 스킬을 읽고 요구사항을 확인합니다.
- 노드 매니저 선택: npm 또는 pnpm (bun은 권장하지 않음).
- 선택적 종속성 설치 (일부는 macOS에서 Homebrew 사용).

9단계: 완료

- 요약과 다음 단계. iOS, Android, macOS 앱 옵션을 포함합니다.

참고: GUI가 감지되지 않으면 마법사가 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 안내를 출력합니다. Control UI 에셋이 없으면 마법사가 빌드를 시도합니다. 실패 시 pnpm ui:build로 폴백합니다(UI 종속성 자동 설치).

원격 모드 상세

원격 모드는 이 머신에서 다른 곳의 Gateway에 연결하도록 설정합니다.

참고: 원격 모드는 원격 호스트에 아무것도 설치하거나 수정하지 않습니다.

설정 항목:

• 원격 Gateway URL (ws://...)
• 원격 Gateway 인증이 필요한 경우 토큰 (권장)

참고:

• Gateway가 루프백 전용이면 SSH 터널링이나 Tailnet을 사용하세요.
• 디스커버리 힌트:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

인증 및 모델 옵션

`ANTHROPIC_API_KEY`가 있으면 사용하고, 없으면 키를 입력받은 뒤 데몬용으로 저장합니다.

- macOS: Keychain 항목 "Claude Code-credentials"를 확인
- Linux 및 Windows: `~/.claude/.credentials.json`이 있으면 재사용

macOS에서는 "항상 허용"을 선택해야 launchd 시작 시 차단되지 않습니다.

아무 머신에서 `claude setup-token`을 실행한 뒤 토큰을 붙여넣으세요.
이름을 지정할 수 있으며, 비워두면 기본값을 사용합니다.

`~/.codex/auth.json`이 존재하면 마법사가 재사용할 수 있습니다.

브라우저 플로우; `code#state`를 붙여넣으세요.

모델이 미설정이거나 `openai/*`인 경우 `agents.defaults.model`을 `openai-codex/gpt-5.4`로 설정합니다.

`OPENAI_API_KEY`가 있으면 사용하고, 없으면 키를 입력받은 뒤 인증 프로필에 저장합니다.

모델이 미설정이거나 `openai/*` 또는 `openai-codex/*`인 경우 `agents.defaults.model`을 `openai/gpt-5.1-codex`로 설정합니다.

`XAI_API_KEY`를 입력받고 xAI를 모델 프로바이더로 설정합니다.

`OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`)를 입력받고 Zen 또는 Go 카탈로그를 선택합니다.
설정 URL: [opencode.ai/auth](https://opencode.ai/auth).

키를 저장합니다.

`AI_GATEWAY_API_KEY`를 입력받습니다.
상세: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

계정 ID, Gateway ID, `CLOUDFLARE_AI_GATEWAY_API_KEY`를 입력받습니다.
상세: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

설정이 자동으로 작성됩니다.
상세: [MiniMax](/docs/providers/minimax).

`SYNTHETIC_API_KEY`를 입력받습니다.
상세: [Synthetic](/docs/providers/synthetic).

기본 URL(기본값 `http://127.0.0.1:11434`)을 입력받은 뒤 클라우드 + 로컬 또는 로컬 모드를 선택합니다.
사용 가능한 모델을 탐색하고 기본값을 제안합니다.
상세: [Ollama](/docs/providers/ollama).

Moonshot (Kimi K2)과 Kimi Coding 설정이 자동으로 작성됩니다.
상세: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

OpenAI 호환 및 Anthropic 호환 엔드포인트에서 동작합니다.

대화형 온보딩에서는 다른 프로바이더 API 키 흐름과 동일한 저장 방식을 선택할 수 있습니다:
- **API 키 직접 입력** (평문)
- **시크릿 참조 사용** (환경 변수 참조 또는 설정된 프로바이더 참조, 사전 검증 포함)

비대화형 플래그:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (선택; `CUSTOM_API_KEY`로 폴백)
- `--custom-provider-id` (선택)
- `--custom-compatibility <openai|anthropic>` (선택; 기본값 `openai`)

인증을 미설정 상태로 둡니다.

모델 동작:

• 감지된 옵션에서 기본 모델을 선택하거나 프로바이더와 모델을 직접 입력합니다.
• 마법사가 모델 검사를 실행하고, 설정된 모델이 알 수 없거나 인증이 누락된 경우 경고합니다.

인증 정보 및 프로필 경로:

• OAuth 인증 정보: ~/.openclaw/credentials/oauth.json
• 인증 프로필 (API 키 + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

인증 정보 저장 모드:

• 기본 온보딩 동작은 API 키를 평문으로 인증 프로필에 저장합니다.
• --secret-input-mode ref는 평문 키 저장 대신 참조 모드를 활성화합니다. 대화형 온보딩에서 다음 중 하나를 선택할 수 있습니다:
  • 환경 변수 참조 (예: keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • 설정된 프로바이더 참조 (file 또는 exec) 프로바이더 별칭 + id 포함
• 대화형 참조 모드는 저장 전 빠른 사전 검증을 실행합니다.
  • 환경 변수 참조: 변수명 + 현재 온보딩 환경에서 비어 있지 않은 값을 검증합니다.
  • 프로바이더 참조: 프로바이더 설정을 검증하고 요청된 id를 해결합니다.
  • 사전 검증 실패 시 오류를 표시하고 재시도할 수 있습니다.
• 비대화형 모드에서 --secret-input-mode ref는 환경 변수 기반만 지원합니다.
  • 프로바이더 환경 변수를 온보딩 프로세스 환경에 설정하세요.
  • 인라인 키 플래그(예: --openai-api-key)는 해당 환경 변수가 설정되어 있어야 합니다. 그렇지 않으면 즉시 실패합니다.
  • 커스텀 프로바이더의 경우 비대화형 ref 모드에서 models.providers.<id>.apiKey를 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }로 저장합니다.
  • 해당 커스텀 프로바이더 케이스에서 --custom-api-key는 CUSTOM_API_KEY가 설정되어 있어야 합니다. 그렇지 않으면 즉시 실패합니다.
• Gateway 인증 정보는 대화형 온보딩에서 평문과 SecretRef를 선택할 수 있습니다:
  • 토큰 모드: 평문 토큰 생성/저장 (기본) 또는 SecretRef 사용.
  • 비밀번호 모드: 평문 또는 SecretRef.
• 비대화형 토큰 SecretRef 경로: --gateway-token-ref-env <ENV_VAR>.
• 기존 평문 설정은 변경 없이 계속 동작합니다.

참고: 헤드리스 및 서버 팁: 브라우저가 있는 머신에서 OAuth를 완료한 뒤 ~/.openclaw/credentials/oauth.json(또는 $OPENCLAW_STATE_DIR/credentials/oauth.json)을 Gateway 호스트로 복사하세요.

출력 및 내부 동작

~/.openclaw/openclaw.json에 기록되는 주요 필드:

• agents.defaults.workspace
• agents.defaults.model / models.providers (Minimax 선택 시)
• tools.profile (로컬 온보딩 시 미설정이면 "coding"으로 기본 설정; 기존 명시적 값은 유지)
• gateway.* (모드, 바인드, 인증, Tailscale)
• session.dmScope (로컬 온보딩 시 미설정이면 per-channel-peer로 기본 설정; 기존 명시적 값은 유지)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• 채널 허용 목록 (Slack, Discord, Matrix, Microsoft Teams) 프롬프트에서 옵트인 시 (이름은 가능한 경우 ID로 해결)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add는 agents.list[]와 선택적 bindings를 기록합니다.

WhatsApp 인증 정보는 ~/.openclaw/credentials/whatsapp/<accountId>/ 아래에 저장됩니다. 세션은 ~/.openclaw/agents/<agentId>/sessions/ 아래에 저장됩니다.

참고: 일부 채널은 플러그인으로 제공됩니다. 온보딩 중 선택하면 마법사가 채널 설정 전에 플러그인 설치(npm 또는 로컬 경로)를 안내합니다.

Gateway 마법사 RPC:

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

클라이언트(macOS 앱 및 Control UI)는 온보딩 로직을 재구현하지 않고도 각 단계를 렌더링할 수 있습니다.

Signal 설정 동작:

• 적절한 릴리스 에셋을 다운로드
• ~/.openclaw/tools/signal-cli/<version>/ 아래에 저장
• 설정에 channels.signal.cliPath를 기록
• JVM 빌드는 Java 21 필요
• 네이티브 빌드가 있으면 사용
• Windows는 WSL2를 사용하여 WSL 내에서 Linux signal-cli 흐름을 따름

관련 문서

• 온보딩 허브: 온보딩 마법사 (CLI)
• 자동화 및 스크립트: CLI 자동화
• 명령어 레퍼런스: openclaw onboard