为Hermes配置硅基流动API的完整实战

目录

• 背景
• 环境准备
• 第一步：安装 Hermes
• 第二步：配置自定义端点（硅基流动）
• 第三步：遭遇“401 API key is invalid”错误
• 排查过程
• 第四步：修复配置文件
• 第五步：验证成功
• 踩坑总结与建议
• 安全提醒
• 最终效果
• 扩展：如何更换模型？
• 结语

Hermes 是一款开源的 AI 代理框架，支持多种模型提供商。硅基流动（SiliconFlow）是国内提供高性价比 API 服务的平台，尤其以 DeepSeek 系列模型受到开发者青睐。然而，将 Hermes 与硅基流动的自定义端点对接时，我遇到了一些典型问题。本文记录了我从安装、配置到最终成功调用的完整过程，希望能为遇到类似问题的朋友提供一份可操作的参考。

• 操作系统：macOS / Linux / WSL2（本文以 macOS 为例）
• 已注册硅基流动账号，并获取 API Key（格式以 sk- 开头）
• 已安装 Node.js 22+ 与 Git
• 终端能正常访问硅基流动 API 地址 https://api.siliconflow.cn/v1

官方推荐的一键安装命令：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc   # 或 source ~/.zshrc

安装完成后，会自动启动配置向导。如果之前使用过类似工具（如 OpenClaw），Hermes 会询问是否迁移数据——我选择了迁移，因为 OpenClaw 中已经配置好了硅基流动的 API Key 和模型。

Hermes 的快速设置只包含预设的官方提供商，没有“硅基流动”选项。因此需要手动选择 Custom endpoint。

在向导的提供商选择环节，向下滚动并选择 Custom endpoint (enter URL manually)（或类似选项），然后填写：

• Base URL：https://api.siliconflow.cn/v1
• API Key：粘贴你的硅基流动 API Key
• Model name：例如 Pro/deepseek-ai/DeepSeek-R1（注意大小写和前缀）
• API 兼容模式：选择 Auto-detect 或 Chat Completions 均可

完成这些后，向导会保存配置到 ~/.hermes/config.yaml。

运行 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-R1
  provider: custom          # ❌ 错误1：应为 custom:hermes
  base_url: https://api.siliconflow.cn/v1   # ❌ 错误2：不应在此处定义
  api_key: sk-重复了两次的key   # ❌ 错误3：密钥被粘贴了两遍
custom_providers:
  - name: hermes
    base_url: https://api.siliconflow.cn/v1
    api_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.yaml：

open -e ~/.hermes/config.yaml

修正后的关键片段：

model:
  default: Pro/deepseek-ai/DeepSeek-R1
  provider: custom:hermes          # ✅ 正确：custom:名称
  # 删除 base_url 和 api_key 行
custom_providers:
  - name: hermes
    base_url: https://api.siliconflow.cn/v1
    api_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 + 硅基流动的组合。如果你有更好的配置技巧，欢迎交流讨论。

以上就是为Hermes配置硅基流动API的完整实战的详细内容，更多关于Hermes配置硅基流动API的资料请关注风君子博客其它相关文章！