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

# OpenAI Codex CLI

> OpenAI's official command-line AI coding agent. Connect it to ePhone AI via a custom model provider.

[Codex CLI](https://github.com/openai/codex) is OpenAI's official command-line AI coding agent. It lets you complete code generation, refactoring, debugging, file editing, and system command execution directly from your terminal using natural language. Compared to other AI coding tools, Codex CLI features full sandbox isolation and fine-grained permission control.

## Installation

<Steps>
  <Step title="Check Node.js Version">
    ```bash theme={null}
    node -v
    ```

    Requires Node.js **22+**.
  </Step>

  <Step title="Install Codex CLI">
    ```bash theme={null}
    npm install -g @openai/codex
    ```
  </Step>
</Steps>

## Configure ePhone AI

Codex CLI uses `model_providers` to define custom API providers, and the top-level `model_provider` key to specify which provider to use by default.

<Steps>
  <Step title="Set the API Key Environment Variable">
    <Accordion title="Mac / Linux (zsh)">
      ```zsh theme={null}
      echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.zshrc
      source ~/.zshrc
      ```
    </Accordion>

    <Accordion title="Mac / Linux (bash)">
      ```bash theme={null}
      echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.bash_profile
      source ~/.bash_profile
      ```
    </Accordion>

    <Accordion title="Windows (PowerShell)">
      ```powershell theme={null}
      [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-api-key", "User")
      ```
    </Accordion>
  </Step>

  <Step title="Create the Configuration File">
    ```bash theme={null}
    mkdir -p ~/.codex
    ```

    Add the following to `~/.codex/config.toml`:

    ```toml theme={null}
    # ~/.codex/config.toml

    model = "gpt-4o"
    model_provider = "ephone"       # Required: set the default provider
    disable_response_storage = true

    [model_providers.ephone]
    name = "ePhone AI"
    base_url = "https://api.ephone.ai/v1"
    env_key = "OPENAI_API_KEY"      # Name of the env var (not the key itself)
    wire_api = "responses"          # Responses API protocol (only supported value)
    ```
  </Step>
</Steps>

<Warning>
  **Three critical settings — all are required:**

  * `model_provider = "ephone"` — without this, Codex routes known model names like `gpt-4o` directly to OpenAI's servers
  * `wire_api = "responses"` — the only protocol supported by Codex, using the Responses API
  * `env_key = "OPENAI_API_KEY"` — this is the **name of the environment variable**, not the API key value itself
</Warning>

## Getting Started & Approval Modes

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

On first launch, choose an approval mode that controls how Codex handles permissions:

| Mode             | Config Value | Description                                                                                |
| ---------------- | ------------ | ------------------------------------------------------------------------------------------ |
| **Suggest**      | `untrusted`  | Default. Codex can only read files — all writes and commands require your confirmation     |
| **Auto Execute** | `on-request` | Safe sandbox operations run automatically; only privilege escalation requires confirmation |
| **Full Auto**    | `never`      | No confirmation needed. Codex acts autonomously — best for trusted dev environments        |

Set the default approval mode in `config.toml`:

```toml theme={null}
approval_policy = "on-request"
```

## Common Commands

### CLI Launch Options

| Command                                       | Description                        |
| --------------------------------------------- | ---------------------------------- |
| `codex`                                       | Start an interactive session       |
| `codex "task description"`                    | Run a one-off task directly        |
| `codex --model gpt-4o "task"`                 | Run a task with a specific model   |
| `codex --image screenshot.png "fix this bug"` | Attach an image as context         |
| `codex --search "task description"`           | Enable web search for the task     |
| `codex --profile fast "quick task"`           | Use a preset configuration profile |

### In-Session Commands

Use these slash commands during an interactive session:

| Command      | Description                                             |
| ------------ | ------------------------------------------------------- |
| `/status`    | View current model, token usage, and config info        |
| `/model`     | Switch the active model                                 |
| `/approvals` | Adjust the approval policy for the current session      |
| `/compact`   | Compress conversation history to free context window    |
| `/clear`     | Clear the current conversation history                  |
| `/init`      | Create an `AGENTS.md` template in the current directory |
| `/feedback`  | Submit feedback                                         |

## Recommended Models

| Use Case                | Recommended Model | Notes                                    |
| ----------------------- | ----------------- | ---------------------------------------- |
| Everyday coding         | `gpt-4o`          | Good balance of speed and capability     |
| Complex refactoring     | `o4-mini`         | Strong reasoning for deep analysis tasks |
| Quick lightweight tasks | `gpt-4o-mini`     | Fast response, lower cost                |

<Tip>
  Use the `/model` command to switch models mid-session without restarting.
</Tip>

## Project Configuration: AGENTS.md

Codex automatically reads `AGENTS.md` files on startup as project context instructions, similar to Claude Code's `CLAUDE.md`. Through layered configuration, you can set different rules for different projects and directories.

### Discovery Order

1. **Global**: `~/.codex/AGENTS.md` — shared defaults for all projects
2. **Project root**: `<project-root>/AGENTS.md` — project-level rules
3. **Subdirectories**: `<subdir>/AGENTS.md` — subdirectory overrides

Each level also supports `AGENTS.override.md`, which takes priority over `AGENTS.md` in the same directory.

### Global Configuration Example

```markdown theme={null}
# ~/.codex/AGENTS.md

## Working Agreements
- Prefer pnpm when installing dependencies
- Run relevant tests after modifying code
- Follow Conventional Commits for commit messages
- Ask for confirmation before adding production dependencies
```

### Project Configuration Example

```markdown theme={null}
# AGENTS.md

## Project Info
This is a full-stack project using Go + React.

## Development Standards
- Backend uses Go 1.22+, follow standard project layout
- Frontend uses TypeScript, no any types allowed
- All user-facing strings must use i18n
- Run make build after backend changes
- Run npm run lint after frontend changes

## Testing Requirements
- New APIs must include unit tests
- Test command: go test ./... -v
```

### Subdirectory Override Example

```markdown theme={null}
# services/payments/AGENTS.override.md

## Payment Service Rules
- Use make test-payments instead of the default test command
- All monetary calculations must use decimal types
- Never operate directly on the production database
```

## Configuration Profiles

Profiles let you quickly switch between different configuration sets — ideal for different projects or scenarios:

```toml theme={null}
# ~/.codex/config.toml

# Use the fast profile by default
profile = "fast"

[profiles.fast]
model_provider = "ephone"
model = "gpt-4o-mini"
approval_policy = "never"

[profiles.careful]
model_provider = "ephone"
model = "o4-mini"
approval_policy = "on-request"
model_reasoning_effort = "high"
```

Switch profiles at launch with `--profile`:

```bash theme={null}
codex --profile careful "refactor the error handling in this module"
```

<Info>
  Each profile needs `model_provider = "ephone"` — otherwise switching profiles may fall back to the default OpenAI provider.
</Info>

## MCP Server Integration

Codex CLI supports [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) to connect external tools, significantly extending its Agent capabilities.

```toml theme={null}
# ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@context7/mcp"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }
```

Once configured, Codex can query documentation, interact with GitHub, and more — without manually providing context.

## Reasoning Control

For models that support reasoning (e.g., `o4-mini`), you can control reasoning depth:

```toml theme={null}
model_reasoning_effort = "high"    # minimal | low | medium | high
model_reasoning_summary = "auto"   # auto | concise | detailed | none
```

Higher reasoning effort means deeper thinking but higher token usage. Use `medium` for daily tasks and `high` for complex refactoring.

## Web Search

Codex supports web search during conversations to fetch the latest documentation and information:

```toml theme={null}
web_search = "cached"   # disabled | cached | live
```

* `cached`: Uses an OpenAI-maintained index (default, fast)
* `live`: Fetches live web pages (most current info)
* `disabled`: Turns off search entirely

You can also enable search at launch with `--search`:

```bash theme={null}
codex --search "find the latest React 19 API changes"
```

## Sandbox & Security

Codex provides three sandbox levels to protect your system:

| Mode                 | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `read-only`          | Read-only mode — cannot modify files or run write commands |
| `workspace-write`    | Can modify files within the workspace directory (default)  |
| `danger-full-access` | Full access with no restrictions (use with caution)        |

```toml theme={null}
sandbox_mode = "workspace-write"
```

## Usage Examples

### Code Refactoring

```bash theme={null}
codex "convert all error handling in utils/helpers.go to use wrapped errors"
```

### Bug Fixing with Screenshots

```bash theme={null}
codex --image bug-screenshot.png "this button doesn't respond when clicked, help me locate and fix the issue"
```

### Project Scaffolding

```bash theme={null}
codex "create a Go + Gin REST API project scaffold with CRUD, middleware, and Docker config"
```

### Git Operations

```bash theme={null}
codex "review recent commit history, find the commit that introduced this bug, then fix it"
```

### Code Review

```bash theme={null}
codex "review recently modified files in src/services/, identify potential security issues and performance concerns"
```

## Full Configuration Reference

```toml theme={null}
# ~/.codex/config.toml

# Default model and provider (required)
model = "gpt-4o"
model_provider = "ephone"

# Approval policy
approval_policy = "on-request"

# Sandbox mode
sandbox_mode = "workspace-write"

# Reasoning control
model_reasoning_effort = "medium"

# Web search
web_search = "cached"

# Disable API response storage (required for third-party providers)
disable_response_storage = true

# Conversation history
[history]
persistence = "save-all"

# ePhone AI Provider
[model_providers.ephone]
name = "ePhone AI"
base_url = "https://api.ephone.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

# Fast profile
[profiles.fast]
model_provider = "ephone"
model = "gpt-4o-mini"
approval_policy = "never"
model_reasoning_effort = "minimal"

# Deep thinking profile
[profiles.think]
model_provider = "ephone"
model = "o4-mini"
approval_policy = "on-request"
model_reasoning_effort = "high"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized — still connecting to api.openai.com">
    **Cause**: Missing `model_provider = "ephone"` in config. Codex routes known model names (like `gpt-4o`) to the built-in OpenAI provider.

    **Fix**: Ensure `model_provider = "ephone"` is set at the top level of `config.toml`.

    If you previously logged into Codex via ChatGPT, also clear cached credentials:

    ```bash theme={null}
    rm -f ~/.codex/auth.json
    ```
  </Accordion>

  <Accordion title="WebSocket connecting to api.openai.com">
    **Cause**: Missing `model_provider` configuration, causing Codex to route WebSocket connections to OpenAI's servers instead of ePhone AI.

    **Fix**: Ensure `model_provider = "ephone"` is set at the top level of `config.toml`. This routes connections to `wss://api.ephone.ai/v1/responses`.
  </Accordion>

  <Accordion title="env_key not working">
    **Cause**: `env_key` should contain the **name of the environment variable** (e.g., `"OPENAI_API_KEY"`), not the API key value itself.

    **Fix**: Set `env_key = "OPENAI_API_KEY"` and make sure the variable is exported via `export OPENAI_API_KEY="sk-..."`.
  </Accordion>

  <Accordion title="Switching profiles falls back to OpenAI">
    **Cause**: The profile doesn't include `model_provider`, so it reverts to the default OpenAI provider.

    **Fix**: Add `model_provider = "ephone"` to every profile section.
  </Accordion>
</AccordionGroup>

## Important Notes

<Warning>
  Codex CLI's autonomous mode calls the model frequently and executes system commands — token usage is much higher than regular chat. We recommend using a Tier 2 account to avoid hitting rate limits.
</Warning>

* Set `disable_response_storage = true` to disable API response storage — required for third-party providers
* Use the `/compact` command to compress overly long conversation history and prevent context window limits
* Log files are located at `~/.codex/log/` — check them for troubleshooting

## Related Resources

<CardGroup cols={3}>
  <Card title="Official Codex Docs" icon="book" href="https://developers.openai.com/codex">
    OpenAI developer documentation
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/openai/codex">
    Source code & issues
  </Card>

  <Card title="AGENTS.md Spec" icon="file" href="https://agents.md">
    Project configuration spec
  </Card>
</CardGroup>