Hermes Agent BYOK 配置指南：自带密钥一步步接入

BYOK 对 Hermes Agent 究竟意味着什么

Hermes Agent 天生就是 BYOK 架构。你把它指向任何已经拥有凭据的服务商，每一次推理调用都直接计入你在该服务商的账户，而不是记在一个会给 token 加价的中间层上。这不是绕过付费墙的小把戏，而是这个智能体的默认姿态：与模型无关、与服务商无关，并倾向于把数据托付给你真正信任的后端。

一开始有两点常常让人困惑。第一，Hermes 的 BYOK 既包括真正的 LLM API 密钥（OpenAI、Anthropic、OpenRouter、Kimi、MiniMax 以及其他很多家），也包括 OpenAI 兼容的接口，也就是说自托管的 vLLM 或 Ollama 同样算数。第二，BYOK 是按后端配置的，不是全有或全无。你可以在同一个智能体上，用 Anthropic 做推理，用 Ollama 做便宜的后台摘要，只要把两个都配好即可。

本指南接下来会带你完成选型、把密钥安全放好，以及日后无需重建配置就能切换服务商。

为什么 BYOK 比"免费 API 额度"更值得关心

每个 AI SaaS 最终都会要求你信任它那把不透明的共用密钥。BYOK 打破了这套模式。凭据是你的、账单是你的、数据留存策略是你的、审计日志也是你的。就算平台明天消失，你在服务商那里的账户仍然能用。

按在真实 Hermes 部署里出现的频率来看，BYOK 带来的实际好处依次是：

数据控制。 服务商侧的日志、留存规则以及 Zero Data Retention 条款，由你和模型服务商之间的协议决定，而不是由智能体供应商谈下来的默认条件决定。
成本透明。 你和模型之间没有任何隐藏加价。用 OpenRouter 时，你看到的每 token 单价，就是你直接用 curl 调用会看到的价格。
摆脱厂商锁定。 更换服务商是改两行配置的事，而不是一个迁移项目。hermes model 命令能让你在 Claude、GPT、Gemini 或 Llama 之间切换，不需要动技能和记忆。
随时可关的开关。 密钥泄漏或账单飙升时，直接在服务商控制台旋转密钥即可。智能体几秒内就停下来，也不用别人来批准你的这次轮换。

对 Hermify 的 Starter 套餐来说，BYOK 就是整个卖点。这个档位的设计思路正是"你带密钥，我们跑容器"。所以就算你以后打算改用托管服务，先把下面这套配置学会也很值得。

一步步为你的第一个 BYOK 服务商完成配置

Hermes 至少需要一个已经配好的服务商才能运行。摩擦最小的路径是 OpenRouter（一把密钥、成百上千个模型），但对 OpenAI、Anthropic 以及其他所有受支持的后端，机制都是一样的。

1. 在服务商处获取一把密钥

选一个，然后在服务商的控制台里生成一把密钥：

OpenRouter，网址 openrouter.ai。密钥以 sk-or- 开头。BYOK 场景下默认的最佳选择。
OpenAI，网址 platform.openai.com。密钥以 sk- 开头。
Anthropic，网址 console.anthropic.com。密钥以 sk-ant- 开头。
Kimi、MiniMax、GLM、Nous Portal 等，流程一致：注册、生成密钥、复制一次。
Ollama 或 vLLM 跑在你自己的机器上。不需要密钥，只需要 OpenAI 兼容接口的 URL。

在服务商处充值或绑定支付方式。如果账户余额为零，Hermes 会在第一次推理调用时抛出清晰的错误提示。

2. 运行交互式配置

在部署 Hermes 的机器上打开终端：

hermes setup

从列表里选服务商，粘贴密钥，选一个模型。Hermes 会替你把配置写好。

如果你更喜欢脚本化操作，同样的事情没有提示：

hermes config set OPENROUTER_API_KEY sk-or-你的密钥
hermes config set MODEL "anthropic/claude-sonnet-latest"

模型 ID 里的 ~ 前缀（如 ~anthropic/claude-sonnet-latest）表示"这一系列的最新版本"，这样就不用自己手动追新版本快照了。

3. 记住密钥存在哪里

Hermes 有意把机密信息和常规配置分开存放：

机密存在 ~/.hermes/.env 中（权限设为 600，只有当前用户能读）。
服务商名、模型和功能开关 存在 ~/.hermes/config.yaml 中，可以放心加入版本控制。

这种拆分很重要。你可以把 config.yaml 放进私有仓库或 dotfiles 里，在另一台机器上重现 Hermes 的安装，然后从环境变量或密钥管理器里加载密钥，永远不用把明文写到磁盘上。

如果你要把配置纳入版本控制，请把 ~/.hermes/.env 加进 .gitignore。如果你使用密钥管理器（1Password CLI、doppler、sops、Bitwarden），可以在启动时生成 .env，而不是把密钥长期留在磁盘上。

4. 验证一切正常

用 Hermes 发一次冒烟测试：

hermes chat "打个招呼，并告诉我你是什么模型"

如果密钥错了、账户没额度或接口不可达，错误会告诉你是哪一种。修好后再试。在服务商顺畅返回之前，先不要动技能、定时任务或记忆调优。

如何为你的场景挑选合适的服务商

第一次选完不代表就锁死。但第一次的选择很关键，因为它会决定 Hermes 能做到多少记忆、工具调用和长上下文工作。

想要零摩擦、"能跑就行"： OpenRouter 搭 ~anthropic/claude-sonnet-latest。一把密钥、一份账单、切换模型也很方便。
你已经有 OpenAI 或 Anthropic 账户： 直接接原生服务商。每 token 单价通常比走 OpenRouter 略低，但没有跨服务商的 fallback。
想留在 Nous Research 基础设施上： Nous Portal 是官方推荐的路径，天然贴合 Hermes 的 system prompt。
想在本地跑： 把 Ollama 或 vLLM 作为 OpenAI 兼容接口。每 token 零成本，但需要有 GPU 的机器，而且必须选一个真正支持工具调用的模型，否则对智能体没用。
需要严格的数据隔离： 直接用 Anthropic（可申请 Zero Data Retention），或者用自托管接口。如果这是首要目标，就不要走聚合服务。

Hermes 需要一个至少 64K 上下文 token 的模型，因为持久记忆文件（MEMORY.md、USER.md、技能）会在每次调用时被注入。小上下文模型会悄悄截断内容，从而破坏那条让 Hermes 区别于无状态聊天机器人的记忆循环。

如果想深入了解模型本身该怎么选，可以看如何为 Hermes Agent 配置 OpenRouter。

需要避开的配置错误

在第一次做 BYOK 配置时，常有几种模式让人翻车：

把 .env 文件提交上去。 最常见的错误。就算 GitHub 上的"私有"仓库，也不是存放 sk- 密钥的安全地方。第一天就把 .env 加进 .gitignore。
选了不支持工具调用的模型。 OpenRouter 上有些便宜模型不能调用工具。Hermes 要靠工具调用来写文件、抓网页、跑定时任务和使用 MCP。如果技能开始悄无声息地失效，先去检查模型的能力标记。
服务商账户预算太紧。 服务商会在额度低于某个阈值时暂停请求。在 OpenRouter 上设置自动充值下限，或在 OpenAI 里配置余额告警，别让长跑的 Hermes 定时任务凌晨三点挂掉。
把密钥留在 shell 历史里。 hermes config set OPENROUTER_API_KEY sk-or-... 默认会被写进 .bash_history。更稳妥的是用 hermes setup（交互式，不写历史），或者让 shell 忽略以空格开头的命令行，再在命令前加一个空格。
以为一把密钥能覆盖所有事。 那些自己需要凭据的 MCP 工具（比如 GitHub token、Notion API 密钥）是独立的 BYOK 槽位。LLM 的密钥并不能解锁它们。
不做轮换。 在日历里加一个每 90 天的提醒，去轮换服务商密钥。hermes config set 会干净利落地覆盖旧值。

如果卡住了，Hermes Agent 在 Telegram 上的故障排查指南从头到尾覆盖了常见的失败模式。

用托管服务时又会变成怎样

上面这些都是 Hermes 自托管安装长什么样。如果你通过 Hermify 部署，BYOK 模式完全相同（你的密钥、你的账单、你的数据），只是所有操作都搬进了控制台：

在引导流程里把 OpenRouter、OpenAI 或 Anthropic 的密钥粘贴一次即可。
Hermify 会静态加密并在容器启动时注入。它不会出现在日志里，也不会在保存后回显，需要时可以干净地轮换。
直接在控制台切换模型，不需要通过 SSH 进去。改动会在下一次智能体重启时生效，而重启只需要点一下。
Starter 套餐是按纯 BYOK 设计的。Pro 和 Dedicated 会附带一把托管密钥，方便你完全跳过在服务商那边注册，但你依然可以自带密钥。

关键在于：BYOK 并不是自托管才有的功能，它是一种姿态：凭据是你的、数据是你的、开关也是你的。托管服务保留了这一点，只是替你处理周边的运维。

现在就开始

如果你要自托管，就跑 hermes setup，粘贴密钥，搞定。如果你想要同样的 BYOK 模式但不想管容器维护，那就从 Hermify 开始，约一分钟就能在 Telegram 上线。

不管哪种方式，都让密钥留在你自己这边。BYOK 就是为此而生的。