459363e17b
This PR cleans up the monolithic README by breaking it into a set navigable pages under docs/ (install, getting started, configuration, authentication, sandboxing and approvals, platform details, FAQ, ZDR, contributing, license). The top‑level README is now more concise and intuitive, (with corrected screenshots). It also consolidates overlapping content from codex-rs/README.md into the top‑level docs and updates links accordingly. The codex-rs README remains in place for now as a pointer and for continuity. Finally, added an extensive config reference table at the bottom of docs/config.md. --------- Co-authored-by: easong-openai <easong@openai.com>
88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```shell
|
|
export OPENAI_API_KEY="your-api-key-here"
|
|
```
|
|
|
|
## 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:
|
|
|
|
```toml
|
|
# ~/.codex/config.toml
|
|
preferred_auth_method = "apikey"
|
|
```
|
|
|
|
Or override ad-hoc via CLI:
|
|
|
|
```bash
|
|
codex --config preferred_auth_method="apikey"
|
|
```
|
|
|
|
- To prefer ChatGPT auth (default), set:
|
|
|
|
```toml
|
|
# ~/.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:
|
|
|
|
```shell
|
|
# 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`](https://en.wikipedia.org/wiki/Secure_copy_protocol):
|
|
|
|
```shell
|
|
ssh user@remote 'mkdir -p ~/.codex'
|
|
scp ~/.codex/auth.json user@remote:~/.codex/auth.json
|
|
```
|
|
|
|
or try this one-liner:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```bash
|
|
# 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. |