CLI 设置参考

​

向导会做什么

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

​

本地流程详情

​

远程模式详情

• 远程网关 URL (ws://... 或 wss://...)
• 令牌、密码，或无需认证，需与远程网关的配置匹配

​

认证和模型选项

• 从检测到的选项中选择默认模型，或手动输入提供方和模型。
• 当 onboarding 从某个提供方认证选项开始时，模型选择器会自动优先使用 该提供方。对于 Volcengine 和 BytePlus，同样的优先级 也适用于它们的 coding-plan 变体（volcengine-plan/*、 byteplus-plan/*）。
• 如果该“首选提供方”筛选结果为空，选择器会回退到 完整目录，而不是不显示任何模型。
• 向导会运行模型检查，并在配置的模型未知或缺少认证时发出警告。

• Auth profiles（API keys + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json

• 默认的 onboarding 行为会将 API keys 作为明文值持久化到 auth profiles 中。
• --secret-input-mode ref 会启用引用模式，而不是以明文形式存储 key。 在交互式设置中，你可以选择：
  • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
  • 已配置的 provider 引用（file 或 exec），带有 provider 别名和 id
• 交互式引用模式会在保存前运行快速预检验证。
  • Env refs：验证变量名称，以及当前 onboarding 环境中的值是否非空。
  • Provider refs：验证 provider 配置并解析请求的 id。
  • 如果预检失败，onboarding 会显示错误并允许你重试。
• 在非交互式模式下，--secret-input-mode ref 只会为新凭证创建基于环境变量的引用。
  • 添加新凭证时，在 onboarding 进程环境中设置 provider 环境变量。
  • 内联 key 标志（例如 --openai-api-key）要求设置相应的环境变量；否则 onboarding 会快速失败。
  • 现有的、可解析的命名 auth profiles 会保持不变地复用，包括现有的 env、file、exec 和 store 引用；不会写入新的 apiKey 或 keyRef，也不需要额外的 provider 环境变量。
  • 对于新的 custom-provider 凭证，非交互式 ref 模式会将 models.providers.<id>.apiKey 存储为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
  • 对于该 custom-provider 场景，必须设置 CUSTOM_API_KEY 才能使用 --custom-api-key；否则 onboarding 会快速失败。
  • 现有的明文 profile 凭证保持不变；引用模式不会迁移这些凭证。运行 openclaw secrets configure --apply，然后运行 openclaw secrets audit --check。请参阅 Secrets management。
• Gateway auth credentials 在交互式设置中支持明文和 SecretRef 选项：
  • Token 模式：生成／存储明文 token（默认）或使用 SecretRef。
  • Password 模式：明文或 SecretRef。
• 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
• 现有的明文设置继续正常工作，不会发生变化。

​

输出与内部机制

• agents.defaults.workspace
• agents.defaults.skipBootstrap 当传入 --skip-bootstrap 时
• agents.defaults.model / models.providers（如果选择了 Minimax）
• tools.profile（本地引导在未设置时默认为 "coding"；现有显式值会被保留）
• gateway.*（模式、绑定、认证、tailscale）
• session.dmScope（引导会保留显式值，否则保持未设置，因此 main 默认会在代理的滚动主会话中保留跨渠道的所有直接消息——这是个人代理的默认行为。对于共享或多用户收件箱，请使用 per-channel-peer；openclaw security audit 在检测到多用户 DM 流量时会建议隔离）
• 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 onboard --non-interactive --accept-risk --skip-health \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

​

网关向导 RPC

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

​

Signal 设置行为

• 从官方 signal-cli GitHub releases 下载合适的 release 资源包（原生构建，仅限 Linux x86-64）
• 在其他平台（macOS、非 x64 Linux）上，改为通过 Homebrew 安装
• 将 release 资源包安装到 ~/.openclaw/tools/signal-cli/<version>/
• 在配置中写入 channels.signal.transport.cliPath，并设置 kind: "managed-native"
• 暂不支持原生 Windows；请在 WSL2 中运行 onboarding 以获取 Linux 安装路径

​

相关文档

• 引导中心：CLI 入门
• 自动化与脚本：CLI 自动化
• 命令参考：openclaw onboard