CLI setup reference

CLI setup reference 문서는 OpenClaw 공식 문서(start/wizard-cli-reference)를 한국어로 정리한 가이드입니다. Step-by-step behavior for openclaw onboard: what each step does, config it writes, and internals 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Step-by-step behavior for openclaw onboard: what each step does, config it writes, and internals

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

문서 구성

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

What the wizard does
Local flow details
Remote mode details
Auth and model options
Outputs and internals
Installed app recommendations
Non-interactive setup
Gateway wizard RPC
Signal setup behavior
Related docs

상세 내용

본문

This page covers step-by-step onboarding behavior, outputs, and internals. For a walkthrough, see Onboarding (CLI). For the full CLI flag reference (every --flag, non-interactive examples, provider-specific commands), see openclaw onboard.

What the wizard does

Remote mode configures this machine to connect to a Gateway elsewhere. It does not install or modify anything on the remote host.

주요 항목:

Model and auth setup (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and more provider-owned auth flows)
Workspace location and bootstrap files
Gateway settings (port, bind, auth, Tailscale)
Channels and providers (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and other bundled or plugin channels)
Web search provider (optional)
Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
Health check
Skills setup

Local flow details

you explicitly confirm the move. Non-interactive reruns warn and preserve the current value.

주요 항목:

If ~/.openclaw/openclaw.json exists, choose Keep current values, Review and update, or Reset before setup.
Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass --reset).
CLI --reset defaults to config+creds+sessions; use --reset-scope full to also remove the workspace.
If config is invalid or contains legacy keys, the wizard stops and asks you to run openclaw doctor before continuing.
Reset moves state to Trash (never deletes directly) and offers scopes:
Config only
Config + credentials + sessions
Full reset (also removes the workspace)
Full option matrix is in Auth and model options.
Default ~/.openclaw/workspace (configurable).
Seeds workspace files needed for first-run bootstrap.
On rerun, an existing agent roster keeps its fleet-wide workspace unless
Workspace layout: Agent workspace.
Prompts for port, bind, auth mode, and Tailscale exposure.
Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
In token mode, interactive setup offers:
Generate/store plaintext token (default)
Use SecretRef (opt-in)
In password mode, interactive setup also supports plaintext or SecretRef storage.
Non-interactive token SecretRef path: --gateway-token-ref-env <ENV_VAR>.
Requires a non-empty env var in the onboarding process environment.
Cannot be combined with --gateway-token.
Disable auth only if you fully trust every local process.
Non-loopback binds still require auth.
WhatsApp: optional QR login

Remote mode details

Remote mode configures this machine to connect to a Gateway elsewhere. It does not install or modify anything on the remote host.

주요 항목:

Remote gateway URL (ws://... or wss://...)
Token, password, or no auth, matching the remote Gateway's configuration
Direct: connects over wss:// and prompts to trust the discovered
SSH tunnel: prints an ssh -N -L 18789:127.0.0.1:18789 <user>@<host>

Auth and model options

If a provider setup step fails in interactive onboarding (for example a CLI reuse option without a local sign-in), the wizard shows the error and returns to the provider picker instead of exiting. Explicit --auth-choice runs still fail fast for automation.

주요 항목:

Paste API key now (plaintext)
Use secret reference (env ref or configured provider ref, with preflight validation)
--auth-choice custom-api-key
--custom-base-url
--custom-model-id
--custom-api-key (optional; falls back to CUSTOM_API_KEY)
--custom-provider-id (optional)
--custom-compatibility <openai|openai-responses|anthropic> (optional; default openai)
--custom-image-input / --custom-text-input (optional; override inferred model input capability)
Pick default model from detected options, or enter provider and model manually.
When onboarding starts from a provider auth choice, the model picker prefers
If that preferred-provider filter would be empty, the picker falls back to
Wizard runs a model check and warns if the configured model is unknown or missing auth.
Auth profiles (API keys + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Legacy OAuth import: ~/.openclaw/credentials/oauth.json
Default onboarding behavior persists API keys as plaintext values in auth profiles.
--secret-input-mode ref enables reference mode instead of plaintext key storage.
environment variable ref (for example keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
configured provider ref (file or exec) with provider alias + id
Interactive reference mode runs a fast preflight validation before saving.
Env refs: validates variable name + non-empty value in the current onboarding environment.
Provider refs: validates provider config and resolves the requested id.
If preflight fails, onboarding shows the error and lets you retry.
In non-interactive mode, --secret-input-mode ref is env-backed only.
Set the provider env var in the onboarding process environment.

Outputs and internals

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)
channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
Channel allowlists (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) when you opt in during prompts; Discord and Slack also resolve entered names to IDs
skills.install.nodeManager
The setup --node-manager flag accepts npm, pnpm, or bun.
Manual config can still set skills.install.nodeManager: "yarn" later.
wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode
wizard.securityAcknowledgedAt

Installed app recommendations

After the model access check succeeds, classic interactive onboarding on macOS scans application names and bundle IDs without requesting macOS privacy permissions. It searches the official plugin catalogs and ClawHub, then asks the configured model to reject false name matches and recommend relevant plugins or skills. Recommended matches are selected by default; optional matches require an explicit selection.

Non-interactive setup

--non-interactive requires --accept-risk (acknowledges that agents are powerful and full system access is risky):

openclaw onboard --non-interactive --accept-risk \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

Gateway wizard RPC

Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.

주요 항목:

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

Signal setup behavior

주요 항목:

Downloads the appropriate release asset from the official signal-cli GitHub releases (native build, Linux x86-64 only)
On other platforms (macOS, non-x64 Linux), installs via Homebrew instead
Stores the release-asset install under ~/.openclaw/tools/signal-cli/<version>/
Writes channels.signal.transport.cliPath with kind: "managed-native" in config
Native Windows is not supported yet; run onboarding inside WSL2 to get the Linux install path

주요 항목:

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

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw onboard --non-interactive --accept-risk \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

CLI setup reference

핵심 요약

Step-by-step behavior for openclaw onboard: what each step does, config it writes, and internals

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

문서 구성

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

What the wizard does
Local flow details
Remote mode details
Auth and model options
Outputs and internals
Installed app recommendations
Non-interactive setup
Gateway wizard RPC
Signal setup behavior
Related docs

상세 내용

본문

What the wizard does

Remote mode configures this machine to connect to a Gateway elsewhere. It does not install or modify anything on the remote host.

주요 항목:

Model and auth setup (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and more provider-owned auth flows)
Workspace location and bootstrap files
Gateway settings (port, bind, auth, Tailscale)
Channels and providers (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and other bundled or plugin channels)
Web search provider (optional)
Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
Health check
Skills setup

Local flow details

you explicitly confirm the move. Non-interactive reruns warn and preserve the current value.

주요 항목:

If ~/.openclaw/openclaw.json exists, choose Keep current values, Review and update, or Reset before setup.
Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass --reset).
CLI --reset defaults to config+creds+sessions; use --reset-scope full to also remove the workspace.
If config is invalid or contains legacy keys, the wizard stops and asks you to run openclaw doctor before continuing.
Reset moves state to Trash (never deletes directly) and offers scopes:
Config only
Config + credentials + sessions
Full reset (also removes the workspace)
Full option matrix is in Auth and model options.
Default ~/.openclaw/workspace (configurable).
Seeds workspace files needed for first-run bootstrap.
On rerun, an existing agent roster keeps its fleet-wide workspace unless
Workspace layout: Agent workspace.
Prompts for port, bind, auth mode, and Tailscale exposure.
Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
In token mode, interactive setup offers:
Generate/store plaintext token (default)
Use SecretRef (opt-in)
In password mode, interactive setup also supports plaintext or SecretRef storage.
Non-interactive token SecretRef path: --gateway-token-ref-env <ENV_VAR>.
Requires a non-empty env var in the onboarding process environment.
Cannot be combined with --gateway-token.
Disable auth only if you fully trust every local process.
Non-loopback binds still require auth.
WhatsApp: optional QR login

Remote mode details

Remote mode configures this machine to connect to a Gateway elsewhere. It does not install or modify anything on the remote host.

주요 항목:

Remote gateway URL (ws://... or wss://...)
Token, password, or no auth, matching the remote Gateway's configuration
Direct: connects over wss:// and prompts to trust the discovered
SSH tunnel: prints an ssh -N -L 18789:127.0.0.1:18789 <user>@<host>

Auth and model options

주요 항목:

Paste API key now (plaintext)
Use secret reference (env ref or configured provider ref, with preflight validation)
--auth-choice custom-api-key
--custom-base-url
--custom-model-id
--custom-api-key (optional; falls back to CUSTOM_API_KEY)
--custom-provider-id (optional)
--custom-compatibility <openai|openai-responses|anthropic> (optional; default openai)
--custom-image-input / --custom-text-input (optional; override inferred model input capability)
Pick default model from detected options, or enter provider and model manually.
When onboarding starts from a provider auth choice, the model picker prefers
If that preferred-provider filter would be empty, the picker falls back to
Wizard runs a model check and warns if the configured model is unknown or missing auth.
Auth profiles (API keys + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Legacy OAuth import: ~/.openclaw/credentials/oauth.json
Default onboarding behavior persists API keys as plaintext values in auth profiles.
--secret-input-mode ref enables reference mode instead of plaintext key storage.
environment variable ref (for example keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
configured provider ref (file or exec) with provider alias + id
Interactive reference mode runs a fast preflight validation before saving.
Env refs: validates variable name + non-empty value in the current onboarding environment.
Provider refs: validates provider config and resolves the requested id.
If preflight fails, onboarding shows the error and lets you retry.
In non-interactive mode, --secret-input-mode ref is env-backed only.
Set the provider env var in the onboarding process environment.

Outputs and internals

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)
channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
Channel allowlists (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) when you opt in during prompts; Discord and Slack also resolve entered names to IDs
skills.install.nodeManager
The setup --node-manager flag accepts npm, pnpm, or bun.
Manual config can still set skills.install.nodeManager: "yarn" later.
wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode
wizard.securityAcknowledgedAt

Installed app recommendations

Non-interactive setup

--non-interactive requires --accept-risk (acknowledges that agents are powerful and full system access is risky):

openclaw onboard --non-interactive --accept-risk \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

Gateway wizard RPC

Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.

주요 항목:

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

Signal setup behavior

주요 항목:

Downloads the appropriate release asset from the official signal-cli GitHub releases (native build, Linux x86-64 only)
On other platforms (macOS, non-x64 Linux), installs via Homebrew instead
Stores the release-asset install under ~/.openclaw/tools/signal-cli/<version>/
Writes channels.signal.transport.cliPath with kind: "managed-native" in config
Native Windows is not supported yet; run onboarding inside WSL2 to get the Linux install path

주요 항목:

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

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw onboard --non-interactive --accept-risk \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

CLI setup reference

핵심 요약

문서 구성

상세 내용

본문

What the wizard does

Local flow details

Remote mode details

Auth and model options

Outputs and internals

Installed app recommendations

Non-interactive setup

Gateway wizard RPC

Signal setup behavior

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

CLI setup reference

핵심 요약

문서 구성

상세 내용

본문

What the wizard does

Local flow details

Remote mode details

Auth and model options

Outputs and internals

Installed app recommendations

Non-interactive setup

Gateway wizard RPC

Signal setup behavior

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

CLI setup reference

핵심 요약

문서 구성

상세 내용

본문

What the wizard does

Local flow details

Remote mode details

Auth and model options

Outputs and internals

Installed app recommendations

Non-interactive setup

Gateway wizard RPC

Signal setup behavior

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

CLI setup reference

핵심 요약

문서 구성

상세 내용

본문

What the wizard does

Local flow details

Remote mode details

Auth and model options

Outputs and internals

Installed app recommendations

Non-interactive setup

Gateway wizard RPC

Signal setup behavior

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드