OpenClaw 模型配置与火山 Coding Plan 支持清单（实践笔记）

低调小一2026-03-12 10:01

OpenClaw 模型配置与火山 Coding Plan 支持清单（实践笔记）

目标：把 OpenClaw 里 provider / model / auth 的关系讲清楚，并给出一套可复用的配置与自检方法：你到底配置了什么、运行时到底用的什么、想自定义时应该改哪里、鉴权到底绑在哪一层。

适用场景：你能跑起来 OpenClaw，但想扩展模型、切默认模型、确认"现在到底在用哪个模型"，或者搞清楚 volcengine / volcengine-plan 的区别。

摘要（先看结论）

  • 你真正要盯住的是一个三元组：providerId / modelId / auth profile；任何一个指向不存在的东西，都会变成"能看到但不能用 / 改了但不生效 / 看起来对但打不通"。
  • providerId 是主键：它既是配置树的 key，也是引用路径 providerId/modelId 的一部分；改名属于"改主键"，需要把所有引用一起改。
  • modelId 必须与服务端真实 modelId 对齐：本地随便起名没用；本地 catalog 里的 id 就是你最终引用的 modelId。
  • 想确认"火山 Coding Plan 在本机 catalog 里支持哪些模型"：看 ~/.openclaw/agents/main/agent/models.json 的 providers.volcengine-plan.models[]。
  • "现在到底用的哪个模型？"别猜：先找 agents.defaults.model.primary（providerId/modelId）→ 再在对应 provider 的 models[] 里确认该 model → 再确认有鉴权 profile 指向同一个 providerId。
  • 安全底线：auth-profiles.json 很可能包含明文 key，任何分享/提交前先脱敏。

快速导航（按问题定位）

目标 / 现象 看哪节 最短动作（可验收） 最有效观测点
想先把 provider/model/auth 关系讲明白 3 记住引用链：providerId/modelId 与 auth profile.provider 都指向 providerId 能从默认模型追到具体 model 与鉴权
想确认"现在到底用的哪个模型" 3.3 解析 agents.defaults.model.primary 并对照 catalog 与鉴权 profile 默认模型字符串能完整解析并能匹配鉴权
想搞清楚鉴权到底绑在哪一层 3.4 对照 auth.profiles 与 agent 侧 auth-profiles.json 的 provider 字段 profile.provider 与默认模型 providerId 对齐
想确认 volcengine-plan 本地支持哪些 modelId 4 打开 ~/.openclaw/agents/main/agent/models.json 搜 providers.volcengine-plan.models 本地 modelId 列表是否包含目标值
新增一个 modelId，让 OpenClaw "认识它" 5.1 在目标 provider 的 models[] 追加一条，并确保 id 与服务端一致 models.providers.<providerId>.models[] 能找到该 id
想把默认模型切到某个 providerId/modelId 5.2 改 agents.defaults.model.primary，并同步校验 provider、model、auth profile 默认模型字符串能被解析且鉴权可用
改了 openclaw.json 但运行时不生效 2 对照检查 agent 侧 models.json/auth-profiles.json 是否覆盖 agent 侧文件与预期是否一致
想把 volcengine 改个自定义名字 3.1 全文统一替换 key 与引用，并同步改 agent 侧文件 providerId/modelId 不再引用旧 providerId
配置看起来都对，但请求仍然打不通 7 按自检清单逐项排除：provider/model/auth 三者一致性 "默认模型字符串"与 catalog 中对象能对上

1. 我们在解决什么问题

在 OpenClaw 里，"能不能用某个模型"通常涉及三层东西：

  • 服务端真实可用的模型 ID（例如火山 Ark 控制台看到的 modelId）
  • 本地配置里登记的 provider/model catalog（OpenClaw 能否识别、展示、校验）
  • 默认模型 / 鉴权 profile 的引用是否一致（providerId/modelId 的链路能否走通）

这也是为什么"我只是改个名字"有时会把链路改断：你改的可能是主键（providerId），不是展示名。

2. OpenClaw 里有哪些关键配置文件

以本机默认目录 ~/.openclaw 为例，最关键的 3 份文件是：

  1. ~/.openclaw/openclaw.json

    • 更像"全局聚合配置"与"默认行为"，包括默认模型、workspace、gateway、tools 等。
    • 典型关心点：
      • models.providers.<providerId>：provider 定义（baseUrl / api / models[] / apiKey 等）
      • agents.defaults.model.primary：默认主模型（形如 providerId/modelId）
      • auth.profiles：鉴权 profile（不一定含明文 key）

  2. ~/.openclaw/agents/main/agent/models.json

    • 更像"Agent 侧模型清单/目录"，这里能看到你环境里登记了哪些 provider、哪些 model。
    • 它往往是你判断"OpenClaw 认为支持哪些模型"的第一手来源。

  3. ~/.openclaw/agents/main/agent/auth-profiles.json

    • Agent 侧鉴权 profile，通常包含明文 key（务必注意不要外泄/不要提交到仓库）。

实践经验：如果你只改 openclaw.json，但运行时仍以 agent 侧的 models.json/auth-profiles.json 为准，就会出现"看起来改对了但实际不生效"的割裂。

2.1 配置为什么会不生效（常见"优先级/覆盖"问题）

当你遇到"默认模型写对了、provider/model 也填了，但运行时还是不按这个走"，优先排查是不是出现了两套目录不一致：

  • 你改的是 ~/.openclaw/openclaw.json，但运行时实际读取的是 ~/.openclaw/agents/main/agent/models.json
  • 你补了 auth.profiles，但运行时实际使用的是 ~/.openclaw/agents/main/agent/auth-profiles.json

最稳的做法是用同一个 providerId/modelId 同时在两边做一次"能否解析"的检查：

  1. agents.defaults.model.primary 里拆出 providerId/modelId
  2. 在 provider 的 models[] 里能找到 id == modelId
  3. 在鉴权 profile 里能找到 provider == providerId

3. providerId / modelId 到底是什么：名字还是主键？

3.1 providerId（例如 volcengine、volcengine-plan）

providerId 是配置树里的 key，也会出现在 providerId/modelId 这种引用里：

text 复制代码 
agents.defaults.model.primary = "<providerId>/<modelId>"

它更像"主键"，而不是展示名。你当然可以把 volcengine 改成 wzy-engine 或其他自定义名字，但要同时保证下面这些都同步改：

  • models.providers.<providerId> 的键名
  • auth.profiles.*.provider
  • agents.defaults.model.primary
  • agents.defaults.models 里的 key
  • 以及 agent 侧的 ~/.openclaw/agents/main/agent/models.json 与 auth-profiles.json（如果运行时会读取它们）

另外还有一个现实因素：某些 providerId 可能存在"内置适配/探测/向导配置"能力（比如 CLI 的 --auth-choice 里有 volcengine-api-key 之类），自定义改名后可能会失去这类内置能力。

3.2 modelId（例如 ark-code-latest、kimi-k2.5）

modelId 通常需要与服务端真实可用的 modelId 对齐，否则请求会打到一个不存在的模型。

它不是"随便起名就行"的。

3.3 我现在到底用的哪个模型（不靠猜）

你要回答的不是"我想用哪个"，而是"运行时会引用哪个"。按下面顺序追一遍引用链：

  1. 在 ~/.openclaw/openclaw.json 找到默认模型：

    • agents.defaults.model.primary = "<providerId>/<modelId>"

  2. 确认这个 <providerId> 在本地 catalog 里存在（两边都对照一次）：

    • ~/.openclaw/openclaw.json 的 models.providers.<providerId>
    • ~/.openclaw/agents/main/agent/models.json 的 providers.<providerId>

  3. 确认这个 <modelId> 在该 provider 的 models[] 里存在（关注 id 字段）：

    • models.providers.<providerId>.models[]

  4. 确认至少有一个鉴权 profile 指向同一个 providerId：

    • ~/.openclaw/openclaw.json 的 auth.profiles.*.provider
    • 或 ~/.openclaw/agents/main/agent/auth-profiles.json（如果运行时以 agent 侧为准）

如果第 2 步不成立，说明"providerId 这个主键没对上"；如果第 3 步不成立，说明"你引用了一个本地目录里不存在的 modelId"；如果第 4 步不成立，说明"模型与 provider 对了，但没有可用鉴权"。

3.4 鉴权 profile 怎么理解（Key 绑定在 provider 层）

把鉴权理解成一句话就够了：Key 不是绑定在 model 上的，而是绑定在 provider 上的；你用哪个 provider，就得有一个 profile 的 provider 指向它。

因此最常见的"能选但不能用"是：

  • 默认模型写的是 volcengine-plan/<modelId>，但你的 auth.profiles.*.provider 只配了 volcengine

安全上也只认一条规则：凡是涉及 auth-profiles.json 的内容，一律先脱敏再分享（用 <REDACTED> 替换明文 key/token）。

4. 火山 Coding Plan 支持哪些模型：去哪里看最靠谱

在本机环境里，"OpenClaw 认为火山 Coding Plan 支持哪些模型"可以直接看：

  • ~/.openclaw/agents/main/agent/models.json 的 providers.volcengine-plan.models[]

在我们排查时，这个 provider 下登记的 modelId 包括：

  • ark-code-latest
  • doubao-seed-code
  • glm-4.7
  • kimi-k2-thinking
  • kimi-k2.5
  • doubao-seed-code-preview-251028

注意：这份清单是"本地 catalog"，不一定等价于"你账号在火山侧一定都可用"。最终是否可用，以火山控制台/接口返回为准。

5. 如何新增模型：两种常见目标

5.1 目标 A：把一个 modelId 加进某个已有 provider（让 OpenClaw 认识它）

思路：在 provider 的 models[] 里追加一个对象，并确保 id 与服务端一致、api 与 provider 兼容。

最小字段通常包括：

json 复制代码 
{
  "id": "ark-code-latest",
  "name": "ark-code-latest",
  "api": "openai-completions",
  "reasoning": false,
  "input": ["text"],
  "contextWindow": 256000,
  "maxTokens": 4096
}

contextWindow/maxTokens 最好按真实限制填，不要"拍脑袋写大"，否则你以为能输出更多，实际被截断会很困惑。

5.2 目标 B：切换默认模型

改 agents.defaults.model.primary 即可：

text 复制代码 
agents.defaults.model.primary = "<providerId>/<modelId>"

并确保：

  • <providerId> 在 models.providers 里存在
  • <modelId> 在该 provider 的 models[] 里存在
  • auth.profiles 里至少有一个 profile 的 provider 指向该 providerId（并且底层真的有 key/凭证）

6. 我们踩过的坑：把 volcengine-plan 的模型加到了 volcengine

一个很常见的误区是：

  • 想用 volcengine-plan/ark-code-latest
  • 但把 ark-code-latest 加进了 models.providers.volcengine.models[]

这会导致：

  • volcengine/ark-code-latest 可以被引用（至少配置上）
  • 但 volcengine-plan/ark-code-latest 仍然可能"找不到 provider / 找不到 model"

换句话说：模型"挂在哪个 provider 下"决定了你最终引用的路径。

7. 快速自检清单（不靠猜）

当你完成配置后，优先做这几件事来确认链路没断：

  • 检查默认模型字符串是否存在于 models.providers.<providerId>.models[]
  • 检查 auth.profiles.*.provider 是否指向真实存在的 providerId
  • 如遇到"看起来都对但仍不工作"，对照检查 agent 侧的：
    • ~/.openclaw/agents/main/agent/models.json
    • ~/.openclaw/agents/main/agent/auth-profiles.json

8. 安全提醒（非常重要）

openclaw.json / auth-profiles.json 里可能包含：

  • API Key（明文）
  • token
  • appSecret

这些都不应该被提交到 Git，也不应该粘到群里/文档里。可以把敏感字段替换成 <REDACTED> 后再分享。

相关推荐
xuxie992 小时前
Next 13 sqlite3 查找、网页
java·数据库·oracle
像少年啦飞驰点、2 小时前
Java策略模式从入门到实战：小白也能看懂的设计模式指南
java·设计模式·策略模式·编程入门·小白教程
毛骗导演2 小时前
万字解析 OpenClaw 源码架构-消息渠道集成简介
前端·架构
Lois_Luo2 小时前
Win10电脑安装openclaw-cn并接入飞书教程
飞书·openclaw
kyriewen2 小时前
别再直接 git push 了！这个"魔法"参数让你的代码质量翻倍
前端·git·命令行
꯭ 瞎꯭扯꯭蛋꯭2 小时前
3万字80道Java基础经典面试题总结
java·开发语言
程序员Terry2 小时前
别再用 if-else 堆砌代码了！策略模式让你的代码优雅十倍
java·设计模式
what丶k2 小时前
深入浅出责任链模式：解耦流程的优雅设计之道
java·责任链模式
陈辛chenxin2 小时前
【零基础学Web-Day1】HTML 基础标签 + CSS 样式规范，附实战案例
css·经验分享·笔记·html·课程设计
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03本地部署 OpenClaw + DeepSeek-R1 完全指南04得物前端部门，没了05OpenClaw 连接飞书完整指南：插件安装、配置与踩坑记录06OpenClaw 飞书机器人不回复消息？3 小时踩坑总结07Window 10部署openclaw报错node.exe : npm error code 12808OpenClaw macOS 完整安装与本地模型配置教程（实战版）09npm-error code 128问题解决方法10OpenClaw 接入 QQ Bot 完整实践指南