> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Use Moxus AI's OpenAI-compatible endpoint in Codex CLI or local Codex environments.

Codex CLI selects model providers from local configuration. To use Moxus AI, add a custom provider to Codex `config.toml` and let Codex read the API key from either an environment variable or `auth.command`.

<Warning>
  This page applies to Codex CLI or local Codex environments that support `config.toml` and custom `model_providers`. Codex versions can differ. If your version reports unsupported fields, follow the current Codex error message and built-in help.
</Warning>

## Values

| Field                        | Value                                             |
| ---------------------------- | ------------------------------------------------- |
| Base URL                     | `https://moxus.cloud/v1`                          |
| API Key                      | `sk-your-key`                                     |
| API key environment variable | `MOXUS_API_KEY`                                   |
| Provider name                | `custom`                                          |
| Default request mode         | Responses API                                     |
| Model                        | Copy the exact model name from Models and pricing |

## Install Codex CLI

Install first, then run the version check separately. Do not put install, update, and verification commands into one copyable block.

<Tabs>
  <Tab title="macOS / Linux">
    Install:

    ```bash theme={null}
    curl -fsSL https://chatgpt.com/codex/install.sh | sh
    ```

    Verify:

    ```bash theme={null}
    codex --version
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    Install:

    ```powershell theme={null}
    powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
    ```

    If the same PowerShell window still says `codex` is not recognized, refresh the current `PATH` first:

    ```powershell theme={null}
    $env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")
    ```

    Verify:

    ```powershell theme={null}
    codex --version
    ```
  </Tab>

  <Tab title="npm">
    Install:

    ```bash theme={null}
    npm install -g @openai/codex
    ```

    Verify:

    ```bash theme={null}
    codex --version
    ```
  </Tab>

  <Tab title="Homebrew">
    Install:

    ```bash theme={null}
    brew install --cask codex
    ```

    Verify:

    ```bash theme={null}
    codex --version
    ```
  </Tab>
</Tabs>

## Recommended: import configuration from an API key

On the Moxus AI API keys page, each key row has an Import configuration action. Choose Codex to generate a terminal script for the selected key and current site address.

<Steps>
  <Step title="Open the API keys page">
    Go to the Moxus AI console API keys page and find the key you want Codex to use.
  </Step>

  <Step title="Open Import configuration">
    Open the actions menu for that key, choose Import configuration, then switch to `Codex`.
  </Step>

  <Step title="Copy the script for your system">
    Use “macOS / Linux terminal” for macOS or Linux. Use “Windows PowerShell” for Windows.
  </Step>

  <Step title="Run the script directly in your terminal">
    Open your terminal, paste the copied script directly into the same terminal window, and press Enter. The script works in both zsh and Bash, and the current terminal can use the new configuration as soon as it finishes.
  </Step>
</Steps>

The generated script does the following:

| System             | What it writes                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| macOS / Linux      | Writes `${CODEX_HOME:-$HOME/.codex}/config.toml`, creates `${CODEX_HOME:-$HOME/.codex}/moxus-env.sh` for `MOXUS_API_KEY`, then adds an auto-load block to `~/.zshrc` and `~/.bashrc`                                                                   |
| Windows PowerShell | Writes `%USERPROFILE%\.codex\config.toml`, writes `%USERPROFILE%\.codex\moxus-api-key.txt`, and uses `auth.command` in `config.toml` to read that file; it also sets `MOXUS_API_KEY` as a current-user environment variable for terminal compatibility |

<Warning>
  The current Import configuration script overwrites Codex `config.toml`. If you already have other providers, models, sandbox settings, or project defaults, back up the file before running the script.
</Warning>

<Info>
  Use the “macOS / Linux terminal” script for macOS or Linux, and the PowerShell script for Windows. Both can be pasted and run directly in their respective terminals; no temporary file or extra command is required.
</Info>

## Codex config file location

Codex reads `.codex/config.toml` from your user directory by default. If you set `CODEX_HOME`, the file moves to `$CODEX_HOME/config.toml`.

<Tabs>
  <Tab title="macOS">
    Default path: `/Users/your-name/.codex/config.toml`

    Create the directory:

    ```bash theme={null}
    mkdir -p ~/.codex
    ```

    Open the directory:

    ```bash theme={null}
    open ~/.codex
    ```
  </Tab>

  <Tab title="Linux">
    Default path: `/home/your-name/.codex/config.toml`

    Create the directory:

    ```bash theme={null}
    mkdir -p ~/.codex
    ```

    Check the file:

    ```bash theme={null}
    ls ~/.codex/config.toml
    ```
  </Tab>

  <Tab title="Windows">
    Default path: `C:\Users\your-name\.codex\config.toml`

    Create the directory:

    ```powershell theme={null}
    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"
    ```

    Open the directory:

    ```powershell theme={null}
    explorer $env:USERPROFILE\.codex
    ```
  </Tab>
</Tabs>

The file name must be `config.toml`. If you create it with Notepad, make sure it is not saved as `config.toml.txt`.

## Manual config.toml setup

If you do not use Import configuration, create or edit `config.toml` manually:

```toml theme={null}
model_provider = "custom"
model = "gpt-5.4"

[model_providers.custom]
name = "custom"
base_url = "https://moxus.cloud/v1"
env_key = "MOXUS_API_KEY"
requires_openai_auth = false
wire_api = "responses"
```

Key fields:

| Field                  | Meaning                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `model_provider`       | The default provider name. It must match `[model_providers.custom]`                                 |
| `model`                | The default model Codex uses. You can change it to an exact model name from Models and pricing      |
| `base_url`             | Moxus AI's OpenAI-compatible endpoint                                                               |
| `env_key`              | Codex reads the key from `MOXUS_API_KEY`, so the secret does not need to be stored in `config.toml` |
| `requires_openai_auth` | Set to `false` so Codex does not require OpenAI account auth for this provider                      |
| `wire_api`             | Set to `responses` to use the Responses API request shape                                           |

## Manually set the API key

### Current terminal only

Use this for a temporary test. macOS and Linux replace only the key read during this launch. Windows also overrides the provider for this launch because the Windows `config.toml` generated by Import configuration uses `auth.command` to read a key file. The variable disappears when you close the terminal.

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    MOXUS_API_KEY="sk-your-key" codex \
      -c 'model_provider = "custom"' \
      -c 'model = "gpt-5.4"' \
      -c 'model_providers.custom = { name = "custom", base_url = "https://moxus.cloud/v1", env_key = "MOXUS_API_KEY", requires_openai_auth = false, wire_api = "responses" }'
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    Copy and run the complete block. It applies to this launch only and does not change the existing `config.toml` or key file:

    ```powershell theme={null}
    $env:MOXUS_API_KEY="sk-your-key"
    codex `
      -c 'model_provider = "moxus_temp"' `
      -c 'model = "gpt-5.4"' `
      -c 'model_providers.moxus_temp.name = "moxus_temp"' `
      -c 'model_providers.moxus_temp.base_url = "https://moxus.cloud/v1"' `
      -c 'model_providers.moxus_temp.env_key = "MOXUS_API_KEY"' `
      -c 'model_providers.moxus_temp.requires_openai_auth = false' `
      -c 'model_providers.moxus_temp.wire_api = "responses"'
    ```
  </Tab>
</Tabs>

For persistent setup or desktop use, choose Codex from Import configuration on the API keys page. The generated script writes both the provider configuration and key, and configures the launch environment for the current operating system.

## Verify

Confirm that Codex can read the config file and environment variable, then run a small task.

Check the key variable:

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    echo "$MOXUS_API_KEY"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    echo $env:MOXUS_API_KEY
    ```
  </Tab>
</Tabs>

Run a test task:

```bash theme={null}
codex "hello"
```

Then open [Usage](/en/platform/dashboard-and-usage) and confirm the request appears under the expected API key.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Can I put the API key directly in config.toml?">
    Not recommended. The latest Windows Codex script generated from `/keys` does not write the plain-text key into `config.toml`; it stores the key in `%USERPROFILE%\.codex\moxus-api-key.txt` and reads it through `auth.command`. macOS and Linux still use environment variables. This keeps the secret out of `config.toml` and makes key rotation easier.
  </Accordion>

  <Accordion title="My previous Codex configuration disappeared after Import configuration">
    The `/keys` Codex script overwrites `config.toml`. If you already have custom settings, back up the file first or manually merge `[model_providers.custom]` into your existing config.
  </Accordion>

  <Accordion title="How do I remove the Moxus AI configuration for Codex?">
    If `config.toml` was created only by the Import configuration script, use these commands to remove the Moxus AI configuration, key, and current-session variable. If you merged other providers or personal settings into that file, do not delete the whole `config.toml`; remove only the `custom` provider configuration.

    macOS / Linux:

    ```bash theme={null}
    CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"

    rm -f "$CODEX_DIR/config.toml" "$CODEX_DIR/moxus-env.sh"

    for profile in "$HOME/.zshrc" "$HOME/.bashrc"; do
      [ -f "$profile" ] || continue
      sed -i.bak '/# Moxus AI Codex start/,/# Moxus AI Codex end/d' "$profile"
    done

    unset MOXUS_API_KEY
    if command -v launchctl >/dev/null 2>&1; then
      launchctl unsetenv MOXUS_API_KEY
    fi
    ```

    Windows PowerShell:

    ```powershell theme={null}
    $CodexDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }

    Remove-Item (Join-Path $CodexDir "config.toml") -Force -ErrorAction SilentlyContinue
    Remove-Item (Join-Path $CodexDir "moxus-api-key.txt") -Force -ErrorAction SilentlyContinue

    [Environment]::SetEnvironmentVariable("MOXUS_API_KEY", $null, "User")
    Remove-Item Env:MOXUS_API_KEY -ErrorAction SilentlyContinue
    ```

    Fully quit and reopen Codex afterwards. On macOS, restart the desktop app as well.
  </Accordion>

  <Accordion title="Authentication fails">
    First check which config style you are using. If `config.toml` uses `env_key = "MOXUS_API_KEY"`, confirm that the terminal or GUI environment launching Codex can read that variable. Reopen the terminal after terminal setup, and GUI-launched Windows clients may still require a system sign-out/sign-in. If you are using the latest Windows script generated from `/keys`, confirm that `%USERPROFILE%\.codex\moxus-api-key.txt` exists and that `[model_providers.custom.auth]` in `config.toml` has not been overwritten by an older config. Then fully quit and reopen Codex.
  </Accordion>

  <Accordion title="After installing on Windows, codex --version says the command cannot be found">
    This usually means installation completed but the current PowerShell window has not refreshed its `PATH` yet. Run:

    ```powershell theme={null}
    $env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")
    ```

    Then run `codex --version` again. If it still fails, close PowerShell, open a new window, and try again.
  </Accordion>

  <Accordion title="Model not found">
    Set `model` to the exact model name from Models and pricing. Do not use a client display name or shorthand.
  </Accordion>

  <Accordion title="wire_api or provider fields are unsupported">
    Your Codex version may use a different custom provider format. Keep the Base URL and API key values, then adjust `wire_api` or provider fields according to the current Codex error message.
  </Accordion>
</AccordionGroup>

## Next steps

* [Quickstart](/en/overview/quickstart)
* [API keys](/en/platform/account-and-keys)