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

# Codex

> Configure Codex through a local Responses adapter with NoMask text models.

Connect the Codex CLI through a local adapter that translates Responses requests into NoMask Chat Completions.

> [!NOTE]
>
> Adapter required. Current Codex uses the Responses API; pointing it directly at NoMask or setting `wire_api = "chat"` does not work. Adapter compatibility depends on your Codex version and selected model.

## Before you start

* Create a key on the [API Keys page](https://nomask.ai/api/keys) and add funds to your API balance.
* Choose a text model with **Function calling** and streaming on the [Models page](https://nomask.ai/models). Copy its exact model ID.
* Use the connection values below. Replace key placeholders locally; keep secrets out of project files and source control.

| Setting | Value |
| - | - |
| **API base URL** | `https://api.nomask.ai/v1` |
| **Model ID** | `your-model-id` |
| **API key** | Your NoMask API key |

> [!NOTE]
>
> Replace `your-model-id` throughout the examples with the exact ID of a text model that supports function calling and streaming. Check the [Models page](https://nomask.ai/models) for current availability and limits.

Examples use your selected model. If you change it, also update context, output and image settings to match that model. These guides cover text models; Image Studio models use separate image endpoints.

## Install and configure

### 1. Start a local protocol adapter

Install Python 3.11 or newer. In a dedicated terminal, install the current LiteLLM proxy package:

```bash theme={"system"}
python -m pip install --upgrade "litellm[proxy]>=1.101.6"
```

Codex needs the tool-call fixes in LiteLLM 1.101.6 or newer. Keep the adapter updated when updating your coding tool.

Set your NoMask key and a separate local adapter password. Replace both placeholders and keep this terminal open.

> [tab] macOS / Linux / WSL
>
> ```bash theme={"system"}
> export NOMASK_API_KEY="YOUR_NOMASK_API_KEY"
> export NOMASK_GATEWAY_KEY="sk-REPLACE_WITH_LOCAL_SECRET"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={"system"}
> $env:NOMASK_API_KEY = "YOUR_NOMASK_API_KEY"
> $env:NOMASK_GATEWAY_KEY = "sk-REPLACE_WITH_LOCAL_SECRET"
> ```

Save this as `nomask-adapter.yaml`. The local alias `nomask` routes to `your-model-id`; changing models means updating this route and restarting the adapter.

```yaml theme={"system"}
model_list:
  - model_name: nomask
    litellm_params:
      model: "custom_openai/your-model-id"
      api_base: "https://api.nomask.ai/v1"
      api_key: os.environ/NOMASK_API_KEY
litellm_settings:
  drop_params: true
  set_verbose: false
general_settings:
  master_key: os.environ/NOMASK_GATEWAY_KEY
```

`custom_openai/` makes LiteLLM translate requests into Chat Completions. Do not enable native Responses or Messages passthrough: NoMask does not expose those protocols. Unsupported optional fields may be removed by `drop_params`.

```bash theme={"system"}
litellm --config nomask-adapter.yaml --host 127.0.0.1 --port 4000
```

This example binds to your own computer. The adapter handles prompt traffic, so its logging and storage settings are under your control. Keep debug logging and `store_prompts_in_spend_logs` off. NoMask's prompt-storage policy is unchanged.

### 2. Install Codex

Install Node.js, then open a second terminal:

```bash theme={"system"}
npm install -g @openai/codex
codex --version
```

### 3. Configure the CLI

Merge the following into `~/.codex/config.toml` on macOS/Linux or `%USERPROFILE%\.codex\config.toml` on Windows. Keep the top-level settings before the first table and avoid duplicate keys.

```toml theme={"system"}
model = "nomask"
model_provider = "nomask_adapter"
web_search = "disabled"

[model_providers.nomask_adapter]
name = "NoMask local adapter"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"
requires_openai_auth = false
```

Set the adapter password in this second terminal, using exactly the same value as `NOMASK_GATEWAY_KEY` in the adapter terminal. This is separate from your NoMask API key.

> [tab] macOS / Linux / WSL
>
> ```bash theme={"system"}
> export CODEX_GATEWAY_API_KEY="sk-REPLACE_WITH_LOCAL_SECRET"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={"system"}
> $env:CODEX_GATEWAY_API_KEY = "sk-REPLACE_WITH_LOCAL_SECRET"
> ```

The `nomask` alias may use generic Codex model settings. For a managed deployment, supply a version-matched Codex model catalog with the same alias and actual capabilities using `model_catalog_json`. NoMask's model-list JSON uses a different schema and cannot be used as that file. Follow the official catalog specification linked below.

## Launch and test

With the adapter running, open a disposable project folder and run `codex`. Use `/status` to confirm the local connection and `nomask` alias.

```text theme={"system"}
Reply with exactly NOMASK_OK. Do not edit files.

List the top-level files using your tools. Then create nomask-test.txt containing NOMASK_OK.
```

Check that text streams, the tool runs, a final answer appears, and a follow-up works in the same session. Approve file actions normally. A successful plain reply does not establish full Codex compatibility.

> [!NOTE]
>
> Stop using this setup if tool results, custom tools or conversation continuation fail. An adapter cannot add missing model capabilities. Cline, Kilo Code, Command Code, OpenCode and Aider have direct Chat Completions setup guides in this section.

For a `/responses` 404, make sure Codex points to the local adapter, and the adapter route uses `custom_openai/`. If ordinary NoMask calls also fail, check the key and model independently:

```bash theme={"system"}
curl https://api.nomask.ai/v1/chat/completions \
  -H "Authorization: Bearer $NOMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model-id","messages":[{"role":"user","content":"Reply with exactly NOMASK_OK."}],"max_tokens":128}'
```

## Troubleshooting

* **401:** check that your key is active and available to the process running the tool. Restart the tool after changing environment variables.
* **402:** add funds to your API balance or reduce the requested output.
* **404:** check the exact model ID and base URL. Direct connections use Chat Completions, not Responses or Anthropic Messages.
* **429:** wait for `Retry-After`. API keys share account limits; creating another key does not reset usage. Check the key's monthly spending cap too.
* **Context or tool errors:** start a shorter task, lower the output limit and confirm the model supports function calling. A plain text reply alone does not confirm file-editing tools work.

Check [API Overview](https://nomask.ai/api/overview) for usage and recent errors. Include the request ID when contacting support; never send your key. See [Errors](https://docs.nomask.ai/errors.md) and [Rate Limits](https://docs.nomask.ai/rate-limits.md).

## Official references

Setup checked against the documentation below. Tool versions may change their settings or configuration format.

* [Codex model compatibility](https://learn.chatgpt.com/docs/models#other-models)
* [Codex custom connections and configuration](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers)
* [Codex gateway compatibility requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility)
* [Codex model catalog specification](https://learn.chatgpt.com/docs/model-catalogs)
* [LiteLLM Responses translation and native passthrough](https://docs.litellm.ai/docs/response_api_native_passthrough)
* [LiteLLM Codex setup and model metadata](https://docs.litellm.ai/docs/proxy/client_setup/codex_cli)
* [LiteLLM 1.101.6 Codex tool-call fixes](https://docs.litellm.ai/release_notes/v1.101.6/v1-101-6)
* [LiteLLM local server configuration](https://docs.litellm.ai/docs/proxy/cli)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.