Hermes Agent Guide

Hermes Agent Custom Endpoint: Three Routes, One Decision

Q: How do I add a custom endpoint to Hermes?

It depends where Hermes runs. Self-hosted, run hermes model and choose Custom endpoint, which is saved to config.yaml and persists across restarts. On a bot hosted by OpenClaw Launch the config is managed for you and a model switch rewrites the endpoint fields, so hand-editing does not persist: save the endpoint on the API keys page using the base URL ending in /v1 plus a key, then select the model under the custom provider in the model dropdown, typing the exact model id if the list comes back empty.

Q: What is the difference between a custom endpoint and OPENAI_BASE_URL?

OPENAI_BASE_URL is an optional override on the openai-api provider, suited to drop-in OpenAI replacements and proxies. The custom endpoint picker registers a separate endpoint and suits a different service entirely.

Q: Does my endpoint need to be OpenAI-compatible?

Yes. The endpoint should expose an OpenAI-compatible chat completions API. Together AI, Groq, DeepSeek and self-hosted servers such as vLLM and LM Studio all provide one.

Q: Is there a per-provider base URL override?

Yes. Several built-in providers accept their own base URL override, such as GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL and HF_BASE_URL, which keeps the provider integration while changing the host.

Hermes gives you three different ways to point it at an endpoint of your own, and picking the wrong one is the usual reason this goes badly. They are not interchangeable: one registers a new endpoint, one overrides OpenAI's host, and one retargets an existing provider integration. All three assume you administer Hermes yourself; if your bot is hosted here, the dashboard route below replaces them.

Running your bot on OpenClaw Launch? The three routes below all assume you administer Hermes yourself, editing its config and environment directly. On a hosted bot those files are managed for you, and switching models rewrites the endpoint fields, so a hand-edited entry does not stick. The equivalent is done from the dashboard instead: save your endpoint under API keys, using the base URL ending in /v1 plus a key. The key field is required, so a server that ignores keys will still accept any value. Your endpoint's models are then listed automatically where it publishes them — open your bot's model dropdown and pick one under the custom provider to route it there. If the list comes back empty, type the model id exactly as your provider spells it. The endpoint has to be reachable from the public internet, so localhost, a LAN IP, and private-network addresses such as Tailscale are refused when you save.

Which route do you need?

Situation	Route
Your bot is hosted on OpenClaw Launch	The API keys page, then the model dropdown
A service Hermes has no provider for	Custom endpoint via `hermes model`
An OpenAI-compatible proxy or drop-in replacement	`OPENAI_BASE_URL` on the `openai-api` provider
A built-in provider on a different host or region	That provider's own `*_BASE_URL` override
A local model server	LM Studio or Ollama entries, or a custom endpoint

Route 1: the custom endpoint picker

The documented path, and the right default:

hermes model
# choose: Custom endpoint

Your entry is saved into config.yaml rather than held only in the environment, which means it persists across restarts and you can read it back later to see exactly what the agent is pointed at. That inspectability matters more than it sounds when an agent starts behaving oddly six weeks later.

Route 2: OPENAI_BASE_URL

The openai-api provider takes an API key and an optional base URL:

# ~/.hermes/.env
OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://your-proxy.example.com/v1

Use this when the thing on the other end genuinely behaves like OpenAI — a corporate proxy, a gateway that adds logging or spend controls, or a compatible service you want treated as OpenAI. You keep the provider's behaviour and change only where requests go.

Route 3: per-provider base URL overrides

Several built-in providers accept their own override, which keeps their integration intact while changing the host:

# examples, all optional
GLM_BASE_URL=https://api.z.ai/api/paas/v4
HF_BASE_URL=https://router.huggingface.co/v1
MINIMAX_BASE_URL=https://api.minimax.io/v1
KIMI_BASE_URL=https://api.kimi.com/coding/v1

The common reason to reach for these is regional endpoints — several vendors run separate China-facing hosts, and Hermes ships distinct providers or base URLs for them rather than expecting you to improvise.

Common OpenAI-compatible base URLs

If you are pointing at a hosted service rather than your own server, these publish OpenAI-compatible endpoints:

Service	Base URL
Together AI	`https://api.together.xyz/v1`
Groq	`https://api.groq.com/openai/v1`
DeepSeek	`https://api.deepseek.com/v1`

Note the asymmetry: DeepSeek also has a first-class provider, so prefer that one. Groq does not — it is configured as a custom endpoint, and upstream's own cookbook covers it that way alongside Together AI and Perplexity. Assuming a well-known vendor must be built in is the usual reason this step goes wrong.

Naming your custom providers

Custom endpoints can be named, which matters once you have more than one. A named entry is then addressable directly when switching models:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:together:meta-llama/Llama-3.3-70B-Instruct-Turbo

The shape is custom:<name>:<model>. Naming them after where they run — local, work, a vendor — is far easier to live with than one anonymous custom entry you have to open config.yaml to identify.

Verifying

Send one small, non-sensitive prompt and confirm the layers separately:

Hermes is using the endpoint you think it is — read it back from config.yaml.
The credential is accepted.
The model id you specified exists on that endpoint.
Tool calls come back well-formed, which is where compatible-in-theory endpoints most often diverge.

The failure worth anticipating: plenty of "OpenAI-compatible" services implement chat completions faithfully and tool calling loosely. Hermes runs tool loops, so test a tool-using prompt rather than a plain chat message before trusting the endpoint.

Security

Keep keys in ~/.hermes/.env, never in a Git-tracked file.
Terminate TLS properly; never point an agent at a plain HTTP endpoint carrying real data.
Prefer a dedicated key per endpoint so one can be revoked independently.
If the endpoint is a shared internal gateway, confirm what it logs before sending agent traffic.

The same setup on the other framework is covered in OpenClaw custom endpoint.

Hermes Agent custom endpoint FAQ

How do I add a custom endpoint to Hermes?

It depends on where the agent runs. Self-hosted, run hermes model and choose Custom endpoint; the result is written to config.yaml, so it survives restarts and is easy to inspect later. On a bot hosted by OpenClaw Launch its config is managed for you and a model switch rewrites the endpoint fields, so a hand-edited file does not survive; save the endpoint under API keys instead — base URL ending in /v1 plus a key — then pick the model under the custom provider in your bot's model dropdown, typing the id yourself if the list comes back empty.

What is the difference between a custom endpoint and OPENAI_BASE_URL?

They solve different problems. OPENAI_BASE_URL is an optional override on the openai-api provider — use it when your service is a drop-in OpenAI replacement and you want to keep using that provider's behaviour. The custom endpoint picker registers a distinct endpoint in its own right. If you are proxying OpenAI, use the base URL; if you are pointing at a different service entirely, use the custom endpoint.

Does my endpoint need to be OpenAI-compatible?

For this path, yes — it should expose an OpenAI-style chat completions API. Many hosts do: Together AI, Groq and DeepSeek all publish OpenAI-compatible base URLs, and most self-hosted servers such as vLLM and LM Studio offer one too.

Is there a per-provider base URL override?

Yes, and it is the least-known of the three. Several built-in providers accept their own override — GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, HF_BASE_URL and others. Use these when you want a provider's existing integration but a different host, such as a regional endpoint.