一句话定义

  • 这一组命令负责修改 OpenClaw 的运行配置、默认模型、模型别名、fallback 链，以及相关认证状态。

解决的问题

  • 默认模型怎么改
  • image model 怎么改
  • 某个配置项现在到底是什么值
  • 配置是否合法
  • 某个 provider 的认证是否可用
  • SecretRef / provider builder / batch mode 怎么走

核心机制

  • configure：交互式配置入口，适合人工引导式修改。
  • config：非交互配置入口，适合精确修改、脚本化处理、校验。
  • models：管理默认模型、fallback、auth profiles、scan 与 probe。
  • secrets：处理 SecretRef / 运行时 secret 重载与审计，属于配置体系的安全层。

关键组成

1. 交互式配置

openclaw configure
openclaw setup --wizard
openclaw crestodian

适合场景：

  • 新环境初始化（推荐 setup --wizard 替代旧 onboard）
  • 不确定配置路径时
  • 需要一步步引导式操作时
  • crestodian 是交互式设置和修复助手

2. 非交互配置

openclaw config file
openclaw config get gateway.port
openclaw config set gateway.port 19000
openclaw config unset gateway.remote
openclaw config validate
openclaw config schema
openclaw config patch --file ./patch.json5

补充说明：

  • config get：精确查看某路径值
  • config set：支持 value mode / SecretRef builder / provider builder / batch mode
  • config unset：删除配置项
  • config file：确认当前配置文件路径
  • config patch：从 JSON5 文件或 stdin 批量补丁修改（新增）
  • config schema：打印配置的 JSON Schema（新增）
  • config validate：校验当前配置是否合法

3. 模型管理

openclaw models status
openclaw models list
openclaw models set <model>
openclaw models set-image <model>
openclaw models aliases list
openclaw models fallbacks list
openclaw models image-fallbacks list
openclaw models scan

补充说明：

  • models status：最常用，看默认模型、fallback 和 auth 概况
  • models set：改默认文本模型
  • models set-image：改默认图像模型
  • aliases：给长模型名取短别名（v2026.5.26 新增子命令）
  • fallbacks / image-fallbacks：主模型失败后的回退链（v2026.5.26 新增子命令）
  • scan：扫描候选模型与可用能力
  • auth：管理模型认证 profiles（v2026.5.26 新增子命令）

4. 模型认证与 Secret 管理

openclaw models auth add
openclaw models auth setup-token
openclaw models auth paste-token
openclaw secrets reload
openclaw secrets audit
openclaw secrets configure
openclaw secrets apply --from <plan.json>

适合场景：

  • 新增 provider 凭证
  • 排查 token 是否过期
  • 审计是否存在明文 secret 或 SecretRef 解析问题
  • 运行时重新加载 secret 快照
  • secrets configure 为 v2026.5.26 新增交互式配置助手

生命周期 / 执行流程

改模型的典型流程

  1. openclaw models list
  2. openclaw models status
  3. openclaw models set <model-or-alias>
  4. 必要时查看 models fallbacks list

改配置的典型流程

  1. openclaw config file
  2. openclaw config get <path>
  3. openclaw config set <path> <value>
  4. openclaw config validate
  5. 需要时重启 gateway

处理 secret / 凭证的典型流程

  1. openclaw models auth add 或 setup-token
  2. 若使用 SecretRef，先确认 provider 配置正确
  3. openclaw secrets audit
  4. 变更后可 openclaw secrets reload

高频命令组合

看当前模型与认证状态

openclaw models status
openclaw models status --probe

精确改配置

openclaw config get agents.defaults.model.primary
openclaw config set agents.defaults.model.primary "teamplus/gpt-5.4"
openclaw config validate

处理 SecretRef 变更

openclaw secrets audit
openclaw secrets reload

边界与限制

  • config set 能改很多，但改错路径也可能引入配置错误，所以最好搭配 config validate。
  • models status --probe 会触发真实探测，可能消耗 token 并受 rate limit 影响。
  • models set 修改的是默认模型，不等于所有 agent / profile / isolated agent 都自动同步。
  • secrets 关注的是 secret 解析与运行时快照，不直接替代业务配置本身。

常见误区

  • 误区 1：以为 configure 和 config 是重复功能。实际上一个偏交互，一个偏精确操作。
  • 误区 2：只改 models set 就结束。实际还要确认 auth profile、fallback、provider 可用性。
  • 误区 3：SecretRef 配好就一定生效。仍需确认 provider、env、file 或 exec provider 真能解析。

对比项

  • configure vs config：交互式 vs 非交互式
  • models status vs models list：当前解析结果 vs 可选模型列表
  • models auth vs secrets：模型认证入口 vs 更通用的 secret 体系