入门向导（CLI）

入门向导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐方式。 它在一个引导流程中配置本地 Gateway 或远程 Gateway 连接，加上频道、技能和工作区默认值。

openclaw onboard
最快的第一次聊天：打开 Control UI（无需设置频道）。运行 `openclaw dashboard` 并在浏览器中聊天。文档：[Dashboard](/zh/docs/web/dashboard)。

稍后重新配置：

openclaw configure
openclaw agents add <name>
`--json` 并不意味着非交互模式。对于脚本，使用 `--non-interactive`。 推荐：设置 Brave Search API 密钥，以便代理可以使用 `web_search` （`web_fetch` 无需密钥即可工作）。最简单的方式：`openclaw configure --section web` 它会存储 `tools.web.search.apiKey`。文档：[Web 工具](/zh/docs/tools/web)。

快速开始 vs 高级

向导从快速开始（默认） vs 高级（完全控制）开始。

- 本地 gateway（环回） - 工作区默认（或现有工作区） - Gateway 端口 **18789** - Gateway 认证 **Token**（自动生成，即使在环回上） - DM 隔离默认：本地 onboarding 在未设置时写入 `session.dmScope: "per-channel-peer"`。详情：[CLI 入门参考](/zh/docs/start/wizard-cli-reference#outputs-and-internals) - Tailscale 暴露 **关闭** - Telegram + WhatsApp DM 默认**允许列表**（系统会提示你输入电话号码） - 暴露每个步骤（模式、工作区、gateway、频道、守护进程、技能）

向导配置的内容

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

  1. 模型/认证 - Anthropic API 密钥（推荐）、OpenAI 或自定义 Provider （OpenAI 兼容、Anthropic 兼容或未知自动检测）。选择默认模型。 对于非交互式运行，--secret-input-mode ref 在 auth profiles 中存储环境支持的引用，而不是明文 API 密钥值。 在非交互式 ref 模式下，必须设置 provider 环境变量；传递内联密钥标志而没有该环境变量会快速失败。 在交互式运行中，选择秘密引用模式让你指向环境变量或配置的 provider 引用（file 或 exec），并在保存前进行快速预检验证。
  2. 工作区 - 代理文件的位置（默认 ~/.openclaw/workspace）。种子引导文件。
  3. Gateway - 端口、绑定地址、认证模式、Tailscale 暴露。
  4. 频道 - WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。
  5. 守护进程 - 安装 LaunchAgent（macOS）或 systemd 用户单元（Linux/WSL2）。
  6. 健康检查 - 启动 Gateway 并验证它正在运行。
  7. 技能 - 安装推荐的技能和可选依赖项。
重新运行向导**不会**清除任何东西，除非你明确选择**重置**（或传递 `--reset`）。 CLI `--reset` 默认为配置、凭证和会话；使用 `--reset-scope full` 以包含工作区。 如果配置无效或包含旧密钥，向导会要求你首先运行 `openclaw doctor`。

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

添加另一个代理

使用 openclaw agents add <name> 创建具有自己工作区、会话和 auth profiles 的单独代理。 不带 --workspace 运行会启动向导。

它设置的内容：

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

注意：

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

完整参考

有关详细步骤分解、非交互式脚本、Signal 设置、RPC API 以及向导写入的配置字段的完整列表，请参阅向导参考。

相关文档