从零到一：为 Hermes 配置硅基流动 API 的完整实战

从零到一为 Hermes 配置硅基流动 API 的完整实战一次真实踩坑与填坑的记录如何让 Hermes 优雅地调用硅基流动的 DeepSeek-R1 模型背景Hermes 是一款开源的 AI 代理框架支持多种模型提供商。硅基流动SiliconFlow是国内提供高性价比 API 服务的平台尤其以 DeepSeek 系列模型受到开发者青睐。然而将 Hermes 与硅基流动的自定义端点对接时我遇到了一些典型问题。本文记录了我从安装、配置到最终成功调用的完整过程希望能为遇到类似问题的朋友提供一份可操作的参考。环境准备操作系统macOS / Linux / WSL2本文以 macOS 为例已注册硅基流动账号并获取 API Key格式以sk-开头已安装 Node.js 22 与 Git终端能正常访问硅基流动 API 地址https://api.siliconflow.cn/v1第一步安装 Hermes官方推荐的一键安装命令curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bashsource~/.bashrc# 或 source ~/.zshrc安装完成后会自动启动配置向导。如果之前使用过类似工具如 OpenClawHermes 会询问是否迁移数据——我选择了迁移因为 OpenClaw 中已经配置好了硅基流动的 API Key 和模型。第二步配置自定义端点硅基流动Hermes 的快速设置只包含预设的官方提供商没有“硅基流动”选项。因此需要手动选择Custom endpoint。在向导的提供商选择环节向下滚动并选择Custom endpoint (enter URL manually)或类似选项然后填写Base URLhttps://api.siliconflow.cn/v1API Key粘贴你的硅基流动 API KeyModel name例如Pro/deepseek-ai/DeepSeek-R1注意大小写和前缀API 兼容模式选择Auto-detect或Chat Completions均可完成这些后向导会保存配置到~/.hermes/config.yaml。第三步遭遇“401 API key is invalid”错误运行hermes尝试对话时出现了如下错误⚠️ API call failed: AuthenticationError [HTTP 401] Provider: custom Model: Pro/deepseek-ai/DeepSeek-R1 Endpoint: https://api.siliconflow.cn/v1 Error: HTTP 401: Error code: 401 - Api key is invalid关键信息相同的 API Key 在 OpenClaw 中能正常工作说明 Key 本身有效且账户权限正常。问题出在 Hermes 的配置格式上。排查过程检查 API Key 是否被正确读取尝试用环境变量强制指定SILICONFLOW_API_KEY你的key hermes。结果仍然 401说明不是环境变量问题。查看~/.hermes/config.yaml内容发现两个致命错误model:default:Pro/deepseek-ai/DeepSeek-R1provider:custom# ❌ 错误1应为 custom:hermesbase_url:https://api.siliconflow.cn/v1# ❌ 错误2不应在此处定义api_key:sk-重复了两次的key# ❌ 错误3密钥被粘贴了两遍custom_providers:-name:hermesbase_url:https://api.siliconflow.cn/v1api_key:sk-重复了两次的key# 同样错误model:Pro/deepseek-ai/DeepSeek-R1问题分析Hermes 要求model.provider必须是custom:名称形式其中名称对应custom_providers中某个条目的name。写单纯的custom会导致 Hermes 忽略custom_providers配置。model层级不应该包含base_url和api_key这些字段只应出现在custom_providers中。API Key 被重复粘贴实际发送的 Authorization header 变成了无效字符串。第四步修复配置文件编辑~/.hermes/config.yamlopen-e~/.hermes/config.yaml修正后的关键片段model:default:Pro/deepseek-ai/DeepSeek-R1provider:custom:hermes# ✅ 正确custom:名称# 删除 base_url 和 api_key 行custom_providers:-name:hermesbase_url:https://api.siliconflow.cn/v1api_key:sk-你的正确且未重复的密钥# ✅ 只粘贴一次model:Pro/deepseek-ai/DeepSeek-R1保存文件后重新运行hermes。第五步验证成功输入你好得到模型回复你好bruce_xiaowei我是你的AI助手……同时注意到一个辅助警告⚠ Auxiliary title generation failed: HTTP 401这是因为 Hermes 尝试用另一个未配置的模型为会话自动生成标题不影响正常对话。可通过将auxiliary.title_generation.provider设为none来消除。踩坑总结与建议现象原因解决方案401 Unauthorized但 Key 在其它工具正常model.provider格式错误或api_key被重复/损坏使用custom:名称格式检查api_key无多余字符Could not fetch models from endpoint硅基流动的/v1/models接口不可公开访问手动在custom_providers中指定model字段无需依赖自动获取部分辅助功能报 401辅助模型如 title_generation未配置禁用辅助功能或为其配置同一个 custom provider安全提醒绝对不要在公开场合包括博客、截图、Issue暴露你的 API Key。本文示例中的 Key 已经废弃。如果不慎泄露请立即登录硅基流动控制台删除该 Key 并生成新 Key。推荐使用环境变量SILICONFLOW_API_KEY并在配置中引用${env.SILICONFLOW_API_KEY}而非明文写在config.yaml中。最终效果现在你可以愉快地使用 Hermes 调用硅基流动的各种模型了。常用命令hermes启动交互对话hermes model更换模型或提供商hermes doctor诊断配置问题hermes doctor --fix尝试自动修复部分问题扩展如何更换模型硅基流动提供了丰富的模型库。登录 模型中心 找到你需要的模型 ID如Qwen/Qwen2.5-7B-Instruct然后hermes model# 选择你的 custom provider输入新的模型名或直接编辑~/.hermes/config.yaml修改custom_providers[].model字段。结语配置自定义 API 端点时常会遇到小坑但只要理解配置文件的映射关系就能迎刃而解。希望这篇实战记录能帮助你节省时间顺利跑通 Hermes 硅基流动的组合。如果你有更好的配置技巧欢迎交流讨论。本文基于 2026年5月14日的实际操作整理软件版本及配置格式可能随时间变化请以官方文档为准。