安装向导

安装向导 (openclaw onboard) 是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐方式。

它配置本地网关或远程网关连接，加上通道、技能和工作区默认值，一步完成。

主要入口

bash

openclaw onboard

最快的首次聊天：打开控制台 UI（无需通道设置）。运行 openclaw dashboard 在浏览器中聊天。

文档：Dashboard

后续重新配置

bash

openclaw configure

网页搜索 API 密钥

推荐：设置 Brave Search API 密钥以便智能体可以使用 web_search（web_fetch 无需密钥也能工作）。

最简单的方式：

bash

openclaw configure --section web

这会存储 tools.web.search.apiKey。

文档：Web 工具

快速开始 vs 高级模式

向导从 快速开始（默认）vs 高级（完全控制）开始。

快速开始 保持默认设置：

本地网关（回环）
工作区默认（或现有工作区）
网关端口 18789
网关认证令牌（自动生成，即使在回环上）
Tailscale 暴露关闭
Telegram + WhatsApp 私聊默认 allowlist（系统会提示你输入电话号码）

高级暴露每个步骤（模式、工作区、网关、通道、守护进程、技能）。

向导功能

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

模型/认证：OpenAI Code (Codex) 订阅 OAuth、Anthropic API key（推荐）或 setup-token（粘贴），加上 MiniMax/GLM/Moonshot/AI Gateway 选项
工作区位置 + 引导文件
网关设置（端口/绑定/认证/tailscale）
提供商：Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal
守护进程安装（LaunchAgent / systemd 用户单元）
健康检查
技能（推荐）

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

要添加更多隔离的智能体（独立的工作区 + 会话 + 认证），使用：

bash

openclaw agents add <name>

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

流程详情（本地模式）

1. 现有配置检测

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

2. 模型/认证

Anthropic API key（推荐）：如果存在 ANTHROPIC_API_KEY 则使用，或提示输入 key，然后将其保存以供守护进程使用。
Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导检查 Keychain 项 "Claude Code-credentials"（选择"始终允许"以避免 launchd 启动阻塞）；在 Linux/Windows 上，如果存在则重用 ~/.claude/.credentials.json。
Anthropic token（粘贴 setup-token）：在任何机器上运行 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 key：如果存在 OPENAI_API_KEY 则使用，或提示输入 key，然后将其保存到 ~/.openclaw/.env 以便 launchd 可以读取。
OpenCode Zen（多模型代理）：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取）。
API key：为你存储 key。
Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
- 更多详情：Vercel AI Gateway
MiniMax M2.1：配置自动写入。
- 更多详情：MiniMax
Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
- 更多详情：Synthetic
Moonshot (Kimi K2)：配置自动写入。
Kimi Code：配置自动写入。
- 更多详情：Moonshot AI (Kimi + Kimi Code)
跳过：尚未配置认证。
从检测到的选项中选择默认模型（或手动输入提供商/模型）。
向导运行模型检查，如果配置的模型未知或缺少认证则发出警告。

OAuth 凭证位于 ~/.openclaw/credentials/oauth.json；认证配置位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API keys + OAuth）。

更多详情：OAuth 认证

3. 工作区

默认 ~/.openclaw/workspace（可配置）。
为智能体引导仪式所需的工作区文件播种。
完整工作区布局 + 备份指南：智能体工作区

4. 网关

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

5. 通道

WhatsApp：可选的 QR 登录。
Telegram：bot token。
Discord：bot token。
Google Chat：服务账户 JSON + webhook 受众。
Mattermost（插件）：bot token + 基础 URL。
Signal：可选的 signal-cli 安装 + 账户配置。
iMessage：本地 imsg CLI 路径 + 数据库访问。
私聊安全：默认是配对。第一条私聊发送验证码；通过 openclaw pairing approve <channel> <code> 批准或使用允许列表。

6. 守护进程安装

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

7. 健康检查

启动网关（如果需要）并运行 openclaw health。
提示：openclaw status --deep 将网关健康探测添加到状态输出（需要可访问的网关）。

8. 技能（推荐）

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

9. 完成

摘要 + 下一步，包括 iOS/Android/macOS 应用以获取额外功能。
如果未检测到 GUI，向导会打印 SSH 端口转发说明以获取控制台 UI，而不是打开浏览器。
如果控制台 UI 资产缺失，向导会尝试构建它们；回退是 pnpm ui:build（自动安装 UI 依赖项）。

远程模式

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

你将设置：

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

注意：

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

添加另一个智能体

使用 openclaw agents add <name> 创建具有独立工作区、会话和认证配置文件的智能体。运行时不带 --workspace 会启动向导。

它设置：

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

注意：

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

非交互模式

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

bash

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 示例：

bash

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 示例：

bash

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 示例：

bash

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 示例：

bash

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

Synthetic 示例：

bash

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 示例：

bash

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

添加智能体（非交互）示例：

bash

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

网关向导 RPC

网关通过 RPC 暴露向导流程（wizard.start、wizard.next、wizard.cancel、wizard.status）。客户端（macOS 应用、控制台 UI）可以呈现步骤而无需重新实现引导逻辑。

Signal 设置（signal-cli）

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

下载相应的 release 资源。
将其存储在 ~/.openclaw/tools/signal-cli/<version>/ 下。
将 channels.signal.cliPath 写入你的配置。

注意：

JVM 构建需要 Java 21。
优先使用原生构建。
Windows 使用 WSL2；signal-cli 安装遵循 WSL2 内的 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/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/ 下。

有些通道作为插件提供。当你在引导过程中选择时，向导会提示安装它（npm 或本地路径），然后才能配置。

安装向导 ​

主要入口 ​

后续重新配置 ​

网页搜索 API 密钥 ​

快速开始 vs 高级模式 ​

向导功能 ​

流程详情（本地模式） ​

1. 现有配置检测 ​

2. 模型/认证 ​

3. 工作区 ​

4. 网关 ​

5. 通道 ​

6. 守护进程安装 ​

7. 健康检查 ​

8. 技能（推荐） ​

9. 完成 ​

远程模式 ​

添加另一个智能体 ​

非交互模式 ​

网关向导 RPC ​

Signal 设置（signal-cli） ​

向导写入的内容 ​

相关文档 ​

安装向导

主要入口

后续重新配置

网页搜索 API 密钥

快速开始 vs 高级模式

向导功能

流程详情（本地模式）

1. 现有配置检测

2. 模型/认证

3. 工作区

4. 网关

5. 通道

6. 守护进程安装

7. 健康检查

8. 技能（推荐）

9. 完成

远程模式

添加另一个智能体

非交互模式

网关向导 RPC

Signal 设置（signal-cli）

向导写入的内容

相关文档