Hermes Agent Guide

Hermes Agent Custom Endpoint: Three Routes, One Decision

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

Run hermes model and choose Custom endpoint. The configuration is saved to config.yaml so it persists across restarts.

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.

Which route do you need?

Situation	Route
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?

Run hermes model and choose Custom endpoint. The result is written to config.yaml, so it survives restarts and is easy to inspect later. This is the right path for a host Hermes does not already know about.

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.