CLI 设置参考

本页介绍分步新手引导的行为、输出和内部机制。 如需操作演练，请参阅新手引导（CLI）。如需完整的 CLI 标志 参考（每个 --flag、非交互式示例、提供商特定 命令），请参阅 openclaw onboard。

向导的作用

本地模式（默认）将引导你完成：

• 模型和身份验证设置（Anthropic、OpenAI Code 订阅 OAuth、xAI、OpenCode、自定义端点，以及更多由提供商负责的身份验证流程）
• 工作区位置和引导文件
• Gateway 网关设置（端口、绑定、身份验证、Tailscale）
• 渠道和提供商（Discord、Feishu、Google Chat、iMessage、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp，以及其他内置或插件渠道）
• Web 搜索提供商（可选）
• 守护进程安装（LaunchAgent、systemd 用户单元，或原生 Windows 计划任务，并以启动文件夹作为回退方案）
• 健康检查
• Skills 设置

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

本地流程详情

远程模式详情

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

你需要设置：

• 远程 Gateway 网关 URL（ws://... 或 wss://...）
• 与远程 Gateway 网关配置匹配的令牌、密码或无身份验证

身份验证和模型选项

如果交互式新手引导中的提供商设置步骤失败（例如在本地未登录的情况下 选择复用 CLI），向导会显示错误并返回提供商选择器，而不是退出。 显式的 --auth-choice 运行仍会快速失败，以便用于自动化。

模型行为：

• 从检测到的选项中选择默认模型，或手动输入提供商和模型。
• 当新手引导从提供商身份验证选项启动时，模型选择器会自动优先显示 该提供商。对于 Volcengine 和 BytePlus，同一偏好设置 还会匹配其编程套餐变体（volcengine-plan/*、 byteplus-plan/*）。
• 如果按首选提供商筛选后结果为空，选择器会回退到 完整目录，而不会显示没有模型。
• 向导会执行模型检查，并在配置的模型未知或缺少身份验证时发出警告。

凭据和配置文件路径：

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

凭据存储模式：

• 默认新手引导行为会将 API key 作为明文值持久化到身份验证配置文件中。
• --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>。
• 现有明文设置继续保持不变。

输出和内部机制

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

• agents.defaults.workspace
• 传递 --skip-bootstrap 时的 agents.defaults.skipBootstrap
• agents.defaults.model / models.providers（如果选择 Minimax）
• tools.profile（本地新手引导在未设置时默认为 "coding"；现有显式值会予以保留）
• gateway.*（模式、绑定、身份验证、Tailscale）
• session.dmScope（本地新手引导在未设置时默认为 per-channel-peer；现有显式值会予以保留）
• channels.telegram.botToken、channels.discord.token、channels.matrix.*、channels.signal.*、channels.imessage.*
• 当你在提示中选择启用时的渠道允许列表（Discord、iMessage、Signal、Slack、Telegram、WhatsApp）；Discord 和 Slack 还会将输入的名称解析为 ID
• skills.install.nodeManager
  • setup --node-manager 标志接受 npm、pnpm 或 bun。
  • 之后仍可通过手动配置设置 skills.install.nodeManager: "yarn"。
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

openclaw agents add 会写入 agents.list[] 和可选的 bindings。

WhatsApp 凭据存放在 ~/.openclaw/credentials/whatsapp/<accountId>/ 下。 活动会话和转录内容存储在 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 中。 ~/.openclaw/agents/<agentId>/sessions/ 目录用于旧版迁移 输入和归档/支持工件。

非交互式设置

--non-interactive 要求同时使用 --accept-risk（确认智能体 功能强大，拥有完整系统访问权限存在风险）：

openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

完整标志参考和提供商特定示例：openclaw onboard、CLI 自动化。

Gateway 网关向导 RPC

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

客户端（macOS 应用和 Control UI）无需重新实现新手引导逻辑即可呈现各个步骤。

Signal 设置行为

• 从官方 signal-cli GitHub 发行版下载适用的发布工件（原生构建，仅限 Linux x86-64）
• 在其他平台（macOS、非 x64 Linux）上，改为通过 Homebrew 安装
• 将发布工件安装到 ~/.openclaw/tools/signal-cli/<version>/ 下
• 在配置中写入 channels.signal.cliPath
• 尚不支持原生 Windows；请在 WSL2 内运行新手引导以获得 Linux 安装路径

相关文档

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