查看“︁OpenClaw手动配置火山引擎方舟coding plan”︁的源代码

<markdown style="gemini">
# 添加 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`）

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

### 1.2 Provider 定义（`models.providers`）

```json
"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`）

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

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

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

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

## 第 3 步：重启 gateway

```bash
openclaw gateway restart
```

## 第 4 步：验证

```bash
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 | 自动生成 | ❌ |


- 补充：/home/openclaw/.openclaw/agents/main/agent/auth-state.json 
——这个文件的作用是记录 Agent 调用各个模型提供商时的认证失败状态和冷却时间，删除后Agent会清除所有认证失败记录，立即重新尝试所有认证配置。
</markdown>