Skip to main content

​
CLI 设置参考

本页是 openclaw onboard 的完整参考。 如需简短指南，请参见 新手引导（CLI）。

​
向导会做什么

本地模式（默认）会引导你完成以下设置：
  • 模型和认证设置（OpenAI Code 订阅 OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot AI、StepFun 和 AI Gateway 网关选项）
  • 工作区位置和引导文件
  • Gateway 网关设置（端口、绑定、认证、tailscale）
  • 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles，以及其他内置渠道插件）
  • 守护进程安装（LaunchAgent、systemd 用户单元，或原生 Windows 计划任务，并在失败时回退到启动文件夹）
  • 健康检查
  • Skills 设置
远程模式会将这台机器配置为连接到其他地方的一个 Gateway 网关。 它不会在远程主机上安装或修改任何内容。

​
本地流程详情

1

现有配置检测

  • 如果 ~/.openclaw/openclaw.json 已存在，可选择保留、修改或重置。
  • 重新运行向导不会清除任何内容，除非你明确选择“重置”（或传入 --reset）。
  • CLI --reset 默认为 config+creds+sessions；使用 --reset-scope full 可同时移除工作区。
  • 如果配置无效或包含旧版键，向导会停止并要求你先运行 openclaw doctor，然后再继续。
  • 重置使用 trash，并提供以下范围：
    • 仅配置
    • 配置 + 凭证 + 会话
    • 完整重置（也会移除工作区）
2

模型和认证

3

工作区

  • 默认是 ~/.openclaw/workspace（可配置）。
  • 写入首次运行引导所需的工作区文件。
  • 工作区布局：智能体工作区。
4

Gateway 网关

  • 会提示输入端口、绑定、认证模式和 tailscale 暴露方式。
  • 推荐：即使是 loopback，也保持启用令牌认证，这样本地 WS 客户端也必须先认证。
  • 在令牌模式下，交互式设置提供：
    • 生成/存储明文令牌（默认）
    • 使用 SecretRef（按需启用）
  • 在密码模式下，交互式设置同样支持明文或 SecretRef 存储。
  • 非交互式令牌 SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
    • 要求新手引导进程环境中存在一个非空环境变量。
    • 不能与 --gateway-token 组合使用。
  • 仅当你完全信任每一个本地进程时，才禁用认证。
  • 非 loopback 绑定仍然需要认证。
5

渠道

  • WhatsApp：可选 QR 登录
  • Telegram：机器人令牌
  • Discord：机器人令牌
  • Google Chat：服务账号 JSON + webhook audience
  • Mattermost：机器人令牌 + 基础 URL
  • Signal：可选 signal-cli 安装 + 账号配置
  • BlueBubbles：推荐用于 iMessage；需要服务器 URL + 密码 + webhook
  • iMessage：旧版 imsg CLI 路径 + DB 访问
  • 私信安全：默认使用配对。第一次私信会发送一个代码；通过 openclaw pairing approve <channel> <code> 进行批准，或使用允许名单。
6

守护进程安装

  • macOS：LaunchAgent
    • 需要已登录的用户会话；如需无头模式，请使用自定义 LaunchDaemon（未随产品提供）。
  • Linux 和通过 WSL2 的 Windows：systemd 用户单元
    • 向导会尝试运行 loginctl enable-linger <user>，以便 Gateway 网关在注销后继续运行。
    • 可能会提示 sudo（写入 /var/lib/systemd/linger）；会先尝试不使用 sudo。
  • 原生 Windows：优先使用计划任务
    • 如果创建任务被拒绝，OpenClaw 会回退到每用户启动文件夹登录项，并立即启动 Gateway 网关。
    • 仍然更推荐计划任务，因为它们提供更好的 supervisor 状态。
  • 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不推荐 Bun。
7

健康检查

  • 启动 Gateway 网关（如需要）并运行 openclaw health。
  • openclaw status --deep 会把实时 Gateway 网关健康探针加入状态输出，包括支持时的渠道探针。
8

Skills

  • 读取可用 Skills 并检查要求。
  • 让你选择 Node 管理器：npm、pnpm 或 bun。
  • 安装可选依赖（有些在 macOS 上使用 Homebrew）。
9

完成

  • 显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。
如果未检测到 GUI，向导会打印用于访问 Control UI 的 SSH 端口转发说明，而不是打开浏览器。 如果缺少 Control UI 资源，向导会尝试构建它们；回退命令为 pnpm ui:build（会自动安装 UI 依赖）。

​
远程模式详情

远程模式会将这台机器配置为连接到其他地方的一个 Gateway 网关。
远程模式不会在远程主机上安装或修改任何内容。
你要设置的内容：
  • 远程 Gateway 网关 URL（ws://...）
  • 如果远程 Gateway 网关要求认证，则设置令牌（推荐）
  • 如果 Gateway 网关仅绑定 loopback，请使用 SSH 隧道或 tailnet。
  • 发现提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

​
认证和模型选项

如果存在 ANTHROPIC_API_KEY 则使用它，否则提示输入密钥，然后保存以供守护进程使用。
如果存在 ~/.codex/auth.json，向导可以复用它。 复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw 会优先重新读取该来源，并且当提供商可以刷新它时，会将 刷新后的凭证写回 Codex 存储，而不是自行接管 该凭证。
浏览器流程；粘贴 code#state。当模型未设置或为 openai/* 时，将 agents.defaults.model 设置为 openai-codex/gpt-5.4。
如果存在 OPENAI_API_KEY 则使用它，否则提示输入密钥，然后将凭证存储到认证 profiles 中。当模型未设置、为 openai/* 或 openai-codex/* 时，将 agents.defaults.model 设置为 openai/gpt-5.4。
提示输入 XAI_API_KEY，并将 xAI 配置为一个模型提供商。
提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY），并让你选择 Zen 或 Go 目录。 设置 URL：opencode.ai/auth。
为你存储该密钥。
提示输入 AI_GATEWAY_API_KEY。 更多详情：Vercel AI Gateway 网关。
提示输入账号 ID、Gateway 网关 ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。 更多详情：Cloudflare AI Gateway 网关。
配置会自动写入。托管默认值为 MiniMax-M2.7；API 密钥设置使用 minimax/...，OAuth 设置使用 minimax-portal/...。 更多详情：MiniMax。
会为中国区或全球端点的 StepFun 标准版或 Step Plan 自动写入配置。 标准版当前包含 step-3.5-flash，Step Plan 还包含 step-3.5-flash-2603。 更多详情：StepFun。
提示输入 SYNTHETIC_API_KEY。 更多详情：Synthetic。
提示输入基础 URL（默认 http://127.0.0.1:11434），然后提供 Cloud + Local 或仅 Local 模式。 发现可用模型并建议默认值。 更多详情：Ollama。
Moonshot AI（Kimi K2）和 Kimi Coding 配置会自动写入。 更多详情：Moonshot AI（Kimi + Kimi Coding）。
可用于兼容 OpenAI 和兼容 Anthropic 的端点。交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项：
  • 立即粘贴 API 密钥（明文）
  • 使用 secret reference（环境变量引用或已配置提供商引用，带预检验证）
非交互式参数：
  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key（可选；回退到 CUSTOM_API_KEY）
  • --custom-provider-id（可选）
  • --custom-compatibility <openai|anthropic>（可选；默认 openai）
保持认证未配置状态。
模型行为：
  • 从检测到的选项中选择默认模型，或手动输入提供商和模型。
  • 当新手引导从某个提供商认证选项开始时，模型选择器会自动优先显示 该提供商。对于 Volcengine 和 BytePlus（国际版），同样的优先级 也会匹配它们的 coding-plan 变体（volcengine-plan/*、 byteplus-plan/*）。
  • 如果该“优先提供商”过滤结果为空，选择器会回退到 完整目录，而不是显示空模型列表。
  • 向导会运行模型检查；如果配置的模型未知或缺少认证，会给出警告。
凭证和 profile 路径：
  • 认证 profiles（API 密钥 + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json
凭证存储模式：
  • 默认新手引导行为会将 API 密钥作为明文值持久化到认证 profiles 中。
  • --secret-input-mode ref 会启用引用模式，而不是明文密钥存储。 在交互式设置中，你可以选择：
    • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 已配置提供商引用（file 或 exec），包含提供商别名 + id
  • 交互式引用模式会在保存前运行快速预检验证。
    • Env 引用：验证变量名，以及当前新手引导环境中该变量具有非空值。
    • 提供商引用：验证提供商配置并解析请求的 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，然后复制 该智能体的 auth-profiles.json（例如 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json，或对应的 $OPENCLAW_STATE_DIR/... 路径）到 Gateway 网关主机上。credentials/oauth.json 仅是旧版导入来源。

​
输出和内部机制

~/.openclaw/openclaw.json 中的典型字段：
  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果选择了 Minimax）
  • tools.profile（本地新手引导在未设置时默认设为 "coding"；现有显式值会被保留）
  • gateway.*（mode、bind、auth、tailscale）
  • session.dmScope（本地新手引导在未设置时默认设为 per-channel-peer；现有显式值会被保留）
  • channels.telegram.botToken、channels.discord.token、channels.matrix.*、channels.signal.*、channels.imessage.*
  • 当你在提示中选择启用时，渠道允许名单（Slack、Discord、Matrix、Microsoft Teams）（如有可能，名称会解析为 ID）
  • skills.install.nodeManager
    • setup --node-manager 参数接受 npm、pnpm 或 bun。
    • 稍后手动配置时仍可将 skills.install.nodeManager: "yarn" 设为 "yarn"。
  • 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 应用和 Control UI）可以渲染步骤，而无需重新实现新手引导逻辑。 Signal 设置行为：
  • 下载适合的发布资源
  • 将其存储到 ~/.openclaw/tools/signal-cli/<version>/
  • 在配置中写入 channels.signal.cliPath
  • JVM 构建需要 Java 21
  • 在可用时优先使用原生构建
  • Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 signal-cli 流程

​
相关文档