上手引导向导 (CLI)

上手引导向导是 推荐的 在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的方式。它通过一个引导式流程配置本地 Gateway 或远程 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 Code (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）用于脚本。

流程详情（本地）

现有配置检测
- 如果 ~/.openclaw/openclaw.json 存在，请选择 保留 / 修改 / 重置。
- 重新运行向导不会不会删除任何内容，除非您明确选择重置（或传入 --reset）。
- 如果配置无效或包含遗留键，向导会停止并要求您运行 openclaw doctor 后再继续。
- 重置使用 trash （绝不使用 rm）并提供作用域：
  - 仅配置
  - 配置 + 凭据 + 会话
  - 完全重置（同时移除工作区）
模型/认证
- 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 Code (Codex) 订阅 (Codex CLI)：如果 ~/.codex/auth.json 存在，向导可以复用它。
- OpenAI Code (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，请在 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)
- 跳过：暂不配置认证。
- 从检测到的选项中选择默认模型（或手动输入提供商/模型）。
- 向导会运行模型检查，如果配置的模型未知或缺少认证则发出警告。

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

工作区
- 默认 ~/.openclaw/workspace （可配置）。
- 生成智能体引导启动仪式所需的工作区文件。
- 完整工作区布局 + 备份指南：智能体工作区
Gateway
- 端口、绑定、认证模式、Tailscale 暴露。
- 认证建议：保持令牌即使在回环地址上也使用，以确保本地 WS 客户端必须进行认证。
- 仅在您完全信任每个本地进程时才禁用认证。
- 非回环绑定仍需认证。
渠道
- WhatsApp：可选二维码登录。
- Telegram：机器人令牌。
- Discord：机器人令牌。
- Google Chat：服务账户 JSON + webhook 受众。
- Mattermost （插件）：机器人令牌 + 基础 URL。
- Signal：可选 signal-cli 安装 + 账户配置。
- iMessage：本地 imsg CLI 路径 + 数据库访问。
- 私信安全：默认为配对模式。首次私信会发送一个验证码；通过 openclaw pairing approve <channel> <code> 批准，或使用允许名单。
守护进程安装
- macOS：LaunchAgent
  - 需要已登录的用户会话；对于无头模式，请使用自定义 LaunchDaemon（未随附）。
- Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
  - 向导会尝试通过 loginctl enable-linger <user> 启用驻留，以便在注销后 Gateway 保持运行。
  - 可能会提示输入 sudo（写入 /var/lib/systemd/linger）；它会先尝试不使用 sudo。
- 运行时选择： Node（推荐；WhatsApp/Telegram 需要）。Bun 不推荐。
健康检查
- 启动 Gateway（如需）并运行 openclaw health。
- 提示： openclaw status --deep 将 Gateway 健康探测添加到状态输出中（需要可达的 Gateway）。
技能（推荐）
- 读取可用技能并检查依赖条件。
- 让您选择一个 Node 管理器： npm / pnpm （不推荐 bun）。
- 安装可选依赖项（部分在 macOS 上使用 Homebrew）。
完成
- 摘要 + 后续步骤，包括 iOS/Android/macOS 应用以获取额外功能。

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

远程模式

远程模式配置本地客户端以连接到其他位置的 Gateway。您需要设置的内容：

远程 Gateway URL（ws://...）
如果远程 Gateway 需要认证，则需提供令牌（推荐）

注意事项：

不会执行远程安装或守护进程更改。
如果 Gateway 仅绑定回环地址，请使用 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 用于自动化或脚本化上手引导：

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

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

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 发布版本）：

下载相应的发布资源。
将其存储在 ~/.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.*
渠道允许名单（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 或本地路径），然后才能进行配置。

开始

​上手引导向导 (CLI)

​快速入门与高级模式

​向导的功能

​流程详情（本地）

​远程模式

​添加另一个智能体

​非交互模式

​Gateway 向导 RPC

​Signal 设置 (signal-cli)

​向导写入的内容

​相关文档

上手引导向导 (CLI)

快速入门与高级模式

向导的功能

流程详情（本地）

远程模式

添加另一个智能体

非交互模式

Gateway 向导 RPC

Signal 设置 (signal-cli)

向导写入的内容

相关文档