Authentication

Usage-based billing alternative: Use an OpenAI API key

If you prefer to pay-as-you-go, you can still authenticate with your OpenAI API key by setting it as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

This key must, at minimum, have write access to the Responses API.

Migrating to ChatGPT login from API key

If you've used the Codex CLI before with usage-based billing via an API key and want to switch to using your ChatGPT plan, follow these steps:

1. Update the CLI and ensure codex --version is 0.20.0 or later
2. Delete ~/.codex/auth.json (on Windows: C:\\Users\\USERNAME\\.codex\\auth.json)
3. Run codex login again

Forcing a specific auth method (advanced)

You can explicitly choose which authentication Codex should prefer when both are available.

• To always use your API key (even when ChatGPT auth exists), set:

# ~/.codex/config.toml
preferred_auth_method = "apikey"

Or override ad-hoc via CLI:

codex --config preferred_auth_method="apikey"

• To prefer ChatGPT auth (default), set:

# ~/.codex/config.toml
preferred_auth_method = "chatgpt"

Notes:

• When preferred_auth_method = "apikey" and an API key is available, the login screen is skipped.
• When preferred_auth_method = "chatgpt" (default), Codex prefers ChatGPT auth if present; if only an API key is present, it will use the API key. Certain account types may also require API-key mode.
• To check which auth method is being used during a session, use the /status command in the TUI.

Connecting on a "Headless" Machine

Today, the login process entails running a server on localhost:1455. If you are on a "headless" server, such as a Docker container or are ssh'd into a remote machine, loading localhost:1455 in the browser on your local machine will not automatically connect to the webserver running on the headless machine, so you must use one of the following workarounds:

Authenticate locally and copy your credentials to the "headless" machine

The easiest solution is likely to run through the codex login process on your local machine such that localhost:1455 is accessible in your web browser. When you complete the authentication process, an auth.json file should be available at $CODEX_HOME/auth.json (on Mac/Linux, $CODEX_HOME defaults to ~/.codex whereas on Windows, it defaults to %USERPROFILE%\\.codex).

Because the auth.json file is not tied to a specific host, once you complete the authentication flow locally, you can copy the $CODEX_HOME/auth.json file to the headless machine and then codex should "just work" on that machine. Note to copy a file to a Docker container, you can do:

# substitute MY_CONTAINER with the name or id of your Docker container:
CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex"
docker cp auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

whereas if you are ssh'd into a remote machine, you likely want to use scp:

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

or try this one-liner:

ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

Connecting through VPS or remote

If you run Codex on a remote machine (VPS/server) without a local browser, the login helper starts a server on localhost:1455 on the remote host. To complete login in your local browser, forward that port to your machine before starting the login flow:

# From your local machine
ssh -L 1455:localhost:1455 <user>@<remote-host>

Then, in that SSH session, run codex and select "Sign in with ChatGPT". When prompted, open the printed URL (it will be http://localhost:1455/...) in your local browser. The traffic will be tunneled to the remote server.