Run Codex on a ChatGPT subscription
The codex runtime can run on a ChatGPT plan instead of an OpenAI API key.
You link the plan once. Codex conversations then run on it, and the usage
counts against the plan's Codex limits rather than an API bill.
Each account can link one subscription. The deployment has none of its own.
Which credential a codex conversation uses
For a codex agent on an openai/ model, Managoat takes the first of these
that exists:
- The account's own ChatGPT subscription.
- The account's own OpenAI API key: the one on Inference credentials,
or
OPENAI_API_KEYin the conversation's environment or vault. This is the order described in Where a secret comes from.
With neither, the conversation has no credential to run codex on. A conversation never moves to another credential: start a new one to use a credential you added since.
The egress broker holds the access token and adds it to Codex's requests to
chatgpt.com. The sandbox gets a placeholder and never the token.
Link your subscription
Open Inference credentials (/account/inference-credentials). Use one
of these two ways:
- Link with a code. Managoat shows a code and a link to
auth.openai.com. Open the link, sign in to ChatGPT and enter the code. The page waits for the approval and says when the subscription is linked. The code is good for fifteen minutes. Leave the page open until it finishes. - Paste an
auth.json. Runcodex loginon your own machine and choose ChatGPT. Then paste the contents of~/.codex/auth.json. The file and Managoat then share one refresh token. Whichever side refreshes it second can be signed out, so runcodex loginon that machine again afterwards. Disconnecting or replacing a pasted sign-in ends it at OpenAI, which also signs out the machine it came from if that machine still holds the same refresh token. Use the code when you can.
Linking again replaces the subscription, and Managoat ends the sign-in it replaced at OpenAI. If you link the same ChatGPT account, running conversations carry on. If you link a different account, start new conversations: a conversation stays on the account it started on.
How Managoat keeps it signed in
An access token lasts about ten days. Once a day, at 04:29 UTC, Managoat
refreshes every subscription that nobody has refreshed for six days. That is
the only routine call Managoat makes to auth.openai.com. The others are
linking, and ending a sign-in Managoat lets go of (see
Disconnect).
Before each turn, Managoat reads the stored access token and puts it in the broker. This is a database read, not a call to OpenAI. There is one exception: when the stored token has already expired, or expires within ten minutes, Managoat refreshes it before the turn.
If OpenAI refuses the refresh for good, the card shows Reconnect and the reason. Link the subscription again.
When something goes wrong
409 chatgpt_reconnect_required. The subscription this conversation runs on was disconnected, refused by OpenAI, or linked to a different account. Link it again and send the prompt again.- The plan's usage limit. The turn fails with the error OpenAI returns. Managoat does not switch to another credential. Wait for the reset, or link a different subscription and start a new conversation.
Disconnect
Select Disconnect on the card. Managoat deletes its copy of the tokens,
and conversations on the subscription stop at their next prompt. Then it
ends the sign-in at OpenAI by revoking its refresh token, as codex logout
does.
Ending the sign-in at OpenAI is best effort. If OpenAI does not confirm it,
for example because it is unreachable, Managoat still deletes its copy and
records chatgpt_subscription.not_revoked_at_openai in your audit log. In
that case, or if you want to be sure, sign the device out in your ChatGPT
account's security settings. An access token Managoat already obtained may
keep working until it expires, within about ten days.
Managoat also ends the sign-in at OpenAI when you link again (the sign-in it replaced), when a sign-in by code completes but cannot be stored, and when you delete your account. Deleting your account deletes your subscription.