`openclaw onboard`

交互式引导，用于本地或远程 Gateway 的配置流程。

示例

bash

openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

对于可信内网中使用明文 ws:// 的场景，在执行引导的进程环境中设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1。

非交互式接入自定义 Provider：

bash

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --secret-input-mode plaintext \
  --custom-compatibility openai

--custom-api-key 在非交互模式下是可选的，若省略，引导程序会自动检查 CUSTOM_API_KEY 环境变量。

非交互式接入 Ollama：

bash

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

--custom-base-url 默认为 http://127.0.0.1:11434；--custom-model-id 可省略，引导会使用 Ollama 的推荐默认值。云端模型 ID（如 kimi-k2.5:cloud）同样适用。

以引用（ref）方式存储 Provider 密钥而非明文：

bash

openclaw onboard --non-interactive \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --accept-risk

使用 --secret-input-mode ref 时，引导会写入环境变量支持的 ref 而非明文密钥。对于 auth-profile 型 Provider，写入 keyRef 条目；对于自定义 Provider，将 models.providers.<id>.apiKey 写为 env ref（例如 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }）。

非交互式 ref 模式约定：

在引导进程环境中提前设置 Provider 对应的环境变量（如 OPENAI_API_KEY）。
不要同时传递内联密钥参数（如 --openai-api-key），除非该环境变量也已设置。
如果传递了内联密钥参数但缺少对应环境变量，引导会立即报错并给出提示。

非交互模式下的 Gateway 令牌选项：

--gateway-auth token --gateway-token <token>：存储明文令牌。
--gateway-auth token --gateway-token-ref-env <name>：将 gateway.auth.token 存为环境变量 SecretRef。
--gateway-token 和 --gateway-token-ref-env 互斥。
--gateway-token-ref-env 要求对应环境变量在引导进程中非空。
使用 --install-daemon 时，若令牌鉴权需要令牌，SecretRef 管理的 Gateway 令牌会被验证，但不会以明文形式持久化到守护进程服务的环境元数据中。
使用 --install-daemon 时，若令牌模式需要令牌而配置的 SecretRef 无法解析，引导会失败并给出修复指引。
使用 --install-daemon 时，若同时配置了 gateway.auth.token 和 gateway.auth.password 但未设置 gateway.auth.mode，引导会阻止安装，直到显式设置 mode。

示例：

bash

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

非交互模式下的本地 Gateway 健康检查：

除非传递 --skip-health，引导会等待本地 Gateway 可达后才算成功退出。
--install-daemon 会先启动托管 Gateway 安装流程；不带此参数时需提前运行 openclaw gateway run。
如果只需要在自动化脚本中写入配置/工作区/引导文件，使用 --skip-health。
在原生 Windows 上，--install-daemon 优先尝试计划任务，若任务创建被拒绝则回退到用户级启动目录快捷方式。

交互模式下使用引用模式的操作流程：

在提示时选择使用 Secret Reference。
然后选择：
- 环境变量
- 已配置的 Secret Provider（file 或 exec）
引导会在保存 ref 前进行快速预检验证。
- 若验证失败，会显示错误并允许重试。

非交互模式下的 Z.AI 端点选项：

--auth-choice zai-api-key 现在会自动检测最适合你密钥的 Z.AI 端点（优先使用含 zai/glm-5 的通用 API）。如果明确需要 GLM Coding Plan 端点，请选择 zai-coding-global 或 zai-coding-cn。

bash

# 无提示端点选择
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# 其他 Z.AI 端点选项：
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn

Mistral 非交互式示例：

bash

openclaw onboard --non-interactive \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

流程说明：

quickstart：最少提示，自动生成 Gateway 令牌，最快完成"养龙虾"。
manual：完整提示，可配置端口/绑定/认证（advanced 的别名）。
本地引导 DM 作用域行为：CLI Setup Reference。
最快开始聊天：openclaw dashboard（Control UI，无需频道配置）。
自定义 Provider：连接任意兼容 OpenAI 或 Anthropic 的端点，包括未列出的托管 Provider，可用 Unknown 自动检测。

常用后续命令

bash

openclaw configure
openclaw agents add <name>

注意：--json 不等同于非交互模式，脚本中请显式加上 --non-interactive。

openclaw onboard ​

相关文档 ​

示例 ​

常用后续命令 ​

`openclaw onboard`

相关文档

示例

常用后续命令