Hermes Agent 接入 Kimi Coding 套餐：修复 Vision 图像分析功能购买了kimi codin

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

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

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

环境信息

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

排查过程

第一步：确认错误现象

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

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 配置：

修改前：

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

修改后：

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

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

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

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

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

验证方法：

# 查看 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，直接写入配置文件。

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：

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

第五步：验证修复

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

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

最终配置

完整的 ~/.hermes/config.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. 图片处理流程

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

用户发送图片（飞书/微信等）
  → 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 格式规范