CLI 设置参考

​

CLI 设置参考

本页是 openclaw onboard 的完整参考。 如需快速指南，请参阅 新手引导 (CLI)。

​

向导的功能

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

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

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

​

本地流程详情

1. Existing config detection

   • 如果 ~/.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 <ENV_VAR>。
     • 要求新手引导流程环境中有一个非空的环境变量。
     • 不能与 --gateway-token 组合使用。
   • 仅当您完全信任每个本地进程时才禁用身份验证。
   • 非回环绑定仍需要身份验证。
5. 频道

   • WhatsApp：可选的 QR 登录
   • Telegram：机器人令牌
   • Discord：机器人令牌
   • Google Chat：服务账号 JSON + Webhook 受众
   • Mattermost 插件：机器人令牌 + 基础 URL
   • Signal：可选的 signal-cli 安装 + 账号配置
   • BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + Webhook
   • iMessage：旧版 imsg CLI 路径 + 数据库访问
   • 私信安全：默认为配对。第一条私信会发送一个代码；通过 openclaw pairing approve <channel> <code> 批准或使用允许列表。
6. Daemon install

   • macOS: LaunchAgent
     • Requires logged-in user 会话; for headless, use a custom LaunchDaemon (not shipped).
   • Linux 和 Windows 通过 WSL2: systemd user unit
     • 向导尝试执行 loginctl enable-linger <user> 以便在注销后保持网关运行。
     • May prompt for sudo (writes /var/lib/systemd/linger); it tries without sudo first.
   • Runtime selection: Node (recommended; required for WhatsApp 和 Telegram). 不推荐使用 Bun。
7. Health check

   • Starts gateway (if needed) and runs openclaw health.
   • openclaw status --deep adds gateway health probes to status output.
8. Skills

   • 读取可用的 Skills 并检查要求。
   • 让您选择节点管理器：npm 或 pnpm（不建议使用 bun）。
   • 安装可选依赖项（某些在 macOS 上使用 Homebrew）。
9. 完成

   • 摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。

If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. If Control UI assets are missing, the wizard attempts to build them; fallback is pnpm ui:build (auto-installs UI deps).

​

Remote mode details

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

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

What you set:

• Remote gateway URL (ws://...)
• Token if remote gateway auth is required (recommended)

• If gateway is loopback-only, use SSH tunneling or a tailnet. - 设备发现提示： - macOS: Bonjour (dns-sd) - Linux: Avahi (avahi-browse)

​

身份验证和模型选项

Anthropic API key

Uses ANTHROPIC_API_KEY if present or prompts for a key, then saves it for daemon use.

Anthropic OAuth (Claude Code CLI)

• macOS: checks Keychain item “Claude Code-credentials”
• Linux 和 Windows: reuses ~/.claude/.credentials.json if present

在 macOS 上，选择“始终允许” 以免 launchd 启动时被阻止。

Anthropic 令牌（setup-token 粘贴）

在任何机器上运行 claude setup-token，然后粘贴令牌。 您可以对其进行命名；留空则使用默认值。

OpenAI Code 订阅（Codex CLI 复用）

如果 ~/.codex/auth.json 存在，向导可以复用它。

OpenAI Code 订阅（OAuth）

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

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

OpenAI API 密钥

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

当模型未设置、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 key (generic)

为您存储密钥。

Vercel AI Gateway(网关)

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

Cloudflare AI Gateway

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

MiniMax

配置会自动写入。托管的默认值为 MiniMax-M2.7；MiniMax-M2.5 保持可用。 更多详情：MiniMax。

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)。

Custom 提供商

适用于 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|anthropic>（可选；默认为 openai）

跳过

保持未配置的身份验证。

模型行为：

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

凭据和配置文件路径：

• OAuth 凭据：~/.openclaw/credentials/oauth.json
• 身份验证配置文件（API 密钥 + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.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>。
• 现有的明文设置继续不受影响地工作。

无头服务器提示：在带有浏览器的机器上完成 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（如果未设置，本地新手引导默认为 "coding"；现有的显式值将被保留）
• 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/ 下。

Some channels are delivered as plugins. When selected during setup, the wizard prompts to install the plugin (npm or local path) before 渠道 configuration.

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

​

相关文档

• 新手引导中心：新手引导 (CLI)
• 自动化和脚本：CLI 自动化
• 命令参考：openclaw onboard

---

本页面源自 openclaw/openclaw，由 BeaversLab 翻译，遵循 MIT 协议 发布。