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

# Codex

> Connect the Orq MCP server to OpenAI Codex to manage experiments, traces, and agents, and route Codex model calls through the Orq.ai AI Gateway.

Codex is an AI coding assistant that supports Model Context Protocol integrations. Connect the **Orq MCP** server to manage AI workflows directly from Codex, and route Codex's model calls through the **AI Gateway**.

<CardGroup cols={2}>
  <Card title="MCP Integration" icon="plug" href="#mcp">
    Access the **Orq.ai** workspace directly from Codex. Manage experiments, query traces, and configure agents using natural language.
  </Card>

  <Card title="AI Gateway" icon="arrow-right-arrow-left" href="#ai-gateway">
    Route Codex's model calls through the **AI Gateway** for unified tracing and cost tracking.
  </Card>
</CardGroup>

## MCP

With the **Orq MCP** integration, manage AI workflows directly from Codex while writing code.

### Prerequisites

* [Codex](https://developers.openai.com/codex/) installed
* Active Orq.ai account
* [Orq.ai API key](/ai-studio/organization/api-keys)

### Installation

#### Add MCP Server via Terminal

Set the `ORQ_API_KEY` environment variable and add the **Orq MCP** server directly from the terminal:

```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ORQ_API_KEY="your-api-key-here"
codex mcp add orq --url https://my.orq.ai/v2/mcp --bearer-token-env-var ORQ_API_KEY
```

Replace `your-api-key-here` with your actual API key from [Workspace Settings → API Keys](https://my.orq.ai/settings/api-keys).

#### Add MCP Server via UI

1. Open Codex Settings by clicking **Codex** → **Settings** in the top-left menu
2. Click **MCP Servers** in the sidebar
3. Click **Connect to a custom MCP** to open the configuration form
4. Fill in the MCP server details:
   * **Name:** `Orq.ai`
   * **Connection Type:** Select **Streamable HTTP** tab
   * **URL:** `https://my.orq.ai/v2/mcp`
5. Add authentication in the **Environment variables** section:
   * Click **+ Add environment variable**
   * **Key:** `AUTHORIZATION`
   * **Value:** `Bearer YOUR_ORQ_API_KEY`
6. Replace `YOUR_ORQ_API_KEY` with your actual API key from [Workspace Settings → API Keys](https://my.orq.ai/settings/api-keys)
7. Click **Save**

The MCP server should connect automatically and all Orq.ai tools will be available immediately.

### Verification

In Codex chat, ask:

```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Can you list the available models from Orq?
```

If configured correctly, Codex will display AI models from the **Orq.ai** workspace.

<Frame caption="Successfully connected Orq MCP in Codex">
  <img src="https://mintcdn.com/orqai/rjY3PTYrNubA6L2q/images/mcp-codex-success.png?fit=max&auto=format&n=rjY3PTYrNubA6L2q&q=85&s=16f1d69bf8c596b70cb42955389ea3b4" alt="Codex showing the Orq MCP server connected and tools available in the chat interface" width="2784" height="1864" data-path="images/mcp-codex-success.png" />
</Frame>

### Available Commands

Use natural language to ask Codex to perform these operations:

<AccordionGroup>
  <Accordion title="Agents" icon="robot">
    * `Create an agent with custom instructions and tools`
    * `Get agent configuration for [agent-key]`
    * `Update agent [agent-key] with new instructions or model`
    * `Configure agent with evaluators and guardrails`
    * `Invoke agent [agent-key] with input [message]`
    * `Retrieve agent response [response-id]`
  </Accordion>

  <Accordion title="Deployments" icon="rocket">
    * `Create a deployment called [deployment-key]`
    * `Get deployment configuration for [deployment-key]`
  </Accordion>

  <Accordion title="Skills" icon="puzzle-piece">
    * `Create a skill called [skill-key]`
    * `List all skills in my workspace`
    * `Get skill [skill-key]`
    * `Update skill [skill-key]`
    * `Delete skill [skill-key]`
  </Accordion>

  <Accordion title="Analytics" icon="chart-line">
    * `Get analytics overview for my workspace`
    * `Show me workspace metrics for the last 7 days`
    * `Query analytics filtered by deployment ID`
  </Accordion>

  <Accordion title="Datasets" icon="database">
    * `Create a dataset called "customer-queries"`
    * `List all datapoints in dataset [dataset-key]`
    * `Add datapoints to dataset [dataset-key]`
    * `Update datapoint [datapoint-id]`
    * `Delete specific datapoints in dataset [dataset-key]`
    * `Delete dataset [dataset-key]`
  </Accordion>

  <Accordion title="Experiments" icon="flask">
    * `Create an experiment from dataset [dataset-key]`
    * `List all experiment runs`
    * `Export experiment run [run-id] as CSV`
    * `Run experiment and auto-evaluate results`
  </Accordion>

  <Accordion title="Evaluators" icon="clipboard-check">
    * `Get evaluator configuration for [evaluator-key]`
    * `Create an LLM-as-a-Judge evaluator for tone`
    * `Create a Python evaluator to check response length`
    * `Add evaluator to experiment [experiment-key]`
    * `Update evaluator [evaluator-key] with a new prompt`
    * `Update Python evaluator [evaluator-key] with revised code`
  </Accordion>

  <Accordion title="Traces" icon="chart-bullet">
    * `List traces from the last 24 hours`
    * `Show me traces with errors`
    * `Get span details for trace [trace-id]`
    * `Find the slowest traces from today`
    * `Show all traces for thread [thread-id]`
  </Accordion>

  <Accordion title="Models" icon="microchip">
    * `List all available chat models`
    * `List all available embedding models`
    * `Invoke model [model-id] with prompt [message]`
  </Accordion>

  <Accordion title="Search" icon="magnifying-glass">
    * `Search for datasets named "customer"`
    * `Find experiments in project [project-id]`
    * `List directories in project [project-id]`
  </Accordion>

  <Accordion title="Documentation" icon="book-open">
    * `Search the Orq.ai docs for [topic]`
  </Accordion>

  <Accordion title="Managing Entities" icon="trash">
    * `Delete agent [agent-key]`
    * `Delete experiment [experiment-key]`
    * `Delete evaluator [evaluator-key]`
    * `Delete prompt [prompt-key]`
    * `Delete knowledge base [knowledge-base-key]`

    Use `delete_dataset` to delete a dataset along with all its datapoints.
  </Accordion>
</AccordionGroup>

See the [MCP Quickstart](/ai-studio/integrations/code-assistants/orq-mcp) for the full tool reference and examples.

### Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Issues">
    1. Verify the MCP endpoint URL
    2. Check the API key is valid
    3. Ensure network connectivity
    4. Review Codex logs for errors
  </Accordion>

  <Accordion title="Authentication Failures">
    1. Confirm API key is valid
    2. Check API key permissions
    3. Try regenerating the API key
    4. Verify the Authorization header format
  </Accordion>

  <Accordion title="Tool Execution Errors">
    1. Check the tool name is correct
    2. Verify required parameters are provided
    3. Review error messages in Codex
    4. Consult [MCP tools list](/ai-studio/integrations/code-assistants/orq-mcp#available-tools)
  </Accordion>
</AccordionGroup>

## Skills

**Orq Skills** add pre-built agentic workflows to Codex for the full Build, Evaluate, Optimize lifecycle.

### Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx skills add orq-ai/assistant-plugins --agent codex
```

Set an [API key and connect the Orq MCP server](/ai-studio/integrations/code-assistants/orq-skills#prerequisites) first. Skills are then triggered by describing what is needed.

<Card title="Orq Skills" icon="wand-magic-sparkles" href="/ai-studio/integrations/code-assistants/orq-skills">
  The full catalogue of skills and slash commands.
</Card>

<Note>
  Slash commands (`/orq:quickstart`, `/orq:traces`, and others) are only available in Claude Code.
</Note>

## AI Gateway

Route every model call Codex CLI makes through the [**Orq.ai AI Gateway**](/ai-gateway/get-started/introduction) by editing `~/.codex/config.toml`. Requests appear in [Traces](/ai-studio/observability/traces) automatically.

### Prerequisites

* [Codex CLI](https://github.com/openai/codex) installed
* Active **Orq.ai** account with **AI Gateway** access
* [Orq.ai API key](/ai-studio/organization/api-keys)
* Model enabled in [**AI Gateway** → **Supported Models**](/ai-gateway/supported-models)

### Setup

<Steps>
  <Step title="Export the API key">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export ORQ_API_KEY="<your-orq-api-key>"
    ```

    Replace `<your-orq-api-key>` with an [API key](/ai-studio/organization/api-keys). This sets the variable for the current shell session. To persist it across sessions, add the line to `~/.zshrc` or `~/.bashrc`.
  </Step>

  <Step title="Create or edit ~/.codex/config.toml">
    Create `~/.codex/config.toml` if it does not exist. Add or merge the following keys. The top-level `model` and `model_provider` lines set the default; the `[model_providers.orq]` block registers the custom provider:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    model = "openai/gpt-5.4"
    model_provider = "orq"

    [model_providers.orq]
    name = "Orq AI Gateway"
    base_url = "https://my.orq.ai/v3/router"
    env_key = "ORQ_API_KEY"
    wire_api = "responses"
    ```

    Replace `openai/gpt-5.4` with the provider-prefixed model to use by default (e.g. `anthropic/claude-sonnet-5`). If a `model` key already exists in the file, replace it.

    <Warning>
      Do not name the provider `openai`. That identifier is reserved and hardcoded to `api.openai.com`. Setting `base_url` has no effect on it.
    </Warning>
  </Step>

  <Step title="Run Codex">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    codex
    ```

    Running `codex` without flags routes all calls through the **AI Gateway** using the model configured in `~/.codex/config.toml`.

    Pass `--model` to override the model for a single invocation:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    codex --model anthropic/claude-sonnet-5
    ```
  </Step>
</Steps>

### Configuration Reference

| Field            | Value                         | Description                                       |
| ---------------- | ----------------------------- | ------------------------------------------------- |
| `model`          | `provider/model-id`           | Default model. Must use provider-prefixed format. |
| `model_provider` | `orq`                         | Selects the custom provider defined below.        |
| `base_url`       | `https://my.orq.ai/v3/router` | AI Gateway router endpoint.                       |
| `env_key`        | `ORQ_API_KEY`                 | Environment variable that holds the API key.      |
| `wire_api`       | `responses`                   | Wire protocol. Codex uses the Responses API.      |

### Tagging requests

Codex cannot modify the request body, so tag requests by adding `http_headers` to the `[model_providers.orq]` block:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[model_providers.orq]
name = "Orq AI Gateway"
base_url = "https://my.orq.ai/v3/router"
env_key = "ORQ_API_KEY"
wire_api = "responses"

[model_providers.orq.http_headers]
"X-ORQ-METADATA-REPO" = "acme-api"
"X-ORQ-METADATA-TICKET" = "PROJ-123"
```

See [Request Metadata](/ai-gateway/request-metadata) for the full header reference and precedence rules.

### Trace capture

Codex sends a stable session ID with each Responses request. The **AI Gateway** uses that ID to group the model round-trips from one Codex run into a session in [**Traces**](/ai-studio/observability/traces). Each round-trip remains a Responses trace and includes its model, token usage, cost, and tool calls.

### Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication error">
    Confirm `ORQ_API_KEY` is exported in the shell running Codex. Run `echo $ORQ_API_KEY` to verify the value is set.
  </Accordion>

  <Accordion title="Model not found">
    The model must be enabled in [**AI Gateway** → **Supported Models**](/ai-gateway/supported-models) before Codex can route to it. Check that the model ID in `config.toml` uses the provider-prefixed format (e.g. `openai/gpt-5.4`, not `gpt-5.6-sol`).
  </Accordion>

  <Accordion title="No Traces appearing in Orq.ai">
    Confirm `base_url` is `https://my.orq.ai/v3/router` and `model_provider` is set to the custom provider name (e.g. `orq`), not `openai`.
  </Accordion>

  <Accordion title="Auto-review requests fail">
    With `approvals_reviewer = "auto_review"` in `~/.codex/config.toml`, Codex sends its internal model name `codex-auto-review` for automatic approval reviews. The **AI Gateway** resolves this name to `openai/gpt-5.3-codex`, so that model must be enabled in [**AI Gateway** → **Supported Models**](/ai-gateway/supported-models). To keep approval prompts interactive instead, set `approvals_reviewer = "user"` (the default).
  </Accordion>
</AccordionGroup>

### Verification

Send a prompt in Codex. The response appears in the terminal, and the Codex session appears in [**Traces**](/ai-studio/observability/traces) with its model identifier, turns, tool calls, token usage, and cost.