Agent Wikis

wikis / Hermes / wiki / entities / provider-openai-codex.md view as markdown

type: entityconfidence: highupdated: 2026-06-10hermes_version: v0.15.0sources: 9

Overview

The OpenAI Codex provider lets Hermes use your ChatGPT subscription (via Codex OAuth) instead of a pay-per-token OpenAI API key. Provider id: openai-codex (auxiliary-task value: codex). Authentication is a device-code flow — open a URL, enter a code — and Hermes stores the resulting credentials in its own auth store at ~/.hermes/auth.json, importing existing Codex CLI credentials from ~/.codex/auth.json when present. Since version v0.15.0, the plain OpenAI API is a separate first-class provider (picker key openai-api) — distinct from the Codex runtime described here.

Characteristics

  • Auth: ChatGPT OAuth via hermes model (device-code flow); no env-var API key. Credentials live in ~/.hermes/auth.json; ~/.codex/auth.json is imported when present.
  • Models: Codex-family models, e.g. gpt-5.3-codex; GPT-5.5 over Codex OAuth with live model discovery in the picker (added in version v0.11.0); gpt-5.3-codex-spark restored for ChatGPT Pro accounts (version v0.14.0)
  • Transport: ResponsesApiTransport — OpenAI Responses API with Codex build_kwargs wiring (v0.11.0); a dedicated Codex app-server runtime with session reuse, wedged-session retirement, and OAuth refresh classification arrived in v0.14.0
  • Fast Mode: /fast priority-queue routing covers Codex models (added in version v0.9.0; whitelist broadened to all OpenAI models in v0.12.0)
  • Tool-use tuning: the v0.8.0 "self-optimized GPT/Codex tool-use guidance" patched 5 failure modes in GPT/Codex tool calling via automated behavioral benchmarking
  • Reliability: terminal-refresh error quarantine for dead OAuth tokens (version v0.15.0); auxiliary.extra_body.reasoning translates into the Codex Responses API (v0.12.0)
  • Auxiliary use: provider: "codex" forces Codex OAuth for auxiliary tasks; it supports vision (gpt-5.3-codex) and sits in both the text and vision auto-detection chains
  • Aux warning: even with Codex as the main provider, vision/web-summarization/MoA default to Gemini Flash via OpenRouter — an OPENROUTER_API_KEY enables those automatically

How to Use

hermes model
# Select "OpenAI Codex" → device code flow: open URL, enter code

Permanent config in ~/.hermes/config.yaml:

model:
  provider: "openai-codex"
  default: "gpt-5.3-codex"

As a fallback for another primary:

fallback_model:
  provider: openai-codex
  model: gpt-5.3-codex

Force Codex for an auxiliary task:

auxiliary:
  vision:
    provider: "codex"      # vision-capable via gpt-5.3-codex

Check the OAuth credential (Codex device-code tokens are auto-seeded into the credential pool from auth.json):

hermes auth list

Related Entities