引导向导（CLI）

引导向导是在 macOS、Linux 或 Windows（通过 WSL2，强烈推荐）上设置 OpenClaw 的推荐方式。它会在一个引导流程中配置本地 Gateway 或远程 Gateway 连接，以及 Channel、Skill 和 Workspace 默认设置。

主要入口：

openclaw onboard

最快开始聊天的方式：打开控制界面（无需设置 Channel）。运行 openclaw dashboard 然后在浏览器中聊天。文档：Dashboard。

后续重新配置：

openclaw configure

推荐：设置 Brave Search API 密钥，这样 Agent 就能使用 web_search（web_fetch 不需要密钥也能用）。最简单的方式：openclaw configure --section web，这会存储 tools.web.search.apiKey。文档：Web 工具。

快速开始 vs 高级模式

向导开始时会让你选择快速开始（使用默认值）还是高级模式（完全控制）。

快速开始保持默认设置：

• 本地 Gateway（loopback）
• 默认 Workspace（或使用现有 Workspace）
• Gateway 端口 18789
• Gateway 认证方式 Token（自动生成，即使在 loopback 上也会启用）
• Tailscale 暴露 关闭
• Telegram + WhatsApp 私信默认使用白名单（会提示你输入手机号）

高级模式会展示每个步骤（模式、Workspace、Gateway、Channel、Daemon、Skill）。

向导的功能

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

• 模型和认证（OpenAI Code (Codex) 订阅 OAuth、Anthropic API 密钥（推荐）或 setup-token（粘贴），以及 MiniMax/GLM/Moonshot/AI Gateway 选项）
• Workspace 位置和引导文件
• Gateway 设置（端口/绑定/认证/tailscale）
• Provider（Telegram、WhatsApp、Discord、Google Chat、Mattermost（Plugin）、Signal）
• Daemon 安装（LaunchAgent / systemd user unit）
• 健康检查
• Skill（推荐）

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

要添加更多隔离的 Agent（独立的 Workspace + Session + 认证），使用：

openclaw agents add <name>

提示：--json 不意味着非交互模式。脚本中使用 --non-interactive（和 --workspace）。

流程详情（本地模式）

1. 检测现有配置

   • 如果 ~/.openclaw/openclaw.json 存在，选择保留 / 修改 / 重置。
   • 重新运行向导不会清除任何内容，除非你明确选择重置（或传递 --reset）。
   • 如果配置无效或包含旧版密钥，向导会停止并要求你先运行 openclaw doctor。
   • 重置使用 trash（永远不用 rm）并提供范围选项：
     • 仅配置
     • 配置 + 凭证 + Session
     • 完全重置（也会删除 Workspace）

2. 模型和认证

   • Anthropic API 密钥（推荐）：如果存在 ANTHROPIC_API_KEY 就使用它，否则提示输入密钥，然后保存供 Daemon 使用。
   • Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导会检查钥匙串项目”Claude Code-credentials”（选择”始终允许”，这样 launchd 启动时不会被阻止）；在 Linux/Windows 上，如果存在 ~/.claude/.credentials.json 就重用它。
   • Anthropic token（粘贴 setup-token）：在任何机器上运行 claude setup-token，然后粘贴 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，在 https://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 (Kimi + Kimi Coding)
   • 跳过：暂不配置认证。
   • 从检测到的选项中选择默认模型（或手动输入 provider/model）。
   • 向导会运行模型检查，如果配置的模型未知或缺少认证会发出警告。

• OAuth 凭证存储在 ~/.openclaw/credentials/oauth.json；认证配置文件存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API 密钥 + OAuth）。
• 更多详情：/concepts/oauth

3. Workspace

   • 默认 ~/.openclaw/workspace（可配置）。
   • 为 Agent Bootstrap 仪式准备所需的 Workspace 文件。
   • 完整的 Workspace 布局和备份指南：Agent Workspace

4. Gateway

   • 端口、绑定、认证模式、tailscale 暴露。
   • 认证建议：即使在 loopback 上也保持 Token 认证，这样本地 WS 客户端必须进行身份验证。
   • 只有在你完全信任每个本地进程时才禁用认证。
   • 非 loopback 绑定仍然需要认证。

5. Channel

   • WhatsApp：可选的二维码登录。
   • Telegram：bot token。
   • Discord：bot token。
   • Google Chat：服务账号 JSON + webhook audience。
   • Mattermost（Plugin）：bot token + base URL。
   • Signal：可选的 signal-cli 安装和账号配置。
   • iMessage：本地 imsg CLI 路径 + 数据库访问。
   • DM 安全：默认是配对模式。首次 DM 会发送一个代码；通过 openclaw pairing approve <channel> <code> 批准或使用白名单。

6. Daemon 安装

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

7. 健康检查

   • 启动 Gateway（如果需要）并运行 openclaw health。
   • 提示：openclaw status --deep 会在状态输出中添加 Gateway 健康探测（需要可访问的 Gateway）。

8. Skill（推荐）

   • 读取可用的 Skill 并检查要求。
   • 让你选择 node 管理器：npm / pnpm（不推荐 bun）。
   • 安装可选依赖（有些在 macOS 上使用 Homebrew）。

9. 完成

   • 摘要和后续步骤，包括 iOS/Android/macOS 应用以获得额外功能。

• 如果未检测到 GUI，向导会打印控制界面的 SSH 端口转发说明，而不是打开浏览器。
• 如果控制界面资源缺失，向导会尝试构建它们；回退方案是 pnpm ui:build（自动安装 UI 依赖）。

远程模式

远程模式配置本地客户端连接到其他地方的 Gateway。

你需要设置：

• 远程 Gateway URL（ws://...）
• Token（如果远程 Gateway 需要认证，推荐）

注意：

• 不会执行远程安装或 Daemon 更改。
• 如果 Gateway 仅限 loopback，使用 SSH 隧道或 tailnet。
• 发现提示：
  • macOS：Bonjour（dns-sd）
  • Linux：Avahi（avahi-browse）

添加另一个 Agent

使用 openclaw agents add <name> 创建一个独立的 Agent，拥有自己的 Workspace、Session 和认证配置文件。不带 --workspace 运行会启动向导。

它会设置：

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

注意：

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

非交互模式

使用 --non-interactive 来自动化或脚本化引导：

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

添加 --json 获取机器可读的摘要。

Gemini 示例：

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

Z.AI 示例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_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

添加 Agent（非交互）示例：

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 应用、控制界面）可以渲染步骤而无需重新实现引导逻辑。

Signal 设置（signal-cli）

向导可以从 GitHub releases 安装 signal-cli：

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

注意：

• JVM 构建需要 Java 21。
• 可用时会使用原生构建。
• Windows 使用 WSL2；signal-cli 安装遵循 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.*
• Channel 白名单（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>/ 下。 Session 存储在 ~/.openclaw/agents/<agentId>/sessions/ 下。

有些 Channel 作为 Plugin 提供。当你在引导期间选择一个时，向导会提示安装它（npm 或本地路径），然后才能配置。

相关文档

• macOS 应用引导：引导
• 配置参考：Gateway 配置
• Provider：WhatsApp、Telegram、Discord、Google Chat、Signal、iMessage
• Skill：Skill、Skill 配置