Hermes Agent + OpenAI Codex

Which Auth Should You Use?

• Device-flow (recommended) — if you have a paid Codex CLI subscription, you can reuse the same login. No separate API key, no quota mismatch.
• BYOK API key — if you don't have Codex CLI, sign up at OpenAI and drop the key in models.providers.openai.apiKey.

Path A: Device-Flow Auth (Codex Subscription)

The codex CLI stores its auth token at ~/.codex/auth.json. Hermes can read the same file so both tools share one login:

# 1. Make sure Codex CLI is logged in
codex login
codex status      # verify

# 2. Symlink auth into Hermes
mkdir -p ~/.hermes/codex
ln -sf ~/.codex/auth.json ~/.hermes/codex/auth.json

# 3. Point Hermes at the Codex profile
# in ~/.hermes/config.json
{
  "auth": {
    "profiles": {
      "openai-codex:[email protected]": {
        "type": "device-flow",
        "tokenPath": "~/.hermes/codex/auth.json"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "openai-codex/gpt-5.5" }
    }
  }
}

Hermes reads the device-flow token on each call, so when codex login refreshes the token Hermes picks it up automatically.

Path B: BYOK with an OpenAI API Key

If you don't have Codex CLI, generate a standard OpenAI key and use it:

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-...",
        "baseUrl": "https://api.openai.com/v1"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "openai/gpt-5.5" }
    }
  }
}

The model ID stays openai/gpt-5.5 for BYOK. Note that Codex-specific features (like the --worktree sandbox) only work via the CLI subprocess path, not the raw API.

Verify the Connection

# Restart Hermes
hermes restart

# Send a one-off prompt
hermes chat "Explain what a Codex CLI worktree is, in two sentences."

If you get a reply within ~5 seconds, you're wired up. If you get 401 Unauthorized, the device-flow token expired — run codex login to refresh.

Pair Hermes Chat with Codex Code Edits

The strongest setup runs Hermes for chat (Telegram/Discord with persistent memory) and Codex CLI for code edits in your terminal. Wire them so they trade off cleanly:

• Hermes uses Codex models for reasoning in chat answers.
• Codex CLI runs in your terminal for actual file edits.
• A Hermes skill can trigger codex exec on the server for autonomous code edits, with results posted back to the chat.

Common Pitfalls

• Wrong model ID prefix. For device-flow use openai-codex/gpt-5.5. For BYOK API use openai/gpt-5.5. The prefix decides the auth path.
• Token expired. The device-flow token rotates every few hours; codex login refreshes both Codex CLI and Hermes (via the symlink).
• Rate limits. Codex CLI subscriptions have separate per-minute and per-day quotas. If you hit them in chat, Hermes returns 429.
• Tool availability mismatch. The Codex CLI subprocess has a hardcoded native tool set — browser and a few others are not available. Use a non-Codex model if you need those tools.

Related Guides

• Hermes + OpenAI (general)
• Hermes + Claude Code
• OpenClaw + Codex

Skip the Setup — Managed Hermes