Hermes Agent with ChatGPT: your subscription or an OpenAI API key

Two routes to OpenAI models

Hermes treats them as two separate providers, and the names are easy to mix up:

• ChatGPT subscription, provider openai-codex (shown in hermes model as “ChatGPT or Codex Subscription”). You sign in with your ChatGPT account and Hermes uses the Codex models that come with your plan. Requests go to ChatGPT’s Codex service and count against your plan’s usage limits, not against a per-token bill. The aliases chatgpt and chatgpt-codex also work with --provider.
• OpenAI API key, provider openai-api (“OpenAI API” in the picker). You create a key on OpenAI’s developer platform and pay for every token at OpenAI’s API prices. This route talks to api.openai.com directly and offers the wider API catalogue.

The short version: the subscription is the better deal if you already pay for ChatGPT and your use fits inside its limits. An API key is billed per token, separately, so it has no rolling usage windows, though API rate limits, quotas and billing limits can still interrupt scheduled work. You can set up either route as a fallback for the other (see below).

GPT models are also available through aggregators that Hermes supports, such as OpenRouter and Nous Portal. Those bill through their own accounts and are not covered here.

Signing in with your ChatGPT account

If you have not installed Hermes yet, start with how to install Hermes Agent. Then either run the model wizard and choose “ChatGPT or Codex Subscription”, or go straight to the login:

hermes model
# or
hermes auth add openai-codex

By default this is a device-code login, which works the same on a laptop or a remote server:

1. Hermes prints the address https://auth.openai.com/codex/device and a short code.
2. Open that address in any browser, on any device, sign in to ChatGPT and enter the code.
3. Hermes waits for your approval (up to 15 minutes) and saves the login. If you used hermes auth add openai-codex, select the provider and model with hermes model afterwards.

The login is stored in Hermes’ own file, ~/.hermes/auth.json. You do not need the Codex CLI installed. During setup through hermes model, Hermes can offer to import the login in ~/.codex/auth.json, but the prompt defaults to no and recommends a separate login. That advice is worth taking, for a reason explained in the troubleshooting section: two programs sharing one ChatGPT login can trip over each other when one renews it.

To check the result, hermes auth status openai-codex shows whether you are signed in, and hermes auth list openai-codex lists every ChatGPT login Hermes holds.

Signing in on a server, over SSH or in a profile

Because the default flow is a device code, a headless server needs nothing special: run hermes auth add openai-codex in your SSH session, open the printed address on your own computer or phone, and enter the code. No browser is needed on the server.

Some company ChatGPT workspaces turn off device-code logins. For those, Hermes has a browser flow instead:

hermes auth add openai-codex --browser

It waits for OpenAI to send the browser back to http://localhost:1455/auth/callback. The port is fixed by OpenAI, and if something else is using it (a Codex CLI login in progress, for example) Hermes says so and falls back to the device code. On a remote machine, forward the port from your computer first, in a second terminal:

ssh -N -L 1455:127.0.0.1:1455 user@your-server

To make the browser flow the default for every ChatGPT login, including the one in hermes model, run hermes config set auth.codex_login_flow browser.

If you run several agents as Hermes profiles, sign in for a particular named profile with hermes -p <profile> auth add openai-codex.

Using an OpenAI API key instead

Create a key on OpenAI’s developer platform, then either run hermes model and choose “OpenAI API”, or put the key in ~/.hermes/.env yourself:

OPENAI_API_KEY=sk-...

To try a model for one session without changing your default:

hermes chat --provider openai-api -m gpt-5.5

A few details that catch people out:

• OPENAI_BASE_URL in the same file points the openai-api provider at a different OpenAI-compatible address, such as a regional endpoint or a company proxy. Only point it at an address you trust with your key.
• An OpenRouter key belongs in OPENROUTER_API_KEY. Put it there rather than in OPENAI_API_KEY.
• The API key and the ChatGPT login are independent. Having both is fine; the provider you select decides which one a request uses.

Which models each route offers, and how to pick one

On the ChatGPT route, Hermes asks OpenAI for its current model list and adds a few compatibility choices, so a model in the picker is not a promise that your plan includes it. If that request fails (offline, or on the very first run) it falls back to a built-in list: gpt-6-sol, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4, gpt-5.4-mini and gpt-5.3-codex-spark. That list can lag behind OpenAI: OpenAI retired Spark on 14 September 2026 and took GPT-5.5 off ChatGPT sign-in on 14 October 2026, though both are still on that list. Two things are specific to this route:

• The -pro models are API-only. Asking for one through a ChatGPT login fails with a “not supported when using Codex with a ChatGPT account” error.
• Some models appear twice, once with a -900k suffix. The plain version uses the 272,000-token context window Codex advertises; the suffixed one lets a conversation grow to about 900,000 tokens. Hermes keeps the larger window opt-in because using it by default burned through subscription limits.

On the API route, Hermes normally filters its own list of agent-ready OpenAI models against the models your key can access, so embedding, speech and other non-chat models stay out of the picker. If that lookup fails, it can show fallback choices your key may not be able to use.

To switch inside a conversation, use /model with the provider in front, for example /model openai-codex:gpt-6-sol or /model openai-api:gpt-6-sol. That change lasts for the current session; add --global to save it as your default. /model only switches between providers you have already set up; a new sign-in has to happen in hermes model or hermes auth add.

Hermes also uses your main model for side jobs such as reading images, unless you point those at another model, so they count against the same plan or bill.

Usage limits on a plan, and what an API key costs

OpenAI’s Codex pricing page (read 30 October 2026) lists Codex as included in the ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise plans. Limits depend on the plan. Plus and Business run in rolling five-hour windows and weekly limits may also apply, while Pro currently has no five-hour limit and flexible Enterprise and Edu pricing has no fixed rate limits. How far a window goes depends on the model: OpenAI’s own figures for Plus show the lighter Luna models allowing many times more messages per window than GPT-6.1 Sol. The Hermes documentation itself does not say which plan tiers work with Hermes or exactly how Hermes usage is counted against them, so treat your ChatGPT usage page as the authority.

Hermes can show you where you stand without leaving the terminal:

hermes usage --provider openai-codex

It prints your plan, the usage windows your account reports, and when each resets. Inside a chat, /usage shows the same, and if your account has a banked limit reset, /usage reset spends it. By default Hermes refuses to spend one unless a window is fully used, since a reset restores both windows in full; /usage reset --force overrides that.

When a window runs out, you have three options:

• Wait. Hermes reports that the Codex quota is exhausted and that your login is still valid; signing in again does not help.
• Add a second ChatGPT account. Each hermes auth add openai-codex with a different OpenAI account becomes another entry, and Hermes moves to the next one when a plan limit is hit. Signing in twice with the same account adds nothing: OpenAI cancels the older login.
• Fall back to an API key. List another provider under fallback_providers in config.yaml (or use hermes fallback) and Hermes switches to it when the plan runs out, then tries the subscription again once its limit resets.

fallback_providers:
  - provider: openai-api
    model: gpt-5.5

API usage is billed at OpenAI’s per-token prices, separately from your ChatGPT plan. It does not use the plan’s Codex windows, but API rate limits, quotas and billing limits still apply.

Staying signed in, and fixing common errors

A ChatGPT login has a short-lived access token and a refresh token. Hermes renews the access token on its own shortly before it expires, so a working login normally needs no attention. The refresh token is single-use: each renewal replaces it, and the old one stops working. That is the cause of most ChatGPT problems below.

• “No Codex credentials stored”. This profile has no ChatGPT login. Run hermes auth add openai-codex, adding -p <profile> when the gateway or job runs under a named profile.
• “refresh token was already consumed by another client”. Hermes and the Codex CLI or VS Code extension were sharing one login, and the other program renewed it first. Hermes can sometimes recover the newer login from the Codex CLI by itself. To stop it happening, give Hermes its own login with hermes auth add openai-codex, and stop Hermes borrowing the Codex CLI’s login with hermes config set auth.adopt_external_logins false.
• Login rejected for good (invalid_grant, or the login was revoked). Hermes marks that login dead and stops retrying it, so you see one clear error rather than a stream of them. Sign in again; nothing recovers it on a timer.
• “Codex provider quota exhausted (429)”. A usage window is used up, not a login problem. See the options in the previous section.
• “not supported when using Codex with a ChatGPT account”. The model is not available through a ChatGPT login, usually a -pro model. Pick one from the picker’s list, or use it through an API key.
• The device login times out. Approval has to happen within 15 minutes; run the command again. If OpenAI is rate-limiting login attempts, Hermes retries a few times by itself before giving up.
• The device login fails with an SSL or TLS handshake error while other sites work. The Hermes docs trace this to network equipment that rejects the post-quantum key exchange OpenSSL 3.5 and later offers. Point OPENSSL_CONF at a config that limits TLS to the classic curves before running the login; the provider guide in the Hermes docs has the exact file.
• An API key is refused. Check it is in OPENAI_API_KEY and is a real OpenAI key, not an OpenRouter one.

ChatGPT and OpenAI on ReadyHermes

ReadyHermes does not offer ChatGPT sign-in. The Model key tab takes API keys only, so a ChatGPT subscription cannot pay for a hosted assistant’s AI. What you can do is bring an OpenAI API key:

1. Open the workspace, choose the Model key tab and pick OpenAI as the provider.
2. Paste your key. “Where do I get a key?” links to the API keys page of OpenAI’s developer platform.
3. Press Load models to see what your key can use. This list comes straight from OpenAI and includes its non-chat models too, so choose a GPT chat model, or type the exact model name.
4. Press Check and switch. We first test a small chat request with your key and the model you chose, which catches basic key and model errors, though not every agent capability. Then the assistant restarts on your key, which takes about a minute.

OpenAI bills you directly and we put no AI limit on your own key. The workspace shows only a masked preview; the full key is stored in your assistant’s configuration so it can authenticate requests. This works during the one-hour free trial as well as on a paid plan, and a key added during the trial stays when you choose a plan. Use included AI switches the assistant back at any time.

Paid plans include AI that runs on DeepSeek V4.1 Flash by default, and the same tab lets you pick another of the included models; larger ones use up the included allowance faster. If you are weighing GPT against Claude, see Hermes Agent with Claude, and for what else a hosted assistant includes, read about managed Hermes Agent hosting.