hermes agent集成google gemini需正确配置api密钥、指定多模态模型（如gemini-1.5-pro-latest）、启用multimodal:true及vision_tools、校验文件格式，并在中国大陆使用合规中转服务。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望在Hermes Agent中集成Google Gemini模型，但调用失败或无法启用图像、音频等多模态能力，则很可能是由于AI Studio密钥未正确配置或模型版本选择不当。以下是实现完整集成的具体操作路径：
一、获取并验证Gemini API密钥有效性
API密钥是Hermes Agent与Google后端通信的身份凭证，必须通过Google AI Studio生成且处于激活状态，否则所有请求将返回401错误。请确保密钥所属项目已启用Gemini API服务，并检查配额是否未耗尽。
1、访问Google AI Studio密钥管理页，使用已绑定Billing账户的Google账号登录。
2、点击“Create API key”，在弹出窗口中选择已有项目（如无，请先创建新项目并启用Gemini API）。
3、生成后立即复制密钥字符串，该密钥明文仅显示一次，刷新页面即不可见。
4、在浏览器中打开模型列表验证接口，将YOUR_KEY替换为刚复制的密钥，确认返回包含gemini-1.5-pro-latest、gemini-2.0-flash、gemini-pro-vision等型号的JSON响应。
二、在Hermes Agent中注入密钥与指定模型
Hermes Agent不支持图形界面输入密钥，必须通过环境变量方式注入，且需显式声明使用Gemini模型及其多模态变体，否则默认调用文本模型导致图像上传失败。
1、在终端中执行命令设置临时环境变量：export GEMINI_API_KEY="sk-gem-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"。
2、启动Hermes Agent前，确认当前Shell会话中已加载该变量：echo $GEMINI_API_KEY应输出非空值。
3、运行hermes setup进入配置向导，当提示选择模型提供商时，使用方向键选中“Google Gemini”，按回车确认。
4、在模型名称输入栏中，必须手动输入gemini-1.5-pro-latest或gemini-pro-vision，不可留空或使用默认值。
三、启用多模态输入通道与文件兼容性校验
即使密钥与模型配置正确，若未激活多模态处理链路，Hermes Agent仍将拒绝接收图像、PDF等非文本内容。该步骤依赖底层工具模块的显式加载和格式白名单控制。
1、编辑Hermes Agent主目录下的config.yaml文件，在llm节下添加字段：multimodal: true。
2、在tools节中确认已启用vision_tools.py和file_parser.py，二者分别负责图像特征提取与文档结构化解析。
3、上传测试图像前，使用file dog.jpg命令检查本地文件元信息，确认输出中包含JPEG image data且尺寸小于20MB。
4、在对话中发送指令时，必须采用Gemini原生支持的图文混合格式，例如：["描述这张图中的交通状况", upload_file("traffic.jpg")]，不可将图像路径作为纯文本字符串传递。
四、绕过地域限制的合规中转配置
针对中国大陆地区用户，直接连接Google API端点可能因网络策略触发超时或TLS握手失败。此时需切换至兼容协议的中转服务，同时保持请求头与载荷结构与官方完全一致，避免模型识别异常。
1、注册合规中转平台（如kulaai.cn），完成实名认证并获取中转密钥。
2、在config.yaml中修改base_url字段为中转服务地址，例如：https://api.kulaai.cn/v1beta。
3、将中转密钥写入GEMINI_API_KEY环境变量，而非原始Google密钥。
4、在llm节中添加proxy_enabled: true标识，强制Hermes Agent跳过直连校验逻辑。
五、调试多模态响应失败的定位步骤
当图像上传成功但模型返回空响应或“unsupported media type”错误时，问题通常位于内容编码层或上下文组装阶段，需逐级剥离验证。
1、在agent/prompt_builder.py中临时插入日志，打印contents参数结构，确认其为列表类型且首元素含parts字典。
2、检查图像是否被正确转换为Base64字符串或genai.upload_file返回的File对象，二者不可混用：gemini-pro-vision接受File对象，而REST API仅接受Base64。
3、调用model.count_tokens方法传入待发送内容，若抛出ValueError，说明输入结构不符合Gemini多模态schema。
4、捕获response.candidates[0].content.parts实际返回内容，判断是否为空列表或含inline_data字段缺失。
