你的Hermes Agent 看不了图片？免费方案来了
Hermes Agent 配置免费 Vision 模型
不用花钱，不用信用卡，让 Hermes Agent 拥有"眼睛"。
很多 Hermes Agent 用户发现：Agent 能写代码、能查资料、能发公众号，但发张图过去，它却看不见。这不是 Agent 的问题，而是 vision 模型没配好。
本文手把手教你配置免费的 vision 模型，让 Hermes Agent 零成本拥有图像理解能力。
一、为什么需要 Vision 模型
Hermes Agent 的 vision_analyze 工具负责看图。但它本身不会"看"——它需要调用一个支持多模态（Multimodal）的 LLM，把图片传过去，模型返回文字描述。
没有 vision 配置时：
-
你发一张截图，Agent 说"我看不见"
-
你发一张设计稿，Agent 无法分析
-
你发一张报错截图，Agent 只能干瞪眼
配好 vision 后：
-
截图直接分析，提取文字、识别界面元素
-
设计稿自动描述布局、颜色、风格
-
照片识别物体、场景、人物动作
二、免费 Vision 模型来源
目前最稳定的免费 vision 来源是 OpenRouter。它是一个模型聚合平台，把 Google、NVIDIA、Meta 等厂商的模型统一暴露成 OpenAI 兼容的 API。
OpenRouter 免费模型特点：
-
无需信用卡，注册即送额度
-
部分模型标有
:free后缀，完全免费 -
自动路由（
openrouter/free）会根据你的请求智能选择可用模型
支持 Vision 的免费模型（截至 2026 年 5 月）：
google/gemma-3-27b-it:free Vision Google 开源模型
google/gemma-3-4b-it:free Vision 轻量版
nvidia/nemotron-nano-12b-v2-vl:free Vision + Tools NVIDIA 出品
openrouter/free 自动路由 智能选择可用模型
注意：免费模型随时可能下线或限流。如果某个模型报 404 No endpoints found，换另一个即可。
三、配置步骤
步骤 1：获取 OpenRouter API Key
-
访问 openrouter.ai/keys[1]
-
用邮箱或 Google 账号注册（免费）
-
点击 Create Key，复制生成的 Key
-
格式类似：
sk-or-v1-xxxxxxxx
步骤 2：配置 Hermes Agent
Hermes Agent 的配置分两层：
-
~/.hermes/config.yaml— 主配置文件 -
~/.hermes/.env— 环境变量（敏感信息放这里）
推荐做法：Key 放 .env，模型配置放 config.yaml。
3.1 编辑 config.yaml
找到 auxiliary.vision 部分，改成：
auxiliary:
vision:
provider: openrouter
model: openrouter/free # 自动路由，免费用
base_url: https://openrouter.ai/api/v1
api_key: '' # 从 .env 读取
timeout: 120
extra_body: {}
download_timeout: 30配置说明：
provider 指定用 openrouter
model openrouter/free 自动选免费模型；也可写死具体模型
base_url OpenRouter API 地址
api_key 留空表示从 .env 的 HERMES_VISION_API_KEY 读取
3.2 编辑 .env
在 ~/.hermes/.env 末尾追加：
# Vision 配置 - OpenRouter 免费模型
HERMES_VISION_PROVIDER=openrouter
HERMES_VISION_MODEL=openrouter/free
HERMES_VISION_API_KEY=sk-or-v1-你的Key注意：.env 是敏感文件，Hermes 会保护它不被随意修改。如果 patch 工具拒绝写入，用终端命令追加：
cat >> ~/.hermes/.env << 'EOF'
HERMES_VISION_PROVIDER=openrouter
HERMES_VISION_MODEL=openrouter/free
HERMES_VISION_API_KEY=sk-or-v1-你的Key
EOF步骤 3：验证配置
配置完成后，重启 Hermes Agent 让新配置生效。
然后测试 vision：
# 在 Hermes 对话中发一张图
# 或者说："vision_analyze 这个图片"如果配置正确，Agent 会返回图片内容描述。
四、常见问题排查
问题 1：401 Missing Authentication
原因：API Key 没传过去。
解决：
-
检查
.env里的HERMES_VISION_API_KEY是否正确 -
检查
config.yaml里api_key是否留空（让系统从.env读取） -
如果直接写在
config.yaml，确保格式：api_key: 'sk-or-v1-xxx'
问题 2：404 No endpoints found
原因：你指定的免费模型当前不可用（额度用完或下线）。
解决：
-
换模型，比如从
google/gemma-3-27b-it:free换成openrouter/free -
openrouter/free是自动路由，会自动跳过不可用的模型
问题 3：配置改了但没生效
原因：Hermes Agent 启动时把配置读进内存，运行中修改不会热加载。
解决：重启 Hermes Agent。
问题 4：Key 泄露风险
原因：把 API Key 直接写在 config.yaml 里，可能随截图或代码提交泄露。
解决：
-
Key 只放在
.env里 -
.env加入.gitignore -
config.yaml里的api_key留空
五、进阶：指定具体模型
如果你不想用自动路由，可以指定具体模型：
auxiliary:
vision:
provider: openrouter
model: google/gemma-3-27b-it:free
base_url: https://openrouter.ai/api/v1
api_key: ''或者换付费但便宜的模型：
model: openai/gpt-4o-mini # $0.15/1M tokens，看图一次几分钱六、总结
1 注册 OpenRouter，获取免费 Key
2 修改 ~/.hermes/config.yaml，设置 auxiliary.vision
3 修改 ~/.hermes/.env，写入 HERMES_VISION_API_KEY
4 重启 Hermes Agent
5 发图测试
核心原则：
-
免费模型用
openrouter/free，自动路由最省心 -
敏感信息放
.env，配置放config.yaml -
404 就换模型，401 就检查 Key
配好后，Hermes Agent 就能看懂截图、分析设计稿、识别照片内容了——完全免费。
引用链接
[1]openrouter.ai/keys: https://openrouter.ai/keys
[3]https://hermes-agent.nousresearch.com/docs