Onboarding 向导（CLI）

Onboarding 向导是在 macOS、Linux 或 Windows（通过 WSL2，强烈推荐）上配置 OpenClaw 的推荐方式。它在一个引导流程中完成本地 Gateway 或远程 Gateway 连接的配置，同时搞定消息渠道、Skills 和工作区默认值。

openclaw onboard

提示： 最快的聊天方式：打开 Control UI（不需要配置任何渠道）。运行 openclaw dashboard 即可在浏览器中聊天。文档：Dashboard。

后续要重新配置：

openclaw configure
openclaw agents add <name>

注意： --json 并不意味着非交互模式。脚本中请使用 --non-interactive。

提示： Onboarding 向导包含一个网页搜索配置步骤，你可以选择一个搜索供应商（Perplexity、Brave、Gemini、Grok 或 Kimi）并粘贴 API key，这样 Agent 就可以使用 web_search。也可以之后通过 openclaw configure --section web 来配置。文档：Web 工具。

QuickStart vs Advanced

向导一开始会让你选择 QuickStart（使用默认值）还是 Advanced（完全掌控每个细节）。

QuickStart（默认配置）

- 本地 Gateway（回环地址）
- 默认工作区（或已有工作区）
- Gateway 端口 **18789**
- Gateway 认证使用 **Token**（自动生成，即使在回环地址上也是如此）
- 新本地安装的工具策略默认为 `tools.profile: "coding"`（已有的显式配置会保留）
- DM 隔离默认值：本地 onboarding 在未设置时会写入 `session.dmScope: "per-channel-peer"`。详情：[CLI Onboarding 参考](/docs/start/wizard-cli-reference#outputs-and-internals)
- Tailscale 暴露 **关闭**
- Telegram + WhatsApp DM 默认为**白名单**模式（会提示你输入手机号）

Advanced（完全掌控）

- 展示每个配置步骤（模式、工作区、Gateway、渠道、守护进程、Skills）。

向导配置了什么

本地模式（默认） 会引导你完成以下步骤：

模型和认证 — 选择任意受支持的供应商和认证方式（API key、OAuth 或 setup-token），包括自定义供应商（OpenAI 兼容、Anthropic 兼容或 Unknown 自动检测）。选择默认模型。安全提示：如果这个 Agent 需要运行工具或处理 webhook/hooks 内容，请优先使用最新一代的最强模型，并保持严格的工具策略。较弱或较旧的模型更容易被 prompt 注入。在非交互模式下，--secret-input-mode ref 会在认证 profile 中存储基于环境变量的引用，而不是明文 API key。在非交互 ref 模式下，供应商环境变量必须已设置；在没有该环境变量的情况下传入内联 key 参数会直接报错。在交互模式下，选择密钥引用模式后可以指向环境变量或已配置的 provider ref（file 或 exec），保存前会进行快速预检验证。
工作区 — Agent 文件的存放位置（默认 ~/.openclaw/workspace）。生成引导文件。
Gateway — 端口、绑定地址、认证模式、Tailscale 暴露。在交互式 token 模式下，可选择默认明文 token 存储或改用 SecretRef。非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
消息渠道 — WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。
守护进程 — 安装 LaunchAgent（macOS）或 systemd 用户单元（Linux/WSL2）。如果 token 认证需要 token 且 gateway.auth.token 是 SecretRef 管理的，守护进程安装会验证但不会把解析后的 token 持久化到 supervisor 服务环境元数据中。如果 token 认证需要 token 且配置的 token SecretRef 无法解析，守护进程安装会被阻止并给出操作指引。如果同时配置了 gateway.auth.token 和 gateway.auth.password 但 gateway.auth.mode 未设置，守护进程安装会被阻止直到显式设置 mode。
健康检查 — 启动 Gateway 并验证其运行状态。
Skills — 安装推荐的 Skills 和可选依赖。

注意： 重新运行向导不会清除任何内容，除非你明确选择 Reset（或传入 --reset）。 CLI --reset 默认清除配置、凭据和会话；使用 --reset-scope full 可以同时清除工作区。如果配置无效或包含旧版字段，向导会要求你先运行 openclaw doctor。

远程模式只配置本地客户端连接到其他位置的 Gateway。它不会在远程主机上安装或修改任何内容。

添加新 Agent

使用 openclaw agents add <name> 创建一个独立的 Agent，拥有自己的工作区、会话和认证 profile。不加 --workspace 参数会启动向导。

它设置的字段：

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

说明：

默认工作区路径为 ~/.openclaw/workspace-<agentId>。
添加 bindings 来路由入站消息（向导可以帮你完成）。
非交互模式参数：--model、--agent-dir、--bind、--non-interactive。

完整参考

各步骤的详细分解和配置输出请参阅 CLI Onboarding 参考。非交互模式示例请参阅 CLI 自动化。更深层的技术参考（包括 RPC 细节）请参阅向导参考。