# Codex CLI

:::tip[An easier way]
- Use [magpie](https://docs.2api.dev/en/magpie/) to switch with one click. You don't touch any config files.
- Or, in the API Keys (API 密钥) list in the console, click Use Key (使用密钥) next to your key. The console generates the Codex configuration for your group. Copy it as it is.
:::

Before you start, create a key in a **GPT group** in the console (see [Groups](https://docs.2api.dev/en/start/endpoints/#groups)).

## Install

Use the official installer. Pick the one for your system:

```bash
  curl -fsSL https://chatgpt.com/codex/install.sh | sh
  ```
  ```powershell
  powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
  ```
  ```bash
  npm install -g @openai/codex
  brew install --cask codex
  ```
  After installing, run `codex --version`. If it prints a version number, you are set.

## Configure

1. Fully quit any running Codex, including the Codex extension in VS Code.

2. Write the API key. Create or edit `~/.codex/auth.json` (on Windows, `%USERPROFILE%\.codex\auth.json`):

   ```json title="~/.codex/auth.json"
   {
     "OPENAI_API_KEY": "sk-your-key"
   }
   ```

   You can also write it with a command. The result is the same:

   ```bash
   printf 'sk-your-key' | codex login --with-api-key
   ```

3. Edit `~/.codex/config.toml` and put the lines below at the **very start** of the file, before any `[...]` section:

   ```toml title="~/.codex/config.toml"
   model_provider = "sub2api"

   [model_providers.sub2api]
   name = "sub2api"
   base_url = "https://2api.dev/v1"
   wire_api = "responses"
   requires_openai_auth = true
   ```

   - To pin a model, add `model = "model-name"` below the first line. Use the model name shown under Use Key in the console, or look it up with [`/v1/models`](https://docs.2api.dev/en/start/endpoints/#model-names).
   - Optional: add the line `model_catalog_url = "https://2api.dev/v1/models"` under `[model_providers.sub2api]`. The `/model` list in newer versions of Codex then shows the 2api models. If Codex shows an error at startup after you add it, delete the line.

4. Go to your project directory and start it:

   ```bash
   cd your-project
   codex
   ```

   In Codex, type `/status`. If the provider shows `sub2api` and the address is `https://2api.dev/v1`, Codex is going through 2api.

:::note[Existing users: don't rename the provider]
Keep `model_provider`, `[model_providers.sub2api]` and `name` all set to `sub2api`. Codex ties its session history to the provider name, so after a rename the old sessions become invisible. Older guides set `base_url` to `https://2api.dev` (without `/v1`). That also works, and you don't need to change it.
:::

:::caution[Don't name the provider openai]
`openai` is a name built into Codex. If you use it as the name of a custom provider, `base_url` is ignored and requests go straight to OpenAI.
:::

## Next steps

- To use it in VS Code or Cursor: [Codex extension](https://docs.2api.dev/en/clients/codex-ide/)
- If you also want features that need a ChatGPT sign-in, such as the mobile app and official plugins: [Codex with ChatGPT sign-in + API](https://docs.2api.dev/en/clients/codex-login/)
- If you get an error: [Codex FAQ](https://docs.2api.dev/en/faq/codex/)