​

CLI Onboarding Reference

이 페이지는 openclaw onboard의 전체 레퍼런스입니다. 짧은 안내는 Onboarding Wizard (CLI)를 참고하세요.

​

What the wizard does

로컬 모드(기본값)는 다음 항목을 안내합니다.

• 모델 및 인증 설정(OpenAI Code subscription OAuth, Anthropic API key 또는 setup token, MiniMax, GLM, Moonshot, AI Gateway 옵션 포함)
• 워크스페이스 위치와 bootstrap 파일
• Gateway 설정(port, bind, auth, tailscale)
• 채널 및 provider(Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
• 데몬 설치(LaunchAgent 또는 systemd user unit)
• 상태 점검
• 스킬 설정

원격 모드는 이 머신이 다른 곳에 있는 gateway에 연결하도록 구성합니다. 원격 호스트에 설치하거나 수정하지는 않습니다.

​

Local flow details

​

Remote mode details

원격 모드는 이 머신이 다른 곳에 있는 gateway에 연결되도록 구성합니다. 설정하는 항목:

• remote gateway URL (ws://...)
• remote gateway auth가 필요한 경우 token(권장)

​

Auth and model options

Model 동작:

• 감지된 옵션 중 기본 model을 고르거나, provider와 model을 수동 입력할 수 있습니다.
• 마법사는 model check를 실행하고, 설정된 model을 모르거나 auth가 없으면 경고합니다.

Credential 및 profile 경로:

• OAuth credentials: ~/.openclaw/credentials/oauth.json
• Auth profiles (API keys + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Credential 저장 모드:

• 기본 온보딩 동작은 API key를 auth profile 안에 plaintext로 저장합니다.
• --secret-input-mode ref를 사용하면 plaintext 대신 reference mode를 켭니다. interactive onboarding에서는 다음 중 하나를 고를 수 있습니다.
  • environment variable ref 예: keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }
  • provider alias + id를 사용하는 configured provider ref (file 또는 exec)
• interactive reference mode는 저장 전에 빠른 preflight validation을 수행합니다.
  • Env ref: 현재 onboarding environment에서 변수 이름과 비어 있지 않은 값을 검증
  • Provider ref: provider config를 검증하고 요청한 id를 해석
  • preflight가 실패하면 onboarding이 오류를 보여 주고 재시도를 허용
• non-interactive mode에서 --secret-input-mode ref는 env-backed 방식만 지원합니다.
  • onboarding process environment에 provider env var를 설정해야 합니다.
  • inline key flag(예: --openai-api-key)를 쓰더라도 대응 env var가 없으면 onboarding은 즉시 실패합니다.
  • custom provider에서 non-interactive ref mode는 models.providers.<id>.apiKey를 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }로 저장합니다.
  • 이 custom-provider 경우 --custom-api-key를 쓰려면 CUSTOM_API_KEY가 설정되어 있어야 하며, 없으면 즉시 실패합니다.
• gateway auth credential도 interactive onboarding에서 plaintext와 SecretRef를 모두 지원합니다.
  • Token mode: Generate/store plaintext token (기본값) 또는 Use SecretRef
  • Password mode: plaintext 또는 SecretRef
• non-interactive token SecretRef 경로: --gateway-token-ref-env <ENV_VAR>
• 기존 plaintext 설정은 그대로 계속 동작합니다.

​

Outputs and internals

~/.openclaw/openclaw.json에 흔히 기록되는 필드:

• agents.defaults.workspace
• agents.defaults.model / models.providers (MiniMax를 선택한 경우)
• tools.profile (local onboarding은 값이 비어 있을 때 "coding"을 기본으로 넣고, 기존 explicit 값은 유지)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (local onboarding은 값이 없을 때 per-channel-peer를 기본으로 넣고, 기존 explicit 값은 유지)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• prompt 중 opt-in했을 때의 channel allowlist(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 credential은 ~/.openclaw/credentials/whatsapp/<accountId>/ 아래에 저장됩니다. session은 ~/.openclaw/agents/<agentId>/sessions/ 아래에 저장됩니다. Gateway wizard RPC:

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

macOS 앱과 Control UI 같은 client는 온보딩 로직을 다시 구현하지 않고도 이 step을 렌더링할 수 있습니다. Signal setup 동작:

• 적절한 release asset을 다운로드
• ~/.openclaw/tools/signal-cli/<version>/ 아래에 저장
• config에 channels.signal.cliPath 기록
• JVM build는 Java 21 필요
• 가능하면 native build를 사용
• Windows는 WSL2를 사용하며, WSL 내부에서 Linux signal-cli 흐름을 따름

​

Related docs

• Onboarding hub: Onboarding Wizard (CLI)
• Automation and scripts: CLI Automation
• Command reference: openclaw onboard