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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Codex

> Use the Phaseo Gateway as a custom provider for Codex CLI, Codex App, and the Codex IDE extension.

Codex supports custom model providers through `config.toml`, so you can route Codex requests through Phaseo while keeping the same CLI, app, or IDE workflow.

If you also want Codex to read the live Phaseo documentation while it works, add the [Docs MCP](https://phaseo.app/docs/v1/guides/integrations/docs-mcp.md) server as well.

> [!NOTE]
>
> Reusable Phaseo skills are available from [`phaseo.app/docs`](https://phaseo.app/docs/.well-known/agent-skills/index.json). For Codex installs, use:
>
> ```bash theme={null}
> npx skills add https://phaseo.app/docs --agent codex --skill '*'
> ```

## Set up with the Phaseo CLI

```bash theme={null}
phaseo login
phaseo codex --model openai/gpt-5.6-terra
```

Install Codex from its official release first. Setup creates a `Phaseo CLI: Codex API Key` that expires after 90 days and has a \$100 monthly spend limit, stores it in the OS credential store, and writes a dedicated Phaseo profile. Codex retrieves the key through the CLI helper, which creates a new key when the old one expires, so no plaintext key is written to `config.toml`.

Start Codex with:

```bash theme={null}
codex --profile phaseo
```

The same Phaseo CLI workflow also launches [Cline](https://phaseo.app/docs/v1/guides/integrations/cline.md), [Kilo Code](https://phaseo.app/docs/v1/guides/integrations/kilo-code.md), [oh-my-pi](https://phaseo.app/docs/v1/guides/integrations/oh-my-pi.md), [Muse Code](https://phaseo.app/docs/v1/guides/integrations/muse-code.md), and [MiniMax Code](https://phaseo.app/docs/v1/guides/integrations/minimax-code.md) with isolated temporary provider configuration.

## Manual configuration

Create or update your user config at `~/.codex/config.toml`. For a trusted project, you can also place the same settings in `.codex/config.toml` inside the repo.

```toml theme={null}
model = "openai/gpt-5.5"
model_provider = "phaseo"

[model_providers.phaseo]
name = "Phaseo"
base_url = "https://api.phaseo.app/v1"
env_key = "PHASEO_API_KEY"
wire_api = "responses"
```

Codex currently uses the Responses wire protocol for custom providers. Keep `wire_api = "responses"` or omit it and use the default.

The Codex App and IDE extension share the same config layers. In the IDE extension, open the config from `Codex Settings > Open config.toml`.

## Verification

* Confirm your model id exists in [Models](https://phaseo.app/docs/v1/api-reference/endpoint/models.md) before launching.
* Use [Responses](https://phaseo.app/docs/v1/api-reference/endpoint/responses.md) for the default Codex-style flow.

## Troubleshooting

* `401 Unauthorized`: run `phaseo whoami`, then rerun `phaseo codex`.
* `model_not_found`: fetch a current id from [Models](https://phaseo.app/docs/v1/api-reference/endpoint/models.md) and update `model`.
* Provider-specific issues: follow [Routing and fallbacks](https://phaseo.app/docs/v1/guides/routing-and-fallbacks.md) for failover behavior.


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