技术参考

入门向导参考

这是 openclaw onboard CLI 向导的完整技术参考。如需高层次概述，请参阅入门向导。

流程详情（本地模式）

步骤 1：现有配置检测

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

步骤 2：模型/身份验证

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。
- 当模型未设置或为 openai/* 时，将 agents.defaults.model 设置为 openai-codex/gpt-5.2。
OpenAI API 密钥：如果存在则使用 OPENAI_API_KEY，否则提示输入密钥，然后存储在身份验证配置文件中。
xAI（Grok）API 密钥：提示输入 XAI_API_KEY 并将 xAI 配置为模型供应商。
OpenCode Zen（多模型代理）：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取）。
API 密钥：为你存储密钥。
Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
更多详情：Vercel AI Gateway
Cloudflare AI Gateway：提示输入账户 ID、网关 ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。
更多详情：Cloudflare AI Gateway
MiniMax M2.5：配置自动写入。
更多详情：MiniMax
Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
更多详情：Synthetic
Moonshot（Kimi K2）：配置自动写入。
Kimi Coding：配置自动写入。
更多详情：Moonshot AI（Kimi + Kimi Coding）
跳过：暂不配置身份验证。
从检测到的选项中选择一个默认模型（或手动输入供应商/模型）。为了获得最佳质量并降低提示注入风险，请选择你的供应商堆栈中可用的最强最新一代模型。
向导运行模型检查，如果配置的模型未知或缺少身份验证，则会发出警告。
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）。
更多详情：/concepts/oauth

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

步骤 3：工作区

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

步骤 4：网关

端口、绑定、身份验证模式、Tailscale 暴露。
身份验证建议：即使对于环回地址也保持令牌模式，以便本地 WebSocket 客户端必须进行身份验证。
在令牌模式下，交互式入门提供：
- 生成/存储纯文本令牌（默认）
- 使用 SecretRef（可选）
- Quickstart 在入门探测/仪表板引导过程中跨 env、file 和 exec 供应商重用现有的 gateway.auth.token SecretRefs。
- 如果该 SecretRef 已配置但无法解析，入门会提前失败并显示清晰的修复消息，而不是在运行时静默降级身份验证。
在密码模式下，交互式入门也支持纯文本或 SecretRef 存储。
非交互式令牌 SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
- 要求入门进程环境中存在非空的环境变量。
- 不能与 --gateway-token 结合使用。
仅当完全信任每个本地进程时才禁用身份验证。
非环回绑定仍然需要身份验证。

步骤 5：通道

WhatsApp：可选的二维码登录。
Telegram：机器人令牌。
Discord：机器人令牌。
Google Chat：服务账户 JSON + webhook 受众。
Mattermost（插件）：机器人令牌 + 基础 URL。
Signal：可选的 signal-cli 安装 + 账户配置。
BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + webhook。
iMessage：旧版 imsg CLI 路径 + 数据库访问。
私信安全：默认是配对。首次私信发送一个代码；通过 openclaw pairing approve <channel> <code> 批准或使用允许列表。

步骤 6：网络搜索

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

步骤 7：守护进程安装

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

步骤 8：健康检查

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

步骤 9：技能（推荐）

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

步骤 10：完成

摘要 + 后续步骤，包括用于额外功能的 iOS/Android/macOS 应用程序。

ℹ️ 如果未检测到 GUI，向导会打印用于控制 UI 的 SSH 端口转发说明，而不是打开浏览器。如果控制 UI 资源缺失，向导会尝试构建它们；回退方案是 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 获取机器可读的摘要。非交互模式下的网关令牌 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）。

Gemini 示例

Z.AI 示例

Vercel AI Gateway 示例

Cloudflare AI Gateway 示例

Moonshot 示例

Synthetic 示例

OpenCode Zen 示例

添加智能体（非交互式）

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 发布版安装 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 或本地路径）。