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

CLI Setup 完整参考

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

向导做了什么

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

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

远程模式：配置本机连接到其他地方的网关，不修改远程主机。

本地模式详细步骤

步骤 1：检测已有配置

• ~/.openclaw/openclaw.json 存在时：选择保留、修改或重置
• --reset 默认范围 config+creds+sessions；用 --reset-scope full 也清除工作区
• 配置无效或含旧版 Key 时，向导停止并提示运行 openclaw doctor

步骤 2：模型与认证

详见认证与模型选项。

步骤 3：工作区

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

步骤 4：网关

• 配置端口、绑定、认证模式和 Tailscale 暴露
• 推荐：即使是本地回环也保持 token 认证，让本地 WS 客户端必须认证
• Token 模式支持：生成/存储明文 token（默认）或 使用 SecretRef（可选）
• 非交互式 token SecretRef：--gateway-token-ref-env <ENV_VAR>

步骤 5：渠道

• WhatsApp：可选 QR 登录
• Telegram：Bot Token
• Discord：Bot Token
• Google Chat：Service Account JSON + Webhook Audience
• Mattermost：Bot Token + Base URL
• Signal：可选安装 signal-cli + 账号配置
• BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + Webhook
• DM 安全：默认配对模式。首条 DM 发送验证码，通过 openclaw pairing approve <channel> <code> 审批，或使用白名单

步骤 6：守护进程安装

• macOS：LaunchAgent（需要登录用户会话；无头环境需自定义 LaunchDaemon）
• Linux 和 WSL2：systemd 用户单元（向导尝试 loginctl enable-linger <user>，退出后网关保持运行）
• 原生 Windows：优先使用计划任务；创建被拒时降级到用户级 Startup 文件夹启动项
• 推荐运行时：Node（必须；WhatsApp 和 Telegram 需要）。不推荐 Bun

步骤 7：健康检查

运行 openclaw health。openclaw status --deep 添加实时网关健康探测，包括渠道探测（当渠道支持时）。

步骤 8：Skills

读取可用 Skills、检查依赖，选择 Node 管理器（npm/pnpm/bun）。

认证与模型选项

Anthropic API Key

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

OpenAI Code 订阅（Codex CLI 复用）

若 ~/.codex/auth.json 存在，向导可复用它。凭证仍由 Codex CLI 管理；到期时 OpenClaw 优先重读源文件并在提供商可以刷新时将刷新的凭证写回 Codex 存储。

OpenAI Code 订阅（OAuth）

浏览器流程；粘贴 code#state。

设置 agents.defaults.model 为 openai-codex/gpt-5.4（当模型未设置或为 openai/* 时）。

OpenAI API Key

使用 OPENAI_API_KEY（若存在）或提示输入，存储到 auth profiles。

设置 agents.defaults.model 为 openai/gpt-5.4（当模型未设置、为 openai/* 或 openai-codex/* 时）。

xAI（Grok）API Key

提示输入 XAI_API_KEY 并配置 xAI 为模型提供商。

OpenCode

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

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。

Synthetic（Anthropic 兼容）

提示输入 SYNTHETIC_API_KEY。详见 Synthetic。

MiniMax

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

详见MiniMax。

Moonshot 和 Kimi Coding

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

详见Moonshot AI。

Ollama

提示输入 base URL（默认 http://127.0.0.1:11434），然后提供云端+本地或纯本地模式，自动发现可用模型并建议默认值。

自定义提供商

支持 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）

凭证存储

存储路径

• Auth profiles（API Key + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json
• WhatsApp 凭证：~/.openclaw/credentials/whatsapp/<accountId>/
• 会话：~/.openclaw/agents/<agentId>/sessions/

凭证存储模式

• 默认：明文值存入 auth profiles
• --secret-input-mode ref：启用引用模式（不存明文）
  • 交互式：可选环境变量引用（如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）或配置提供商引用
  • 非交互式：仅支持 env 引用，需要在 onboarding 进程环境中设置提供商 env 变量

无头/服务器提示：在有浏览器的机器上完成 OAuth，然后将该 Agent 的 auth-profiles.json 复制到网关主机。credentials/oauth.json 仅为旧版导入源。

配置输出字段（openclaw.json）

向导通常写入以下字段：

• agents.defaults.workspace
• agents.defaults.model / models.providers（如选择 MiniMax 时）
• tools.profile（本地 onboarding 默认为 "coding"；已有明确值时保留）
• gateway.*（mode、bind、auth、tailscale）
• session.dmScope（本地 onboarding 默认 per-channel-peer）
• 各渠道凭证（channels.telegram.botToken 等）
• 渠道白名单（Slack、Discord、Matrix、Microsoft Teams，在提示时选择加入，名称尽可能解析为 ID）
• skills.install.nodeManager（setup --node-manager 接受 npm、pnpm、bun；手动配置仍可设置 yarn）
• wizard.lastRunAt、wizard.lastRunVersion 等向导元数据

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

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

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

Signal 安装行为

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

网关向导 RPC

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

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

常见问题

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

A: 不会自动覆盖。向导检测到已有配置后会先让你选择"保留/修改/重置"。选择"保留"继续使用现有配置；选择"修改"可以更新特定设置；只有选择"重置"（或传入 --reset 标志）才会清除配置。

Q: 在无头服务器上完成 OAuth 认证的正确方式是什么？

A: 在有浏览器的机器上运行 openclaw onboard，完成 OAuth 流程后将 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 复制到无头服务器。或者使用 API Key 认证方式，直接设置相应的环境变量（如 ANTHROPIC_API_KEY），在无头环境中运行 openclaw onboard --non-interactive --anthropic-api-key "$ANTHROPIC_API_KEY"。

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

A: 默认模式将 API Key 直接写入 auth-profiles.json（明文）。ref 模式只存储"从哪里读取 Key"的引用（如 { source: "env", id: "OPENAI_API_KEY" }），实际 Key 从运行时环境变量中读取，不落盘，更适合有安全合规要求的场景。

延伸阅读

• 接入向导
• CLI 自动化
• openclaw onboard 命令参考