上手引导向导
关于使用上手引导向导手动或通过引导流程配置 OpenClaw 的指南。
上手引导向导是 **推荐的** 在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的方式。它引导您完成配置本地或远程 Gateway 连接、渠道、技能和工作区默认设置。
主要入口：
openclaw onboard
最快开始对话的方式：打开 Control UI（无需设置渠道）。运行
`openclaw dashboard` 然后在浏览器中对话。文档：仪表盘。
后续重新配置：
openclaw configure
推荐：设置 Brave Search API 密钥，以便智能体可以使用 `web_search`
（`web_fetch` 无需密钥也可使用）。最简单的方式：`openclaw configure --section web`
它会将 `tools.web.search.apiKey` 存储。文档：网页工具。
快速入门与高级模式
向导以 **快速入门**（默认设置）与 **高级**（完全控制）模式开始。
**快速入门** 保留默认设置：
本地 Gateway（回环地址）
默认工作区（或现有工作区）
Gateway 端口 **18789**
Gateway 认证 **令牌**（自动生成，即使在回环地址上也是如此）
Tailscale 暴露 **关闭**
Telegram + WhatsApp 私信默认为 **允许名单**（系统会提示您输入手机号码）
**高级** 展示每个步骤（模式、工作区、Gateway、渠道、守护进程、技能）。
向导的功能
**本地模式 (默认)** 引导您完成：
模型/认证（OpenAI Codex 订阅 OAuth、Anthropic API 密钥（推荐）或 setup-token（粘贴），以及 MiniMax/GLM/Moonshot/AI Gateway 选项）
工作区位置 + 引导文件
Gateway 设置（端口/绑定/认证/Tailscale）
提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal）
守护进程安装（LaunchAgent / systemd 用户单元）
健康检查
技能（推荐）
**远程模式** 仅配置本地客户端以连接到其他位置的 Gateway。它 **不会** 在远程主机上安装或更改任何内容。
要添加更多隔离的智能体（独立的工作区 + 会话 + 认证），请使用：
openclaw agents add '<name>'
提示：`--json` **不** 意味着非交互模式。请使用 `--non-interactive`（以及 `--workspace`）用于脚本。
流程详情（本地）
1. 现有配置检测
如果 `~/.openclaw/openclaw.json` 存在，请选择 **保留 / 修改 / 重置**。
重新运行向导 **不会** 删除任何内容，除非您明确选择 **重置**（或传入 `--reset`）。
如果配置无效或包含遗留键，向导会停止并要求您运行 `openclaw doctor` 后再继续。
重置使用 `trash`（绝不使用 `rm）并提供作用域：
- 仅配置
- 配置 + 凭据 + 会话
- 完全重置（同时移除工作区）
2. 模型/认证
**Anthropic API 密钥（推荐）**：使用 `ANTHROPIC_API_KEY`（如果存在）或提示输入密钥，然后保存供守护进程使用。
**Anthropic OAuth (Claude Code CLI)**：在 macOS 上，向导会检查钥匙串项 “Claude Code-credentials”（请选择“始终允许”以避免 launchd 启动时被阻止）；在 Linux/Windows 上，它会复用 `~/.claude/.credentials.json`（如果存在）。
**Anthropic 令牌（粘贴 setup-token）**：运行 `claude setup-token` 在任意机器上执行，然后粘贴令牌。
**OpenAI Codex 订阅 (Codex CLI)**：如果 `~/.codex/auth.json` 存在，向导可以复用它。
**OpenAI Codex 订阅 (OAuth)**：浏览器流程；粘贴 `code#state`。
设置 `agents.defaults.model` 为 `openai-codex/gpt-5.2`（当模型未设置或为 `openai/*` 时）。
**OpenAI API 密钥**：使用 `OPENAI_API_KEY`（如果存在）或提示输入密钥，然后保存到 `~/.openclaw/.env` 以便 launchd 可以读取。
**OpenCode Zen（多模型代理）**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，请在 opencode.ai/auth 获取）。
**API 密钥**：为您存储密钥。
**Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。更多详情：Vercel AI Gateway
**MiniMax M2.1**：配置会自动写入。更多详情：MiniMax
**Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。更多详情：Synthetic
**Moonshot (Kimi K2)**：配置会自动写入。
**Kimi Coding**：配置会自动写入。更多详情：Moonshot AI
**跳过**：暂不配置认证。
从检测到的选项中选择默认模型（或手动输入提供商/模型）。
向导会运行模型检查，如果配置的模型未知或缺少认证则发出警告。
OAuth 凭据存储在 `<code1>~/.openclaw/credentials/oauth.json</code1>`；认证配置存储在 `<code2>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code2>`。更多详情：<link6>OAuth 概念</link6>
3. 工作区
4. 网关
端口、绑定、认证模式、Tailscale 暴露。
认证建议：保持 **令牌** 即使在回环地址上也使用，以确保本地 WS 客户端必须进行认证。
仅在您完全信任每个本地进程时才禁用认证。
非回环绑定仍需认证。
5. 渠道
WhatsApp：可选二维码登录。
Telegram：机器人令牌。
Discord：机器人令牌。
Google Chat：服务账户 JSON + webhook 受众。
Mattermost（插件）：机器人令牌 + 基础 URL。
Signal：可选 `signal-cli` 安装 + 账户配置。
iMessage：本地 `imsg` CLI 路径 + 数据库访问。
私信安全：默认为配对模式。首次私信会发送一个验证码；通过 `<code2>openclaw pairing approve <channel> <code>'</code2>` 批准，或使用允许名单。
6. 守护进程安装
macOS：LaunchAgent。需要已登录的用户会话；对于无头模式，请使用自定义 LaunchDaemon。
Linux（以及通过 WSL2 的 Windows）：systemd 用户单元。向导会尝试通过 `<code1>loginctl enable-linger <user>'</code1>` 启用驻留，以便在注销后 Gateway 保持运行。
可能会提示输入 sudo（写入 `/var/lib/systemd/linger）；它会先尝试不使用 sudo。
**运行时选择：** Node（推荐；WhatsApp/Telegram 需要）。Bun **不推荐**。
7. 健康检查
启动 Gateway（如需）并运行 `openclaw health`。
提示：`openclaw status --deep` 将 Gateway 健康探测添加到状态输出中。
8. 技能（推荐）
读取可用技能并检查依赖条件。
让您选择一个 Node 管理器：**npm / pnpm**（不推荐 Bun）。
安装可选依赖项（部分在 macOS 上使用 Homebrew）。
9. 完成
摘要 + 后续步骤，包括 iOS/Android/macOS 应用。
如果未检测到 GUI，向导会打印 SSH 端口转发说明，而不是打开浏览器。
如果 Control UI 资源文件缺失，向导会尝试构建它们；后备方案是 `pnpm ui:build`。
远程模式
远程模式配置本地客户端以连接到其他位置的 Gateway。
您需要设置的内容：
远程 Gateway URL（`ws://...`）
如果远程 Gateway 需要认证，则需提供令牌（推荐）
Notes:
不会执行远程安装或守护进程更改。
如果 Gateway 仅绑定回环地址，请使用 SSH 隧道或 tailnet。
发现提示：macOS: Bonjour (`dns-sd`); Linux: Avahi (`avahi-browse`)
添加另一个智能体
使用 `<code1>openclaw agents add <name>'</code1>` 创建一个拥有独立工作区、会话和认证配置的单独智能体。不使用 `<code2>--workspace</code2>` 运行会启动向导。
它设置：
`agents.list[].name`
`agents.list[].workspace`
`agents.list[].agentDir`
Notes:
默认工作区遵循 `<code1>~/.openclaw/workspace-<agentId>'</code1>`。
添加 `bindings` 以路由入站消息（向导可以执行此操作）。
非交互标志：`--model`，`--agent-dir`，`--bind`，`--non-interactive`。
非交互模式
使用 `--non-interactive` 用于自动化或脚本化上手引导：
openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
添加 `--json` 以获取机器可读的摘要。
Z.AI 示例：
openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$Z_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Vercel AI Gateway 示例：
openclaw onboard --non-interactive \ --mode local \ --auth-choice ai-gateway-api-key \ --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Moonshot 示例：
openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Synthetic 示例：
openclaw onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
OpenCode Zen 示例：
openclaw onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODE_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
增加智能体 (非交互) 示例：
openclaw agents add work \ --workspace ~/.openclaw/workspace-work \ --model openai/gpt-5.2 \ --bind whatsapp:biz \ --non-interactive \ --json
Gateway 向导 RPC
Gateway 通过 RPC 暴露向导流程（`wizard.start`，`wizard.next`，`wizard.cancel`，`wizard.status`）。客户端（macOS 应用、Control UI）可以渲染步骤而无需重新实现上手引导逻辑。
Signal 设置 (signal-cli)
向导可以安装 `signal-cli`（从 GitHub 发布版本）：
下载相应的发布资源。
将其存储在 `<code1>~/.openclaw/tools/signal-cli/<version>/</code1>`。
写入 `channels.signal.cliPath` 到您的配置中。
Notes:
JVM 构建需要 **Java 21**。
如有原生构建则优先使用。
Windows 使用 WSL2；安装遵循 WSL 内的 Linux 流程。
向导写入的内容
`~/.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/Teams），在提示期间选择启用时生效。
`skills.install.nodeManager`
`wizard.*`（lastRunAt, lastRunVersion 等）
`openclaw agents add` 写入 `agents.list[]` 和可选的 `bindings`。
WhatsApp 凭据存储在 `<code1>~/.openclaw/credentials/whatsapp/<accountId>/</code1>`。会话存储在 `<code2>~/.openclaw/agents/<agentId>/sessions/</code2>`。
部分渠道以插件形式提供。当您在上手引导期间选择某个渠道时，向导会提示先安装它（通过 npm 或本地路径），然后才能进行配置。