Onboarding reference

Onboarding reference 문서는 OpenClaw 공식 문서(reference/wizard)를 한국어로 정리한 가이드입니다. Full reference for CLI onboarding: every step, flag, and config field 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Full reference for CLI onboarding: every step, flag, and config field

한국어 가이드 범위: reference/wizard 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Flow details (local mode)
Non-interactive mode
Add agent (non-interactive)
Gateway wizard RPC
Signal setup (signal-cli)
What the wizard writes
Related docs

상세 내용

본문

This is the full reference for openclaw onboard. For a high-level overview, see Onboarding (CLI). For step-by-step behavior and outputs, see CLI setup reference.

Flow details (local mode)

keeps existing config and reuses it as defaults.

주요 항목:

--reset resets state before setup runs; without it, re-running onboarding
--reset-scope controls what --reset removes: config (config file
If the config file is invalid, onboarding stops and tells you to run
Reset moves state to Trash (never deletes directly).
First run (or any run before wizard.securityAcknowledgedAt is set)
--non-interactive requires --accept-risk explicitly; without it,
Interactive runs get a confirm prompt instead of the flag; declining
Anthropic API key: uses ANTHROPIC_API_KEY if present or prompts for a key, then saves it for daemon use.
Anthropic Claude CLI: preferred local path when a Claude CLI sign-in already exists; OpenClaw still supports Anthropic setup-token auth as an alternative.
OpenAI Code (Codex) subscription (OAuth): browser flow; paste the code#state.
On a fresh setup with no primary model, sets agents.defaults.model to openai/gpt-5.6-sol through the Codex runtime.
OpenAI Code (Codex) subscription (device pairing): browser pairing flow with a short-lived device code.
On a fresh setup with no primary model, sets agents.defaults.model to openai/gpt-5.6-sol through the Codex runtime.
OpenAI API key: uses OPENAI_API_KEY if present or prompts for a key, then stores it in auth profiles.
On a fresh setup with no primary model, sets agents.defaults.model to openai/gpt-5.6; the bare direct-API model id resolves to the Sol tier.
Adding or reauthenticating OpenAI preserves an existing explicit primary model, including openai/gpt-5.5. If the account does not expose GPT-5.6, select openai/gpt-5.5 explicitly; OpenClaw does not silently downgrade the model.
xAI OAuth: device-code browser sign-in with no localhost callback required, so it works over SSH/Docker/VPS too (--auth-choice xai-oauth).
xAI API key: prompts for XAI_API_KEY (--auth-choice xai-api-key).
--auth-choice xai-device-code still works as a manual-only compatibility alias for the same xAI OAuth device-code flow; use xai-oauth for new scripts.
OpenCode: prompts for OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY, get it at https://opencode.ai/auth) and lets you pick the Zen or Go catalog.
Ollama: offers Cloud + Local, Cloud only, or Local only first. Cloud only prompts for OLLAMA_API_KEY and uses https://ollama.com; the host-backed modes prompt for the Ollama base URL (default http://127.0.0.1:11434), discover available models, and auto-pull the selected local model when needed; Cloud + Local also checks whether that Ollama host is signed in for cloud access.
More detail: Ollama
API key: stores the key for you.
Vercel AI Gateway (multi-model proxy): prompts for AI_GATEWAY_API_KEY.
More detail: Vercel AI Gateway

Non-interactive mode

Use --non-interactive --accept-risk to automate or script onboarding (the flag is the required risk acknowledgement; onboarding exits with an error without it):

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

openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

Add agent (non-interactive)

main is a reserved agent id and cannot be used for openclaw agents add.

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

Gateway wizard RPC

The Gateway exposes the onboarding flow over RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Clients (macOS app, Control UI) can render steps without re-implementing onboarding logic.

Signal setup (signal-cli)

Onboarding detects whether signal-cli is on PATH and, if missing, offers to install it:

주요 항목:

Linux x86-64: downloads the official native GraalVM build from the signal-cli GitHub releases and stores it under ~/.openclaw/tools/signal-cli/<version>/.
macOS and other architectures: installs via Homebrew instead.
Native Windows: not supported yet; run onboarding inside WSL2 to get the Linux install path.
Writes channels.signal.transport.cliPath with kind: "managed-native" either way.

What the wizard writes

Typical fields in ~/.openclaw/openclaw.json:

주요 항목:

agents.defaults.workspace
agents.defaults.skipBootstrap when --skip-bootstrap is passed
agents.defaults.model / models.providers (if Minimax chosen)
tools.profile (local onboarding defaults to "coding" when unset; existing explicit values are preserved)
gateway.* (mode, bind, auth, tailscale)
session.dmScope (onboarding preserves explicit values and otherwise leaves it unset, so the "main" default keeps all direct messages across channels in the agent's rolling main session—the personal-agent default. For shared or multi-user inboxes, use "per-channel-peer"; openclaw security audit recommends isolation when it detects multi-user DM traffic. Details: CLI Setup Reference)
channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
Channel DM allowlists when you opt in during the channel prompts. Discord, Matrix, Microsoft Teams, and Slack resolve names to IDs when possible; other channels take IDs directly (for example numeric Telegram sender IDs or WhatsApp phone numbers).
skills.install.nodeManager
setup --node-manager accepts npm, pnpm, or bun.
Manual config can still use yarn by setting skills.install.nodeManager directly.
wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode
wizard.securityAcknowledgedAt

주요 항목:

Onboarding overview: Onboarding (CLI)
CLI setup reference: CLI setup reference
macOS app onboarding: Onboarding
Config reference: Gateway configuration
Providers: WhatsApp, Telegram, Discord, Google Chat, Signal, iMessage
Skills: Skills, Skills config

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/wizard
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

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

Onboarding reference

핵심 요약

Full reference for CLI onboarding: every step, flag, and config field

한국어 가이드 범위: reference/wizard 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Flow details (local mode)
Non-interactive mode
Add agent (non-interactive)
Gateway wizard RPC
Signal setup (signal-cli)
What the wizard writes
Related docs

상세 내용

본문

This is the full reference for openclaw onboard. For a high-level overview, see Onboarding (CLI). For step-by-step behavior and outputs, see CLI setup reference.

Flow details (local mode)

keeps existing config and reuses it as defaults.

주요 항목:

--reset resets state before setup runs; without it, re-running onboarding
--reset-scope controls what --reset removes: config (config file
If the config file is invalid, onboarding stops and tells you to run
Reset moves state to Trash (never deletes directly).
First run (or any run before wizard.securityAcknowledgedAt is set)
--non-interactive requires --accept-risk explicitly; without it,
Interactive runs get a confirm prompt instead of the flag; declining
Anthropic API key: uses ANTHROPIC_API_KEY if present or prompts for a key, then saves it for daemon use.
Anthropic Claude CLI: preferred local path when a Claude CLI sign-in already exists; OpenClaw still supports Anthropic setup-token auth as an alternative.
OpenAI Code (Codex) subscription (OAuth): browser flow; paste the code#state.
On a fresh setup with no primary model, sets agents.defaults.model to openai/gpt-5.6-sol through the Codex runtime.
OpenAI Code (Codex) subscription (device pairing): browser pairing flow with a short-lived device code.
On a fresh setup with no primary model, sets agents.defaults.model to openai/gpt-5.6-sol through the Codex runtime.
OpenAI API key: uses OPENAI_API_KEY if present or prompts for a key, then stores it in auth profiles.
On a fresh setup with no primary model, sets agents.defaults.model to openai/gpt-5.6; the bare direct-API model id resolves to the Sol tier.
Adding or reauthenticating OpenAI preserves an existing explicit primary model, including openai/gpt-5.5. If the account does not expose GPT-5.6, select openai/gpt-5.5 explicitly; OpenClaw does not silently downgrade the model.
xAI OAuth: device-code browser sign-in with no localhost callback required, so it works over SSH/Docker/VPS too (--auth-choice xai-oauth).
xAI API key: prompts for XAI_API_KEY (--auth-choice xai-api-key).
--auth-choice xai-device-code still works as a manual-only compatibility alias for the same xAI OAuth device-code flow; use xai-oauth for new scripts.
OpenCode: prompts for OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY, get it at https://opencode.ai/auth) and lets you pick the Zen or Go catalog.
Ollama: offers Cloud + Local, Cloud only, or Local only first. Cloud only prompts for OLLAMA_API_KEY and uses https://ollama.com; the host-backed modes prompt for the Ollama base URL (default http://127.0.0.1:11434), discover available models, and auto-pull the selected local model when needed; Cloud + Local also checks whether that Ollama host is signed in for cloud access.
More detail: Ollama
API key: stores the key for you.
Vercel AI Gateway (multi-model proxy): prompts for AI_GATEWAY_API_KEY.
More detail: Vercel AI Gateway

Non-interactive mode

Use --non-interactive --accept-risk to automate or script onboarding (the flag is the required risk acknowledgement; onboarding exits with an error without it):

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

openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

Add agent (non-interactive)

main is a reserved agent id and cannot be used for openclaw agents add.

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

Gateway wizard RPC

Signal setup (signal-cli)

Onboarding detects whether signal-cli is on PATH and, if missing, offers to install it:

주요 항목:

Linux x86-64: downloads the official native GraalVM build from the signal-cli GitHub releases and stores it under ~/.openclaw/tools/signal-cli/<version>/.
macOS and other architectures: installs via Homebrew instead.
Native Windows: not supported yet; run onboarding inside WSL2 to get the Linux install path.
Writes channels.signal.transport.cliPath with kind: "managed-native" either way.

What the wizard writes

Typical fields in ~/.openclaw/openclaw.json:

주요 항목:

agents.defaults.workspace
agents.defaults.skipBootstrap when --skip-bootstrap is passed
agents.defaults.model / models.providers (if Minimax chosen)
tools.profile (local onboarding defaults to "coding" when unset; existing explicit values are preserved)
gateway.* (mode, bind, auth, tailscale)
session.dmScope (onboarding preserves explicit values and otherwise leaves it unset, so the "main" default keeps all direct messages across channels in the agent's rolling main session—the personal-agent default. For shared or multi-user inboxes, use "per-channel-peer"; openclaw security audit recommends isolation when it detects multi-user DM traffic. Details: CLI Setup Reference)
channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
Channel DM allowlists when you opt in during the channel prompts. Discord, Matrix, Microsoft Teams, and Slack resolve names to IDs when possible; other channels take IDs directly (for example numeric Telegram sender IDs or WhatsApp phone numbers).
skills.install.nodeManager
setup --node-manager accepts npm, pnpm, or bun.
Manual config can still use yarn by setting skills.install.nodeManager directly.
wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode
wizard.securityAcknowledgedAt

주요 항목:

Onboarding overview: Onboarding (CLI)
CLI setup reference: CLI setup reference
macOS app onboarding: Onboarding
Config reference: Gateway configuration
Providers: WhatsApp, Telegram, Discord, Google Chat, Signal, iMessage
Skills: Skills, Skills config

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/wizard
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

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

Onboarding reference

핵심 요약

문서 구성

상세 내용

본문

Flow details (local mode)

Non-interactive mode

Add agent (non-interactive)

Gateway wizard RPC

Signal setup (signal-cli)

What the wizard writes

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Onboarding reference

핵심 요약

문서 구성

상세 내용

본문

Flow details (local mode)

Non-interactive mode

Add agent (non-interactive)

Gateway wizard RPC

Signal setup (signal-cli)

What the wizard writes

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Onboarding reference

핵심 요약

문서 구성

상세 내용

본문

Flow details (local mode)

Non-interactive mode

Add agent (non-interactive)

Gateway wizard RPC

Signal setup (signal-cli)

What the wizard writes

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Onboarding reference

핵심 요약

문서 구성

상세 내용

본문

Flow details (local mode)

Non-interactive mode

Add agent (non-interactive)

Gateway wizard RPC

Signal setup (signal-cli)

What the wizard writes

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드