# Agnes 模型图片/视觉能力配置说明

> 适用版本：OpenClaw ≥ v0.2.26
> 更新日期：2026-06-26

---

## 一、核心配置

在 `openclaw.json` 的 `models.providers` 中添加 agnes 提供商：

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "agnes": {
        "baseUrl": "https://apihub.agnes-ai.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "api": "openai-completions",
        "timeoutSeconds": 300,
        "models": [
          {
            "id": "agnes-2.0-flash",
            "name": "Agnes 2.0 Flash",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 384000
          },
          {
            "id": "agnes-1.5-flash",
            "name": "Agnes 1.5 Flash",
            "input": ["text"],
            "contextWindow": 1000000,
            "maxTokens": 384000
          }
        ]
      }
    }
  }
}
```

## 二、关键配置项说明

### 1. `"input": ["text", "image"]` — 启用视觉能力

这是**最关键**的配置。在 model 条目中设置 `input` 数组包含 `"image"`，OpenClaw 就知道该模型支持图片输入。

- `["text"]` — 仅文本，不支持图片
- `["text", "image"]` — 支持图文混合输入（多模态/视觉）

### 2. `"api": "openai-completions"` — API 适配器

Agnes 的 API 兼容 OpenAI Completions 格式，所以使用 `openai-completions` 适配器。

### 3. `"baseUrl"` — 端点地址

`https://apihub.agnes-ai.com/v1` 是 Agnes 的 API 基础地址，遵循 OpenAI 兼容格式。

### 4. `"timeoutSeconds": 300` — 超时设置

图片输入可能耗时较长，建议设置为 300 秒（5 分钟）。默认约 120 秒，处理大图或复杂图片可能超时。

## 三、图片输入的工作方式

当模型配置了 `"input": ["text", "image"]` 后，OpenClaw 会自动：

1. **识别图片意图**：用户发送图片时，OpenClaw 知道 agnes-2.0-flash 支持图片
2. **自动调用 image 工具**：将图片传给 agnes 模型进行分析
3. **返回分析结果**：模型返回对图片的理解和分析

### 使用方式

用户只需在对话中发送图片即可，OpenClaw 会自动处理。无需额外配置。

## 四、两个实例的配置差异

### QClaw 嵌入式（main agent，端口 11154）

配置文件：`C:\Users\jayxu\.qclaw\openclaw.json`

agnes 配置已包含 `agnes-2.0-flash`（支持 text + image）和 `agnes-1.5-flash`（仅 text）。

### 独立版（TraeProject，端口 15512）

配置文件：`D:\TraeProject\myOpenclaw\.openclaw\openclaw.json`

同样配置了 agnes 提供商，包含：
- `agnes-2.0-flash` — 文本+图片
- `agnes-1.5-flash` — 仅文本
- `agnes-image-2.1-flash` — 生图
- `agnes-image-2.0-flash` — 生图
- `agnes-video-v2.0` — 生视频（独立 provider "agnes-video"）

## 五、注意事项

1. **API Key 保密**：apiKey 是敏感信息，不要在公开场合分享
2. **图片大小限制**：虽然配置中未显式设置，但实际 API 可能有图片大小限制
3. **生图/生视频**：`agnes-image-*` 和 `agnes-video-*` 模型的 `input` 仅为 `["text"]`，它们是输出型模型（生成图片/视频），不支持图片输入
4. **模型选择**：如果需要图片理解，必须使用 `agnes-2.0-flash`，不能用 `agnes-1.5-flash`

## 六、验证配置是否生效

配置完成后重启 gateway（热重载），可以通过以下方式验证：

1. 在对话中发送一张图片
2. 如果 agnes-2.0-flash 是默认模型，它会自动分析图片
3. 如果配置正确，你会看到模型对图片的描述和分析