CLI 引导参考

本文档详细说明 openclaw onboard 引导向导的完整行为，涵盖本地模式和远程模式的所有技术细节。

向导执行的操作

本地模式（默认）

本地模式（Local mode）会引导你完成以下配置步骤：

模型与认证设置 — 支持 OpenAI Code 订阅 OAuth、Anthropic API Key 或 Setup Token，以及 MiniMax、GLM、Moonshot、AI Gateway 等选项
工作空间位置与引导文件 — 配置并初始化工作空间目录
Gateway（网关）设置 — 端口、绑定地址、认证方式、Tailscale
渠道与 Provider — Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal
守护服务安装 — LaunchAgent 或 systemd 用户级服务
健康检查 — 验证配置正确性
技能安装 — 选择并安装 Skill 包

远程模式

远程模式（Remote mode）配置当前机器连接到远程 Gateway（网关），不会在远程主机上安装或修改任何内容。

本地流程详解

配置文件检测

如果 ~/.openclaw/openclaw.json 已存在，向导会提示选择：

Keep — 保留现有配置
Modify — 在现有配置上修改
Reset — 重置配置

安全重置

重新运行向导不会清除任何内容，除非你显式选择 Reset（或使用 --reset）。

重置范围

CLI --reset 默认范围为 config+creds+sessions；使用 --reset-scope full 可同时移除工作空间。

重置使用 trash 命令（移至回收站），支持以下范围：

范围	说明
Config only	仅重置配置文件
Config + credentials + sessions	重置配置、凭证和会话（默认）
Full reset	完全重置，包括移除工作空间

如果配置无效或包含过期的 legacy key，向导会停止并要求你先运行 openclaw doctor 再继续。

工作空间

默认路径：~/.openclaw/workspace（可配置）
初始化工作空间所需的引导文件（用于首次运行的 bootstrap ritual）
工作空间布局详见：Agent 工作空间

Gateway（网关）设置

引导程序会提示配置：

端口 — 监听端口
绑定地址 — 绑定的网络接口
认证模式 — Token 或密码认证
Tailscale — 是否通过 Tailscale 暴露

认证建议

即使在 loopback（回环地址）模式下，也建议保持 Token 认证，以确保本地 WebSocket 客户端必须通过身份验证。

Token 认证模式

在交互式引导中，Token 模式提供两种存储方式：

生成/存储明文 Token（默认）
使用 SecretRef（手动选择启用）

密码认证模式

密码模式同样支持明文存储或 SecretRef 存储。

非交互式 Token SecretRef

bash

--gateway-token-ref-env <ENV_VAR_NAME>

要求对应的环境变量非空
不能与 --gateway-token 同时使用

WARNING

仅在完全信任所有本地进程时才应禁用认证。非 loopback 绑定仍然需要认证。

渠道配置

渠道	配置要点
WhatsApp	可选 QR 码登录
Telegram	Bot Token
Discord	Bot Token
Google Chat	Service Account JSON + Webhook Audience
Mattermost	Bot Token + Base URL（插件形式）
Signal	可选 `signal-cli` 安装 + 账号配置
BlueBubbles	推荐用于 iMessage；Server URL + Password + Webhook
iMessage	旧版 `imsg` CLI 路径 + 数据库访问

DM 安全： 默认使用配对（pairing）机制。首次收到 DM 时会发送一个配对码，需要通过 openclaw pairing approve <code> 批准，或使用 allowlist（白名单）。

守护服务安装

平台	服务类型	注意事项
macOS	LaunchAgent	需要已登录的用户会话；无头（headless）模式需自定义 LaunchDaemon（未随附）
Linux	systemd 用户级服务	向导会尝试运行 `loginctl enable-linger <user>` 以在注销后保持 Gateway 运行
Windows (WSL2)	systemd 用户级服务	在 WSL2 环境中遵循 Linux 流程

运行时选择

推荐使用 Node 运行时（WhatsApp 和 Telegram 渠道必须使用 Node）。不推荐 Bun 运行时。

Linux/WSL2 中，向导会尝试不使用 sudo 启用 linger；如果失败，会提示输入 sudo 密码（写入 /var/lib/systemd/linger/<user>）。

健康检查

启动 Gateway（如果尚未运行）并运行 openclaw health
openclaw status --deep 可在状态输出中增加 Gateway 健康探针

技能安装

读取可用的 Skill（技能）并检查依赖
允许选择包管理器：npm 或 pnpm（不推荐 bun）
安装可选依赖（macOS 上部分使用 Homebrew）
完成后显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项

无 GUI 环境

如果未检测到 GUI，向导会打印 SSH 端口转发指令用于访问 Control UI，而非尝试打开浏览器。如果 Control UI 资产缺失，向导会尝试构建它们；回退方案是 pnpm ui:build（自动安装 UI 依赖）。

远程模式详解

远程模式配置当前机器连接到远程 Gateway，不会在远程主机上安装或修改任何内容。

需要配置的信息：

远程 Gateway URL — 如 ws://...
Token — 如果远程 Gateway 启用了认证（推荐）
- 如果 Gateway 仅绑定到 loopback，请使用 SSH 隧道或 Tailnet

发现提示：

macOS：Bonjour（dns-sd）
Linux：Avahi（avahi-browse）

认证与模型选项

Anthropic

使用 ANTHROPIC_API_KEY 环境变量（如果存在）或提示输入 Key，然后保存以供守护服务使用。

macOS：检查 Keychain 中的 "Claude Code-credentials" 项
Linux 和 Windows：复用 ~/.claude/.credentials.json（如果存在）

macOS 用户

在 macOS 上选择 "Always Allow" 以确保 launchd 启动时不会阻塞。

Claude Code Token

在任何机器上运行 claude setup-token，然后粘贴 Token。可以命名；留空使用默认值。

OpenRouter

如果 ~/.codex/auth.json 存在，向导可以复用。通过浏览器流程获取；粘贴 code#state。

当模型未设置或为 openai/* 时，设置 agents.defaults.model 为 openai-codex/gpt-5.3-codex。

OpenAI

使用 OPENAI_API_KEY 环境变量（如果存在）或提示输入 Key，然后将凭证存储到 auth profiles。

当模型未设置、为 openai/* 或 openai-codex/* 时，设置 agents.defaults.model 为 openai/gpt-5.1-codex。

xAI

提示输入 XAI_API_KEY 并将 xAI 配置为模型 Provider。

Opencode

提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）。注册地址：opencode.ai/auth。

Vercel AI Gateway

提示输入 AI_GATEWAY_API_KEY。详情：Vercel AI Gateway。

Cloudflare AI Gateway

提示输入 Account ID、Gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。详情：Cloudflare AI Gateway。

MiniMax

配置自动写入。详情：MiniMax。

Synthetic

提示输入 SYNTHETIC_API_KEY。详情：Synthetic。

Moonshot

Moonshot（Kimi K2）和 Kimi Coding 配置自动写入。详情：Moonshot AI (Kimi + Kimi Coding)。

自定义 Provider

支持 OpenAI-compatible 和 Anthropic-compatible 端点。交互式引导支持与其他 Provider API Key 流程相同的存储选项：

直接粘贴 API Key（明文）
使用 Secret Reference（环境变量引用或已配置的 Provider 引用，带预检验证）

非交互模式参数：

参数	说明
`--auth-choice custom-api-key`	选择自定义 API Key 认证
`--custom-base-url`	自定义端点 URL
`--custom-model-id`	模型 ID
`--custom-api-key`	API Key（可选；回退到 `CUSTOM_API_KEY`）
`--custom-provider-id`	Provider ID（可选）
`--custom-compatibility <mode>`	兼容模式（可选；默认 `openai`）

模型行为：

从检测到的选项中选择默认模型，或手动输入 Provider 和模型名称
向导会运行模型检查，如果配置的模型未知或缺少认证则发出警告

凭证存储

凭证路径

类型	路径
OAuth 凭证	`~/.openclaw/credentials/oauth.json`
Auth Profiles（API Keys + OAuth）	`~/.openclaw/agents/<agent-id>/auth-profiles.json`

凭证存储模式

默认行为：以明文值形式将 API Key 持久化到 auth profiles
--secret-input-mode ref：启用引用模式替代明文存储

交互式引用模式

在交互式引导中，可以选择：

环境变量引用 — 例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }
已配置的 Provider 引用 — file 或 exec 类型，指定 Provider 别名 + ID

交互式引用模式会在保存前运行快速预检验证：

环境变量引用：验证变量名称和当前引导环境中的非空值
Provider 引用：验证 Provider 配置并解析请求的 ID
如果预检失败，引导程序会显示错误并允许重试

非交互式引用模式

在非交互模式中，--secret-input-mode ref 仅支持环境变量引用：

在引导进程环境中设置 Provider 环境变量
内联 Key 参数（如 --openai-api-key）要求环境变量已设置；否则引导立即失败
对于自定义 Provider，非交互 ref 模式将 models.providers.<id>.apiKey 存储为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }
在自定义 Provider 场景中，--custom-api-key 要求 CUSTOM_API_KEY 已设置；否则引导立即失败

Gateway 认证凭证

Gateway 认证凭证在交互式引导中支持明文和 SecretRef 两种选项：

Token 模式：生成/存储明文 Token（默认）或使用 SecretRef
密码模式：明文或 SecretRef
非交互 Token SecretRef 路径：--gateway-token-ref-env <ENV_VAR_NAME>
现有的明文配置继续正常工作

无头服务器提示

在有浏览器的机器上完成 OAuth 流程，然后将 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json）复制到 Gateway 主机。

输出与内部机制

openclaw.json 中的典型字段

向导完成后，~/.openclaw/openclaw.json 中通常包含以下字段：

agents.defaults.workspace — 默认工作空间路径
agents.defaults.model / models.providers — 模型配置
tools.profile — 本地引导默认设为 "messaging"（未设置时）；已有显式值保持不变
gateway.* — 网关配置（模式、绑定、认证、Tailscale）
session.dmScope — 本地引导默认设为 per-channel-peer（未设置时）；已有显式值保持不变
channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.* — 渠道凭证
渠道 Allowlist（Slack、Discord、Matrix、Microsoft Teams）— 在引导提示中启用时写入（名称尽可能解析为 ID）
skills.install.nodeManager — 包管理器
wizard.lastRunAt、wizard.lastRunVersion、wizard.lastRunCommit、wizard.lastRunCommand、wizard.lastRunMode — 向导运行元数据

Agent 数据

openclaw agents add 写入 agents.list[] 和可选的 bindings
WhatsApp 凭证存储在 ~/.openclaw/credentials/whatsapp/<phone-number>/
会话存储在 ~/.openclaw/agents/<agent-id>/sessions/

插件渠道

部分渠道以插件形式提供。在引导过程中选择这些渠道时，向导会提示安装插件（npm 或本地路径），然后再进行渠道配置。

Gateway 向导 RPC

向导通过以下 RPC 方法与 Gateway 通信：

方法	说明
`wizard.start`	启动向导会话
`wizard.next`	进入下一步
`wizard.cancel`	取消向导
`wizard.status`	查询向导状态

客户端（macOS 应用和 Control UI）可以渲染向导步骤而无需重新实现引导逻辑。

Signal 安装行为

下载对应平台的 release 资产
存储在 ~/.openclaw/tools/signal-cli/<version>/
在配置中写入 channels.signal.cliPath
JVM 构建需要 Java 21
有 native build 时优先使用
Windows 使用 WSL2，在 WSL 内遵循 Linux signal-cli 流程

CLI 引导参考 ​

向导执行的操作 ​

本地模式（默认） ​

远程模式 ​

本地流程详解 ​

配置文件检测 ​

重置范围 ​

工作空间 ​

Gateway（网关）设置 ​

Token 认证模式 ​

密码认证模式 ​

非交互式 Token SecretRef ​

渠道配置 ​

守护服务安装 ​

健康检查 ​

技能安装 ​

远程模式详解 ​

认证与模型选项 ​

Anthropic ​

Claude Code Token ​

OpenRouter ​

OpenAI ​

xAI ​

Opencode ​

Vercel AI Gateway ​

Cloudflare AI Gateway ​

MiniMax ​

Synthetic ​

Moonshot ​

自定义 Provider ​

凭证存储 ​

凭证路径 ​

凭证存储模式 ​

交互式引用模式 ​

非交互式引用模式 ​

Gateway 认证凭证 ​

输出与内部机制 ​

openclaw.json 中的典型字段 ​

Agent 数据 ​

插件渠道 ​

Gateway 向导 RPC ​

Signal 安装行为 ​

相关文档 ​