# 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

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

```powershell
iex (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

```bash
AIPRIME_API_KEY=your_gateway_key
```

```yaml
providers:
  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:` 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

> Setting `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..provider` and `.model` to send them to a cheaper model |
| Scheduled jobs | `cron.model` for all jobs; `hermes cron pause ` or `hermes pause` |
| Messaging gateway (Telegram, Discord and others) | Allow-lists such as `TELEGRAM_ALLOWED_USERS`; avoid `GATEWAY_ALLOW_ALL_USERS=true` |

```yaml
delegation:
  max_concurrent_children: 3
  model: claude-haiku-4-5
auxiliary:
  background_review:
    enabled: false
cron:
  model: claude-haiku-4-5
```

`hermes 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](/learn/run-openclaw-with-claude-api/).

## FAQ

### How do I use Hermes Agent with a custom Claude endpoint?

Add a named provider in ~/.hermes/config.yaml with api set to the gateway URL, key_env pointing at a variable in ~/.hermes/.env, and transport: anthropic_messages, then set model.provider: custom:.

### Why does Hermes ignore my Anthropic base_url?

With provider: anthropic, Hermes accepts a base-URL override only for Anthropic, Claude and Azure hosts, so a third-party URL is dropped. Use a named custom provider instead.

### How do I reduce Hermes Agent token usage?

Limit subagents (delegation settings), route auxiliary tasks and cron jobs to a cheaper model, turn off background review, and check hermes prompt-size.

### Can Hermes Agent use a Claude Pro subscription?

According to Hermes' documentation, no: the Claude login path works only on Max with extra-usage credits. An API key avoids subscription limits altogether.

---

Source: https://aiprimetech.io/learn/run-hermes-agent-with-claude-api/
Provider: AI Prime Tech — independent Anthropic-compatible API gateway (not affiliated with Anthropic).