Hermes Agent 接入 Kimi Coding 套餐：修复 Vision 图像分析功能

在使用 Hermes Agent（一个多平台 AI 网关，类似于openclaw）搭配 Kimi Coding 套餐时，我遇到了一个棘手的问题：

图像分析功能（vision）完全无法使用，每次发送图片都会返回 404 错误。

但奇怪的是，文本对话功能一切正常。这说明主模型连接没问题，问题出在 vision 这个辅助功能上。

环境信息

AI 网关: Hermes Agent
主模型: kimi-for-coding
API 端点 : https://api.kimi.com/coding
问题功能: vision（图像分析）

排查过程

第一步：确认错误现象

发送图片后，vision 工具返回：

css 复制代码

Error code: 404 - {'error': {'message': 'Not Found', 'type': 'not_found_error'}}

404 通常意味着请求的端点或资源不存在。

第二步：分析 Kimi Coding 的 API 架构

通过查阅文档和实际测试，我发现 Kimi Coding 套餐同时支持两种 API 协议：

协议	端点	用途
Anthropic 兼容	`https://api.kimi.com/coding`	主对话流，支持 Claude 格式的消息
OpenAI 兼容	`https://api.kimi.com/coding/v1`	标准 OpenAI API 格式

关键发现：

Hermes 主模型配置使用的是 Anthropic 端点（/coding）
但 vision 工具发送的是 OpenAI 格式的 image_url 类型消息
让 OpenAI 格式的消息走 Anthropic 端点，就会 404

第三步：修改 vision 端点配置

在 ~/.hermes/config.yaml 中，找到 auxiliary vision 配置：

修改前：

yaml 复制代码

auxiliary:
  vision:
    provider: auto      # 自动选择，实际走了主模型的 Anthropic 端点
    base_url: ''
    api_key: ''
    model: ''

修改后：

yaml 复制代码

auxiliary:
  vision:
    provider: custom
    base_url: https://api.kimi.com/coding/v1   # 切换到 OpenAI 兼容端点
    api_key: ''
    model: kimi-for-coding
    timeout: 120

第四步：解决 API Key 认证问题

修改端点后，再次测试，这次报错变成了 401 认证失败：

css 复制代码

Error code: 401 - {'error': {'message': 'The API Key appears to be invalid...'}}

排查发现：Gateway 进程没有继承 KIMI_API_KEY 环境变量。

验证方法：

bash 复制代码

# 查看 gateway 进程的环境变量
cat /proc/<gateway_pid>/environ | tr '\0' '\n' | grep -i kimi
# 返回空，说明没有 KIMI_API_KEY

根本原因：

主模型使用 provider: kimi-coding，Hermes 会从 ~/.hermes/auth.json 的 credential_pool 中自动获取认证信息
但 auxiliary vision 配置 provider: custom 时，api_key: '' 表示依赖环境变量，而环境变量不存在

解决方案：从 auth.json 中提取已存储的 API key，直接写入配置文件。

python 复制代码

import json

with open('~/.hermes/auth.json') as f:
    data = json.load(f)

# 从 credential_pool 获取 kimi-coding 的 API key
for cred in data['credential_pool']['kimi-coding']:
    api_key = cred['access_token']
    print(f"Found key: {api_key[:10]}...")

将获取到的 key 写入 config.yaml：

yaml 复制代码

auxiliary:
  vision:
    provider: custom
    base_url: https://api.kimi.com/coding/v1
    api_key: 'sk-kimi-xxxxxxxx'   # 直接写入，不再依赖环境变量
    model: kimi-for-coding
    timeout: 120

第五步：验证修复

再次发送图片测试，vision 分析成功返回结果：

json 复制代码

{
  "success": true,
  "analysis": "这张图片是一张分屏式桌面截图..."
}

最终配置

完整的 ~/.hermes/config.yaml 相关部分：

yaml 复制代码

model:
  default: kimi-for-coding
  provider: kimi-coding
  base_url: https://api.kimi.com/coding          # 主模型走 Anthropic 端点

auxiliary:
  vision:
    provider: custom
    base_url: https://api.kimi.com/coding/v1     # vision 走 OpenAI 兼容端点
    api_key: 'sk-kimi-xxxxxxxx'                  # 显式配置 API key
    model: kimi-for-coding
    timeout: 120
    extra_body: {}
    download_timeout: 30

技术要点总结

1. 双协议端点的理解

Kimi Coding 套餐的 /coding 和 /coding/v1 不是同一个端点：

/coding → Anthropic Messages API 格式
/coding/v1 → OpenAI Chat Completions API 格式

不同工具可能需要不同的协议，不能一刀切。

2. Hermes 的认证机制

Hermes 有两层认证：

层级	配置位置	认证来源
主模型	`model.provider`	auth.json credential_pool / 环境变量
辅助功能	`auxiliary.*.api_key`	显式配置 / 环境变量

陷阱：辅助功能不会自动继承主模型的认证信息，特别是当 provider: custom 时。

3. 图片处理流程

用户发送图片时的内部流程：

bash 复制代码

用户发送图片（飞书/微信等）
  → Gateway 下载图片到 ~/.hermes/images/
  → 生成本地路径如 /home/kali/.hermes/images/clip_xxx.png
  → 调用 vision_analyze(image_url="本地路径")
  → vision 工具读取本地文件，编码为 base64
  → 通过 API 发送给 vision 模型

这里的 image_url 参数既支持 HTTP URL，也支持本地文件路径。

经验总结

404 不一定是资源不存在，可能是协议不匹配 ------ 同样的域名，不同的路径，支持不同的 API 格式
环境变量不是万能的 ------ 后台进程（如 systemd 启动的 gateway）可能无法继承 shell 的环境变量
显式配置优于隐式依赖 ------ 关键认证信息直接写入配置文件，避免依赖运行时环境
多协议 API 需要仔细匹配 ------ 使用第三方工具时，确认其发送的消息格式与端点期望的格式一致

参考

Kimi Coding API 文档
Hermes Agent 文档
OpenAI Vision API 格式规范
Anthropic Messages API 格式规范