OpenClaw 🦞

CLI 引导参考

CLI 引导参考

本页是 openclaw onboard 的完整参考。 简要指南请参阅 引导向导 (CLI)。

向导的作用

本地模式（默认）引导您完成：

  • 模型和认证设置（OpenAI Code 订阅 OAuth、Anthropic API 密钥或设置令牌，以及 MiniMax、GLM、Moonshot 和 AI Gateway 选项）
  • 工作区位置和引导文件
  • 网关设置（端口、绑定、认证、tailscale）
  • 频道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal）
  • 守护进程安装（LaunchAgent 或 systemd 用户单元）
  • 健康检查
  • 技能设置

远程模式配置此机器以连接到其他地方的网关。 它不会在远程主机上安装或修改任何内容。

本地流程详情

1

现有配置检测

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

模型和认证

3

工作区

  • 默认 ~/.openclaw/workspace（可配置）。
  • 种子首次运行引导仪式所需的工作区文件。
  • 工作区布局：代理工作区。
4

网关

  • 提示输入端口、绑定、认证模式和 tailscale 暴露。
  • 推荐：即使对于环回也保持令牌认证启用，以便本地 WS 客户端必须进行认证。
  • 仅在您完全信任每个本地进程时禁用认证。
  • 非环回绑定仍然需要认证。
5

频道

  • WhatsApp：可选 QR 登录
  • Telegram：机器人令牌
  • Discord：机器人令牌
  • Google Chat：服务账户 JSON + webhook 受众
  • Mattermost 插件：机器人令牌 + 基础 URL
  • Signal：可选 signal-cli 安装 + 账户配置
  • BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + webhook
  • iMessage：遗留 imsg CLI 路径 + DB 访问
  • DM 安全：默认为配对。首次 DM 发送代码；通过 openclaw pairing approve <channel> <code> 批准或使用允许列表。
6

守护进程安装

  • macOS：LaunchAgent
    • 需要登录用户会话；对于无头模式，使用自定义 LaunchDaemon（未提供）。
  • Linux 和 Windows 通过 WSL2：systemd 用户单元
    • 向导尝试 loginctl enable-linger <user> 以便网关在注销后保持运行。
    • 可能提示输入 sudo（写入 /var/lib/systemd/linger）；它首先尝试不使用 sudo。
  • 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不推荐 Bun。
7

健康检查

  • 启动网关（如需要）并运行 openclaw health。
  • openclaw status --deep 将网关健康探测添加到状态输出。
8

技能

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

完成

  • 摘要和下一步，包括 iOS、Android 和 macOS 应用选项。

如果未检测到 GUI，向导会打印 SSH 端口转发说明以获取控制 UI，而不是打开浏览器。 如果控制 UI 资源丢失，向导会尝试构建它们；回退是 pnpm ui:build（自动安装 UI 依赖项）。

远程模式详情

远程模式配置此机器以连接到其他地方的网关。

远程模式不会在远程主机上安装或修改任何内容。

您设置的内容：

  • 远程网关 URL（ws://...）
  • 如果远程网关需要认证则使用令牌（推荐）
  • 如果网关仅限环回，请使用 SSH 隧道或 tailnet。
  • 发现提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

认证和模型选项

模型行为：

  • 从检测到的选项中选择默认模型，或手动输入提供商和模型。
  • 向导运行模型检查并在配置的模型未知或缺少认证时发出警告。

凭据和配置文件路径：

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

API 密钥存储模式：

  • 默认引导行为将 API 密钥作为明文值持久化在认证配置文件中。
  • --secret-input-mode ref 启用引用模式而不是明文密钥存储。 在交互式引导中，您可以选择：
    • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 已配置的提供商引用（file 或 exec），具有提供商别名 + id
  • 交互式引用模式在保存前运行快速预检验证。
    • 环境变量引用：验证当前引导环境中的变量名 + 非空值。
    • 提供商引用：验证提供商配置并解析请求的 id。
    • 如果预检失败，引导显示错误并让您重试。
  • 在非交互模式下，--secret-input-mode ref 仅支持环境变量。
    • 在引导进程环境中设置提供商环境变量。
    • 内联密钥标志（例如 --openai-api-key）需要设置该环境变量；否则引导快速失败。
    • 对于自定义提供商，非交互 ref 模式将 models.providers.<id>.apiKey 存储为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 在该自定义提供商情况下，--custom-api-key 需要设置 CUSTOM_API_KEY；否则引导快速失败。
  • 现有明文设置继续正常工作。

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

输出和内部机制

~/.openclaw/openclaw.json 中的典型字段：

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果选择 Minimax）
  • tools.profile（本地引导在未设置时默认为 "messaging"；保留现有的显式值）
  • gateway.*（模式、绑定、认证、tailscale）
  • session.dmScope（本地引导在未设置时默认为 per-channel-peer；保留现有的显式值）
  • 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 或本地路径）。

网关向导 RPC：

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

客户端（macOS 应用和控制 UI）可以渲染步骤而无需重新实现引导逻辑。

Signal 设置行为：

  • 下载适当的发布资源
  • 存储在 ~/.openclaw/tools/signal-cli/<version>/ 下
  • 在配置中写入 channels.signal.cliPath
  • JVM 构建需要 Java 21
  • 原生构建在可用时使用
  • Windows 使用 WSL2 并在 WSL 内遵循 Linux signal-cli 流程

相关文档