openclaw-cn 引导向导（onboard）完全指南：一站式配置网关、模型、频道与技能

原创2026-10-15 14:30:381,991 阅读

文章标签：人工智能AI Agent即时通讯后端本地部署语音

openclaw-cn 引导向导（onboard）完全指南：一站式配置网关、模型、频道与技能

本文围绕 openclaw-cn 的 CLI 引导向导展开，讲解如何通过 openclaw-cn onboard 在 macOS、Linux 与 Windows（WSL2）上完成本地/远程网关、模型认证、频道接入、守护进程安装与技能部署的整套初始化流程。读完本文，你将掌握向导的快速开始与高级模式差异、每一步的具体配置含义、非交互式脚本化引导方式，以及 agents add 多代理扩展与网关 RPC 向导的底层工作机制。

引导向导是什么

引导向导（Onboarding Wizard）是 openclaw-cn 在 macOS、Linux 或 Windows（通过 WSL2，强烈推荐）上完成初始设置的推荐方式。它在一个引导流程中同时配置本地网关或远程网关连接，以及频道、技能和工作区默认设置，把原本分散的"配置网关 → 配置模型 → 接入频道 → 安装守护进程 → 检查健康"等环节合并为一次引导式问答。

从源码结构看，向导分为两条执行路径：交互式路径与脚本化路径。交互式入口由 src/commands/onboard-interactive.ts 实现，它创建 Clack 提示器（createClackPrompter）后调用 src/wizard/onboarding.ts 中的 runOnboardingWizard 逐步推进；非交互入口则由 src/commands/onboard-non-interactive.ts 承接，直接消费命令行参数写入配置。两条路径共用位于 src/commands/onboard-types.ts 的 OnboardOptions 类型定义，保证交互与非交互模式下可配置项完全一致。

三个核心入口命令

openclaw-cn onboard：完整引导向导，用于新机器初始化或整体重新配置，命令注册见 src/cli/program/register.onboard.ts。
openclaw-cn configure：后续按需重新配置（如只改模型、只改网关），支持 --section 精准定位配置项，注册代码见 src/cli/program/register.configure.ts。
openclaw-cn dashboard：打开控制 UI（仪表板），无需配置任何频道即可在浏览器中与代理聊天，注册代码见 src/cli/program/register.maintenance.ts。

# 主要入口点：完整引导
openclaw-cn onboard

# 最快首次聊天：打开控制 UI（无需频道设置）
openclaw-cn dashboard

# 后续重新配置
openclaw-cn configure

其中 configure 支持按 section 精准配置，例如只设置 Web 搜索：

# 推荐：设置 Brave Search API 密钥，让代理可以使用 web_search
# web_fetch 无需密钥即可工作
openclaw-cn configure --section web

这会存储 tools.web.search.apiKey。--section 可重复指定，可选值由 src/commands/configure.shared.ts 中的 CONFIGURE_WIZARD_SECTIONS 定义：workspace、model、web、gateway、daemon、channels、skills、health。

快速开始 vs 高级模式

向导以快速开始（默认设置）或高级（完全控制）开始。需要说明的是，--flow 还接受 manual 作为 advanced 的别名，代码中显式做了归一化处理（见 src/commands/onboard.ts）。

快速开始保持默认设置：

本地网关（回环 loopback）
工作区默认设置（或复用现有工作区）
网关端口 18789
网关认证令牌（自动生成，即使是回环也会启用认证）
Tailscale 暴露关闭
Telegram + WhatsApp 私信默认为白名单（会提示输入手机号码）

高级模式则逐步展示每个设置步骤：模式、工作区、网关、频道、守护进程、技能。

从 src/wizard/onboarding.ts 的源码实现看，快速开始还会自动跳过私信策略（DM policy）确认、跳过最终确认，并将允许来源频道（allowFrom）限定在插件元数据中声明了 quickstartAllowFrom 的频道集合——也就是说快速开始不是为了"少问几个问题"，而是为了把风险决策收敛到一组经过默认安全权衡的取值。

本地模式：向导的完整流程

本地模式（默认） 引导你完成以下环节：模型/认证 → 工作区 → 网关 → 频道 → 守护进程 → 健康检查 → 技能。以下按顺序详解每一步。

1. 现有配置检测

如果 ~/.openclaw/openclaw.json 已存在，向导会让你选择保留 / 修改 / 重置。
重新运行向导不会清除任何内容，除非你明确选择重置（或传递 --reset）。
如果配置无效或包含旧版密钥，向导会停止，并要求你先运行 openclaw-cn doctor 修复后再继续。
重置使用 trash（从不使用 rm），并提供三种范围：
- 仅配置（config）
- 配置 + 凭据 + 会话（config+creds+sessions）
- 完全重置（也移除工作区，full）

这一行为在源码中有直接印证：handleReset（见 src/commands/onboard-helpers.ts）首先将 ~/.openclaw/openclaw.json 移入废纸篓，config 范围到此为止；config+creds+sessions 范围再依次移入凭据目录与会话转录目录；full 范围最后移入工作区目录。整个实现只调用 trash 命令，符合"从不使用 rm"的安全约束。

2. 模型/认证

向导支持非常丰富的认证来源，覆盖 Anthropic、OpenAI、Google 以及多家国内与第三方模型提供商：

Anthropic API 密钥（推荐）：如果环境已存在 ANTHROPIC_API_KEY 则直接复用，否则提示输入密钥，并保存供守护进程使用。
Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导检查钥匙串项目 "Claude Code-credentials"（选择"始终允许"以避免 launchd 启动被阻止）；在 Linux/Windows 上，如果存在则复用 ~/.claude/.credentials.json。
Anthropic 令牌（粘贴设置令牌）：在任何机器上运行 claude setup-token 生成令牌，然后粘贴到向导（可以命名；空白 = 默认）。
OpenAI Code (Codex) 订阅（Codex CLI）：如果 ~/.codex/auth.json 存在，向导可以复用它。
OpenAI Code (Codex) 订阅（OAuth）：走浏览器流程，粘贴 code#state。当模型未设置或为 openai/* 时，向导会把 agents.defaults.model 设置为 openai-codex/gpt-5.2。
OpenAI API 密钥：复用 OPENAI_API_KEY 或提示输入密钥，保存到 ~/.openclaw/.env 以便 launchd 读取。
OpenCode Zen（多模型代理）：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）。
Vercel AI 网关（多模型代理）：提示输入 AI_GATEWAY_API_KEY，详见 Vercel AI 网关。
Cloudflare AI 网关：提示输入账户 ID、网关 ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY，详见 Cloudflare AI 网关。
MiniMax M2.1：配置自动写入，详见 MiniMax。
Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY，详见 Synthetic。
**Moonshot（Kimi K2）**与 Kimi Coding：配置自动写入，详见 Moonshot AI。
Gemini / Z.AI / 更多国内提供商：openclaw-cn 中文社区版额外内置了 Gemini、Z.AI、小米、硅基流动、阿里云百炼、DeepSeek、火山方舟、OpenRouter、Venice、HuggingFace 等选项，完整枚举定义在 src/commands/onboard-types.ts 的 AuthChoice 类型中。
跳过：暂不配置认证。

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

认证凭据的落盘位置：OAuth 凭据位于 ~/.openclaw/credentials/oauth.json；认证配置文件位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（包含 API 密钥 + OAuth 两种形态）。认证配置文件写入逻辑在 src/agents/auth-profiles/store.ts，更完整的机制说明见 OAuth 概念。

3. 工作区

默认工作区为 ~/.openclaw/workspace（可配置）。
向导为代理启动仪式生成所需的工作区文件。
完整工作区布局与备份指南见代理工作区。

4. 网关

可配置项：端口、绑定、认证模式、Tailscale 暴露。
认证建议：即使是回环也要保持令牌认证，这样本地 WS 客户端也必须进行认证。
仅当你完全信任每个本地进程时才建议禁用认证。
非回环绑定仍然需要认证。

从类型定义看（src/wizard/onboarding.types.ts 与 src/commands/onboard-types.ts），网关绑定支持 loopback、lan、auto、custom、tailnet 五种模式；认证模式支持 off、token、password 三种；Tailscale 暴露支持 off、serve、funnel 三种模式。快速开始默认采用 loopback 绑定 + 自动生成的随机令牌（令牌由 randomToken() 生成 24 字节十六进制随机串，见 src/commands/onboard-helpers.ts）。

5. 频道

向导支持以下频道接入，均可在引导过程中交互式配置：

WhatsApp：可选的二维码登录。
Telegram：机器人令牌。
Discord：机器人令牌。
Google Chat：服务账户 JSON + webhook 受众。
Mattermost（插件）：机器人令牌 + 基础 URL。
Signal：可选的 signal-cli 安装 + 账户配置。
BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + webhook。
iMessage：旧版 imsg CLI 路径 + 数据库访问。

私信安全默认采用配对机制：第一条私信会发送配对代码，通过 openclaw-cn pairing approve <channel> <code> 批准，或直接配置白名单。某些频道以插件形式提供，当你在引导中选择其中一个时，向导会在配置之前提示安装它（npm 或本地路径）。

6. 守护进程安装

macOS：安装 LaunchAgent。需要已登录的用户会话；对于无头模式，可使用自定义 LaunchDaemon（向导未提供）。
Linux（及通过 WSL2 的 Windows）：安装 systemd 用户单元。向导会尝试通过 loginctl enable-linger <user> 启用 linger，使网关在注销后仍保持运行；可能需要 sudo（写入 /var/lib/systemd/linger），向导会先尝试不使用 sudo。
运行时选择：推荐 Node（WhatsApp/Telegram 必需）；不推荐使用 Bun。

7. 健康检查

向导会启动网关（如果需要）并运行 openclaw-cn health。
提示：openclaw-cn status --deep 会将网关健康探针加入状态输出（需要可访问的网关）。health 命令定义见 src/cli/program/register.status-health-sessions.ts，--deep 提示也出现在 src/commands/status.command.ts 的输出逻辑中。
源码中的健康检查步骤（见 src/wizard/onboarding.finalize.ts）会先等待守护进程完成安装/重启，避免网关 WebSocket 短暂抖动导致健康检查误报，然后以 10 秒超时调用 healthCommand。

8. 技能（推荐）

读取可用技能并检查其依赖要求。
让你选择节点管理器：npm / pnpm（不推荐 bun）。
安装可选依赖项（某些在 macOS 上使用 Homebrew）。

9. 完成

输出总结与下一步建议，包括用于额外功能的 iOS/Android/macOS 应用。
如果未检测到 GUI（如 SSH 环境），向导会打印 SSH 端口转发指令用于控制 UI，而不是尝试打开浏览器。
如果缺少控制 UI 资产，向导会尝试构建它们；备用方案是 pnpm ui:build（自动安装 UI 依赖项）。

远程模式

远程模式仅配置本地客户端连接到其他地方的网关，它不会在远程主机上安装或更改任何内容。

需要设置的内容：

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

注意事项：

不执行远程安装或守护进程更改。
如果网关仅为回环，则使用 SSH 隧道或 tailnet 访问。
发现提示：
- macOS：Bonjour（dns-sd）
- Linux：Avahi（avahi-browse）

从源码看（src/wizard/onboarding.ts），快速开始模式仅支持本地网关，一旦选择远程模式会强制切换到手动/高级流程。remoteUrl 与 remoteToken 也是 OnboardOptions 的标准字段，可用于非交互式远程配置。

添加另一个独立代理

使用 openclaw-cn agents add <name> 创建具有自己工作区、会话和认证配置文件的独立代理。不带 --workspace 运行会启动向导；带 --workspace 则直接创建。

# 添加名为 work 的独立代理
openclaw-cn agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

它设置的内容：

agents.list[].name
agents.list[].workspace
agents.list[].agentDir

注意事项：

默认工作区遵循 ~/.openclaw/workspace-<agentId>。
可添加 bindings 来路由入站消息（向导可以做到这一点）。
非交互标志：--model、--agent-dir、--bind、--non-interactive。

agents 命令组的注册位于 src/cli/program/register.agent.ts，其中 agents list 支持 --json 与 --bindings 输出，agents add 支持 --workspace、--model、--agent-dir、--bind（可重复）等选项；--bind 的取值形如 <channel[:accountId]>，可用于将特定频道的消息路由到该代理。

非交互模式：脚本化引导

使用 --non-interactive 可以自动化或脚本化引导过程。注意：--json 不意味着非交互模式，脚本请使用 --non-interactive（并配合 --workspace）。

一个重要细节：非交互模式必须显式传递 --accept-risk。源码（src/commands/onboard.ts）在检测到 --non-interactive 而未声明 --accept-risk 时会直接报错退出，提示阅读安全文档并重新运行 openclaw-cn onboard --non-interactive --accept-risk ...。添加 --json 可获得机器可读的摘要。

Anthropic API 密钥示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

Gemini 示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AI 示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI 网关示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Cloudflare AI 网关示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshot 示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Synthetic 示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode Zen 示例

openclaw-cn onboard --non-interactive \
  --accept-risk \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

其他实用选项

--flow quickstart|advanced|manual：manual 是 advanced 的别名。
--mode local|remote：本地或远程网关模式。
--gateway-auth token|password、--gateway-token、--gateway-password：网关认证细粒度控制。
--tailscale off|serve|funnel 与 --tailscale-reset-on-exit：Tailscale 暴露控制。
--install-daemon / --no-install-daemon / --skip-daemon：守护进程安装控制（--skip-daemon 显式传入时优先级最高，见 src/cli/program/register.onboard.ts 的 resolveInstallDaemonFlag 逻辑）。
--daemon-runtime node|bun：守护进程运行时。
--skip-channels、--skip-skills、--skip-health、--skip-ui：按需跳过环节。
--node-manager npm|pnpm|bun：技能安装的节点管理器。
--reset：在运行向导前重置配置 + 凭据 + 会话 + 工作区。
--token-provider / --token / --token-profile-id / --token-expires-in：与 --auth-choice token 配合的令牌认证参数。

网关向导 RPC

网关通过 RPC 暴露向导流程（wizard.start、wizard.next、wizard.cancel、wizard.status）。客户端（macOS 应用、控制 UI）可以在不重新实现引导逻辑的情况下渲染每一步。

实现位于 src/gateway/server-methods/wizard.ts，核心设计：

wizard.start：创建新的 WizardSession（会话 ID 为随机 UUID），驱动 WizardSession 执行第一步；若已有向导在运行则返回 UNAVAILABLE 错误。
wizard.next：向当前会话提交 { stepId, value } 答案后推进到下一步；会话不在 running 状态会返回错误。
wizard.cancel：取消会话并返回其最终状态（cancelled / error）。
wizard.status：查询会话状态；若已非 running 则自动清理会话。

会话状态机定义在 src/wizard/session.ts：running、done、cancelled、error。每个 RPC 方法都会先用对应的 validateWizard*Params 校验参数，非法请求返回 INVALID_REQUEST 错误码——这种"状态机 + 校验器"的组合意味着第三方客户端可以安全地驱动任意复杂度的引导流程，而无需了解内部实现。

Signal 设置（signal-cli）

向导可以从 GitHub 发布版本安装 signal-cli：

下载适当的发布资产。
将其存储在 ~/.openclaw/tools/signal-cli/<version>/ 下。
将 channels.signal.cliPath 写入配置。

注意事项：

JVM 构建需要 Java 21。
可用时优先使用原生（GraalVM）构建。
Windows 使用 WSL2；signal-cli 安装遵循 WSL 内的 Linux 流程。

安装逻辑位于 src/commands/signal-install.ts：向导会优先探测原生二进制（官方 release 仅对部分架构发布 GraalVM 原生构建），架构不匹配时回退到 Homebrew 安装（brew install signal-cli），再不行才走 GitHub 发布资产下载流程。安装完成后将可执行文件放入 ~/.openclaw/tools/signal-cli/<version>/ 并写入 channels.signal.cliPath。

向导写入的配置内容

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

agents.defaults.workspace
agents.defaults.model / models.providers（如果选择了 MiniMax 等）
gateway.*（模式、绑定、认证、tailscale）
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-cn agents add 写入 agents.list[] 和可选的 bindings。

wizard.* 元数据字段由 applyWizardMetadata（见 src/commands/onboard-helpers.ts）在引导结束时写入：lastRunAt 为 ISO 时间戳，lastRunVersion 取当前版本号，lastRunCommit 取 GIT_COMMIT/GIT_SHA 环境变量，lastRunCommand 记录本次执行的命令，lastRunMode 记录 local/remote。这些字段的 schema 校验定义在 src/config/zod-schema.ts 中（lastRunMode 仅允许 local 或 remote 两个字面量）。

其他数据位置：

WhatsApp 凭据位于 ~/.openclaw/credentials/whatsapp/<accountId>/ 下。
会话存储在 ~/.openclaw/agents/<agentId>/sessions/ 下。
部分频道以插件形式提供，引导中选择时会先提示安装（npm 或本地路径）再写入配置。

openclaw-cn 引导向导（onboard）完全指南：一站式配置网关、模型、频道与技能

openclaw-cn 引导向导（onboard）完全指南：一站式配置网关、模型、频道与技能

引导向导是什么

三个核心入口命令

快速开始 vs 高级模式

本地模式：向导的完整流程

1. 现有配置检测

2. 模型/认证

3. 工作区

4. 网关

5. 频道

6. 守护进程安装

7. 健康检查

8. 技能（推荐）

9. 完成

远程模式

添加另一个独立代理

非交互模式：脚本化引导

Anthropic API 密钥示例

Gemini 示例

Z.AI 示例

Vercel AI 网关示例

Cloudflare AI 网关示例

Moonshot 示例

Synthetic 示例

OpenCode Zen 示例

其他实用选项

网关向导 RPC

Signal 设置（signal-cli）

向导写入的配置内容

相关文档

热门文章

openclaw-cn 引导向导（onboard）完全指南：一站式配置网关、模型、频道与技能

openclaw-cn 引导向导（onboard）完全指南：一站式配置网关、模型、频道与技能

引导向导是什么

三个核心入口命令

快速开始 vs 高级模式

本地模式：向导的完整流程

1. 现有配置检测

2. 模型/认证

3. 工作区

4. 网关

5. 频道

6. 守护进程安装

7. 健康检查

8. 技能（推荐）

9. 完成

远程模式

添加另一个独立代理

非交互模式：脚本化引导

Anthropic API 密钥示例

Gemini 示例

Z.AI 示例

Vercel AI 网关示例

Cloudflare AI 网关示例

Moonshot 示例

Synthetic 示例

OpenCode Zen 示例

其他实用选项

网关向导 RPC

Signal 设置（signal-cli）

向导写入的配置内容

相关文档

相关推荐

热门文章