`openclaw onboard`

交互式引导向导（本地或远程 Gateway 设置）。

示例

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：

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：

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 也可以在这里使用。

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

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

使用 --secret-input-mode ref 时，引导程序会写入基于环境变量的引用而非明文密钥值。对于基于认证配置文件的 provider，写入 keyRef 条目；对于自定义 provider，将 models.providers.<id>.apiKey 写为环境变量引用（例如 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }）。

非交互式 ref 模式规范：

在引导进程环境中设置 provider 环境变量（例如 OPENAI_API_KEY）。
除非同时设置了该环境变量，否则不要传内联密钥参数（例如 --openai-api-key）。
如果传了内联密钥参数但没有设置对应环境变量，引导程序会直接报错并给出指引。

非交互模式下的 Gateway token 选项：

--gateway-auth token --gateway-token <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 时，如果 token 认证需要 token，SecretRef 管理的 gateway token 会被验证，但不会以解析后的明文形式持久化到 supervisor 服务环境元数据中。
使用 --install-daemon 时，如果 token 模式需要 token 但配置的 token SecretRef 未解析，引导程序会直接失败并给出修复指引。
使用 --install-daemon 时，如果同时配置了 gateway.auth.token 和 gateway.auth.password 且 gateway.auth.mode 未设置，引导程序会阻止安装，直到显式设置 mode。

示例：

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 的安装流程。不传的话，你需要已经有一个运行中的本地 gateway（比如先执行 openclaw gateway run）。
如果你在自动化中只需要写入配置 / 工作空间 / 引导文件，用 --skip-health。
在原生 Windows 上，--install-daemon 会先尝试计划任务，如果任务创建被拒绝则回退到用户级启动文件夹登录项。

交互式引导中使用引用模式：

提示时选择 Use secret reference。
然后选择：
- 环境变量
- 已配置的 secret provider（file 或 exec）
引导程序会在保存引用前做快速预检验证。
- 验证失败时会显示错误并让你重试。

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

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

# 无需提示的端点选择
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 示例：

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

流程说明：

quickstart：最少的交互提示，自动生成 gateway token。
manual：完整的端口 / 绑定 / 认证配置提示（advanced 的别名）。
本地引导的 DM 作用域行为：CLI Onboarding Reference。
最快开始对话：openclaw dashboard（Control UI，无需设置频道）。
自定义 Provider：连接任何兼容 OpenAI 或 Anthropic 的端点，包括未列出的托管 provider。用 Unknown 自动检测。

常见后续命令

openclaw configure
openclaw agents add <name>

注意： --json 不等于非交互模式。脚本中请用 --non-interactive。

openclaw onboard

相关指南

示例

常见后续命令

`openclaw onboard`