How to use multiple Codex accounts

Give each account its own CODEX_HOME

Codex keeps its local state in one directory. OpenAI’s configuration documentation is direct about it: Codex stores its local state under CODEX_HOME, which defaults to ~/.codex. Inside sit config.toml, the cached credentials, history.jsonl when history is on, plus logs and caches.

That single variable is the whole mechanism. Point it at a different path and Codex reads a different account’s settings, credentials and history, with no knowledge that the first one exists.

# one directory per account
mkdir -p ~/.codex-personal ~/.codex-work

# sign in to each, separately
CODEX_HOME=~/.codex-personal codex login
CODEX_HOME=~/.codex-work     codex login

# then run whichever you want
CODEX_HOME=~/.codex-work codex

Typing that prefix every time gets old by the second day. Put it behind shell functions instead, so the account is something you choose rather than something you remember.

# ~/.zshrc
codex-personal() { CODEX_HOME="$HOME/.codex-personal" codex "$@"; }
codex-work()     { CODEX_HOME="$HOME/.codex-work"     codex "$@"; }

Each directory is a complete Codex home, which cuts both ways. Your work account will not see your personal session history, and any config.toml tuning you did has to be repeated in the other home or copied across deliberately. Isolation is the feature and also the chore.

Whether this stays a chore depends on how often you switch. Twice a week is fine. Several times a day, across a CLI and a desktop app, is where people start looking for something that manages it for them.

Why codex --profile is not the answer

Codex has a feature called profiles, and the name sends a lot of people down the wrong path. Profiles are configuration layers. Passing --profile deep-review loads config.toml and then overlays deep-review.config.toml from the same CODEX_HOME, which is how you switch model or reasoning settings.

Credentials are not part of that overlay. They belong to the home directory, so every profile inside one CODEX_HOME is the same signed-in account. If you want a second account, the variable is the lever, and the profile flag is unrelated.

Check where your credentials actually live

This is the step almost every guide on the subject skips, and it decides whether the isolation above is real.

Codex does not always keep credentials in auth.json. A setting called cli_auth_credentials_store picks the storage backend, and its default is auto, which prefers the operating system credential store and falls back to the file. On a Mac with a working keychain, auto generally means the keychain.

OpenAI’s documentation does not say whether keychain entries are separated by CODEX_HOME. Rather than guess, take the ambiguity off the table: write the setting into each account’s own config file, and the credential is then a file you can point at, inside the directory you named.

# in ~/.codex-personal/config.toml and ~/.codex-work/config.toml
cli_auth_credentials_store = "file"

The trade is explicit. OpenAI describes auth.json as a plaintext file, so you are choosing a readable file on disk over the keychain’s protection. For a multi-account setup that certainty is usually worth it. Keep the directories out of any repository, Dropbox folder or backup that leaves the machine.

Never copy auth.json between accounts

Plenty of switcher scripts work by moving auth.json files in and out of ~/.codex. The approach looks sound, passes every test you run on the day, and fails later.

OpenAI’s authentication documentation states that Codex refreshes tokens automatically during use, so the credential in the active directory is rewritten in place as you work. The maintainers of the open-source codex-accounts tool describe the consequence: OpenAI rotates an account’s refresh token on every login and invalidates the previous one server-side, so a stored copy older than the account’s most recent login is already dead no matter how well-formed it looks. We have not found that rotation behaviour in OpenAI’s own documentation, so treat the mechanism as third-party reporting; the symptom is easy to confirm yourself and turns up constantly in issue trackers.

Three specific ways it bites:

• The stale copy. You switch back to an account after a fortnight. The file is intact, the JSON parses, and the token was rotated away days ago. You are signed out with no useful error.
• The duplicate directory. The same account sitting in two homes has two credentials rotating against each other. Each refresh invalidates the other, so both eventually die.
• The misdirected login. A plain codex login writes into whichever home is active. Sign in as personal while work is active and the work directory now holds a personal credential.

Setting CODEX_HOME avoids all three, because nothing ever moves. Each account refreshes its own credential in the directory it lives in. If you do want a switcher that swaps the active account rather than running several at once, prefer one that symlinks ~/.codex/auth.json into the account’s own file so refreshes write through, which is what codex-accounts does.

Running two Codex desktop apps at once

The CLI is the easy case. Two terminals with different CODEX_HOME values coexist without any special handling, since each process reads its own directory.

The desktop app adds a second problem on top. It is an Electron application, so launching it again hands you the existing window instead of starting a fresh instance. Getting two running means isolating Electron’s own data directory as well as the Codex home, using --user-data-dir alongside the environment variable. Edi Hasaj’s write-up on running two Codex accounts on macOS covers the launcher details, including the caution that this is a local workaround rather than a supported mode: a crash, a manual quit or a system sleep can interrupt it.

What the environment-variable method leaves unsolved

Everything above is worth doing and it is where most people stop. It is also worth being clear about what you still do not have, because no amount of shell configuration produces these.

The pooled-allowance row is permanent, whatever any tool claims. The other three are interface problems, so a layer above Codex can address them, and it is worth checking which ones a given tool actually covers for Codex rather than for Claude Code. We list our own gaps below.

Doing it in Crowsnest

Crowsnest is ours, so weigh this section accordingly. It handles the directory bookkeeping described above and adds the part shell configuration cannot reach: a reading of how much each account has left, before you commit a task to one.

Registering an account creates its home at ~/.crowsnest/codex-accounts/<id>/ and hands back the exact command to run in your own terminal, CODEX_HOME=<dir> codex login. Crowsnest does not perform the sign-in. The OAuth exchange stays between you and OpenAI, and the credential is written by Codex into that directory.

It also never touches the credential afterwards. Crowsnest checks whether auth.json exists, to show the account as signed in, and reads nothing from it. No copying, no symlinking, no token parsing, which is the same discipline the section above asks of any switcher you might use instead.

Where Codex support is thinner than Claude Code

Worth stating plainly, because the two providers are not at parity in the shipped app and a feature list would hide it.

• The early warning is Claude Code only. Crowsnest can warn at 90% of a window and offer to continue before a failure, and today that path does not run for Codex conversations. A Codex conversation gets the offer after a turn has already failed.
• Codex history is not attributed per account. The conversation gallery reads Codex sessions from the default ~/.codex home, so older Codex threads are not labelled by the account that wrote them, and reopening one runs it under the default account.
• Automatic continuation acts only when the destination is unambiguous. You have to turn it on, and it proceeds only when exactly one other account of that provider is signed in. With two or more it draws a chooser and waits.
• Signed in means the file is there. An expired credential still shows as signed in until a turn actually fails.

Quota is never pooled here either. Each account keeps its own meter, shown separately, because adding them together would hide which subscription is about to run out.

Several accounts per provider is a Pro feature. Standard drives one Claude Code or Codex account at a time and still browses and searches history. If you run a single Codex account, none of this applies to you and the environment variable above is the whole answer.

Questions behind the search

Related reading