Hermes Agent Provider: OpenAI and Codex Auth (GPT + Image Gen)

Why OpenAI

OpenAI is the second-most-used provider on Hermes, with two distinct strengths:

1. Image gen via the API. gpt-image-2-medium produces 1024×1024 at ~$0.04 per image. The image gen plugin at /opt/hermes/plugins/image_gen/openai/ reads OPENAI_API_KEY from the env and is the working backend (verified import openai succeeds). The Codex OAuth backend is broken as of 2026-07-14.

2. Generalist GPT-5 class. GPT-5 / GPT-5-mini are useful as fallback or for jobs that Anthropic’s Claude family fails at. Multi-provider setups typically have OpenAI as the third slot.

The cost-vs-latency tradeoff

Within the OpenAI family, picking between gpt-5, gpt-5-mini, gpt-5-nano is one of the more impactful cost decisions on Hermes. The per-token ratio is roughly 10x; the latency ratio is roughly 3x; the capability delta is real but smaller than the price gap for short structured outputs.

For a typical ABS review draft (2-3K input tokens + 2K output), the per-call cost differences:

• gpt-5-nano — ~$0.005 per draft
• gpt-5-mini — ~$0.02 per draft
• gpt-5 — ~$0.10 per draft

Pin to mini for review drafts when the body is straightforward. Switch to the full GPT-5 only on review-pass work where the body-flow polish matters.

Two auth paths

OpenAI on Hermes supports two auth models that are NOT interchangeable:

• API key (paid per-token). Standard 4-line setup:

  1. export OPENAI_API_KEY=<key> from https://platform.openai.com/api-keys.
  2. hermes config set provider.openai.api_key "$OPENAI_API_KEY".
  3. hermes config set provider.openai.default_model "gpt-5".
  4. hermes chat --provider openai -q "Reply with OK".

• Codex/ChatGPT OAuth (subscription-based). Run hermes auth codex once to log in with a ChatGPT Plus/Pro subscription. Subsequent calls don’t hit per-token charges (subscription-tariff applies). The credential refreshes every ~14 days; Hermes handles the silent refresh.

The right pick: API key for high-volume image gen (cheaper per-image than a $20/mo sub when usage is under 5M tok/mo), OAuth for chat-heavy workloads where the subscription-tariff ceiling saves money.

The image gen backend

For image generation, the working path is openai (API key). The flow:

1. OPENAI_API_KEY is exported.
2. The image gen plugin at /opt/hermes/plugins/image_gen/openai/__init__.py uses the official Python openai package.
3. Image gen calls charge per-image, not per-token for the model — typically ~$0.04 per 1024×1024 with gpt-image-2-medium.

If you try gpt-image-2-medium via Codex OAuth instead, you’ll get a 402 — ChatGPT’s quotas don’t include API-only models. The API key is the only realistic path for image gen.

Dashboard-vs-realtime usage

OpenAI’s web dashboard usage display is hourly-sampled. For realtime:

curl -sS -H "Authorization: Bearer $OPENAI_API_KEY" \
  "https://api.openai.com/v1/organizations/usage" | jq

For a per-call cost estimate at runtime, use the model’s response usage block (input_tokens, output_tokens) multiplied by the matrix row’s input/output prices.

The 14-day OAuth refresh

Codex OAuth tokens have a 14-day refresh cycle. The Hermes client refreshes them silently — usually transparently — but if the refresh fails (e.g., you cancelled the original ChatGPT OAuth grant at https://chatgpt.com/ settings), the next call returns a 401. Recovery: hermes auth codex again, browser re-authorize.

The credential lives at ~/.hermes/auth/codex.json for desktop installs; on a headless VPS, run the OAuth on a separate desktop browser and copy the credential file over.

The Codex OAuth failure shapes

1. Token revoked mid-session. Hermes retries once with a fresh refresh; if that fails, the session ends. Recovery: re-auth via hermes auth codex.
2. Subscription lapsed. The OAuth still claims to authenticate, but the actual chat returns 402. Recovery: resubscribe, then re-auth.
3. Headless box can’t open a browser. OAuth requires browser completion. Workaround: do OAuth on a desktop, copy ~/.hermes/auth/codex.json to the server. Or use the API key path on the server.

What not to do

• Don’t accidentally feed a gpt-image-2-medium call a ChatGPT-subscription OAuth token — billing is per-image, and the OAuth path doesn’t carry API credits.
• Don’t pin renamed models. gpt-5 is current; gpt-4-turbo is deprecated. Check the live matrix.
• Don’t put Codex OAuth as primary for high-volume batch jobs — the per-minute token ceiling on Plus/Pro is tighter than the API.

Verification checklist

#	Command	What it proves
1	hermes config show --provider openai	API-key path configured
2	hermes chat --provider openai -q "Reply with OK"	Runtime alive (paid)
3	hermes chat --provider openai --use-codex-auth -q "Reply with OK"	Runtime alive (sub)
4	/opt/hermes/.venv/bin/python -c "import openai"	Image-gen backend working
5	curl /v1/organizations/usage	Realtime usage reachable
6	~/.hermes/auth/codex.json exists (or absent for API-only)	Credential stored

Sources

• OpenAI API keys dashboard
• Hermes Agent provider docs
• ABS live matrix: AI Model Matrix
• ABS companion: OpenAI Provider on ABS: Quick Setup, API Key vs Codex OAuth

Last verified: 2026-07-14 against Hermes v0.18.2 (2026.7.7.2). openai-codex backend broken as of 2026-07-14; openai (API-key) was the working image-gen backend.