思渡AI Logo
OpenClaw 官方手册快速开始StartCLI 设置参考

CLI 设置参考

CLI 设置参考

本页是 openclaw onboard 的完整参考。 简短指南请参见 设置向导（CLI）。

向导会执行什么

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

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

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

本地流程详情

  • 如果 ~/.openclaw/openclaw.json 存在，可选择 Keep、Modify 或 Reset。
  • 重新运行向导不会清除任何内容，除非你明确选择 Reset（或传递 --reset）。
  • CLI --reset 默认作用于 config+creds+sessions；使用 --reset-scope full 还会删除工作区。
  • 如果配置无效或包含旧版键，向导会停止，并要求你先运行 openclaw doctor 再继续。
  • Reset 使用 trash，并提供以下范围：
    • 仅配置
    • 配置 + 凭证 + 会话
    • 完全重置（也会删除工作区）
  • 默认值为 ~/.openclaw/workspace（可配置）。
  • 会植入首次运行 bootstrap 仪式所需的工作区文件。
  • 工作区布局：智能体工作区。
  • 会提示你输入端口、绑定、身份验证模式和 tailscale 暴露设置。
  • 建议：即使仅用于 loopback，也保持启用令牌身份验证，这样本地 WS 客户端也必须进行身份验证。
  • 在令牌模式下，交互式设置提供：
    • 生成/存储明文令牌（默认）
    • 使用 SecretRef（可选）
  • 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
  • 非交互式令牌 SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
    • 要求在新手引导进程环境中存在一个非空环境变量。
    • 不能与 --gateway-token 组合使用。
  • 仅当你完全信任每个本地进程时才禁用身份验证。
  • 非 loopback 绑定仍然需要身份验证。
  • WhatsApp：可选 QR 登录
  • Telegram：bot 令牌
  • Discord：bot 令牌
  • Google Chat：服务账号 JSON + webhook audience
  • Mattermost 插件：bot 令牌 + 基础 URL
  • Signal：可选 signal-cli 安装 + 账户配置
  • BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + webhook
  • iMessage：旧版 imsg CLI 路径 + 数据库访问
  • 私信安全：默认是配对。首次私信会发送一个代码；通过 openclaw pairing approve <channel> <code> 批准，或使用 allowlist。
  • macOS：LaunchAgent
    • 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。
  • Linux 和通过 WSL2 的 Windows：systemd 用户单元
    • 向导会尝试执行 loginctl enable-linger <user>，使网关在注销后仍保持运行。
    • 可能会提示输入 sudo（写入 /var/lib/systemd/linger）；会先尝试不使用 sudo。
  • 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不建议使用 Bun。
  • 启动 Gateway 网关（如有需要），并运行 openclaw health。
  • openclaw status --deep 会在状态输出中添加 Gateway 网关健康探测。
  • 读取可用的 Skills 并检查要求。
  • 让你选择 node 管理器：npm 或 pnpm（不建议使用 bun）。
  • 安装可选依赖（部分依赖在 macOS 上使用 Homebrew）。
  • 显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。

如果未检测到 GUI，向导会打印用于控制 UI 的 SSH 端口转发说明，而不是打开浏览器。 如果缺少控制 UI 资源，向导会尝试构建它们；回退命令为 pnpm ui:build（首次运行会自动安装 UI 依赖）。

远程模式详情

远程模式会将此机器配置为连接到其他位置的网关。

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

你需要设置的内容：

  • 远程 Gateway 网关 URL（ws://...）
  • 如果远程 Gateway 网关需要身份验证，则设置令牌（推荐）
  • 如果网关仅绑定到 loopback，请使用 SSH 隧道或 tailnet。
  • 发现提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

身份验证和模型选项

模型行为：

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

凭证和配置档案路径：

  • OAuth 凭证：~/.openclaw/credentials/oauth.json
  • Auth profile（API 密钥 + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

凭证存储模式：

  • 默认新手引导行为会将 API 密钥作为明文值持久化到 auth profile 中。
  • --secret-input-mode ref 会启用引用模式，而不是明文密钥存储。 在交互式设置中，你可以选择：
    • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 已配置提供商引用（file 或 ext），带提供商别名 + 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；否则新手引导会快速失败。
  • Gateway 网关身份验证凭证在交互式设置中支持明文和 SecretRef 选项：
    • 令牌模式：生成/存储明文令牌（默认）或 使用 SecretRef。
    • 密码模式：明文或 SecretRef。
  • 非交互式令牌 SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
  • 现有的明文设置会继续保持不变并正常工作。

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

输出和内部机制

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

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果选择了 Minimax）
  • tools.profile（本地新手引导在未设置时默认设为 "coding"；现有显式值会保留）
  • gateway.*（模式、绑定、身份验证、tailscale）
  • session.dmScope（本地新手引导在未设置时默认设为 per-channel-peer；现有显式值会保留）
  • channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
  • 当你在提示中选择加入时的渠道 allowlist（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 或本地路径），然后再进行渠道配置。

Gateway 网关向导 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 流程

相关文档

Previous

CLI 自动化

Next

CLI 新手引导