Onboarding（CLI）

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。

提示： CLI onboarding 包含一个网络搜索配置步骤，你可以选择提供商（Perplexity、Brave、Gemini、Grok 或 Kimi）并粘贴 API Key，让 agent 具备 web_search 能力。也可以之后通过 openclaw configure --section web 配置。文档：Web 工具。

QuickStart vs Advanced

Onboarding 开始时会让你选择 QuickStart（使用默认值）或 Advanced（完全控制）。

QuickStart（默认值）

• 本地 gateway（loopback）
• 默认工作区（或使用已有工作区）
• Gateway 端口：18789
• Gateway 认证：Token（自动生成，即使在 loopback 上也会生成）
• 工具策略默认值（新建本地设置）：tools.profile: "coding"（已有显式配置时保留）
• DM 隔离默认值：本地 onboarding 在未设置时写入 session.dmScope: "per-channel-peer"。详情参见 CLI Setup Reference
• Tailscale 暴露：关闭
• Telegram + WhatsApp DM 默认使用许可名单（会提示你输入手机号）

Advanced（完全控制）

暴露每一个配置步骤（模式、工作区、gateway、频道、守护进程、skills）。

Onboarding 配置内容

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

1. 模型/认证 — 选择任何支持的提供商/认证流程（API Key、OAuth 或 setup-token），包括自定义提供商（OpenAI 兼容、Anthropic 兼容或未知自动检测）。选择默认模型。 安全提示：如果这个 agent 会执行工具或处理 webhook/hooks 内容，请优先选用最强的最新一代模型，并保持工具策略严格。较弱/较旧的模型更容易被提示注入攻击。 非交互式运行时，--secret-input-mode ref 会在认证配置中存储环境变量引用而非明文 API Key。 非交互式 ref 模式下，提供商环境变量必须已设置；在该环境变量未设置的情况下直接传递内联 Key 标志会快速失败。 交互式运行中，选择 secret reference 模式后可以指向环境变量或配置好的提供商引用（file 或 exec），并在保存前进行快速预检验证。
2. 工作区 — agent 文件的存放位置（默认 ~/.openclaw/workspace），会生成引导所需的初始文件。
3. Gateway — 端口、绑定地址、认证模式、Tailscale 暴露。 交互式 token 模式下，可选择默认明文 token 存储或使用 SecretRef。 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
4. 频道 — WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。
5. 守护进程 — 安装 LaunchAgent（macOS）或 systemd 用户单元（Linux/WSL2）。 如果 token 认证需要 token 且 gateway.auth.token 由 SecretRef 管理，守护进程安装会验证 token 但不将解析后的 token 持久化到 supervisor 服务环境元数据中。 如果配置的 token SecretRef 无法解析，守护进程安装会被阻止并提供可操作的指导。 如果同时配置了 gateway.auth.token 和 gateway.auth.password 但 gateway.auth.mode 未设置，守护进程安装会被阻止，直到显式设置 mode。
6. 健康检查 — 启动 Gateway 并验证其正在运行。
7. Skills — 安装推荐 skills 和可选依赖。

注意： 重新运行 onboarding 不会清除任何内容，除非你明确选择 Reset（或传入 --reset）。 CLI --reset 默认范围为配置、凭证和会话；用 --reset-scope full 也包含工作区。 如果配置无效或包含过期 key，onboarding 会要求你先运行 openclaw doctor。

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

添加另一个 Agent

使用 openclaw agents add <name> 创建一个有独立工作区、会话和认证配置的 agent。不带 --workspace 运行时会启动 onboarding 引导。

设置内容：

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

注意事项：

• 默认工作区遵循 ~/.openclaw/workspace-<agentId> 格式。
• 添加 bindings 以路由入站消息（onboarding 可以完成这一步）。
• 非交互式标志：--model、--agent-dir、--bind、--non-interactive。

完整参考

详细的分步说明和配置输出，参见 CLI Setup Reference。 非交互式示例，参见 CLI Automation。 更深层的技术参考，包括 RPC 详情，参见 Onboarding Reference。

相关文档

• CLI 命令参考：openclaw onboard
• Onboarding 概述：Onboarding Overview
• macOS App Onboarding：Onboarding
• Agent 首次运行仪式：Agent Bootstrapping