OpenClaw 引导向导（openclaw onboard）完全指南：一站式配置 Gateway、模型认证、频道与技能

导读

openclaw onboard 是 OpenClaw 官方推荐的 CLI 引导向导，面向 macOS、Linux 与 Windows（经 WSL2，强烈建议）用户，在一次交互式流程中完成本地 Gateway（或远程 Gateway 连接）、模型认证、频道接入、工作区、守护进程与技能的初始化配置。本文以仓库文档 docs/start/wizard.md 为主线，结合 docs/start/wizard-cli-reference.md、docs/start/wizard-cli-automation.md 与 commands/onboard*.ts 源码实现，带你完整掌握交互式快速上手、Advanced 全量配置、非交互式脚本自动化、SecretRef 密钥引用模式，以及向导最终写入了哪些配置字段。读完本文，你可以在新机器上几分钟内完成 OpenClaw 环境初始化，并能用 --non-interactive 把同样的流程固化进 CI 或部署脚本。

快速开始：openclaw onboard

在终端直接运行即可启动向导：

openclaw onboard

最快的首次聊天路径：如果只想立刻与 Agent 对话，可以不配置任何频道——直接运行 openclaw dashboard，在浏览器中打开 Control UI 聊天（详见 docs/web/dashboard.md）。

向导完成后需要调整配置时，使用：

openclaw configure          # 重新进入配置流程
openclaw agents add <name>  # 追加新的 Agent

几个需要提前明确的约定：

• --json 不代表非交互模式：--json 只影响输出格式，脚本自动化必须显式加 --non-interactive。
• 向导内置 Web 搜索步骤：可在此步选择搜索提供商（Perplexity、Brave、Gemini、Grok 或 Kimi）并粘贴 API Key，让 Agent 获得 web_search 能力；也可以稍后用 openclaw configure --section web 补配（详见 docs/tools/web.md）。
• 再次运行不会抹掉任何东西：除非你显式选择 Reset 或传入 --reset。

从源码看，openclaw onboard 的入口是 commands/onboard.ts 中的 setupWizardCommand（第 20-102 行）：它先做运行时检查与旧版 auth-choice 兼容归一化，校验 --secret-input-mode（只允许 plaintext 或 ref）与 --reset-scope（只允许 config、config+creds+sessions、full），随后根据 --non-interactive 分流到 runNonInteractiveSetup 或 runInteractiveSetup。值得注意的约束：非交互模式必须显式传入 --accept-risk 才会继续，否则直接报错退出（commands/onboard.ts 第 64-74 行）。

QuickStart 与 Advanced 两种流程

向导开局会询问选择 QuickStart（默认值） 还是 Advanced（完全控制）：

维度	QuickStart（默认值）	Advanced（完全控制）
Gateway	本地 Gateway（loopback）	暴露每一个步骤（模式、工作区、Gateway、频道、守护进程、技能）
工作区	使用默认工作区（或已有工作区）	可自定义
Gateway 端口	18789	可改
Gateway 认证	Token（自动生成，即使 loopback 也启用）	可改
工具策略	本地新装默认 tools.profile: "coding"（已有显式配置则保留）	可改
DM 隔离	本地引导在未设置时写入 session.dmScope: "per-channel-peer"（详见 docs/start/wizard-cli-reference.md）	可改
Tailscale 暴露	Off	可改
私聊安全	Telegram 与 WhatsApp 私聊默认走 allowlist（会提示输入你的手机号）	可改

这两个默认值在源码中有直接对应：commands/onboard-config.ts 定义了 ONBOARDING_DEFAULT_DM_SCOPE = "per-channel-peer" 与 ONBOARDING_DEFAULT_TOOLS_PROFILE = "coding"（第 5-6 行），applyLocalSetupWorkspaceConfig 在配置未设置这些字段时才写入默认值、已有值则原样保留（第 8-34 行）。

向导到底配置了什么：本地模式的 7 个步骤

本地模式（默认）会依次带你走完以下步骤：

1. Model/Auth（模型与认证）

选择任意受支持的提供商与认证方式：API Key、OAuth、或 setup-token，包括 Custom Provider（OpenAI 兼容、Anthropic 兼容、或 Unknown 自动探测），然后挑选默认模型。

安全提示（原文强调）：如果该 Agent 会运行工具或处理 webhook/hooks 内容，建议选择当前最强的最新代模型，并保持工具策略严格——较弱/较旧档次的模型更容易被提示注入（prompt-inject）。

密钥存储方面：

• 非交互运行加 --secret-input-mode ref 会在认证配置文件中写入环境变量引用（env-backed refs），而不是明文 API Key 值。
• 非交互 ref 模式下，提供商环境变量必须已设置；如果只传内联 key 参数而未设置对应环境变量，会快速失败（fail fast）。
• 交互式运行选择密钥引用模式时，可以指向环境变量或已配置的 provider ref（file 或 exec），保存前会做一次快速 preflight 校验。

2. Workspace（工作区）

指定 Agent 文件存放位置，默认 ~/.openclaw/workspace，并播种（seed）首次运行所需的自举文件（如 AGENTS.md、SOUL.md、USER.md 等，布局说明见 docs/concepts/agent-workspace.md）。源码中 ensureWorkspaceAndSessions（commands/onboard-helpers.ts 第 170-183 行）负责创建工作区与 sessions 目录并打印确认。

3. Gateway（网关）

配置端口、绑定地址、认证模式与 Tailscale 暴露方式：

• 交互式 Token 模式中，可选择默认的明文 Token 存储，或选择进入 SecretRef。
• 非交互 Token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。

源码中的安全收紧逻辑值得关注（commands/onboard-non-interactive/local/gateway-config.ts 第 43-51 行）：

• 开启 Tailscale 时强制 loopback 绑定（外部访问由隧道负责）；
• 使用 Tailscale Funnel 时强制要求密码认证。
• 在 Token 模式下，未提供 token 时由 randomToken() 自动生成 24 字节随机 hex（commands/onboard-helpers.ts 第 75-77 行），即使 loopback 也保持认证，保证本地 WS 客户端必须通过身份校验。

4. Channels（频道）

支持接入的频道与各自的配置要点：

• 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 路径 + DB 访问。

DM 安全默认策略是 pairing（配对）：首个 DM 会发送一个配对码，通过 openclaw pairing approve <channel> <code> 批准，或改用 allowlists。

另外注意：部分频道以插件形式交付（如 Slack、Discord、Matrix、Microsoft Teams 的 allowlist 配置），向导选中时会先提示安装插件（npm 或本地路径）再进入频道配置。

5. Daemon（守护进程安装）

• macOS：安装 LaunchAgent（需要已登录的用户会话；无头环境请使用自定义 LaunchDaemon，向导不附带）。
• Linux / Windows（WSL2）：安装 systemd 用户单元。向导会尝试 loginctl enable-linger <user>（先免 sudo 尝试，必要时提示 sudo 写入 /var/lib/systemd/linger），确保注销后 Gateway 仍然存活。
• 运行时选择：Node（推荐，WhatsApp 和 Telegram 必需）；Bun 不推荐（源码 commands/daemon-runtime.ts 定义 DEFAULT_GATEWAY_DAEMON_RUNTIME = "node"）。

Token 认证相关的守护进程安装约束（原文档明确）：

• 若 token 由 SecretRef 管理，daemon 安装会校验它但不会把解析出的明文 token 持久化到 supervisor 服务环境元数据中；
• 若配置的 token SecretRef 无法解析，daemon 安装会被阻止并给出可操作的指引；
• 若同时配置了 gateway.auth.token 与 gateway.auth.password 而 gateway.auth.mode 未设置，daemon 安装会被阻止，直到显式设置 mode。

源码对应：installGatewayDaemonNonInteractive（commands/onboard-non-interactive/local/daemon-install.ts 第 11-87 行）会先探测 Linux 下 systemd 用户服务是否可用，不可用时以 skippedReason: "systemd-user-unavailable" 跳过并提示改用 openclaw gateway run 直接前台运行。

6. Health check（健康检查）

启动 Gateway（如需要）并运行 openclaw health 验证其可用；openclaw status --deep 会在 status 输出中加入 Gateway 健康探测。源码中 waitForGatewayReachable 以轮询方式调用 Gateway health 探针（commands/onboard-helpers.ts 第 249-281 行），安装 daemon 时健康检查总超时为 45 秒，仅连接已有 Gateway 时为 15 秒。

7. Skills（技能）

读取可用技能并检查依赖：可选择节点管理器 npm 或 pnpm（bun 不推荐），并安装可选依赖（部分技能在 macOS 上依赖 Homebrew）。源码 commands/onboard-skills.ts 会检测所选技能是否需要 brew 依赖（缺失时提示安装命令）或 node 依赖（缺失时询问首选 node manager），并把选择写入 skills.install.nodeManager。

Reset 语义（重要）

• 重复运行向导不会清空任何数据，除非显式选择 Reset（或传 --reset）。
• CLI --reset 默认清理范围是 config + creds + sessions；需要连同工作区一起清理时用 --reset-scope full。
• 如果现有配置无效或包含旧版遗留 key，向导会停止并提示你先运行 openclaw doctor 修复。
• Reset 使用 trash（移入回收站而非直接删除），可选范围：仅 config / config+creds+sessions / full（含工作区）。
• 源码对应 handleReset（commands/onboard-helpers.ts 第 213-223 行），按 scope 依次把配置文件、凭据目录、会话目录乃至工作区移入回收站。

远程模式（Remote mode）

远程模式只把本机配置成连接“别处”的 Gateway，不会在远程主机上安装或修改任何东西。你只需要设置：

• 远程 Gateway URL（ws://...）；
• 若远程 Gateway 要求认证，提供 Token（推荐）。

注意：如果远程 Gateway 只监听 loopback，需要 SSH 隧道或 tailnet；本机可用 Bonjour（macOS，dns-sd）或 Avahi（Linux，avahi-browse）做服务发现。非交互远程模式的实现见 commands/onboard-non-interactive/remote.ts，它只写 gateway.mode: "remote"、gateway.remote.url 与可选 token（第 24-37 行）。

模型认证选项速查：Auth and model options

向导提供的认证选项覆盖主流提供商与网关（以下均来自 docs/start/wizard-cli-reference.md）：

选项	认证方式与要点
Anthropic API key	使用已有 ANTHROPIC_API_KEY 或提示输入，保存供 daemon 使用
Anthropic OAuth（Claude Code CLI）	macOS 检查 Keychain 项 Claude Code-credentials；Linux/Windows 复用 ~/.claude/.credentials.json（macOS 选择 "Always Allow" 以免 launchd 启动被阻塞）
Anthropic token（setup-token 粘贴）	任意机器上运行 claude setup-token 后粘贴 token，可命名（留空用默认）
OpenAI Code subscription（复用 Codex CLI）	若存在 ~/.codex/auth.json 可直接复用
OpenAI Code subscription（OAuth）	浏览器流程，粘贴 code#state；模型未设置或为 openai/* 时写入 agents.defaults.model = openai-codex/gpt-5.4
OpenAI API key	使用 OPENAI_API_KEY 或提示输入，存入认证配置文件；模型未设置/为 openai/*/openai-codex/* 时写入 openai/gpt-5.1-codex
xAI（Grok）API key	提示输入 XAI_API_KEY 并配置 xAI 为模型提供商
OpenCode Zen	提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）
API key（通用）	直接为你保存 key
Vercel AI Gateway	提示输入 AI_GATEWAY_API_KEY
Cloudflare AI Gateway	提示输入 account ID、gateway ID 与 CLOUDFLARE_AI_GATEWAY_API_KEY
MiniMax M2.5	配置自动写入
Synthetic（Anthropic 兼容）	提示输入 SYNTHETIC_API_KEY
Moonshot 与 Kimi Coding	Moonshot（Kimi K2）与 Kimi Coding 配置自动写入
Custom provider	兼容 OpenAI / Anthropic 端点；交互式支持与 API Key 相同的两种存储选择（粘贴明文 / 密钥引用 + preflight 校验）
Skip	不配置任何认证

Custom Provider 非交互参数（源码类型定义见 commands/onboard-types.ts）：

--auth-choice custom-api-key
--custom-base-url <url>
--custom-model-id <id>
--custom-api-key <key>        # 可选，缺省时回退到 CUSTOM_API_KEY
--custom-provider-id <id>     # 可选
--custom-compatibility openai|anthropic   # 可选，默认 openai

模型行为：从检测到的候选中挑选默认模型，或手动输入 provider 与模型；向导会运行一次模型检查，若配置的模型未知或缺少认证会给出警告。凭据路径：

• OAuth 凭据：~/.openclaw/credentials/oauth.json
• 认证配置文件（API Key + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

无头/服务器小贴士：在带浏览器的机器上完成 OAuth，然后把 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json）复制到 Gateway 主机即可。

凭据存储模式：plaintext 与 SecretRef（ref）

默认引导行为是把 API Key 以明文写入认证配置文件。使用 --secret-input-mode ref 切换为引用模式：

• 交互式引导中可选择两种引用：
  • 环境变量引用，例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }；
  • 已配置的 provider ref（file 或 exec），提供 provider 别名 + id。
• 交互式引用模式保存前会执行快速 preflight 校验：env ref 校验变量名与当前环境中的非空值；provider ref 校验 provider 配置并解析请求的 id。校验失败会显示错误并允许重试。
• 非交互模式下的 --secret-input-mode ref 仅支持环境变量引用：提供商环境变量必须在引导进程环境中设置；内联 key 参数（如 --openai-api-key）在对应环境变量未设置时快速失败。
• Custom Provider 在非交互 ref 模式下写入 models.providers.<id>.apiKey = { source: "env", provider: "default", id: "CUSTOM_API_KEY" }，此时 --custom-api-key 要求 CUSTOM_API_KEY 已设置，否则快速失败。
• Gateway 认证凭据同样支持两种选择：Token 模式默认“生成/存储明文 token”，也可选 SecretRef；Password 模式同样支持明文或 SecretRef。
• 已有的明文配置不受影响，继续正常工作。

脚本化与 CI：非交互模式 --non-interactive

用 --non-interactive 自动化 openclaw onboard。再次强调：--json 不等于非交互，脚本请用 --non-interactive（并配 --workspace）；非交互模式还必须加 --accept-risk。

基线示例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --secret-input-mode plaintext \
  --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

# Cloudflare AI Gateway
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_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

# Mistral
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_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

Custom Provider 非交互与 ref 变体

# 明文模式
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --custom-provider-id "my-custom" \
  --custom-compatibility anthropic \
  --gateway-port 18789 \
  --gateway-bind loopback

# ref 模式（env 引用）
export CUSTOM_API_KEY="your-key"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --secret-input-mode ref \
  --custom-provider-id "my-custom" \
  --custom-compatibility anthropic \
  --gateway-port 18789 \
  --gateway-bind loopback

ref 模式下 onboarding 会把 apiKey 存为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。--custom-api-key 是可选的：缺省时引导流程自动检查 CUSTOM_API_KEY 环境变量。

非交互 Gateway Token 选项

• --gateway-auth token --gateway-token <token>：存储明文 token；
• --gateway-auth token --gateway-token-ref-env <name>：把 gateway.auth.token 存为 env SecretRef；
• 两者互斥，不能同时使用；--gateway-token-ref-env 要求引导进程环境中存在非空的环境变量；
• 示例：

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 \
  --accept-risk

Z.AI 端点说明：--auth-choice zai-api-key 现在会根据 key 自动探测最佳 Z.AI 端点（优先通用 API 的 zai/glm-5）；若你明确想要 GLM Coding Plan 端点，请选择 zai-coding-global 或 zai-coding-cn，此外还有 zai-global、zai-cn 可选。

明文内网 ws:// 提示：对可信内网的明文 ws:// 目标，需要在引导进程环境中设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1。

从源码看，非交互模式还会做一次 auth-choice 推断：inferAuthChoiceFromFlags（commands/onboard-non-interactive/local/auth-choice-inference.ts 第 21-54 行）扫描传入的提供商 key 参数；如果同时传了多个提供商 flag 且未显式 --auth-choice，会直接报错提示只用一个提供商 flag 或显式指定 auth-choice，避免歧义。

添加另一个 Agent：openclaw agents add

openclaw agents add <name> 创建拥有独立工作区、会话与认证配置文件的独立 Agent。不带 --workspace 运行时，会启动向导。

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

它会写入：

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

注意：

• 默认工作区遵循 ~/.openclaw/workspace-<agentId>；
• 可通过 bindings 为入站消息配置路由（向导可以代做）；
• 非交互可用参数：--model、--agent-dir、--bind、--non-interactive。

向导的输出与内部实现（Outputs and internals）

引导完成后，~/.openclaw/openclaw.json 中典型的写入字段包括：

• agents.defaults.workspace
• agents.defaults.model / models.providers（如选择 MiniMax）
• tools.profile（本地引导在未设置时默认 "coding"，已有显式值保留）
• gateway.*（mode、bind、auth、tailscale）
• session.dmScope（本地引导在未设置时默认 per-channel-peer，已有显式值保留）
• channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
• 频道 allowlists（Slack、Discord、Matrix、Microsoft Teams，选择加入时写入，名称尽量解析为 ID）
• skills.install.nodeManager
• wizard.lastRunAt、wizard.lastRunVersion、wizard.lastRunCommit、wizard.lastRunCommand、wizard.lastRunMode

其中 wizard.lastRun* 元数据由 applyWizardMetadata 写入（commands/onboard-helpers.ts 第 119-135 行），记录运行时间、版本、GIT commit、命令与模式，便于追踪配置来源。其他数据落盘位置：WhatsApp 凭据在 ~/.openclaw/credentials/whatsapp/<accountId>/，会话在 ~/.openclaw/agents/<agentId>/sessions/。

Gateway wizard RPC：向导逻辑通过一组 RPC 方法暴露给客户端（macOS App 与 Control UI 可直接渲染各步骤，而无需重新实现引导逻辑）：

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Signal 设置行为：向导会自动下载对应版本的发布资产，存放于 ~/.openclaw/tools/signal-cli/<version>/，并把 channels.signal.cliPath 写入配置；JVM 构建要求 Java 21，原生构建优先使用；Windows 走 WSL2，在 WSL 内按 Linux 流程执行 signal-cli。

无 GUI 环境的处理：检测不到 GUI 时，向导会打印 Control UI 的 SSH 端口转发指引（ssh -N -L <port>:127.0.0.1:<port> <user>@<host>）而不是打开浏览器；若 Control UI 资源缺失，向导会尝试构建，回退方案是 pnpm ui:build（自动安装 UI 依赖）。

进一步阅读

• 完整的分步参考、auth 选项矩阵与输出字段： docs/start/wizard-cli-reference.md
• 脚本自动化与各提供商非交互示例： docs/start/wizard-cli-automation.md
• openclaw onboard 命令参考与流程说明： docs/cli/onboard.md
• 多路径选择总览（CLI 向导 vs macOS App）： docs/start/onboarding-overview.md
• macOS App 引导： docs/start/onboarding.md
• Agent 首次运行仪式与工作区自举： docs/start/bootstrapping.md