Hermes Agent with Claude through a gateway: custom provider setup, cost controls and fixes
Hermes Agent keeps secrets in ~/.hermes/.env and everything else in ~/.hermes/config.yaml. The reliable way to run it on Claude through a gateway is a named custom provider that speaks the Anthropic Messages format. The shortcut, provider: anthropic with a different base URL, looks right but sends requests to Anthropic for any host it doesn't recognise.
Install
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashiex (irm https://hermes-agent.nousresearch.com/install.ps1)hermes setup runs the full wizard; hermes model handles only provider and model; hermes doctor checks an existing install.
Add the gateway as a custom provider
AIPRIME_API_KEY=your_gateway_keyproviders:
aiprime:
api: https://aiprimetech.io/v1
key_env: AIPRIME_API_KEY
transport: anthropic_messages
catalog_provider: anthropic
model:
provider: custom:aiprime
default: claude-sonnet-5| Key | Why |
|---|---|
transport: anthropic_messages | Speak Anthropic's Messages format. Without it Hermes falls back to the OpenAI Chat Completions format |
key_env | The name of the variable in .env that holds the key |
catalog_provider: anthropic | The gateway's Claude models inherit Anthropic's context and vision metadata |
provider: custom:aiprime | Selects the named provider; /model custom:aiprime:<model> switches inside a chat |
The wizard does the same: hermes model, then **Custom endpoint**, then the API mode **Anthropic Messages**. If you choose Chat Completions instead, keep /v1 in the URL.
Why provider: anthropic with a base URL doesn't work
provider: anthropic and base_url: https://aiprimetech.io looks correct but has no effect: in current Hermes source, a base-URL override on the built-in Anthropic provider is accepted only for Anthropic, Claude and Azure hosts, so requests still go to Anthropic. Use the named custom provider above.ANTHROPIC_BASE_URL is documented as an override for the Anthropic base URL, but an open Hermes bug means the model picker ignores it. The custom provider avoids both problems.
What drives token use, and the settings that limit it
Hermes runs work beyond the conversation you see, and all of it bills to the same key unless you route it elsewhere.
| Source of usage | Setting |
|---|---|
| Subagents (delegation) | delegation.max_concurrent_children (default 10), delegation.max_iterations (default 250), delegation.max_spawn_depth (default 1); a cheaper delegation.model |
| Background memory and skill review after each turn | auxiliary.background_review.enabled: false, or a lower max_input_tokens |
| Auxiliary tasks (compression, titles, vision) | auxiliary.<task>.provider and .model to send them to a cheaper model |
| Scheduled jobs | cron.model for all jobs; hermes cron pause <id> or hermes pause |
| Messaging gateway (Telegram, Discord and others) | Allow-lists such as TELEGRAM_ALLOWED_USERS; avoid GATEWAY_ALLOW_ALL_USERS=true |
delegation:
max_concurrent_children: 3
model: claude-haiku-4-5
auxiliary:
background_review:
enabled: false
cron:
model: claude-haiku-4-5hermes prompt-size shows the fixed cost every call carries; /usage and /compress help inside a long session.
Claude Pro or Max login instead of a key
Hermes can sign in to a Claude account, but its documentation says that path works only on a Max plan with purchased extra-usage credits, and that Pro subscribers can't use it. With an API key from a gateway there is no subscription window; usage is billed per token from your balance.
Models
| Model ID | Use it for |
|---|---|
claude-sonnet-5 | Default for coding and agent work: fast, strong, mid-priced. |
claude-opus-5-5 | Harder reasoning, large refactors, long agent runs. |
claude-fable-5-1 | Most capable and most expensive; save it for the hardest tasks. |
claude-haiku-4-5 | Cheap and quick: titles, summaries, classification, small steps. |
Hermes needs a context window of at least 64K tokens; every model in the table qualifies.
Troubleshooting
| What you see | Cause | Fix |
|---|---|---|
| HTTP 400 on the first run | The model name doesn't match a gateway model ID | Use an ID from the table above |
| Requests go to Anthropic or fail with an Anthropic auth error | provider: anthropic with a third-party base URL | Use the named custom provider |
| Garbage or empty replies | Wrong transport for the URL | transport: anthropic_messages for Claude |
| Context length exceeded | Session larger than the configured window | Set model.context_length; /compress |
403 Your request was blocked | A firewall in front of the endpoint rejects the client | Add extra_headers with a browser-like User-Agent |
| Missing settings after an update | Config schema changed | hermes config check, then hermes config migrate |
| Bot silent on Telegram or Discord | Gateway not running or sender not allowed | hermes gateway status; check ~/.hermes/logs/gateway.log |
Comparing agent frameworks? See the OpenClaw setup guide.
Frequently asked questions
How do I use Hermes Agent with a custom Claude endpoint?
Why does Hermes ignore my Anthropic base_url?
How do I reduce Hermes Agent token usage?
Can Hermes Agent use a Claude Pro subscription?
Get an API key — no Anthropic account or waitlist required.
Get your API keyAI Prime Tech is an independent API gateway. It is not affiliated with, endorsed by, or a reseller of Anthropic. Claude and related model names are trademarks of their respective owners.