CLI Onboarding 参考

这是 openclaw onboard 的完整参考。 简短指南请参见 Onboarding 向导（CLI）。

向导做什么

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

  • 模型和 auth 设置（OpenAI Code 订阅 OAuth、Anthropic API 密钥或设置令牌，加上 MiniMax、GLM、Moonshot 和 AI Gateway 选项）
  • 工作区位置和引导文件
  • Gateway 设置（端口、绑定、auth、tailscale）
  • 频道和 providers（Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal）
  • Daemon 安装（LaunchAgent 或 systemd user unit）
  • 健康检查
  • 技能设置

远程模式配置这台机器连接到其他地方运行的 gateway。 它不会在远程主机上安装或修改任何东西。

本地流程详情

- 如果 `~/.openclaw/openclaw.json` 存在，选择保留、修改或重置。 - 重新运行向导不会清除任何东西，除非你明确选择重置（或传递 `--reset`）。 - CLI `--reset` 默认为 `config+creds+sessions`；使用 `--reset-scope full` 也会删除工作区。 - 如果配置无效或包含旧密钥，向导会停止并要求你运行 `openclaw doctor` 后再继续。 - 重置使用 `trash` 并提供范围： - 仅配置 - 配置 + 凭证 + 会话 - 完全重置（也删除工作区） - 完整选项矩阵见 [Auth 和模型选项](#auth-和模型选项)。 - 默认 `~/.openclaw/workspace`（可配置）。 - 为首次运行引导仪式种子工作区文件。 - 工作区布局：[代理工作区](/zh/docs/concepts/agent-workspace)。 - 提示端口、绑定、auth 模式和 tailscale 暴露。 - 建议：即使对 loopback 也保持令牌 auth 启用，这样本地 WS 客户端必须认证。 - 仅在你完全信任每个本地进程时才禁用 auth。 - 非 loopback 绑定仍需要 auth。 - [WhatsApp](/zh/docs/channels/whatsapp)：可选的 QR 登录 - [Telegram](/zh/docs/channels/telegram)：bot 令牌 - [Discord](/zh/docs/channels/discord)：bot 令牌 - [Google Chat](/zh/docs/channels/googlechat)：服务账户 JSON + webhook audience - [Mattermost](/zh/docs/channels/mattermost) 插件：bot 令牌 + 基础 URL - [Signal](/zh/docs/channels/signal)：可选的 `signal-cli` 安装 + 账户配置 - [BlueBubbles](/zh/docs/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook - [iMessage](/zh/docs/channels/imessage)：旧版 `imsg` CLI 路径 + 数据库访问 - DM 安全：默认是配对。第一个 DM 发送代码；通过 `openclaw pairing approve ` 或使用白名单批准。 - macOS: LaunchAgent - 需要已登录的用户会话；对于无头环境，使用自定义 LaunchDaemon（不附带）。 - Linux 和 Windows（通过 WSL2）：systemd user unit - 向导尝试 `loginctl enable-linger ` 以便 gateway 在注销后保持运行。 - 可能提示 sudo（写入 `/var/lib/systemd/linger`）；它先尝试不带 sudo。 - 运行时选择：Node（推荐；WhatsApp 和 Telegram 需要）。不推荐使用 Bun。 - 启动 gateway（如需要）并运行 `openclaw health`。 - `openclaw status --deep` 将 gateway 健康探测添加到状态输出。 - 读取可用技能并检查要求。 - 让你选择节点管理器：npm 或 pnpm（不推荐使用 bun）。 - 安装可选依赖项（有些在 macOS 上使用 Homebrew）。 - 摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。 如果未检测到 GUI，向导会打印 SSH 端口转发 instructions 而不是打开浏览器。 如果 Control UI 资源缺失，向导会尝试构建它们；回退选项是 `pnpm ui:build`（自动安装 UI 依赖）。

远程模式详情

远程模式配置这台机器连接到其他地方运行的 gateway。

远程模式不会在远程主机上安装或修改任何东西。

你设置的内容：

  • 远程 gateway URL（ws://...）
  • 如果远程 gateway 需要 auth，则需要令牌（推荐）
- 如果 gateway 仅限 loopback，使用 SSH 隧道或 tailnet。 - 发现提示： - macOS: Bonjour（`dns-sd`） - Linux: Avahi（`avahi-browse`）

Auth 和模型选项

如果存在则使用 `ANTHROPIC_API_KEY`，或提示输入密钥，然后为 daemon 保存。 - macOS: 检查 Keychain 项 "Claude Code-credentials" - Linux 和 Windows: 重用 `~/.claude/.credentials.json`（如果存在） 
在 macOS 上，选择"始终允许"以便 launchd 启动不会阻塞。
 在任何机器上运行 `claude setup-token`，然后粘贴令牌。 你可以命名它；空白使用默认名称。 如果 `~/.codex/auth.json` 存在，向导可以重用它。 浏览器流程；粘贴 `code#state`。 
当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.3-codex`。
 如果存在则使用 `OPENAI_API_KEY`，或提示输入密钥，然后将凭证存储在 auth 配置文件中。 
当模型未设置、为 `openai/*` 或为 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.1-codex`。
 提示 `XAI_API_KEY` 并将 xAI 配置为模型 provider。 提示 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。 设置 URL：[opencode.ai/auth](https://opencode.ai/auth)。 为你存储密钥。 提示 `AI_GATEWAY_API_KEY`。 更多详情：[Vercel AI Gateway](/zh/docs/providers/vercel-ai-gateway)。 提示账户 ID、gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 更多详情：[Cloudflare AI Gateway](/zh/docs/providers/cloudflare-ai-gateway)。 配置自动写入。 更多详情：[MiniMax](/zh/docs/providers/minimax)。 提示 `SYNTHETIC_API_KEY`。 更多详情：[Synthetic](/zh/docs/providers/synthetic)。 Moonshot（Kimi K2）和 Kimi Coding 配置自动写入。 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/zh/docs/providers/moonshot)。 与 OpenAI 兼容和 Anthropic 兼容端点配合工作。 
交互式 onboarding 支持与其他 provider API 密钥流程相同的 API 密钥存储选择：
- **现在粘贴 API 密钥**（明文）
- **使用密钥引用**（env 引用或配置的 provider 引用，带预验证）

非交互式标志：
- `--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 未配置。

模型行为：

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

凭证和配置文件路径：

  • OAuth 凭证：~/.openclaw/credentials/oauth.json
  • Auth 配置文件（API 密钥 + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

API 密钥存储模式：

  • 默认 onboarding 行为将 API 密钥作为明文值持久化在 auth 配置文件中。
  • --secret-input-mode ref 启用引用模式而不是明文密钥存储。 在交互式 onboarding 中，你可以选择：
    • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 配置的 provider 引用（file 或 exec）带 provider 别名和 ID
  • 交互式引用模式在保存前运行快速预验证。
    • Env 引用：验证变量名称 + 当前 onboarding 环境中的非空值。
    • Provider 引用：验证 provider 配置并解析请求的 ID。
    • 如果预验证失败，onboarding 显示错误并允许重试。
  • 在非交互式模式下，--secret-input-mode ref 仅支持 env 支持的引用。
    • 在 onboarding 进程环境中设置 provider env 变量。
    • 内联密钥标志（例如 --openai-api-key）要求该 env 变量已设置；否则 onboarding 快速失败。
    • 对于自定义 providers，非交互式 ref 模式将 models.providers.<id>.apiKey 存储为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 在这种自定义 provider 情况下，--custom-api-key 要求 CUSTOM_API_KEY 已设置；否则 onboarding 快速失败。
  • 现有的明文设置继续正常工作。
无头服务器提示：先在有浏览器的机器上完成 OAuth，然后复制 `~/.openclaw/credentials/oauth.json`（或 `$OPENCLAW_STATE_DIR/credentials/oauth.json`） 到 gateway 主机。

输出和内部机制

~/.openclaw/openclaw.json 中的典型字段：

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果选择 Minimax）
  • gateway.*（模式、绑定、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 设置行为：

  • 下载适当的发布资源
  • 存储在 ~/.openclaw/tools/signal-cli/<version>/ 下
  • 在配置中写入 channels.signal.cliPath
  • JVM 构建需要 Java 21
  • 有原生构建时使用原生构建
  • Windows 使用 WSL2，并在 WSL 内遵循 Linux signal-cli 流程

相关文档