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

2026-05-17 15:50:06 Bruce_xiaowei

背景

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 -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。

第三步：遭遇“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-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的资料请关注脚本之家其它相关文章！