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 计划任务，并带 Startup 文件夹回退）
• 健康检查
• Skills 设置

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

本地流程详情

远程模式详情

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

你需要设置：

• 远程 Gateway 网关 URL（ws://... 或 wss://...）
• 令牌、密码或无凭证，需匹配远程 Gateway 网关的配置

凭证和模型选项

模型行为：

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

凭证和配置文件路径：

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

凭证存储模式：

• 默认新手引导行为会将 API keys 作为明文值持久化到凭证配置文件中。
• --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>/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 releases 下载合适的发布资产（原生构建，仅 Linux x86-64）
• 在其他平台（macOS、非 x64 Linux）上，改为通过 Homebrew 安装
• 将发布资产安装存储在 ~/.openclaw/tools/signal-cli/<version>/ 下
• 在配置中写入 channels.signal.cliPath
• 暂不支持原生 Windows；请在 WSL2 内运行新手引导以获取 Linux 安装路径

相关文档

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