Hermes Agent

在 ~/.hermes/config.yaml 里写一个命名提供商——api https://api.kunavo.com，transport anthropic_messages，用 provider: custom:kunavo 选中——就能让 Hermes Agent 通过 Messages 协议跑在 Claude 上，在这种协议下它会自己发送缓存标记和输出上限。

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

分步操作

1. 在 /app/keys 创建密钥并复制——它只会显示一次。
2. 把它存到 Hermes 保存机密的地方：hermes config set KUNAVO_API_KEY sk-kn-... 会把它写入 ~/.hermes/.env。配置块里的 key_env 一行只写这个变量的名字；密钥本身不会进入 config.yaml。
3. 把配置块加到 ~/.hermes/config.yaml——用 hermes config edit 可以打开它。如果里面已经有 model: 一节，只替换其中的 default 和 provider，其余保持不变。
4. 也可以让向导来写：在终端里（不要在聊天会话中）运行 hermes model，选择 Custom endpoint (self-hosted / VLLM / etc.)，然后依次回答它的提问——API 基础 URL、密钥、模型名称、API 模式和上下文长度。
5. 启动 hermes 并查看启动横幅：那里会显示模型及其上下文窗口，两者都应与配置块一致。
6. 发送两条消息，然后打开 /usage 查看这两轮的用量。要在会话中更换模型，使用 /model custom:kunavo:claude-opus-5-5。

已于 2026年10月5日 对照 Hermes Agent 的 AI 提供商页面 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 Hermes Agent 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

OpenAI 兼容协议

同一个密钥通过 /v1/chat/completions 还能调用其他所有模型系列，这时用 Hermes 文档里最短的写法就够了——一个带 provider: custom 和 base_url 的 model: 块，hermes model 询问的也正是这些：

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

这里的基础 URL 保留 /v1，Hermes 的文档在本地服务器示例中用的就是这种写法；context_length 则把窗口固定下来，Hermes 不必再去检测。想同时保留两种协议的配置，就给这一种单独建一个命名条目——transport: chat_completions——再用 /model custom:<name>:<model> 切换。

两种协议下的提示缓存

在 Anthropic 协议下，缓存标记由 Hermes 自己附加。对于自定义提供商，它的模型配置页面记载了上面配置块里用到的开关——模型上的 prompt_caching: true——并说明布局取决于传输方式：anthropic_messages 用原生块，OpenAI 兼容协议用封装（envelope）布局。Kunavo 的 /v1/messages 会原样转发请求体，自己不添加任何断点，所以在这种协议下，标记要么来自 Hermes，要么就没有。

缓存能保留多久，是 Hermes 的文档对自定义端点没有说明的部分。prompt_caching.cache_ttl——5m、1h 或 auto——的说明针对的是通过原生 Anthropic API、OpenRouter 和 Nous Portal 使用 Claude 的情况，对其他端点只字未提。Kunavo 会转发收到的任何一种标记，并按同一费率对写入计费，所以答案要从你自己的用量里读：停顿十分钟之后的一轮如果仍然显示缓存读取，说明它用的是一小时的缓存条目。

在 OpenAI 兼容协议下，只要提示词长到可以缓存，Kunavo 就会自己为 Claude 模型放置断点——在系统提示词、工具定义和对话末尾——无论客户端是否发送标记。GPT 模型则由其厂商隐式缓存。

不管断点由哪一端放置，账单的算法都一样。在 Claude Sonnet 5 上，缓存读取是每 1M token $0.14，而新输入是 $1.40；缓存写入是 $1.75——这是 Claude 在输入价之上的写入溢价，条目要求一小时有效期时也按这同一费率收取。一个条目保留五分钟，每次读取都会给它续期，所以智能体要付多少，与其说取决于模型，不如说取决于它的下一个请求能否在这个窗口内到达。每个模型的缓存费率见提示缓存页面。

Hermes 有一种行为比任何费率都更费钱：它的文档指出，在会话中途切换模型、自动回退或轮换凭据都会重置提示缓存，于是下一条消息要按完整的输入价格把整个对话重新读一遍。长会话开始之前就把模型选好。

常驻智能体一天要花多少

在 Hermes 上，没人输入时仍在计费的，是你排定的那些任务，再加上每次对话都会触发的辅助任务。它的cron 文档说，每次定时运行都会开启一个全新的会话，所以每触发一次，都要为整个提示词计费——指令、工具 schema、附带的技能。这个提示词有多大取决于你的配置，所以下表是一个明说的假设：每次运行 20,000 个 token，每 30 分钟运行一次，即每天 48 次。请把这两个数换成你自己的。

有三项设置能改变这个数字，都出自 Hermes 自己的文档。定时任务跑在为该任务单独指定的模型上，没有指定就用 cron.model，再没有才用主模型——所以设置 hermes config set cron.model claude-haiku-4-5 就能让所有没有单独指定模型的任务离开贵的那一档。任务脚本如果输出 {"wakeAgent": false}，这一次触发就跳过模型；no-agent 任务则从不调用模型。至于辅助任务——压缩、标题、视觉——都跑在主模型上，除非用 auxiliary 把它们路由到别处：

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

窗口很大时，要紧的是 threshold_tokens。压缩默认在上下文长度用到一半时开始，而 Hermes 的文档给出的办法正是用这项设置，为单次调用的费用设一个固定的上限。

智能体真正在干活的那些小时是账单的另一半，这一半由缓存说了算。以连续 100 个请求为例，每个请求都重新发送 100,000 个 token 的上下文，外加 2,000 个新 token，并返回 800 个 token 的输出。在 Claude Sonnet 5 上，上下文从缓存读取时约为 $2.31；每个请求都把它当作新输入计费时约为 $14.84。同样的工作，同样的模型：差别只在于断点有没有放，以及请求之间的间隔是否不到五分钟。

再给一个量级，这是实测而非假设：在运行常驻智能体的 Kunavo 账户中，活跃日的花费中位数是 $12.67，第 90 百分位的一天约为 $163。这些是截至 2026年10月5日 实际计费的金额，按各自当天生效的费率计算。这组账户数量不多，所以请把它看作范围有多宽，而不是对你的智能体的预测。

余额用完时

Kunavo 是预付费的：每次调用都从钱包里扣，而一个在你睡觉时干活的智能体，也会在你睡觉时把钱包花空。钱包付不起的请求会被拒绝，返回 HTTP 402 和错误码 insufficient_balance，两种协议都一样，并且不为它收取任何费用。拒绝会在钱包归零之前就出现：每个请求都要先预留它在最坏情况下的费用，也就是提示词加上它被允许生成的最长回复，所以智能体要求的输出上限越大，它的调用就越早开始被退回。错误信息会用 balance_usd 和 needed_usd 说明还差多少。

Hermes Agent 应对提供商故障的办法是回退链：config.yaml 里的 fallback_providers，用 hermes fallback 管理，逐轮尝试。它的文档列出了会让主模型触发回退的情况——速率限制、服务器错误、认证失败和 404——并把 HTTP 402 列在会让辅助任务沿自己的回退链往下走的容量类错误之中；至于没有配置回退时，一轮对话遇到 402 会怎样，文档没有说。请按最直白的理解来做打算——这一轮会失败，定时任务也一样——并记住，真发生回退的那一轮要从冷的提示缓存开始。

有两项设置能让无人值守的智能体不落到这种境地，它们各管各的事：

• 自动充值，在充值与账单页面里。保存一次银行卡，再设三个数：余额低于多少时充值、每次充多少，以及月度上限。此后，只要某次调用让余额跌破阈值，钱包就会在几秒内自动补上。钱包仍然不够时到达的请求，会等这笔扣款完成后照常得到处理，而不是被拒绝。扣不了款（银行卡被拒、月度上限已到）时，或者单个请求要预留的金额超过充值后的钱包余额时，仍会返回 402。它需要银行卡或 Link——Alipay、WeChat Pay、Pix 等本地支付方式无法自动扣款。
• 密钥的月度上限，在API 密钥页面里。给智能体单独一个密钥，并设定这个密钥在一个自然月里最多能花多少。超过这个数之后，它的调用会被拒绝并返回 402，不收取任何费用，而你的其他密钥照常可用。失控的循环需要的正是这样一个上限，而钱包给不了，因为所有密钥用的是同一个钱包。

把充值阈值设在单个请求的预留金额之上，充值金额则按你的智能体一天的花费来定，而不是按最低额：最小充值额是 $10，而上文常驻智能体的日花费中位数是 $12.67。自动充值的各项限制见计费页面，完整的错误响应体见错误码页面。

相关指南

• Hermes Agent 自定义 API——出站的提供商为什么不是入站的 API 服务器、transport 字段的解释，以及第一次调用时要做的检查。
• Hermes Agent 定价——除了 token 费率，运行它还要花哪些钱。
• Hermes 上下文压缩超时——摘要生成器卡住时这个报错意味着什么，以及怎么恢复。
• Hermes 与 OpenClaw 对比——另一个智能体的同样配置，见 OpenClaw 页面。