跳转到内容
OpenClaw Docs

CLI 设置参考

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

向导的功能

Section titled “向导的功能”

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

  • 模型和身份验证设置（OpenAI Code 订阅 OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway(网关) 选项）
  • 工作区位置和引导文件
  • Gateway(网关) 设置（端口、绑定、身份验证、Tailscale）
  • 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、iMessage 以及其他捆绑的渠道插件）
  • 守护进程安装（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](/en/channels/discordGoogle Chat)：机器人令牌
    • Google Chat：服务账户 JSON + Webhook 受众
    • Mattermost：机器人令牌 + 基础 URL
    • Signal：可选的 signal-cliiMessage 安装 + 账户配置
    • iMessage：imsgCLIGateway(网关) CLI 路径 + Messages 数据库访问；当 Gateway 在 Mac 以外运行时，请使用 SSH 封装器
    • 私信安全：默认为配对。第一条私信发送一个代码；通过 `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)

Auth and 模型 options

Section titled “Auth and 模型 options”
Anthropic API key

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

OpenAI Code subscription (OAuth)

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

当模型未设置或已经是 OpenAI 系列时，通过 Codex 运行时将 agents.defaults.model 设置为 openai/gpt-5.5。

OpenAI Code subscription (device pairing)

使用短期设备代码的浏览器配对流程。

当模型未设置或已经是 OpenAI 系列时，通过 Codex 运行时将 agents.defaults.model 设置为 openai/gpt-5.5。

OpenAIAPIOpenAI API 密钥

如果存在 OPENAI_API_KEY 则使用它，否则提示输入密钥，然后将凭据存储在身份验证配置文件中。

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

OAuthxAI (Grok) OAuth

适用于符合条件的 SuperGrok 或 X 高级账户的浏览器登录。对于大多数用户来说，这是推荐的 xAI 路径。OpenClaw 会为 Grok 模型、x_search 和 code_execution 存储生成的身份验证配置文件。

xAI (Grok) 设备代码

通过短代码而不是本地主机回调进行适合远程环境的浏览器登录。在 SSH、Docker 或 VPS 主机上使用此方法。

APIxAI (Grok) API 密钥

提示输入 XAI_API_KEYAPIOAuth 并将 xAI 配置为模型提供商。当您需要 xAI 控制台 API 密钥而不是订阅 OAuth 时，请使用此选项。

OpenCode

提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）并让您选择 Zen 或 Go 目录。 设置 URL：opencode.ai/auth。

APIAPI 密钥（通用）

为您存储密钥。

VercelGateway(网关)Vercel AI 网关

提示输入 AI_GATEWAY_API_KEYVercelGateway(网关)。 更多详细信息：Vercel AI 网关。

Gateway(网关)Cloudflare AI Gateway

提示输入账户 ID、Gateway(网关) ID 和 CLOUDFLARE_AI_GATEWAY_API_KEYGateway(网关)。 更多详情：Cloudflare AI Gateway。

MiniMaxMiniMax

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

StepFun

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

AnthropicSynthetic (Anthropic-compatible)

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

OllamaOllama (Cloud and local open models)

首先提示输入 Cloud + Local、Cloud only 或 Local only。 Cloud only 使用 OLLAMA_API_KEY 配合 https://ollama.com。 主机支持的模式会提示输入基础 URL（默认为 http://127.0.0.1:11434），发现可用模型并建议默认值。 Cloud + LocalOllamaOllama 还会检查该 Ollama 主机是否已登录以进行云端访问。 更多详情：Ollama。

MoonshotMoonshot 和 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） - —custom-image-input/—custom-text-input`（可选；覆盖推断的模型输入能力）

跳过

保持未配置身份验证。

模型行为：

  • 从检测到的选项中选择默认模型，或手动输入提供商和模型。
  • 自定义提供商新手引导会推断常见模型 ID 的图像支持，并仅在模型名称未知时询问。
  • 当新手引导从提供商身份验证选择开始时，模型选择器会自动首选该提供商。对于 Volcengine 和 BytePlus，同样的首选项也匹配其编码计划变体（volcengine-plan/*， byteplus-plan/*）。
  • 如果该首选提供商筛选结果为空，选择器将回退到完整目录，而不是不显示任何模型。
  • 向导运行模型检查，如果配置的模型未知或缺少身份验证，则会发出警告。

凭证和配置文件路径：

  • Auth profiles (API 密钥 + OAuth): APIOAuth~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 传统 OAuth 导入: OAuth~/.openclaw/credentials/oauth.json

凭证存储模式:

  • 默认的新手引导行为会将 API 密钥以明文形式持久化存储在 auth profiles 中。
  • --secret-input-mode ref 启用引用模式，而不是明文密钥存储。 在交互式设置中，您可以选择：
    • 环境变量引用 (例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
    • 配置的提供商引用 (file 或 exec)，带有提供商别名 + id
  • 交互式引用模式在保存之前会运行快速的起飞前验证。
    • Env refs: 验证变量名称 + 当前新手引导环境中的非空值。
    • Provider refs: 验证提供商配置并解析请求的 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 选择：
    • Token 模式：生成/存储明文令牌 (默认) 或 使用 SecretRef。
    • 密码模式：明文或 SecretRef。
  • 非交互式令牌 SecretRef 路径: --gateway-token-ref-env <ENV_VAR>。
  • 现有的明文设置继续照常工作，无需更改。

输出和内部机制

Section titled “输出和内部机制”

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

  • agents.defaults.workspace
  • 当传递 --skip-bootstrap 时显示 agents.defaults.skipBootstrap
  • 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 “相关文档”