本页是 openclaw onboard 命令的完整技术参考。本地模式逐步引导你完成：模型与认证设置、工作区配置、网关设置（端口/绑定/Token/Tailscale）、渠道接入（Telegram/WhatsApp/Discord/Signal 等）、守护进程安装（LaunchAgent/systemd/Windows 计划任务）、健康检查和 Skills 设置。远程模式仅配置本机连接其他网关，不修改远程主机。

OpenClaw CLI Setup 完整参考：openclaw onboard 命令详解

本页是 openclaw onboard 的完整参考。快速上手见接入向导。

向导做了什么

本地模式（默认）逐步引导：

1. 模型与认证设置
2. 工作区位置与引导文件
3. 网关设置（端口、绑定、认证模式、Tailscale）
4. 渠道与提供商配置
5. 守护进程安装
6. 健康检查
7. Skills 设置

远程模式：配置本机连接到其他地方的网关。不安装或修改远程主机上的任何内容。

本地模式详细步骤

1. 检测已有配置：如果 ~/.openclaw/openclaw.json 存在，选择保留、修改或重置。重新运行向导不会自动清空任何内容，除非你明确选择重置（或传入 --reset）。--reset 默认为 config+creds+sessions；使用 --reset-scope full 也会清除工作区。如果配置无效或包含旧版 key，向导会停止并提示运行 openclaw doctor。重置使用 trash 并提供范围选项。

2. 模型与认证：详见认证与模型选项。

3. 工作区：默认 ~/.openclaw/workspace（可配置）。生成首次运行引导所需的工作区文件。工作区布局：Agent workspace。

4. 网关：配置端口、绑定、认证模式和 Tailscale 暴露。推荐：即使是本地回环也保持 token 认证，让本地 WS 客户端必须认证。Token 模式交互式设置支持：生成/存储明文 token（默认）或 使用 SecretRef（可选）。密码模式也支持明文或 SecretRef 存储。非交互式 token SecretRef：--gateway-token-ref-env <ENV_VAR>（需要在 onboarding 进程环境中设置非空环境变量，不能与 --gateway-token 同时使用）。仅在完全信任所有本地进程时才禁用认证。非回环绑定仍需要认证。

5. 渠道：

   • WhatsApp：可选 QR 登录
   • Telegram：Bot Token
   • Discord：Bot Token
   • Google Chat：Service Account JSON + Webhook Audience
   • Mattermost：Bot Token + Base URL
   • Signal：可选安装 signal-cli + 账号配置
   • iMessage：imsg CLI 路径 + Messages DB 访问；Gateway 不在 Mac 上时使用 SSH 包装器
   • DM 安全：默认配对模式。首条 DM 发送验证码，通过 openclaw pairing approve &lt;channel&gt; <code> 审批，或使用白名单

6. 守护进程安装：

   • macOS：LaunchAgent（需要登录用户会话；无头环境需自定义 LaunchDaemon，不随产品提供）
   • Linux 和 WSL2：systemd 用户单元（向导尝试 loginctl enable-linger <user>，退出后网关保持运行；可能需要 sudo 写入 /var/lib/systemd/linger，向导先尝试无 sudo）
   • 原生 Windows：优先使用计划任务；如果任务创建被拒绝，降级到用户级 Startup 文件夹登录项并立即启动网关。计划任务仍是首选，因为提供更好的监控状态
   • 推荐运行时：Node（必须；WhatsApp 和 Telegram 需要）。不推荐 Bun

7. 健康检查：启动网关（如果需要），然后运行 openclaw health。openclaw status --deep 添加实时网关健康探测，包括渠道探测（当渠道支持时）。

8. Skills：读取可用 Skills，检查依赖。让你选择 Node 管理器：npm、pnpm 或 bun。安装可选依赖（macOS 上有些使用 Homebrew）。

9. 完成：显示摘要和下一步，包括 iOS、Android、macOS 应用选项。

INFO

如果未检测到 GUI，向导会打印 Control UI 的 SSH 端口转发说明，而不是打开浏览器。如果 Control UI 资源缺失，向导尝试构建它们；回退方案是 pnpm ui:build（自动安装 UI 依赖）。

远程模式细节

远程模式配置本机连接到其他地方的网关。它不安装或修改远程主机上的任何内容。

需要设置：

• 远程网关 URL（ws://...）
• 如果远程网关需要认证（推荐），则设置 Token

INFO

• 如果网关仅限本地回环，使用 SSH 隧道或 tailnet。
• 发现提示：
  • macOS：Bonjour（dns-sd）
  • Linux：Avahi（avahi-browse）

认证与模型选项

Anthropic API Key

使用 ANTHROPIC_API_KEY（若存在）或提示输入，然后存储供守护进程使用。

OpenAI Code 订阅（OAuth）

浏览器流程；粘贴 code#state。设置 agents.defaults.model 为 openai/gpt-5.5（当模型未设置或已经是 OpenAI 系列时，通过 Codex 运行时设置）。

OpenAI Code 订阅（设备配对）

浏览器配对流程，使用短期设备代码。同样设置 agents.defaults.model 为 openai/gpt-5.5（条件同上）。

OpenAI API Key

使用 OPENAI_API_KEY（若存在）或提示输入，存储到 auth profiles。设置 agents.defaults.model 为 openai/gpt-5.5（当模型未设置、是 openai/* 或 openai-codex/* 时）。

xAI（Grok）OAuth

浏览器登录，适用于有资格的 SuperGrok 或 X Premium 账户。这是大多数用户的推荐路径。OpenClaw 存储结果 auth profile 用于 Grok 模型、Grok web_search、x_search 和 code_execution。

xAI（Grok）设备代码

远程友好的浏览器登录，使用短代码代替 localhost 回调。用于 SSH、Docker 或 VPS 主机。

xAI（Grok）API Key

提示输入 XAI_API_KEY 并配置 xAI 为模型提供商。当你想要 xAI Console API 密钥而不是订阅 OAuth 时使用。

OpenCode

提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY），并让你选择 Zen 或 Go 目录。设置 URL：opencode.ai/auth。

API Key（通用）

存储输入的 key。

Vercel AI Gateway

提示输入 AI_GATEWAY_API_KEY。详见 Vercel AI Gateway。

Cloudflare AI Gateway

提示输入 account ID、gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。详见 Cloudflare AI Gateway。

MiniMax

自动写入配置。托管默认模型 MiniMax-M2.7；API Key 接入用 minimax/...，OAuth 接入用 minimax-portal/...。详见 MiniMax。

StepFun

自动写入 StepFun 标准或 Step Plan 配置（支持中国或全球端点）。标准当前包含 step-3.5-flash，Step Plan 还包含 step-3.5-flash-2603。详见 StepFun。

Synthetic（Anthropic 兼容）

提示输入 SYNTHETIC_API_KEY。详见 Synthetic。

Ollama（云端和本地开放模型）

先提示选择 Cloud + Local、Cloud only 或 Local only。Cloud only 使用 OLLAMA_API_KEY 配合 https://ollama.com。主机后端模式提示输入 base URL（默认 http://127.0.0.1:11434），发现可用模型并建议默认值。Cloud + Local 还会检查 Ollama 主机是否已登录云访问。详见 Ollama。

Moonshot 和 Kimi Coding

Moonshot（Kimi K2）和 Kimi Coding 配置自动写入。详见 Moonshot AI。

自定义提供商

支持 OpenAI 兼容和 Anthropic 兼容端点。

交互式 onboarding 支持与其他 API Key 提供相同的存储选项：

• 立即粘贴 API Key（明文）
• 使用 secret reference（env ref 或配置的提供商 ref，带预检验证）

非交互式标志：

• --auth-choice custom-api-key
• --custom-base-url
• --custom-model-id
• --custom-api-key（可选；降级到 CUSTOM_API_KEY）
• --custom-provider-id（可选）
• --custom-compatibility <openai|anthropic>（可选；默认 openai）
• --custom-image-input / --custom-text-input（可选；覆盖推断的模型输入能力）

跳过

保持认证未配置。

模型行为说明：

• 从检测到的选项中选择默认模型，或手动输入提供商和模型。
• 自定义提供商 onboarding 推断通用模型 ID 的图片支持，仅在模型名称未知时询问。
• 当 onboarding 从提供商认证选择开始时，模型选择器自动优先选择该提供商。对于 Volcengine 和 BytePlus，此偏好也匹配它们的 coding-plan 变体（volcengine-plan/*、byteplus-plan/*）。
• 如果该优先提供商过滤结果为空，选择器回退到完整目录而不是显示空列表。
• 向导运行模型检查，如果配置的模型未知或缺少认证，则给出警告。

凭证与配置路径

• Auth profiles（API Key + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json

凭证存储模式：

• 默认 onboarding 将 API Key 以明文值持久化到 auth profiles。
• --secret-input-mode ref 启用引用模式代替明文存储。交互式设置中，你可以选择：
  • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
  • 配置的提供商引用（file 或 exec），包含提供商别名和 id
• 交互式引用模式在保存前运行快速预检验证：
  • 环境变量引用：验证变量名 + 当前 onboarding 环境中非空值
  • 提供商引用：验证提供商配置并解析请求的 id
  • 如果预检失败，onboarding 显示错误并允许重试
• 非交互式模式下，--secret-input-mode ref 仅支持环境变量引用：
  • 需要在 onboarding 进程环境中设置提供商环境变量
  • 内联 key 标志（如 --openai-api-key）要求该环境变量已设置，否则 onboarding 快速失败
  • 对于自定义提供商，非交互式 ref 模式将 models.providers.<id>.apiKey 存储为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }
  • 在该自定义提供商情况下，--custom-api-key 要求设置 CUSTOM_API_KEY，否则 onboarding 快速失败
• 网关认证凭据在交互式设置中支持明文和 SecretRef 选择：
  • Token 模式：生成/存储明文 token（默认）或 使用 SecretRef
  • 密码模式：明文或 SecretRef
• 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>
• 现有明文设置继续工作，不受影响。

无头/服务器提示

在有浏览器的机器上完成 OAuth，然后复制该 Agent 的 auth-profiles.json（例如 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 或对应的 $OPENCLAW_STATE_DIR/... 路径）到网关主机。credentials/oauth.json 仅为旧版导入源。

输出与内部字段（openclaw.json）

典型写入字段：

• agents.defaults.workspace
• agents.defaults.skipBootstrap（当使用 --skip-bootstrap 时）
• agents.defaults.model / models.providers（如果选择了 MiniMax）
• tools.profile（本地 onboarding 默认 "coding"；已有明确值时保留）
• gateway.*（mode、bind、auth、tailscale）
• session.dmScope（本地 onboarding 默认 per-channel-peer；已有明确值时保留）
• channels.telegram.botToken、channels.discord.token、channels.matrix.*、channels.signal.*、channels.imessage.*
• 渠道白名单（Slack、Discord、Matrix、Microsoft Teams），在提示时选择加入，名称尽可能解析为 ID
• skills.install.nodeManager（setup --node-manager 接受 npm、pnpm、bun；手动配置仍可设置 "yarn"）
• wizard.lastRunAt、wizard.lastRunVersion、wizard.lastRunCommit、wizard.lastRunCommand、wizard.lastRunMode

openclaw agents add 写入 agents.list[] 和可选的 bindings。

WhatsApp 凭证存储在 ~/.openclaw/credentials/whatsapp/<accountId>/。会话存储在 ~/.openclaw/agents/<agentId>/sessions/。

INFO

部分渠道通过插件提供。在 setup 时选择后，向导会提示安装该插件（npm 或本地路径），然后再配置渠道。

网关向导 RPC

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

客户端（macOS 应用和 Control UI）可渲染步骤，无需重新实现 onboarding 逻辑。

Signal 安装行为

• 下载对应版本的发行工件
• 存储到 ~/.openclaw/tools/signal-cli/<version>/
• 写入 channels.signal.cliPath 到配置
• JVM 构建需要 Java 21
• 有原生构建时优先使用原生构建
• Windows 使用 WSL2，在 WSL 内部按 Linux signal-cli 流程处理

相关文档

• 接入中心：接入向导
• 自动化与脚本：CLI 自动化
• 命令参考：openclaw onboard

常见问题

重新运行 openclaw onboard 会覆盖我现有的配置吗？

不会自动覆盖。向导检测到已有配置后会让你选择保留、修改或重置。选择“保留”继续使用现有配置；选择“修改”可以更新特定设置；只有选择“重置”（或传入 --reset 标志）才会清除配置，且默认只清除配置+凭证+会话，不会动工作区（除非指定 --reset-scope full）。

在无头服务器上如何完成 OAuth 认证？

有两种推荐方式：

1. 在有浏览器的机器上运行 openclaw onboard，完成 OAuth 后将 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 复制到无头服务器对应位置。
2. 使用 API Key 认证（如 --anthropic-api-key 或设置环境变量 ANTHROPIC_API_KEY）在无头环境运行 openclaw onboard --non-interactive。

--secret-input-mode ref 和默认的明文存储有什么区别？

默认模式将 API Key 直接写入 auth-profiles.json（明文）。ref 模式只存储“从哪里读取 Key”的引用（如 { source: "env", id: "OPENAI_API_KEY" }），实际 Key 从运行时环境变量中读取，不落盘。非交互式 ref 仅限于环境变量引用，交互式还支持文件或 exec 提供商引用，并会进行预检验证。