你付了 Claude Pro/Max，Hermes 却还在要 API Key：把订阅接进 Agent 循环

你手上有一个 Claude Max 订阅，平时在终端里用 claude 写代码写得挺顺。于是你想把这套订阅也接到 Hermes 上：让那个会记事的 Agent 用同样的额度干活。结果配置向导问你 API Key，你去订了个按量付费的 key，月底账单和订阅费叠在一起——两个都付了，额度还各管各的。这个别扭的地方现在有官方做法了：把官方 claude 可执行文件本身当成 Hermes 的模型提供方。

它到底做了什么

新插件叫 Claude Subscription DirectSDK (Experimental)，插件名 claude-subscription-directsdk-experimental。它驱动未经修改的官方 Claude Code 可执行文件，把它作为请求级的模型客户端，额度走你的 Claude Pro/Max 订阅；而 Hermes 保留自己的 Agent 循环——工具调用、审批策略、上下文压缩、记忆、技能，全都还是 Hermes 那一套。

名字里的 “DirectSDK” 有点误导：它的实现直接说原生 stream-json 协议，不需要 Python 版 Agent SDK 包。插件自己在 plugin.yaml 的 external_dependencies 里声明了对 claude 的依赖，但不持有任何凭据——认证完全属于官方 CLI。插件从不让 Hermes 打开、复制、刷新或打印 CLI 的凭据文件，也没有“悄悄退回 HTTP + API Key”的降级路径。

它需要什么：

  • Hermes Agent 0.21.4 或更新的版本（或 main 上 118984d7a02f 之后的提交，对应核心侧 PR #117451）。在更老的 Hermes 上插件会加载失败并打出 Failed to load user provider plugin，而不是半死不活地跑着。
  • Python 3.10+（Linux / macOS / Windows 都行；原生运行在独立进程组里，取消时整棵进程树一起结束，所以 npm shim 背后的 node 子进程不会在请求被取消后继续活着）。
  • 已安装并已登录的官方 Claude Code CLI：npm install -g @anthropic-ai/claude-code，然后 claude auth login。

claude 不在时会怎样，插件做得很明确：插件加载时只在日志里留一条警告、提供方仍注册（这样设置流程能解释缺什么）；hermes model 走到这个提供方时直接停下并给出安装提示、不往配置里写任何东西；单次请求会立刻以安装提示失败，而不是丢一个 Popen 的堆栈。

安装与选择

# 1) 官方 CLI（插件自己不存凭据）
npm install -g @anthropic-ai/claude-code
claude auth login

# 2) 从 Hermes 插件目录安装（已钉版本、已审核）
hermes plugins install claude-subscription-directsdk

# 或者直接从 GitHub 装（跟 main）
hermes plugins install NousResearch/hermes-plugin-claude-subscription-directsdk

# 3) 选它
hermes model          # 选 "Claude Subscription DirectSDK (Experimental)"

想按 profile 隔离，插件装在 ~/.hermes/profiles/<profile>/plugins/ 下即可。插件声明了 kind: model-provider，所以 Hermes 的提供方发现机制会直接导入它，不需要往 plugins.enabled 里加条目。

也可以一次性指定跑一次：

hermes --provider claude-subscription-directsdk-experimental -m sonnet

持久化配置就是普通的 provider 键：

model:
  provider: claude-subscription-directsdk-experimental
  default: sonnet

两个环境变量在真实项目里很有用：CLAUDE_CONFIG_DIR（或插件侧的 CLAUDE_SUBSCRIPTION_DIRECTSDK_CONFIG_DIR）指向 CLI 自己管理的认证目录；CLAUDE_SUBSCRIPTION_DIRECTSDK_COMMAND 指向不在 PATH 里的可执行文件。另外，如果启动环境里带着 ANTHROPIC_API_KEY、自定义 Anthropic endpoint 或 cloud-backend 覆盖，Hermes 的客户端路径会在启动子进程之前拒绝——错误里只列出冲突的变量名，不打印它们的值。要用订阅就把这些覆盖从环境里去掉。

一次请求就是一次上游调用：准入中继

这是这个插件最值得理解的部分。原生 Claude Code 2.1.263 在 --max-turns 1 且禁用 HTTP 重试的情况下，仍然可能尝试额外的生成。如果放任不管，Hermes 的一次调用可能对应两次上游请求，账单和用量都会悄悄翻倍。

所以插件在中间放了一个请求级的中继：只转发第一个 Messages 请求，后续尝试在本地被拒绝。对 Hermes 来说，它拿到的是第一份完整的上游响应，连带原生的 usage 与 stop reason；被拦下的原生恢复动作不会把一个已经完成的响应变成异常（截断或不完整的上游 HTTP 错误仍然是失败）。

官方给的资格验证数据可以当作“它真的收敛住了”的证据：一次订阅驱动的整轮评审跑完，7 次 Hermes 调用对应恰好 7 次上游请求，执行了 12 次工具调用、留下 12 条持久化工具结果；上下文从 138,498 增长到 165,697 token，后续请求的缓存读取平均 97.13%；原生记账报出 $0.8793728 的“列表价等价金额”。

幂等性也做了：每次 chat.completions.create 都会在一个私有临时目录里起一个全新进程，原生的工具、技能与设置来源全部禁用；MCP 只播报当前 Hermes 的工具清单，回调是惰性的，并由原生 dontAsk 拒绝执行；系统提示与生成字段通过私有文件传递，绕开操作系统的单个参数长度限制。认证与身份字段永远不被替换。

计费：列表价 ≈ 不等于发票

这一点官方写得很克制，也值得你原样记住：当原生上报的每个模型都带 costBasis: list、且总额有限非负时，Hermes 会把它记为估算的 API 列表价等价金额——它不代表你的订阅账单或额外用量扣费，而且永远不会被标成“免费/已包含”，也不会被替换成猜出来的价格。缺失或无效的最终记账就是“未知”，中断的请求也不能被解释成免费或零 token。

所以两句话：订阅额度与额外用量的开关属于你的账号和原生服务——不想被超额计费就在账号里关掉 extra usage；原生报出的列表价不是订阅扣费的证明。

两个真实的缓存踩坑（以及它们怎么被修的）

这类“自己套一层 CLI”的方案，最容易踩的是 prompt 缓存。官方公开了两次长上下文验证，很值钱：

第一次：真实 Sonnet 5 评审任务的首个请求有 187,049 个输入 token，而下一轮工具调用只从 190,840 个输入 token 里读到了 6,989 个缓存（3.66%），其余 183,849 个 token 被重新写进一小时缓存。同样规模的“完全相同请求”测试是通过的（179K token），因为那个测试没有压到这个回放边界上。

根因是原生 CLI 会在上下文里塞一条 token 预算提醒，而 Hermes 自己拥有预算、回放时会跨缓存边界重建这条提醒——于是前缀不再稳定。修法是禁用原生提醒，不额外加缓存标记、也不改 TTL。修完之后：完成一次 7 调用评审、10 次真实工具执行，上下文从 187K 涨到 212K，后续请求的平均缓存读取 97.99%（把冷启动一起算进去是 85.45%），原生列表价记账 $1.1030034。

这两组数字要连着读：它说明缓存能被打通，也说明 187K 以上的工作负载需要你先量一遍再决定。另外这些是 Sonnet 5 的结果——同一账号上的 Fable 5.1 因为需要付费额度没被这次验证覆盖。

边界与注意

  • 这是评审级构建，不是全功能对等或生产就绪的承诺。 原生 Claude Code 2.1.263 是被认证过的版本；回放确认与 extra-body 行为属于版本敏感接口。
  • 工具名会经过 mcp__hermes__ 映射，原始名字必须是唯一的 ASCII 字母数字/下划线/连字符标识符且不超过 50 个字符。
  • 文本是增量流式的，但完整的工具批次只在助手回合收尾之后发布（等原生 message_stop、最终 usage 和进程退出）；随后 Hermes 才施加自己的钩子、审批、工具与持久化。
  • 原生自动压缩被禁用，压缩权归 Hermes；这不等于所有历史变换或跨模型签名回放都已对等。
  • 辅助模型与回退路由仍然归 Hermes 所有：如果你希望它们也走订阅，需要显式配置；这个提供方不会悄悄改掉你其他已选的提供方。

小结

如果你同时有 Claude Pro/Max 订阅和 Hermes，这个插件把“再买一份 API 额度”变成了可选项：安装三条命令，选择提供方，剩下的是官方 CLI 的原生协议在跑。真正需要你动手的只有两处——订阅账号里的超额设置，以及你自己的环境变量（把 ANTHROPIC_API_KEY 之类的覆盖清干净，别让它在启动时被拒绝）。想先看这个插件依赖的核心侧改动随哪个版本发布，可以读 v0.21.4 都带了什么；模型与提供方的日常操作在 hermes model 命令参考 与 提供方插件钩子 里。