# OpenClaw 配置与调试知识库
## 一、模型智能路由配置
### 核心概念
- OpenClaw 不支持按内容类型自动选模型（除了图片）
- OpenClaw 仅支持图片专用模型配置
### 配置结构
#### 1. `agents.defaults.model`
```json
{
"model": {
"primary": "minimax/MiniMax-M2.5",
"fallbacks": [
"volcengine/ark-code-latest",
"volcengine-deepseek/ep-20260222233553-c82s9"
]
}
}
```
- `primary`: 主模型（日常对话）
- `fallbacks`: 主模型失败时自动用的备用模型
#### 2. `agents.defaults.imageModel`
```json
{
"imageModel": {
"primary": "volcengine-doubao/ep-20260224233623-qj22g",
"fallbacks": ["minimax/MiniMax-M2.5"]
}
}
```
- `primary`: 图片专用模型（检测到图片自动切换）
- `fallbacks`: 图片模型失败时备用
---
## 二、火山引擎豆包 Doubao 配置
### 关键知识点 1：API 类型
- 文本生成：`api: "openai-completions"`
- 多模态（图片理解）：`api: "openai-responses"`
### 关键知识点 2：模型必须标记支持图片
在 `models.providers.<provider>.models[]` 中，必须添加：
```json
{
"id": "ep-20260224233623-qj22g",
"name": "Doubao-Seed-1.8",
"contextWindow": 128000,
"maxTokens": 8192,
"input": ["text", "image"] // ← 必须有这个！
}
```
重要：如果没有 `input: ["text", "image"]`，OpenClaw 会报错：
```
Model does not support images: volcengine-doubao/ep-20260224233623-qj22g
```
---
## 三、完整配置示例
```json
{
"models": {
"mode": "merge",
"providers": {
"volcengine-doubao": {
"baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
"apiKey": "你的API Key",
"api": "openai-responses", // ← 必须是这个
"models": [
{
"id": "ep-20260224233623-qj22g",
"name": "Doubao-Seed-1.8",
"contextWindow": 128000,
"maxTokens": 8192,
"input": ["text", "image"] // ← 必须有这个
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "minimax/MiniMax-M2.5",
"fallbacks": [
"volcengine/ark-code-latest",
"volcengine-deepseek/ep-20260222233553-c82s9"
]
},
"imageModel": {
"primary": "volcengine-doubao/ep-20260224233623-qj22g",
"fallbacks": ["minimax/MiniMax-M2.5"]
}
}
}
}
```
---
## 四、配置后验证
### 重启 OpenClaw
```bash
docker restart OpenClaw
```
### 查看日志
```bash
docker logs OpenClaw --tail 50
```
---
## 五、常见问题与调试
### 问题 1：`Model does not support images`
原因：模型配置没有 `input: ["text", "image"]`
解决：在模型配置中添加 `input: ["text", "image"]`
### 问题 2：`Unrecognized key: "capabilities"`
原因：旧版配置使用 `capabilities`，新版 OpenClaw 用 `input`
解决：删除 `capabilities`，改用 `input`
---
## 六、当前可用模型
| Provider | Model ID | 用途 | 特点 |
|----------|-----------|------|------|
| minimax | MiniMax-M2.5 | 主模型，日常对话 | - |
| volcengine | ark-code-latest | 代码任务 | - |
| volcengine-deepseek | ep-20260222233553-c82s9 | 通用对话 | - |
| volcengine-doubao | ep-20260224233623-qj22g | 图片理解 | 必须有 `input: ["text", "image"]` |
---
## 七、模型引用格式
```
<provider>/<model-id>
```
示例：
- `minimax/MiniMax-M2.5`
- `volcengine-doubao/ep-20260224233623-qj22g`
