OpenClaw手动配置火山引擎方舟coding plan

添加 volcengine-plan provider 排查记录

日期：2026-05-23 目标：让 volcengine-plan/ark-code-latest 等模型能正常使用

背景

volcengine-plan 是 volcengine 的 Coding 套餐 provider，端点是 https://ark.cn-beijing.volces.com/api/coding/v3，跟标准 volcengine (/api/v3) 是不同 baseUrl + 不同 API key。

调用 volcengine-plan/ark-code-latest 时一直失败，401 AuthenticationError。

排查过程

第一步：确认 API 本身可用

直接 curl 测试 volcengine-plan 的端点 → 200 OK，正常返回。

第二步：检查 OpenClaw 配置

在 openclaw.json 里 models.providers.volcengine-plan 已有，但 auth.profiles 缺少 volcengine-plan:default。

第三步：第一次尝试（错误方向）

往 openclaw.json 的 auth.profiles 加声明后重启，仍然 401。

第四步：找到真正的 auth profile 文件

跑 openclaw models status --json 发现 storePath 指向： ~/.openclaw/agents/main/agent/auth-profiles.json

这个文件才是实际密钥存储，里面只有 volcengine:default，没有 volcengine-plan:default。所以 volcengine-plan 的模型调用一直 fallback 用了 volcengine 的 key（两者不同），导致 401。

第五步：修复

在 auth-profiles.json 里追加正确的条目后重启 → 验证通过。

关键经验

1. openclaw.json 的 auth.profiles 只是声明，实际密钥存储在每个 agent 的 auth-profiles.json 里
2. openclaw.json 的 models.providers.apiKey 可以省略，密钥只需写在 auth-profiles.json
3. 真实存储路径：~/.openclaw/agents/<agent-id>/agent/auth-profiles.json
4. 诊断命令：openclaw models status --json 能看到 storePath 和实际加载的 profiles
5. 路由 fallback 行为：当 provider 没有对应 auth profile 时，OpenClaw 会用同 provider 家族的其他 key，导致认证失败
6. models.json 自动生成，不需要手动修改

---

三者的关系与作用（源码级）

1️⃣ openclaw.json — 全局配置声明

OpenClaw 的主配置文件，声明了"可以有什么"。

models.providers — Provider 定义

定义 provider 是谁、端点在哪、包含哪些模型。apiKey 字段可留空。

auth.profiles — Auth profile 声明

源码证据（order-BpP0LHg3.js:resolveAuthProfileOrder）：OpenClaw 运行时读取 cfg.auth.profiles 作为优先级排序参考和命名注册。

不包含实际密钥！ 只声明了名字和模式。

2️⃣ auth-profiles.json — 实际密钥存储

路径：~/.openclaw/agents/<agent-id>/agent/auth-profiles.json

源码路径（models-config-hNCfzm-l.js:830、store-BYnn-xRZ.js）

关键要点：

• 每个 agent 独立
• openclaw.json 的声明不会自动写入这里
• 源码函数：saveAuthProfileStore() / upsertAuthProfile() / markAuthProfileSuccess()

3️⃣ models.json — 自动缓存的模型清单

自动生成，不需要手动修改，删了也会重建。触发时机：重启、openclaw models scan、配置变化。

生成时会合并 openclaw.json 的 providers + 插件发现的 provider + auth-profiles.json 里的密钥。

---

通用步骤：给 OpenClaw 添加新 provider

第 1 步：在 openclaw.json 声明

1.1 模型别名（agents.defaults.models）

"volcengine-plan/ark-code-latest": {}

1.2 Provider 定义（models.providers）

"volcengine-plan": {
  "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
  "api": "openai-completions",
  "models": [
    { "id": "ark-code-latest", "name": "ark-code-latest", "contextWindow": 256000, "maxTokens": 32000, "input": ["text", "image"] }
  ]
}

apiKey 可选，密钥只需在 auth-profiles.json 写。

1.3 Auth profile 声明（auth.profiles）

"volcengine-plan:default": {
  "provider": "volcengine-plan",
  "mode": "api_key"
}

第 2 步：在 auth-profiles.json 写入密钥（关键！）

路径：~/.openclaw/agents/main/agent/auth-profiles.json

"volcengine-plan:default": {
  "type": "api_key",
  "provider": "volcengine-plan",
  "key": "你的API密钥"
}

第 3 步：重启 gateway

openclaw gateway restart

第 4 步：验证

openclaw models status --json | jq '.auth.providers[] | select(.provider=="volcengine-plan")'
openclaw models list --provider volcengine-plan
/model volcengine-plan/ark-code-latest

检查清单

步骤	文件	必需
Provider 定义	openclaw.json → models.providers	✅
模型别名	openclaw.json → agents.defaults.models	✅
Auth profile 声明	openclaw.json → auth.profiles	✅ 推荐
写入密钥	agents/main/agent/auth-profiles.json	✅ 必需
重启	-	✅
models.json	自动生成	❌

• 补充1：/home/openclaw/.openclaw/agents/main/agent/auth-state.json ——这个文件的作用是记录 Agent 调用各个模型提供商时的认证失败状态和冷却时间，删除后Agent会清除所有认证失败记录，立即重新尝试所有认证配置。
• 补充2：在OpenClaw 05.18的版本上，火山引擎的插件为了兼容，在获取volcengine-plan的apiKey时会默认从 volengine（如果有的话）中的配置取，也就是说是共用一个key，这时要确保火山引擎后台要给这个key打开所有模型权限。