CLI Onboarding 参考

本页是 openclaw onboard 的完整参考文档。 简要指南请参阅 Onboarding 向导（CLI）。

向导做了什么

本地模式（默认）会引导你完成：

  • 模型和认证配置（OpenAI Code 订阅 OAuth、Anthropic API key 或 setup token，以及 MiniMax、GLM、Ollama、Moonshot 和 AI Gateway 选项）
  • 工作区位置和引导文件
  • Gateway 设置（端口、绑定、认证、Tailscale）
  • 消息渠道和供应商（Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal）
  • 守护进程安装（LaunchAgent 或 systemd 用户单元）
  • 健康检查
  • Skills 配置

远程模式配置本机连接到其他位置的 Gateway。 它不会在远程主机上安装或修改任何内容。

本地模式详细流程

第 1 步：检测已有配置

- 如果 `~/.openclaw/openclaw.json` 已存在，可选择保留、修改或重置。
- 重新运行向导不会清除任何内容，除非你明确选择重置（或传入 `--reset`）。
- CLI `--reset` 默认范围为 `config+creds+sessions`；使用 `--reset-scope full` 可同时清除工作区。
- 如果配置无效或包含旧版字段，向导会停止并要求你先运行 `openclaw doctor`。
- 重置使用 `trash` 并提供以下范围选项：
  - 仅配置
  - 配置 + 凭据 + 会话
  - 完全重置（同时清除工作区）

第 2 步：模型和认证

- 完整选项矩阵见 [认证和模型选项](#认证和模型选项)。

第 3 步：工作区

- 默认 `~/.openclaw/workspace`（可配置）。
- 生成首次运行引导仪式所需的工作区文件。
- 工作区布局：[Agent 工作区](/docs/concepts/agent-workspace)。

第 4 步：Gateway

- 提示输入端口、绑定地址、认证模式和 Tailscale 暴露设置。
- 建议：即使在回环地址上也保持 token 认证，这样本地 WS 客户端必须通过认证。
- 在 token 模式下，交互式 onboarding 提供：
  - **生成/存储明文 token**（默认）
  - **使用 SecretRef**（可选）
- 在密码模式下，交互式 onboarding 同样支持明文或 SecretRef 存储。
- 非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
  - 需要在 onboarding 进程环境中设置一个非空的环境变量。
  - 不能与 `--gateway-token` 同时使用。
- 仅在你完全信任所有本地进程时才禁用认证。
- 非回环绑定仍然需要认证。

第 5 步：消息渠道

- [WhatsApp](/docs/channels/whatsapp)：可选的二维码登录
- [Telegram](/docs/channels/telegram)：bot token
- [Discord](/docs/channels/discord)：bot token
- [Google Chat](/docs/channels/googlechat)：服务账号 JSON + webhook audience
- [Mattermost](/docs/channels/mattermost) 插件：bot token + base URL
- [Signal](/docs/channels/signal)：可选的 `signal-cli` 安装 + 账号配置
- [BlueBubbles](/docs/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook
- [iMessage](/docs/channels/imessage)：旧版 `imsg` CLI 路径 + 数据库访问
- DM 安全：默认使用配对模式。首次 DM 会发送一个验证码；通过
  `openclaw pairing approve <channel> <code>` 批准，或使用白名单。

第 6 步：守护进程安装

- macOS：LaunchAgent
  - 需要已登录的用户会话；headless 场景需使用自定义 LaunchDaemon（未随附）。
- Linux 和 Windows（WSL2）：systemd 用户单元
  - 向导会尝试执行 `loginctl enable-linger <user>`，以便注销后 Gateway 继续运行。
  - 可能需要 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。
- 运行时选择：Node（推荐，WhatsApp 和 Telegram 必需）。不推荐 Bun。

第 7 步：健康检查

- 启动 Gateway（如需要）并运行 `openclaw health`。
- `openclaw status --deep` 会在状态输出中添加 Gateway 健康探测。

第 8 步：Skills

- 读取可用 Skills 并检查依赖。
- 让你选择包管理器：npm 或 pnpm（不推荐 bun）。
- 安装可选依赖（部分在 macOS 上使用 Homebrew）。

第 9 步：完成

- 摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。

注意： 如果未检测到图形界面，向导会打印 SSH 端口转发指令来访问 Control UI，而不是尝试打开浏览器。 如果 Control UI 资源文件缺失，向导会尝试构建它们；备选方案是 pnpm ui:build（会自动安装 UI 依赖）。

远程模式详情

远程模式配置本机连接到其他位置的 Gateway。

提示： 远程模式不会在远程主机上安装或修改任何内容。

你需要设置：

  • 远程 Gateway URL（ws://...）
  • Token（如果远程 Gateway 启用了认证，建议提供）

注意：

  • 如果 Gateway 仅绑定回环地址，需要使用 SSH 隧道或 tailnet。
  • 发现提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

认证和模型选项

Anthropic API key 
如果存在 `ANTHROPIC_API_KEY` 环境变量则直接使用，否则会提示输入，然后保存供守护进程使用。
Anthropic OAuth（Claude Code CLI） 
- macOS：检查 Keychain 项 "Claude Code-credentials"
- Linux 和 Windows：复用 `~/.claude/.credentials.json`（如果存在）

在 macOS 上，选择"始终允许"以避免 launchd 启动时被阻塞。
Anthropic token（粘贴 setup-token） 
在任意机器上运行 `claude setup-token`，然后粘贴 token。
可以命名；留空使用默认名称。
OpenAI Code 订阅（复用 Codex CLI） 
如果 `~/.codex/auth.json` 存在，向导可以复用它。
OpenAI Code 订阅（OAuth） 
浏览器流程；粘贴 `code#state`。

当模型未设置或为 `openai/*` 时，设置 `agents.defaults.model` 为 `openai-codex/gpt-5.4`。
OpenAI API key 
如果存在 `OPENAI_API_KEY` 环境变量则直接使用，否则会提示输入，然后将凭据存储在认证 profile 中。

当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，设置 `agents.defaults.model` 为 `openai/gpt-5.1-codex`。
xAI (Grok) API key 
提示输入 `XAI_API_KEY` 并将 xAI 配置为模型供应商。
OpenCode 
提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），让你选择 Zen 或 Go catalog。
配置 URL：[opencode.ai/auth](https://opencode.ai/auth)。
API key（通用） 
为你保存 key。
Vercel AI Gateway 
提示输入 `AI_GATEWAY_API_KEY`。
更多详情：[Vercel AI Gateway](/docs/providers/vercel-ai-gateway)。
Cloudflare AI Gateway 
提示输入 account ID、gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
更多详情：[Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway)。
MiniMax M2.5 
配置会自动写入。
更多详情：[MiniMax](/docs/providers/minimax)。
Synthetic（Anthropic 兼容） 
提示输入 `SYNTHETIC_API_KEY`。
更多详情：[Synthetic](/docs/providers/synthetic)。
Ollama（云端 + 本地开放模型） 
提示输入 base URL（默认 `http://127.0.0.1:11434`），然后提供 Cloud + Local 或仅 Local 模式选项。
自动发现可用模型并建议默认值。
更多详情：[Ollama](/docs/providers/ollama)。
Moonshot 和 Kimi Coding 
Moonshot（Kimi K2）和 Kimi Coding 配置会自动写入。
更多详情：[Moonshot AI（Kimi + Kimi Coding）](/docs/providers/moonshot)。
自定义供应商 
支持 OpenAI 兼容和 Anthropic 兼容端点。

交互式 onboarding 支持与其他供应商 API key 流程相同的存储选项：
- **立即粘贴 API key**（明文）
- **使用密钥引用**（环境变量引用或已配置的 provider 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`）
跳过 
不配置认证。

模型行为：

  • 从检测到的选项中选择默认模型，或手动输入供应商和模型。
  • 向导会运行模型检查，如果配置的模型未知或缺少认证会发出警告。

凭据和 profile 路径：

  • OAuth 凭据：~/.openclaw/credentials/oauth.json
  • 认证 profile（API key + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

凭据存储模式：

  • 默认 onboarding 行为将 API key 以明文形式持久化到认证 profile 中。
  • --secret-input-mode ref 启用引用模式替代明文存储。 在交互式 onboarding 中，可以选择：
    • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 已配置的 provider ref（file 或 exec），指定 provider 别名和 id
  • 交互式引用模式会在保存前进行快速预检验证。
    • 环境变量引用：验证变量名和当前 onboarding 环境中的非空值。
    • Provider ref：验证 provider 配置并解析请求的 id。
    • 预检失败时，onboarding 会显示错误并允许重试。
  • 非交互模式下，--secret-input-mode ref 仅支持环境变量。
    • 在 onboarding 进程环境中设置供应商环境变量。
    • 内联 key 参数（例如 --openai-api-key）要求该环境变量已设置，否则直接报错。
    • 自定义供应商的非交互 ref 模式将 models.providers.<id>.apiKey 存储为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 在这种自定义供应商场景下，--custom-api-key 要求 CUSTOM_API_KEY 已设置，否则直接报错。
  • Gateway 认证凭据在交互式 onboarding 中支持明文和 SecretRef 选项：
    • Token 模式：生成/存储明文 token（默认）或 使用 SecretRef。
    • 密码模式：明文或 SecretRef。
  • 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
  • 已有的明文配置继续正常工作。

注意： Headless 和服务器提示：在有浏览器的机器上完成 OAuth，然后把 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json） 复制到 Gateway 主机。

输出与内部机制

~/.openclaw/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、channels.discord.token、channels.signal.*、channels.imessage.*
  • 渠道白名单（Slack、Discord、Matrix、Microsoft Teams），在配置时选择加入（名称会尽可能解析为 ID）
  • skills.install.nodeManager
  • 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/。

注意： 部分消息渠道以插件形式交付。在 onboarding 中选中后，向导会先提示安装插件 （npm 或本地路径），再进行渠道配置。

Gateway 向导 RPC：

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

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

Signal 配置行为：

  • 下载对应的 release 资产
  • 存储在 ~/.openclaw/tools/signal-cli/<version>/
  • 在配置中写入 channels.signal.cliPath
  • JVM 构建需要 Java 21
  • 有原生构建时会优先使用
  • Windows 使用 WSL2，在 WSL 内部走 Linux signal-cli 流程

相关文档

arrow_back
上一页
Openclaw
下一页
Wizard CLI Automation
arrow_forward