OpenAI Provider on ABS: Quick Setup, API Key vs Codex OAuth

Two auth paths

OpenAI on Hermes Agent supports two different authentication models, and they are NOT interchangeable:

• API key (paid per-token). Generate at https://platform.openai.com/api-keys. Each chat/image charges the OpenAI account against per-token pricing.
• 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 instead).

The right pick depends on your usage pattern:

Usage	Pick	Why
Image gen only (<50 calls/day)	API key	Cheaper than a $20/mo sub if you’re under 5M tok/mo
High-volume chat ($30+/mo usage)	Codex OAuth	Subscription-tariff has a ceiling; per-token doesn’t
Both chat and image gen	API key for chat + image gen, Codex OAuth as fallback	Mix-and-match; pick the cheaper path per type

The API key path

The standard 4-line setup:

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

Image-gen works through OPENAI_API_KEY too. The image gen providers used by ABS’s image-gen plugins (/opt/hermes/plugins/image_gen/openai/__init__.py) all read OPENAI_API_KEY from the env. Image gen with gpt-image-2-medium runs at ~$0.04 per 1024×1024 image.

The Codex OAuth path

hermes auth codex

A browser window opens for the ChatGPT subscription OAuth flow. One-time. After it completes, hermes chat --provider openai --use-codex-auth works without a per-token charge, but only for ChatGPT Plus/Pro subscription plans.

Caveats:

• The Codex OAuth credential refreshes every ~14 days; Hermes handles the silent refresh.
• Image gen via Codex OAuth passes through ChatGPT’s quotas, which are tighter than the API’s.
• If your subscription lapses, the OAuth fails and the API-key fallback picks it up — if configured.

The image-gen backend today

On this VPS the openai Python package is the working image-gen backend (verified via /opt/hermes/.venv/bin/python -c "import openai"). The openai-codex backend is broken as of 2026-07-14 (no ChatGPT OAuth handshake). Pick openai for image gen:

# Force the working backend in plugin config
export IMAGE_GEN_BACKEND=openai

The dashboard-vs-realtime usage trap

Like Anthropic, the OpenAI dashboard’s usage display is hourly-sampled. Realtime usage requires curl-ing /v1/organizations/usage or wiring a small hourly cron that writes the number to a log. Don’t trust the dashboard for budget-gating.

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

The fallback chain position

OpenAI’s place in the fallback chain matters:

• Primary — pick OpenAI when your daily token spend is low enough to live under the ChatGPT Plus/Pro subscription tier (CoDEX OAuth) or you need image gen (gpt-image-2-medium) which the API key covers.
• Fallback (not primary) — direct Anthropic is faster and cheaper for chat-only work. Put Anthropic first; OpenAI takes the second slot for image gen and overflow chat.
• Avoid — putting OpenAI third or later. Most crons never get to the third slot before they fail; the cost of being down is worse than a small overage on direct Anthropic.

The position reflects one fact: OpenAI’s strength is image gen + a usable general model, not a price floor. Use it where the strengths line up (image-heavy workflows) and let the cheaper/faster direct providers take text-only paths.

When the OAuth credential gets stuck

Three failure shapes hit Codex OAuth specifically:

1. Token revoked mid-session. Hermes retries once with a fresh refresh; if that fails too, the session ends and the operator sees a clean error. Recovery: hermes auth codex again, browser OAuth, ~30 seconds.
2. Subscription lapsed. The OAuth token still claims to authenticate, but the actual chat returns a 402. Recovery: resubscribe at https://chatgpt.com/, then hermes auth codex to refresh.
3. Browser can’t open on this headless box. OAuth requires a browser; on a headless server the flow gets nothing. Workaround: do the OAuth on a separate desktop browser with the same Hermes config dir copy, then move the credential file to the server. The credential lives at ~/.hermes/auth/codex.json.

For a server-only install (like this VPS), the API-key path is the realistic one — keep API-key as primary and Codex OAuth as the secondary “trick” when you’ve already paid for a sub elsewhere.

What not to do

• Don’t accidentally ship a gpt-image-2-medium call with an OPENAI_API_KEY that’s a ChatGPT sub’s OAuth token — the per-token billing won’t apply, but the call will fail.
• Don’t pin a model that was renamed. gpt-5 is the current canonical; gpt-4-turbo is deprecated. Check the live matrix.
• Don’t ignore the soft-cap warning.
• Don’t put Codex OAuth as primary for high-volume batch jobs — the subscription tariff includes a per-minute token ceiling.

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	monthly_cap_usd 50 in config	Soft-cap set

Sources

• OpenAI API keys dashboard
• Hermes Agent provider docs
• ABS live matrix: AI Model Matrix
• ABS companion: Hermes Agent: Switching Providers Mid-Run When a Provider Fails

Last verified: 2026-07-14 against OpenAI’s published pricing snapshot and the live matrix dashboard. Note: openai-codex backend auth path was broken on 2026-07-14; openai (API-key) path was the working image-gen backend.