Hermes and OpenClaw provider setup with MonkeyAI: a five-step safe order

What does the safe setup order actually buy you?

Direct answer: it separates API failure from config failure. Each step proves one layer before the next layer is touched. If GET /v1/models fails with the right key, the API itself is the problem and changing provider config will only add noise.

Step 1 — confirm the route before the key

An unauthenticated request must still reach the gateway's auth layer. If the route returns HTML or a generic 404, the client is not hitting the OpenAI-compatible endpoint at all.

curl -sS https://monkeytheme.com/v1/models
# HTTP 401 — {"code":"API_KEY_REQUIRED","message":"API key is required ..."}

curl -sS https://monkeytheme.com/models
# HTTP 404 — nginx default 404 HTML (the path is wrong)

The same API_KEY_REQUIRED response is returned by /v1/chat/completions, /v1/responses, /v1/messages and /v1/embeddings. That is the four endpoint families an agent client might call.

Step 2 — confirm the credential is accepted

A fake Bearer key and a fake Anthropic-style x-api-key both reach the auth layer. The server returns a different error code so you can tell "no key" from "bad key" from "wrong key system".

This matches what an OpenAI-compatible client expects: a Bearer header in Authorization is enough to reach the auth layer, and the server tells you the key is wrong rather than silently rejecting the request.

Step 3 — what to put in Hermes Agent or OpenClaw config

For Hermes Agent the public docs describe custom_providers entries that point an OpenAI-compatible base URL at a third-party gateway. The same shape applies to any agent gateway that exposes an OpenAI-compatible mode.

# ~/.hermes/config.yaml
model:
  default: gpt-5.4
  provider: monkeytheme
  base_url: https://monkeytheme.com/v1
  api_key: sk-***

custom_providers:
  - name: monkeytheme
    base_url: https://monkeytheme.com/v1
    api_key: sk-***
    models:
      - gpt-5.5
      - gpt-5.4

After saving the file, restart the gateway process so the new custom_providers entry is read. Hermes Agent caches provider state in the OpenAI client object — credential rotation or provider addition rebuilds the client, but a long-running session may need a fresh prompt or restart to pick up model-list changes.

Step 4 — pick a model name the dashboard actually shows

Before changing the provider config, confirm the model name is visible to the same account. Use the live models endpoint:

curl -sS https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer sk-***" \
| python3 -c 'import json,sys; [print(x.get("id")) for x in json.load(sys.stdin).get("data", [])]'

Copy one of the printed id values into the models: list or the active model field. A display name, a model from another provider's docs, or a guessed alias will return model not found even when the credential and base URL are correct.

Step 5 — restart, then run one small request

After the config file change, restart the gateway or open a fresh session. Then run one short completion to confirm the wiring end-to-end:

curl -sS https://monkeytheme.com/v1/chat/completions \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"hi"}]}'

If this request returns a normal completion, the provider config is wired correctly. If it still returns 401, the issue is in the credential or the base URL, not in the agent's provider list.

What is explicitly out of scope here

• Anthropic Messages-format support in Hermes Agent or OpenClaw. This article covers the OpenAI-compatible mode only. The Anthropic-protocol path uses different env vars (ANTHROPIC_BASE_URL, apiKeyHelper) and a separate protocol-boundary guide.
• OAuth flow changes. The credential model assumed here is a static sk-… API key from the dashboard.
• Account-group specific model lists. Visible models differ by group; the live /v1/models call is the only source of truth.
• Subscription or billing changes. Provider setup does not touch the billing path.

Related guides and references

• Separate 401, 404 and model not found errors
• Why the API Base URL usually needs /v1
• Claude Code and API gateways (protocol boundary)
• Agent client center: Hermes, Codex, Cline, Roo Code
• Fix 429 rate-limit errors
• Fix 504 timeout and upstream errors

Frequently asked questions