古法编程

openclaw onboard 是 OpenClaw 的交互式引导命令，适用于首次配置或自动化部署。支持 --non-interactive 脚本模式，接入自定义 Provider（OpenAI、Ollama、LM Studio 等），令牌可选择 ref 环境变量存储代替明文。运行前需确保本地 Gateway 运行或使用 --skip-health 跳过等待，–install-daemon 可自动安装守护进程。支持 zh-CN 和 zh-TW 语言。

openclaw onboard — 交互式引导与脚本自动化

完整引导流程，用于本地或远程 Gateway 的设置。使用此命令让 OpenClaw 一步步指导你完成模型认证、工作区、Gateway、频道、技能和健康检查。

相关文档

CLI 引导中心

交互式 CLI 流程的完整说明。

引导总览

OpenClaw 引导各组件如何组合。

CLI 设置参考

输出、内部实现及各步骤行为。

CLI 自动化

非交互式标志和脚本化设置。

macOS 应用引导

macOS 菜单栏应用的引导流程。

示例 

openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow import 使用插件拥有的迁移提供者（如 Hermes）。它只在全新的 OpenClaw 设置上运行；如果存在现有的配置、凭据、会话或工作区内存/身份文件，请在导入前重置或选择全新设置。

--modern 启动 Crestodian 对话式引导预览。不加 --modern 时使用经典引导流程。

明文 ws:// 仅允许用于 loopback、私有 IP 地址、.local 和 Tailnet *.ts.net Gateway URL。对于其他受信任的私有 DNS 名称，请在引导进程环境中设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1。

Locale

交互式引导使用 CLI 向导的 locale 来显示固定设置文案。解析顺序：

  1. OPENCLAW_LOCALE
  2. LC_ALL
  3. LC_MESSAGES
  4. LANG
  5. 英文回退

支持的向导 locale：en、zh-CN、zh-TW。Locale 值也可以使用下划线或 POSIX 后缀形式，例如 zh_CN.UTF-8。产品名称、命令名称、配置键、URL、提供者 ID、模型 ID 及插件/频道标签保持原样。

示例：

OPENCLAW_LOCALE=zh-CN openclaw onboard

非交互式自定义 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-image-input

--custom-api-key 在非交互模式下可选。省略时，引导自动检查 CUSTOM_API_KEY 环境变量。OpenClaw 会自动将常见视觉模型 ID 标记为支持图像功能。对于未知的自定义视觉 ID，使用 --custom-image-input；对于纯文本模型，使用 --custom-text-input 强制标记为文本。

LM Studio 非交互式示例 

openclaw onboard --non-interactive \
  --auth-choice lmstudio \
  --custom-base-url "http://localhost:1234/v1" \
  --custom-model-id "qwen/qwen3.5-9b" \
  --lmstudio-api-key "$LM_API_TOKEN" \
  --accept-risk

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）同样适用。

使用 ref 模式存储 Provider 密钥 

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。

示例：

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。
  • 如果自行管理工作区文件，使用 --skip-bootstrap，它将设置 agents.defaults.skipBootstrap: true，并跳过创建 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md 和 BOOTSTRAP.md。
  • 在原生 Windows 上，--install-daemon 优先尝试计划任务，若任务创建被拒绝则回退到用户级启动目录快捷方式。

交互模式下的 ref 操作

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

非交互模式 Z.AI 端点选择

::: info --auth-choice zai-api-key 自动检测最适合你密钥的 Z.AI 端点（优先使用含 zai/glm-5.1 的通用 API）。如果明确需要 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 令牌。
- `manual`：完整提示，可配置端口、绑定和认证（`advanced` 的别名）。
- `import`：运行检测到的迁移提供者，预览迁移计划，确认后执行。

Provider 预过滤

当某个认证选项暗示了首选 Provider 时，引导会预过滤默认模型和允许列表选择器，仅显示该 Provider。对于 Volcengine 和 BytePlus，也会匹配 coding-plan 变体（`volcengine-plan/*`、`byteplus-plan/*`）。

如果预过滤后尚未加载任何模型，引导会回退到未过滤的完整目录，而非显示空列表。

网络搜索的后续提示

某些网络搜索 Provider 会触发特定后续提示：

- **Grok** 可提供可选的 `x_search` 设置，使用相同的 xAI OAuth 个人资料或 API 密钥，并选择 `x_search` 模型。
- **Kimi** 可询问 Moonshot API 区域（`api.moonshot.ai` vs `api.moonshot.cn`）和默认 Kimi 网络搜索模型。

其他行为

- 本地引导的 DM 作用域行为：参考 [CLI 设置参考](/ai/ai-tools/openclaw/start/wizard-cli-reference#outputs-and-internals)。
- 最快开始聊天：`openclaw dashboard`（Control UI，无需频道配置）。
- 自定义 Provider：连接任意兼容 OpenAI 或 Anthropic 的端点，包括未列出的托管 Provider。使用 Unknown 可自动检测。
- 如果检测到 Hermes 状态，引导会提供迁移流程。使用 [Migrate](/ai/ai-tools/openclaw/cli/migrate) 进行预演计划、覆盖模式、报告和精确映射。

常用后续命令 

openclaw channels add
openclaw configure
openclaw agents add <name>

如果只需要基础配置/工作区，使用 openclaw setup。后续针对性的调整使用 openclaw configure，仅配置频道时使用 openclaw channels add。

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

常见问题

怎么设置 openclaw onboard 的语言为中文？

设置环境变量 OPENCLAW_LOCALE=zh-CN 后运行命令即可，例如 OPENCLAW_LOCALE=zh-CN openclaw onboard。也支持 zh-TW。Locale 值可以使用 POSIX 后缀（如 zh_CN.UTF-8）。

如何跳过健康检查，只生成配置文件？

使用 --skip-health 标志。例如：openclaw onboard --non-interactive --auth-choice skip --skip-health。这会直接写入配置并退出，不等待 Gateway 就绪。

非交互模式下怎么设置自定义 Provider 并存储密钥为环境变量引用？

使用 --non-interactive --auth-choice custom-api-key --secret-input-mode ref，同时确保已设置 CUSTOM_API_KEY 环境变量。引导会写入 env ref，而不是明文密钥。其他 Provider 如 OpenAI 也类似，使用对应的 --secret-input-mode ref。