온보딩 마법사 레퍼런스¶

이 문서는 openclaw onboard CLI 마법사의 전체 레퍼런스입니다. 상위 수준 개요는 Onboarding Wizard를 참고하십시오.

흐름 상세 (로컬 모드)¶

- ~/.openclaw/openclaw.json 이 존재하면 유지 / 수정 / 초기화 중에서 선택합니다. - 마법사를 다시 실행해도 명시적으로 초기화를 선택하지 않는 한 (또는 --reset 을 전달하지 않는 한) 아무것도 삭제되지 않습니다. - 설정이 유효하지 않거나 레거시 키를 포함하는 경우, 마법사는 중단하고 계속하기 전에 openclaw doctor 를 실행하라고 요청합니다. - 초기화는 trash 를 사용하며(rm 는 절대 사용하지 않음) 다음 범위를 제공합니다: - 설정만 - 설정 + 자격 증명 + 세션 - 전체 초기화(워크스페이스도 제거)
- Anthropic API 키(권장): 존재하면 ANTHROPIC_API_KEY 를 사용하거나 키 입력을 요청한 뒤, 데몬 사용을 위해 저장합니다. - Anthropic OAuth (Claude Code CLI): macOS 에서는 Keychain 항목 'Claude Code-credentials' 를 확인합니다('Always Allow' 를 선택해야 launchd 시작이 차단되지 않음). Linux/Windows 에서는 존재할 경우 ~/.claude/.credentials.json 을 재사용합니다. - Anthropic 토큰(setup-token 붙여넣기): 어떤 머신에서든 claude setup-token 을 실행한 뒤 토큰을 붙여넣습니다(이름 지정 가능, 비워두면 기본값). - OpenAI Code (Codex) 구독 (Codex CLI): ~/.codex/auth.json 이 존재하면 마법사가 이를 재사용할 수 있습니다. - OpenAI Code (Codex) 구독 (OAuth): 브라우저 플로우로 진행하며 code#state 를 붙여넣습니다. - 모델이 설정되지 않았거나 openai/* 인 경우 agents.defaults.model 을 openai-codex/gpt-5.2 로 설정합니다. - OpenAI API 키: 존재하면 OPENAI_API_KEY 을 사용하거나 키 입력을 요청한 뒤, launchd 가 읽을 수 있도록 ~/.openclaw/.env 에 저장합니다. - xAI (Grok) API 키: XAI_API_KEY 입력을 요청하고 xAI 를 모델 프로바이더로 구성합니다. - OpenCode Zen (멀티 모델 프록시): OPENCODE_API_KEY (또는 OPENCODE_ZEN_API_KEY, https://opencode.ai/auth 에서 발급) 입력을 요청합니다. - API 키: 키를 대신 저장합니다. - Vercel AI Gateway (멀티 모델 프록시): AI_GATEWAY_API_KEY 입력을 요청합니다. - 자세한 내용: Vercel AI Gateway - Cloudflare AI Gateway: Account ID, Gateway ID, CLOUDFLARE_AI_GATEWAY_API_KEY 입력을 요청합니다. - 자세한 내용: Cloudflare AI Gateway - MiniMax M2.1: 설정이 자동으로 기록됩니다. - 자세한 내용: MiniMax - Synthetic (Anthropic 호환): SYNTHETIC_API_KEY 입력을 요청합니다. - 자세한 내용: Synthetic - Moonshot (Kimi K2): 설정이 자동으로 기록됩니다. - Kimi Coding: 설정이 자동으로 기록됩니다. - 자세한 내용: Moonshot AI (Kimi + Kimi Coding) - 건너뛰기: 아직 인증을 구성하지 않습니다. - 감지된 옵션에서 기본 모델을 선택합니다(또는 프로바이더/모델을 수동으로 입력). - 마법사는 모델 검사를 실행하고 구성된 모델을 알 수 없거나 인증이 누락된 경우 경고합니다. - OAuth 자격 증명은 ~/.openclaw/credentials/oauth.json 에, 인증 프로필은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 에 저장됩니다(API 키 + OAuth). - 자세한 내용: /concepts/oauth
헤드리스/서버 팁: 브라우저가 있는 머신에서 OAuth 를 완료한 뒤 ~/.openclaw/credentials/oauth.json (또는 $OPENCLAW_STATE_DIR/credentials/oauth.json) 를 게이트웨이 호스트로 복사하십시오. - 기본값은 ~/.openclaw/workspace (구성 가능). - 에이전트 부트스트랩 의식을 위해 필요한 워크스페이스 파일을 시드합니다. - 전체 워크스페이스 레이아웃 + 백업 가이드: Agent workspace
- 포트, 바인드, 인증 모드, Tailscale 노출. - 인증 권장 사항: 로컬 loopback 이더라도 Token 을 유지하여 로컬 WS 클라이언트가 반드시 인증하도록 하십시오. - 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하십시오. - non‑loopback 바인드는 여전히 인증이 필요합니다. - WhatsApp: 선택적 QR 로그인. - Telegram: 봇 토큰. - Discord: 봇 토큰. - Google Chat: 서비스 계정 JSON + 웹훅 오디언스. - Mattermost (플러그인): 봇 토큰 + 기본 URL. - Signal: 선택적 signal-cli 설치 + 계정 구성. - BlueBubbles: iMessage 권장; 서버 URL + 비밀번호 + 웹훅. - iMessage: 레거시 imsg CLI 경로 + DB 접근. - 다이렉트 메시지 보안: 기본값은 페어링입니다. 첫 다이렉트 메시지는 코드를 전송하며, openclaw pairing approve <channel><code> 를 통해 승인하거나 허용 목록을 사용하십시오. 를 통해 승인하거나 허용 목록을 사용하십시오. </Step> <Step title="데몬 설치"> - macOS: 런치 에이전트 - 로그인된 사용자 세션이 필요합니다. 헤드리스의 경우 사용자 정의 LaunchDaemon 을 사용하십시오(제공되지 않음). - Linux (및 WSL2 를 통한 Windows): systemd 사용자 유닛 - 로그아웃 후에도 Gateway 가 유지되도록loginctl enable-linger 를 통해 lingering 활성화를 시도합니다. - sudo 를 요청할 수 있습니다(/var/lib/systemd/linger기록). 먼저 sudo 없이 시도합니다. - **런타임 선택:** Node (권장; WhatsApp/Telegram 에 필수). Bun 은 **권장되지 않음**. </Step> <Step title="헬스 체크"> - 필요 시 Gateway 를 시작하고openclaw health을 실행합니다. - 팁:openclaw status --deep` 는 상태 출력에 게이트웨이 헬스 프로브를 추가합니다(접근 가능한 게이트웨이 필요). - 사용 가능한 Skills 를 읽고 요구 사항을 확인합니다. - 노드 매니저를 선택합니다: npm / pnpm (bun 은 권장되지 않음). - 선택적 의존성을 설치합니다(일부는 macOS 에서 Homebrew 사용). - 요약 + 다음 단계, 추가 기능을 위한 iOS/Android/macOS 앱 포함.

GUI 가 감지되지 않으면 마법사는 브라우저를 여는 대신 Control UI 를 위한 SSH 포트 포워딩 안내를 출력합니다. Control UI 에셋이 없는 경우 마법사는 빌드를 시도하며, 대체 수단은 pnpm ui:build 입니다(UI 의존성을 자동 설치).

비대화형 모드¶

--non-interactive 를 사용하여 온보딩을 자동화하거나 스크립트화할 수 있습니다:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

머신 판독 가능한 요약을 위해 --json 를 추가하십시오.

--json 는 비대화형 모드를 의미하지 않습니다. 스크립트에서는 --non-interactive (및 --workspace) 를 사용하십시오.

bash openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$ZAI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice ai-gateway-api-key \ --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice cloudflare-ai-gateway-api-key \ --cloudflare-ai-gateway-account-id "your-account-id" \ --cloudflare-ai-gateway-gateway-id "your-gateway-id" \ --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODE_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback

에이전트 추가(비대화형)¶

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway 마법사 RPC¶

Gateway 는 RPC 를 통해 마법사 흐름을 노출합니다(wizard.start, wizard.next, wizard.cancel, wizard.status). 클라이언트(macOS 앱, Control UI)는 온보딩 로직을 재구현하지 않고도 단계를 렌더링할 수 있습니다.

Signal 설정 (signal-cli)¶

마법사는 GitHub 릴리스에서 signal-cli 를 설치할 수 있습니다:

• 적절한 릴리스 에셋을 다운로드합니다.
• ~/.openclaw/tools/signal-cli/<version>/ 아래에 저장합니다.
• 설정에 channels.signal.cliPath 를 기록합니다.

참고 사항:

• JVM 빌드는 Java 21 이 필요합니다.
• 가능한 경우 네이티브 빌드를 사용합니다.
• Windows 는 WSL2 를 사용하며, signal-cli 설치는 WSL 내부에서 Linux 흐름을 따릅니다.

마법사가 기록하는 내용¶

~/.openclaw/openclaw.json 에 기록되는 일반적인 필드:

• agents.defaults.workspace
• agents.defaults.model / models.providers (MiniMax 선택 시)
• gateway.* (모드, 바인드, 인증, Tailscale)
• 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 또는 로컬 경로)를 요청받게 됩니다.

관련 문서¶

• 마법사 개요: Onboarding Wizard
• macOS 앱 온보딩: Onboarding
• 설정 레퍼런스: Gateway configuration
• 프로바이더: WhatsApp, Telegram, Discord, Google Chat, Signal, BlueBubbles (iMessage), iMessage (레거시)
• 스킬: 스킬, 스킬 구성