引导向导参考

这是 openclaw onboard 的完整参考文档。 高层概述见引导向导（CLI）。

流程详情（本地模式）

步骤一：检测现有配置

• 如果 ~/.openclaw/openclaw.json 存在，选择保留 / 修改 / 重置。
• 重新运行引导不会清除任何内容，除非你明确选择重置（或传入 --reset）。
• CLI --reset 默认为 config+creds+sessions；使用 --reset-scope full 也删除工作区。
• 如果配置无效或包含旧版密钥，向导会停止并要求你在继续之前运行 openclaw doctor。
• 重置使用 trash（从不使用 rm），并提供以下范围：
  • 仅配置
  • 配置 + 凭据 + 会话
  • 完全重置（也删除工作区）

步骤二：模型/认证

• Anthropic API 密钥：如果存在 ANTHROPIC_API_KEY 则使用，否则提示输入，然后为守护进程使用保存。
• Anthropic Claude CLI：在 macOS 上引导检查钥匙串项"Claude Code-credentials"（选择"始终允许"以便 launchd 启动不被阻塞）；在 Linux/Windows 上如果存在 ~/.claude/.credentials.json 则重用，并将模型选择切换为 claude-cli/...。
• Anthropic 令牌（粘贴 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 密钥：如果存在 OPENAI_API_KEY 则使用，否则提示输入，然后存储在认证配置文件中。
• xAI（Grok）API 密钥：提示输入 XAI_API_KEY 并将 xAI 配置为模型提供商。
• OpenCode：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取）并让你选择 Zen 或 Go 目录。
• Ollama：提示输入 Ollama 基础 URL，提供云端 + 本地或仅本地模式，发现可用模型，并在需要时自动拉取所选本地模型。
  • 更多详情：Ollama
• API 密钥：为你存储密钥。
• Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
  • 更多详情：Vercel AI Gateway
• Cloudflare AI Gateway：提示输入账户 ID、Gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。
  • 更多详情：Cloudflare AI Gateway
• MiniMax：自动写入配置；托管默认为 MiniMax-M2.7，MiniMax-M2.5 仍然可用。
  • 更多详情：MiniMax
• Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
  • 更多详情：Synthetic
• Moonshot（Kimi K2）：自动写入配置。
• Kimi Coding：自动写入配置。
  • 更多详情：Moonshot AI（Kimi + Kimi Coding）
• 跳过：暂不配置认证。
• 从检测到的选项中选择默认模型（或手动输入 provider/model）。为获得最佳质量和更低的提示词注入风险，选择你的提供商栈中可用的最强最新一代模型。
• 引导运行模型检查，如果配置的模型未知或缺少认证则发出警告。
• API 密钥存储模式默认为明文认证配置文件值。使用 --secret-input-mode ref 改为存储环境变量支持的引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
• OAuth 凭据存储在 ~/.openclaw/credentials/oauth.json；认证配置文件存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API 密钥 + OAuth）。
• 更多详情：/openclaw/concepts/oauth

无头/服务器提示：在有浏览器的机器上完成 OAuth，然后将 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json）复制到网关主机。

步骤三：工作区

• 默认 ~/.openclaw/workspace（可配置）。
• 播种代理启动仪式所需的工作区文件。
• 完整工作区布局 + 备份指南：代理工作区

步骤四：Gateway

• 端口、绑定、认证模式、tailscale 暴露。
• 认证建议：即使是回环也保持令牌模式，以便本地 WS 客户端必须进行认证。
• 在令牌模式下，交互式设置提供：
  • 生成/存储明文令牌（默认）
  • 使用 SecretRef（可选）
  • 快速启动在引导探测/控制面板引导中跨 env、file 和 exec 提供商重用现有的 gateway.auth.token SecretRef。
  • 如果该 SecretRef 已配置但无法解析，引导会提前失败并给出清晰的修复消息，而不是在运行时静默降级认证。
• 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
• 非交互式令牌 SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
  • 在引导过程环境中需要一个非空的环境变量。
  • 不能与 --gateway-token 组合使用。
• 仅当你完全信任每个本地进程时才禁用认证。
• 非回环绑定仍然需要认证。

步骤五：渠道

• WhatsApp：可选 QR 登录。
• Telegram：机器人令牌。
• Discord：机器人令牌。
• Google Chat：服务账户 JSON + webhook audience。
• Mattermost（插件）：机器人令牌 + 基础 URL。
• Signal：可选 signal-cli 安装 + 账户配置。
• BlueBubbles：iMessage 推荐方案；服务器 URL + 密码 + webhook。
• iMessage：旧版 imsg CLI 路径 + 数据库访问。
• DM 安全：默认为配对模式。首次 DM 发送一个代码；通过 openclaw pairing approve <channel> <code> 批准，或使用白名单。

步骤六：网页搜索

• 选择提供商：Perplexity、Brave、Gemini、Grok 或 Kimi（或跳过）。
• 粘贴你的 API 密钥（快速启动从环境变量或现有配置自动检测密钥）。
• 使用 --skip-search 跳过。
• 稍后配置：openclaw configure --section web。

步骤七：守护进程安装

• macOS：LaunchAgent
  • 需要已登录的用户会话；对于无头，使用自定义 LaunchDaemon（未附带）。
• Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
  • 引导尝试通过 loginctl enable-linger <user> 启用驻留，以便 Gateway 在注销后保持运行。
  • 可能提示 sudo（写入 /var/lib/systemd/linger）；首先不用 sudo 尝试。
• 运行时选择： Node（推荐；WhatsApp/Telegram 必需）。Bun 不推荐。
• 如果令牌认证需要令牌且 gateway.auth.token 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文令牌值持久化到监督程序服务环境元数据中。
• 如果令牌认证需要令牌且配置的令牌 SecretRef 未解析，守护进程安装会被阻止，并给出可操作的指导。
• 如果同时配置了 gateway.auth.token 和 gateway.auth.password 且 gateway.auth.mode 未设置，守护进程安装会被阻止，直到显式设置模式。

步骤八：健康检查

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

步骤九：Skills（推荐）

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

步骤十：完成

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

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

非交互式模式

使用 --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 获取机器可读的摘要。

非交互式模式下的 Gateway 令牌 SecretRef：

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

--gateway-token 和 --gateway-token-ref-env 互斥。

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

特定提供商的命令示例见 CLI 自动化。 本参考页面用于标志语义和步骤顺序。

非交互式添加代理

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）
• tools.profile（本地引导在未设置时默认为 "coding"；现有明确值会保留）
• gateway.*（模式、绑定、认证、tailscale）
• session.dmScope（行为详情：CLI 设置参考）
• 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 或本地路径）才能进行配置。

养龙虾技巧：用 --non-interactive 配合环境变量，一行命令就能把龙虾部署到新机器上，省去大量交互操作。

相关文档

• 引导概述：引导向导（CLI）
• macOS 应用引导：引导向导
• 配置参考：Gateway 配置
• 提供商：WhatsApp、Telegram、Discord、Google Chat、Signal、BlueBubbles（iMessage）、iMessage（旧版）
• Skills：Skills、Skills 配置