跳转到内容
OpenClaw Docs

CLI 设置参考

CLI 设置参考

Section titled “CLI 设置参考”

此页面是 openclaw onboard 的完整参考。 如需简短指南，请参阅 新手引导 (CLI)。

向导的功能

Section titled “向导的功能”

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

  • OpenAI 和身份验证设置（OAuth Code 订阅 Anthropic、CLI Claude API 或 MiniMax 密钥，以及 GLM、Ollama、Moonshot、Gateway(网关)、StepFun 和 AI Gateway(网关) 选项）
  • 工作区位置和引导文件
  • Gateway(网关) 设置（端口、绑定、认证、tailscale）
  • 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles 以及其他捆绑的渠道插件）
  • 守护进程安装（LaunchAgent、systemd 用户单元或原生 Windows 计划任务，并带有启动文件夹回退机制）
  • 健康检查
  • Skills 设置

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

本地流程详情

Section titled “本地流程详情”

  1. 现有配置检测

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

  2. 模型和身份验证

  3. 工作区

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

  4. Gateway(网关)

    • 提示输入端口、绑定、身份验证模式和 Tailscale 暴露。
    • 建议：即使是环回连接，也要保持令牌身份验证已启用，以便本地 WS 客户端必须进行身份验证。
    • 在令牌模式下，交互式设置提供：
      • 生成/存储明文令牌（默认）
      • 使用 SecretRef（可选）
    • 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
    • 非交互式令牌 SecretRef 路径：`—gateway-token-ref-env

    。 - 需要在新手引导过程环境中有一个非空环境变量。 - 不能与 —gateway-token` 结合使用。 - 仅当您完全信任每个本地进程时才禁用身份验证。 - 非环回绑定仍然需要身份验证。

  5. Channels

    • WhatsApp：可选的二维码登录
    • Telegram：机器人令牌
    • Discord：机器人令牌
    • Google Chat：服务帐户 JSON + Webhook 受众
    • Mattermost：机器人令牌 + 基础 URL
    • Signal：可选的 signal-cli 安装 + 帐户配置
    • BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + Webhook
    • iMessage：传统 imsg CLI 路径 + 数据库访问
    • 私信安全：默认为配对。第一条私信发送代码；通过 `openclaw pairing approve

    ` 批准或使用允许列表。

Remote mode details

Section titled “Remote mode details”

Remote mode configures this machine to connect to a gateway elsewhere.

What you set:

  • 远程网关 URL (ws://...)
  • Token if remote gateway auth is required (recommended)

身份验证和模型选项

Section titled “身份验证和模型选项”
Anthropic API 密钥

如果存在则使用 ANTHROPIC_API_KEY，否则提示输入密钥，然后将其保存供守护进程使用。

OpenAI Code 订阅 (Codex CLI 复用)

如果 ~/.codex/auth.json 存在，向导可以复用它。 复用的 Codex CLI 凭据仍由 Codex CLI 管理；过期时 OpenClaw 会首先重新读取该来源，并且当提供商可以刷新它时，将 刷新后的凭据写回 Codex 存储，而不是自己接管所有权。

OpenAI Code 订阅 (OAuth)

浏览器流程；粘贴 code#state。

当模型未设置或为 openai/* 时， 将 agents.defaults.model 设置为 openai-codex/gpt-5.4。

OpenAI API 密钥

如果存在 OPENAI_API_KEY 则使用，或者提示输入密钥，然后将凭据存储在 auth profiles 中。

当模型未设置、openai/* 或 openai-codex/* 时， 将 agents.defaults.model 设置为 openai/gpt-5.4。

xAI (Grok) API 密钥

提示输入 XAI_API_KEY 并将 xAI 配置为模型提供商。

OpenCode

提示输入 OPENCODE_API_KEY (或 OPENCODE_ZEN_API_KEY) 并允许您选择 Zen 或 Go 目录。 设置 URL: opencode.ai/auth。

API 密钥 (通用)

为您存储密钥。

Vercel AI 网关

提示输入 AI_GATEWAY_API_KEY。 更多详情：Vercel AI 网关。

Cloudflare AI 网关

提示输入账户 ID、网关 ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。 更多详情：Cloudflare AI 网关。

MiniMax

配置会自动写入。托管默认为 MiniMax-M2.7；API-key 设置使用 minimax/...，OAuth 设置使用 minimax-portal/...。 更多详情：MiniMax。

StepFun

配置会针对中国或全球端点上的 StepFun 标准版或 Step Plan 自动写入。 标准版目前包括 step-3.5-flash，Step Plan 还包括 step-3.5-flash-2603。 更多详情：StepFun。

Synthetic (Anthropic-compatible)

提示输入 SYNTHETIC_API_KEY。 更多详情：Synthetic。

Ollama (Cloud and local open models)

提示输入基础 URL（默认为 http://127.0.0.1:11434），然后提供 Cloud + Local 或 Local 模式。 发现可用模型并建议默认值。 更多详情：Ollama。

Moonshot and Kimi Coding

Moonshot (Kimi K2) 和 Kimi Coding 配置会自动写入。 更多详情：Moonshot AI (Kimi + Kimi Coding)。

自定义提供商

适用于与 OpenAI 兼容和与 Anthropic 兼容的端点。

交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项：

  • 立即粘贴 API 密钥（明文）
  • 使用密钥引用（环境变量引用或配置的提供商引用，带有预检验证）

非交互式标志：

  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key（可选；回退到 CUSTOM_API_KEY）
  • --custom-provider-id（可选）
  • `—custom-compatibility

（可选；默认为 openai`）

跳过

保持未配置认证状态。

模型行为：

  • 从检测到的选项中选择默认模型，或手动输入提供商和模型。
  • 当新手引导从提供商认证选项开始时，模型选择器会自动优先选择该提供商。对于 Volcengine 和 BytePlus，同样的偏好也会匹配其 coding-plan 变体（volcengine-plan/*、 byteplus-plan/*）。
  • 如果首选提供商筛选结果为空，选择器将回退到完整目录，而不是不显示任何模型。
  • 向导会运行模型检查，如果配置的模型未知或缺少认证，则会发出警告。

凭证和配置文件路径：

  • 身份验证配置文件（API 密钥 + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json

凭证存储模式：

  • 默认的新手引导行为会将 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；否则新手引导会快速失败。
  • Gateway(网关) 身份验证凭据在交互式设置中支持明文和 SecretRef 选择：
    • 令牌模式：生成/存储明文令牌（默认）或 使用 SecretRef。
    • 密码模式：明文或 SecretRef。
  • 非交互式令牌 SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
  • 现有的明文设置继续不受影响地工作。

输出和内部细节

Section titled “输出和内部细节”

~/.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"。
  • 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/ 之下。

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 流程

相关文档

Section titled “相关文档”