Hermes "Codex token refresh failed with status 401"

Why it happens

Hermes keeps its Codex OAuth tokens in ~/.hermes/auth.json. Every refresh consumes the old refresh token and issues a new pair, so whenever two programs share one token family, the first to refresh invalidates the other's copy. Hermes treats any 401 or 403 from the Codex token endpoint as a hard relogin-required failure.

1. Shared token family with the Codex CLI. Hermes borrowed or imported your Codex CLI login from ~/.codex/auth.json, then the CLI refreshed and the copy Hermes held became invalid. Issue #6651 documented this exact pair of log lines.
2. Stale credential pool state. Before the April 2026 fix for issue #6651, a pool entry marked exhausted could stay unavailable even after fresh tokens were available, so the gateway kept failing while local hermes chat worked.
3. Two logins of the same OpenAI account. Adding the same account twice puts both entries on one token family upstream, so OpenAI revokes the older one. Hermes warns about this at add time.
4. The session was revoked or expired on OpenAI's side, for example after signing out of ChatGPT everywhere or a long idle period.

The fix

1. 1 Confirm which credential is active: hermes auth list openai-codex. The arrow marks the entry currently in use.
2. 2 Give Hermes its own Codex session: hermes auth add openai-codex --type oauth. Decline the prompt to import ~/.codex/auth.json; the CLI asks this because a separate login is recommended.
3. 3 If you also use the Codex CLI or VS Code extension on the same machine, stop Hermes from borrowing their tokens by setting auth.adopt_external_logins: false in ~/.hermes/config.yaml.
4. 4 Remove dead entries left over from earlier logins with hermes auth remove openai-codex followed by the entry id shown in hermes auth list.
5. 5 Restart the gateway so it picks up the new credential: hermes gateway restart, then send a test message.

Why the Codex CLI and Hermes fight over one login

OpenAI's Codex OAuth uses rotating refresh tokens: each refresh returns a new refresh token and invalidates the previous one. Hermes's auth module says it plainly: tokens live in ~/.hermes/auth.json, not ~/.codex/, so one app's rotation cannot invalidate the other's session. That only holds if Hermes has its own login. If it borrowed the Codex CLI's session, both programs are holding the same single-use token and whichever refreshes second gets the 401.

Current builds try to self-heal: on a relogin-required refresh failure Hermes re-reads ~/.codex/auth.json and adopts the newer pair if it belongs to the same account. A login into a different ChatGPT workspace is refused, and then only a fresh hermes auth add openai-codex fixes it. If the message instead says the refresh token was already consumed by another client, run codex once to get fresh CLI tokens and then re-authenticate Hermes.

Still failing?

• If you use named profiles, run the login with the profile selector (hermes -p yourprofile auth add openai-codex --type oauth), because each profile has its own credential store.
• Check whether the error is actually a 429: Hermes reports Codex quota exhaustion separately and says the credentials are still valid, so a relogin will not help there.
• Run hermes update; the stale pool behaviour from issue #6651 was fixed in April 2026 and older installs can still get stuck.

Related errors

• Hermes fallback never triggers on Codex 429s
• Hermes provider authentication failed