ChatGPT Codex Subscription

ChatGPT / Codex subscription

Each ChatHub account can click Sign in with ChatGPT on Settings → OpenAI and pay OpenAI chat from that user's ChatGPT Plus/Pro Codex quota. The API key and proxy fields stay on the same page. Sign-out returns chat to the key.

This is an unofficial Codex client path. Official docs only cover Codex CLI / IDE / desktop. OpenAI can change the public client or endpoints at any time.

Sign in

1. Enable device code login in ChatGPT first. Official Codex authentication requires this in ChatGPT Security settings (personal account) or ChatGPT workspace permissions (workspace admin). If the workspace does not allow device login, ChatHub cannot complete Sign in with ChatGPT.
2. Open Settings → OpenAI.
3. Keep or fill the API key / proxy fields if you still need images, speech, embeddings, group-supervisor structured calls, or a fallback.
4. Click Sign in with ChatGPT.
5. ChatHub shows a device code. Open the ChatGPT device page (the Open ChatGPT link) and enter the code.
6. After authorization, the card shows the connected email, plan tag, 5-hour and weekly remaining bars when ChatGPT reports them, and the session expiry. The billing, device-code permission, and unofficial-client notes live on the title help icon, not as body copy.

ChatHub has no env flag, admin toggle, or CLI login. Only this Settings button starts the ChatHub flow. That is separate from the ChatGPT workspace permission above.

Quota vs API key

Surface	While signed in	After sign-out
OpenAI chat (including background Graphile turns)	Codex / ChatGPT quota	Platform API key or OPENAI_API_KEY
Images, TTS, STT, embeddings, realtime	Platform API key	Platform API key
Knowledge Base / RAG embeddings	Platform / embedding key	unchanged

While a Codex session is connected, ChatHub does not silently send OpenAI chat to the Platform API. Temporary token-refresh failures (429/5xx) keep the session and do not bill Platform. If the access token is still valid, that chat continues on Codex. If it has already expired, that chat fails instead of using the API key. Confirmed invalid_grant / reused refresh tokens disconnect and the next chat can use the API key. Browser request mode is forced off so refresh tokens never leave the server. Group supervisors keep using the Platform key for structured generateObject decisions.

Usage meters

The same Settings card shows 5-hour and weekly remaining as labeled bars when the ChatGPT account has those Codex windows. Plus is the usual case. ChatHub reads the official Codex usage snapshot (GET /backend-api/wham/usage) with your stored ChatGPT token and shows leftover percent plus the reset time, the same numbers Codex CLI /status uses.

OpenAI sometimes returns only the weekly window (for example when the 5-hour meter is off). ChatHub then shows weekly only. A failed usage lookup does not sign you out.

Official usage help: Using Codex with your ChatGPT plan.

Limits

• Chat streaming only. Structured object generation and image APIs stay on a Platform key.
• Per-user only. There is no instance-wide shared Plus login.
• Tokens are stored encrypted on the server (openai_codex_oauth_tokens). They are never written to keyVaults or sent to the browser.
• Model listing while connected uses the Codex catalog (GET /backend-api/codex/models with pinned Codex CLI client_version 0.154.0). If that fetch fails, ChatHub shows a small built-in subscription list.

Re-auth

Sign out from the same Settings card, then sign in again. Use this after a confirmed dead refresh (invalid_grant / reused token), or after an interrupted server refresh that retries cannot clear (see Troubleshooting). If refresh fails with invalid_grant or a reused refresh token, ChatHub deletes that session. Settings then shows signed-out (not still connected), and the next OpenAI chat uses the API key. A temporary token-endpoint error (429/5xx) or a hung refresh (headers or body) that hits the 8-second per-exchange timeout does not sign you out; wait and retry that chat. Same-process Sign out waits for the in-flight refresh only; other tabs sharing that process reuse that failed attempt instead of stacking another 8 seconds each. If the access token is still valid, Settings may still show usage meters after the timeout.

Troubleshooting

• Device login not allowed — enable device code login in ChatGPT Security settings, or ask the workspace admin to allow it. ChatHub cannot bypass that ChatGPT permission.
• unsupported_region — the ChatGPT account cannot use Codex in that region. Use a Platform API key instead.
• Expired or reused refresh token — Settings shows signed-out. Sign in again. ChatHub will not keep a dead session.
• Chat keeps failing after a server interrupt, Settings still shows connected — a ChatGPT token refresh that was interrupted (process exit, container restart, or a failed server-side cleanup) can stay stuck. Retrying the chat or restarting ChatHub again does not recover it. Sign out of the ChatGPT connection on Settings → OpenAI, then sign in again. After sign-out, OpenAI chat uses the Platform API key until you reconnect. Ordinary temporary OpenAI errors (429/5xx) are different: keep the session and retry those.
• Settings or Sign out stuck while refreshing — each ChatGPT token refresh (headers and body) waits at most 8 seconds. A hung refresh is temporary: the session stays, chat can keep using a still-valid access token, and Sign out waits for that one in-flight attempt rather than one timeout per open Settings tab. Usage meters appear only if the later usage lookup succeeds. refresh_settled reason=timeout on CHATHUB_OPENAI_CODEX_DEBUG=1 marks the refresh bound.
• Cloudflare / HTML error page — the Codex backend rejected or challenged the request. Retry later; do not paste tokens into chat.
• Device code expired — codes last 15 minutes. Click Sign in with ChatGPT again.
• Chat still bills Platform — confirm the Settings card still shows connected, then send from a server-reachable session (not a stale client-only tab).
• Usage meters missing — ChatGPT omitted that window, or the usage lookup failed. Sign-in stays connected. Refresh Settings → OpenAI. usage_fetch_settled on CHATHUB_OPENAI_CODEX_DEBUG=1 shows whether the 5-hour and weekly windows were present.
• Empty chat / no model reply after Sign in — there is no Codex traffic on DEBUG_OPENAI_CHAT_COMPLETION or DEBUG_OPENAI_RESPONSES (those dump Platform API only and can leak prompts). Set CHATHUB_OPENAI_CODEX_DEBUG=1 on the ChatHub container, recreate it, send one OpenAI chat, then look for [chathub-openai-codex-debug:…] lines. resolve_overlay_settled outcome=codex means the turn used the subscription. chat_request_settled ok only means HTTP 200. chat_stream_settled follows the Responses lifecycle, not SSE event count: ok is a completed reply; empty is a 200 with no events; failed / incomplete / unexpected_end / parse_error are provider or stream terminals (reason names the allowlisted cause). See Debug and Diagnostics.

See also Model Providers and official Codex Authentication.