Integration Guide

Hermes Agent + LiteLLM: One Proxy for Many Models

Q: Does Hermes Agent support LiteLLM?

Yes. Hermes Agent supports LiteLLM Proxy through its OpenAI-compatible API.

Q: Should the LiteLLM master key go into Hermes?

Use a scoped LiteLLM virtual key instead of the administrative master key.

Q: Does LiteLLM make models cheaper?

LiteLLM adds routing and controls but does not automatically reduce upstream model prices.

LiteLLM gives Hermes Agent one OpenAI-compatible endpoint while the proxy handles provider credentials, model aliases, budgets, retries, and fallbacks behind it.

When LiteLLM belongs in the stack

A direct provider key is simpler for one model. LiteLLM becomes useful when several agents share provider accounts, you need per-key budgets, or you want a stable alias such as support-fast that can change upstream models without editing Hermes.

Hermes Agent → LiteLLM Proxy → OpenAI / Anthropic / OpenRouter / local model

Prepare the proxy

Deploy LiteLLM Proxy from its official documentation.
Add the upstream providers and model aliases you intend to expose.
Create a virtual key scoped to the agent’s models and budget.
Expose the proxy to Hermes over a private network or authenticated HTTPS endpoint.
Verify GET /v1/models with the virtual key before changing Hermes.

Configure Hermes Agent

Hermes supports LiteLLM through its documented custom-provider fields. Use the proxy base URL, the scoped virtual key, and the exact alias returned by LiteLLM:

# /opt/data/config.yaml
model:
  provider: custom
  base_url: https://litellm.example.com/v1
  api_key: sk-litellm-...
  default: support-fast

For a local proxy, the usual base is http://127.0.0.1:4000/v1. If Hermes and LiteLLM are in different containers, localhost points at the wrong container; use the private service name instead.

Key boundary: Hermes needs only a LiteLLM client key. Provider keys and the LiteLLM master key should stay inside the proxy’s secret store.

On OpenClaw Launch

Open the API Keys page, use the Custom API Provider card, and enter your HTTPS LiteLLM base URL and virtual key. Then choose an alias that the proxy exposes. The hosted container cannot reach a LiteLLM server bound only to your laptop’s localhost.

Useful LiteLLM controls

Aliases: keep the Hermes model name stable while changing the upstream route.
Budgets: cap a key or team before a provider bill grows unexpectedly.
Fallbacks: retry an approved secondary model when the primary is unavailable.
Central logs: see which agent, alias, and provider consumed tokens.

Troubleshooting

401: use a LiteLLM virtual key, not an upstream provider key.
404 or model not found: use the alias returned by the proxy’s models endpoint.
Connection refused: fix container networking or expose an authenticated HTTPS endpoint.
Tools fail but chat works: confirm the selected upstream model and proxy route preserve tool-call fields.

Hermes and LiteLLM FAQ

Does Hermes Agent support LiteLLM?

Yes. Hermes documents LiteLLM Proxy as a custom OpenAI-compatible provider. Point Hermes at the proxy base URL and use a LiteLLM key.

Should the LiteLLM master key go into Hermes?

Prefer a scoped LiteLLM virtual key with the minimum models and budget the agent needs. Keep the administrative master key out of client configuration.

Does LiteLLM make models cheaper?

LiteLLM does not change upstream prices by itself. It can route, budget, retry, and record usage across providers.