# Codex Complete Tutorial

> **Last verified**: 2026-09-18 · 📄 Per official docs (Codex CLI v0.155.0, released 2026-09-17) · the profile behaviour in 5.4 was additionally tested locally (✅ codex-cli 0.155.0, isolated HOME, no model requests sent)

## At a glance

| Item | Details |
|---|---|
| Models you can use | GPT ✅ (Responses leg) · Claude ❌ · Chinese models ❌ (the Responses leg does not serve them) · Gemini ❌ |
| Protocol & Base URL | OpenAI Responses: `base_url = "https://api.qcode.cc/openai"` + `wire_api = "responses"` in config.toml |
| Where to configure | `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\`) |
| Official docs | [openai/codex](https://github.com/openai/codex) |

> 📖 Why does Codex's `base_url` differ from Claude's `ANTHROPIC_BASE_URL`? What's the difference between `/openai` and `/openai/v1`? See [Endpoints & API Paths](../getting-started/endpoints-and-api-paths).

This is a **complete Codex CLI tutorial for Chinese developers**, taking you from zero to installing, configuring, and using OpenAI Codex CLI, and enjoying low-cost, low-latency AI programming experience through QCode.cc. Whether you're first touching AI programming tools or already using Claude Code and want to try new tools, this tutorial is suitable for you.

---

## 1. Codex Introduction

### What is OpenAI Codex CLI?

[Codex CLI](https://github.com/openai/codex) is an **open-source command-line AI programming assistant** (Apache 2.0 license) launched by OpenAI, written in Rust and can run directly in the terminal. It can:

- **Read and understand** your code repository
- **Edit files** and generate new code
- **Execute commands** (such as running tests, installing dependencies)
- **Iterate autonomously** until the task is complete

The core philosophy of Codex is **Autonomous Agent**: you describe the task, Codex completes it autonomously in a sandbox, and you review the results at the end. This complements Claude Code's **interactive dialogue** style.

### Development History of Codex

The name "Codex" has gone through multiple evolutions in OpenAI's product lineup:

- **2021**: The earliest Codex was a code fine-tuned version of GPT-3, powering GitHub Copilot
- **2024**: OpenAI reactivated the Codex brand, launching a cloud-based asynchronous AI programming agent
- **2025-2026**: Codex CLI developed into a mature local command-line tool, rewritten in Rust, supporting advanced features such as MCP, Skills, and Multi-Agent

Current Codex is a multi-interface product: including **CLI command-line tool** (focus of this article), **macOS desktop app**, **IDE plugins**, and **cloud agents** integrated into ChatGPT. The version used through QCode.cc is the CLI version.

### Core Differences Between Codex and Claude Code

| Dimension | Codex CLI | Claude Code |
|------|-----------|-------------|
| Execution Style | Autonomous execution, delivers results upon completion | Interactive dialogue, step-by-step confirmation |
| Open Source | Fully open source (Apache 2.0) | Not open source |
| Language | Rust (fast startup, low resource usage) | TypeScript |
| Sandbox Security | Built-in Landlock/seccomp sandbox | Permission prompt confirmation |
| Instruction File | `AGENTS.md` | `CLAUDE.md` |
| Cloud Agent | Supported (built into ChatGPT) | Not supported |

In simple terms: **Codex excels at "hands-off tasks"** (give a clear requirement, let it run through), **Claude Code excels at "pair programming"** (discuss and modify while exploring, suitable for exploratory tasks). Using both together yields the best results.

### Why Use Codex Through QCode.cc?

Codex CLI requires OpenAI API Key or ChatGPT subscription by default, but there are two problems in mainland China:

1. **Network unreachable**: OpenAI API cannot be accessed directly
2. **High cost**: Official GPT-5.3-Codex token pricing is not cheap

Through QCode.cc, you can:

- **Low-latency access via global multi-node endpoints** (`api.qcode.cc` geo routing / `us`/`eu`/`asia` fallbacks; CN users prefer `asia.qcode.cc` Hong Kong), no VPN or self-built proxy required
- **Cost reduction up to 80%**, significant savings compared to official pricing
- **Claude Code and Codex share plan quota**, one plan works for both tools
- **Multiple nodes available** (global Route 53 + HK / US / EU backups), ensuring connection stability

---

## 2. Installing Codex CLI

### System Requirements

Before installing, please confirm your environment meets the following conditions:

- **Operating System**: macOS 12+, Ubuntu 20.04+, Windows 10+ (WSL2 recommended)
- **Node.js**: v22 LTS or higher (required for npm installation)
- **Git**: 2.x or higher (Codex needs Git to recognize the code repository)
- **Disk Space**: Approximately 200MB (including npm dependencies)

### Method 1: npm Installation (Recommended)

This is the most common installation method, applicable to all operating systems:

```bash
npm install -g @openai/codex
```

> **Tip**: If you encounter permission issues, macOS/Linux users can add `sudo`, or use [nvm](https://github.com/nvm-sh/nvm) to manage Node.js to avoid permission issues.

> **Chinese users**: If npm download is slow, you can use the Taobao mirror:
> ```bash
> npm install -g @openai/codex --registry=https://registry.npmmirror.com
> ```

### Method 2: Homebrew Installation (macOS)

macOS users can also install via Homebrew:

```bash
brew install --cask codex
```

Homebrew's advantage is automatic dependency management and updates.

### Method 3: Direct Binary Download (Advanced)

Download pre-compiled binaries for your platform from the [GitHub Releases](https://github.com/openai/codex/releases) page and place them in the `PATH` directory. This method doesn't depend on Node.js.

```bash
# Example: Download and install Linux x64 version
wget https://github.com/openai/codex/releases/latest/download/codex-linux-x64
chmod +x codex-linux-x64
sudo mv codex-linux-x64 /usr/local/bin/codex
```

### Verify Installation

```bash
codex --version
```

If you see a version number, the installation succeeded. Do not treat a number in this page as “the current latest” — use [GitHub Releases](https://github.com/openai/codex/releases) and [npm `@openai/codex`](https://www.npmjs.com/package/@openai/codex), and check the machine with `codex --version`.

### Configure Shell Auto-Completion (Optional)

Codex supports shell auto-completion; press `Tab` when entering commands for suggestions:

```bash
# Zsh users
echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash users
echo 'eval "$(codex completion bash)"' >> ~/.bashrc
source ~/.bashrc
```

> If Zsh prompts `command not found: compdef`, add `autoload -Uz compinit && compinit` before `eval`.

---

## 3. QCode.cc Configuration

Codex CLI requires configuring two files to connect to QCode.cc service:

- `~/.codex/config.toml` — Server endpoint and model configuration
- `~/.codex/auth.json` — API key authentication

### Step 1: Create Configuration Directory

<div data-os="windows" markdown="1">

**Windows (PowerShell):**

```powershell
mkdir $HOME\.codex
```

</div>

<div data-os="macos" markdown="1">

**macOS:**

```bash
mkdir -p ~/.codex
```

</div>

<div data-os="linux" markdown="1">

**Linux:**

```bash
mkdir -p ~/.codex
```

</div>

### Step 2: Create config.toml

Write the following content to `~/.codex/config.toml`:

```toml
model_provider = "crs"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
```

**config.toml Field Details:**

| Field | Description |
|------|------|
| `model_provider` | Model provider name, set to custom `crs` |
| `model` | Default model. For programming, recommend `gpt-5.6-terra` |
| `model_reasoning_effort` | Reasoning effort: `low`, `medium`, `high`. Higher is more accurate but slower |
| `disable_response_storage` | Disable OpenAI storing conversation content (privacy protection) |
| `preferred_auth_method` | Authentication method, set to `apikey` to use API key |
| `base_url` | QCode.cc endpoint address (example uses `api.qcode.cc` global entry; see [Endpoints & API Paths](../getting-started/endpoints-and-api-paths) for alternatives) |
| `wire_api` | API protocol type, Codex uses `responses` |
| `requires_openai_auth` | Requires carrying OpenAI format authentication header |
| `env_key` | Environment variable name, Codex reads API key from this variable |

### Step 3: Create auth.json

Write the following content to `~/.codex/auth.json`:

```json
{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}
```

> Replace `cr_xxxxxxxxxx` with your [QCode.cc API key](https://qcode.cc/dashboard). The key starts with `cr_`.

**auth.json Notes:**

- This file provides API key to Codex, equivalent to setting `OPENAI_API_KEY` environment variable
- File permissions recommended as `600` (readable/writable only by owner): `chmod 600 ~/.codex/auth.json`
- If both `auth.json` and environment variable exist, `auth.json` takes priority

### Step 4: Set Environment Variables (Optional Alternative)

If you prefer providing the key via environment variable (instead of `auth.json`), you can set `CRS_OAI_KEY`:

<div data-os="windows" markdown="1">

**Windows (PowerShell):**

```powershell
# Temporary setting (current session)
$env:CRS_OAI_KEY = "cr_xxxxxxxxxx"

# Permanent setting (write to user environment variable)
[System.Environment]::SetEnvironmentVariable("CRS_OAI_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
```

</div>

<div data-os="macos" markdown="1">

**macOS:**

```bash
# Temporary setting
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# Permanent setting
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

<div data-os="linux" markdown="1">

**Linux:**

```bash
# Temporary setting
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# Permanent setting (Bash)
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# Permanent setting (Zsh)
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

When using environment variables, set `OPENAI_API_KEY` in `auth.json` to `null`:

```json
{
  "OPENAI_API_KEY": null
}
```

### Available Models

The following Codex/GPT models are available through QCode.cc:

| Model | Description | Recommended Scenario |
|------|------|----------|
| **`gpt-5.5`** | Latest flagship, 1M context | Top capability (recommended ★) |
| **`gpt-5.4`** 🔥 | Latest generation GPT, 1M context | Daily complex tasks (recommended) |
| `gpt-5.6-mini` | Lightweight, 272K context, fast | Lightweight / cost-effective |
| `gpt-5.6-terra` | GPT-5.6 flagship, code-optimized | Programming / Codex CLI (recommended) |

> All models **share** QCode.cc plan quota with Claude Code. Switching models doesn't require additional payment.

---

## 4. Basic Usage Tutorial

### 4.1 Launch Codex

Open terminal, go to your project directory, then run:

```bash
cd /path/to/your/project
codex
```

Codex will launch a terminal interactive interface (TUI), where you can enter natural language instructions. The interface consists of:

- **Top status bar**: Shows current model, approval mode, sandbox status
- **Main area**: AI's replies and operation logs
- **Bottom input box**: Where you enter instructions

You can also give tasks directly on the command line (non-interactive mode), suitable for script invocation:

```bash
# Interactive launch
codex

# Non-interactive mode: execute single task then exit
codex "Read this project's structure and give me an overview"

# Task with image
codex -i screenshot.png "Fix the UI issue shown in the screenshot"

# Specify model
codex -m gpt-5.4 "Refactor the error handling in the authentication module"
```

### 4.2 First Task: Let Codex Write a Function

Let's start with a simple example. Run Codex in your project directory and enter:

```text
Write a Python function that accepts a list of strings and returns the longest one. If there are multiple strings with the same length, return the first one. Save to utils.py.
```

Codex will execute the following steps:

1. **Plan**: Analyze your requirements and formulate implementation plan
2. **Generate code**: Create `utils.py` and write the function
3. **Request confirmation**: In default mode, Codex will show pending file modifications and wait for your confirmation

You'll see a prompt like this:

```text
Codex wants to create file: utils.py
─────────────────────────────────────
+ def find_longest(strings: list[str]) -> str:
+     """Return the longest string in the list, or the first one if there are multiple."""
+     if not strings:
+         raise ValueError("List cannot be empty")
+     return max(strings, key=len)

Accept? [y/n]
```

Enter `y` to confirm, and Codex will write the code to the file.

Next, you can continue to give more instructions, and Codex will maintain context within the same session:

```text
Write a unit test for this function using pytest
```

Codex will automatically read the `utils.py` you just created, then generate the corresponding test file.

### 4.3 Understanding Codex's Sandbox Execution Mode

This is one of Codex's most important security features. Codex executes commands in a **sandbox**, with three security levels:

| Sandbox Mode | File Read | File Write | Command Execute | Network Access |
|----------|---------|---------|---------|---------|
| `read-only` | Allowed | Requires confirmation | Requires confirmation | Requires confirmation |
| `workspace-write` (default) | Allowed | Allowed within workspace | Allowed within workspace | Denied by default |
| `danger-full-access` | Allowed | All allowed | All allowed | Allowed |

The default `workspace-write` mode is the best choice for daily development: Codex can freely read/write files and run commands within the project directory, but cannot access files or network outside the project.

**If your task requires network access** (such as `npm install`), you can temporarily enable network access:

```bash
codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies and run tests"
```

### 4.4 Review and Accept Codex's Changes

Codex's file modifications follow an **Approval Policy**. By default:

- **File editing**: Shows diff and waits for your confirmation
- **Shell commands**: Shows command content and waits for your confirmation

When Codex proposes modifications, you can:

- **Accept (y)**: Apply the modification
- **Reject (n)**: Skip this modification
- **View details**: Carefully review the diff before deciding

> **Tip**: Use the `/diff` slash command to view all applied modifications in the current session at any time.

### 4.5 Common Interaction Tips

**File reference**: Enter `@` followed by filename, Codex will automatically read that file's content:

```text
Review @src/app.py and optimize error handling
```

**Execute Shell commands**: Start with `!` to run commands directly, output will be passed to Codex:

```text
!cat error.log
Analyze the error log above and find the root cause
```

**Append instructions**: When Codex is running, press `Enter` to insert new instructions, press `Tab` to queue the next round of instructions.

**Backtrack editing**: When the input box is empty, press `Esc` twice to return to the previous message and modify/resend. Continue pressing `Esc` to backtrack to earlier messages, then press `Enter` to fork a new dialogue line from that point.

**Pipe input**: You can pipe output from other commands to Codex for analysis:

```bash
# Analyze recent git changes
git diff HEAD~3 | codex "Review these changes and identify potential issues"

# Analyze error logs
cat /var/log/app/error.log | codex "Analyze the root causes of these errors"

# Review PR
gh pr diff 42 | codex "Review this PR's code quality and security"
```

**Keyboard shortcuts:**

| Shortcut | Function |
|--------|------|
| `Tab` | Auto-complete file path (use with `@`) |
| `Enter` | Insert new instruction while Codex is running |
| `Tab` | Queue next round of instructions while Codex is running |
| `Esc` x 2 | Backtrack to previous message for editing |
| `Ctrl+C` | Cancel current operation |

**Slash commands:**

| Command | Description |
|------|------|
| `/help` | Show help |
| `/mode` | Switch approval mode |
| `/diff` | View all changes |
| `/mcp` | View connected MCP servers |
| `/status` | Show current session status |
| `/compact` | Compact conversation history to save tokens |
| `/permissions` | View and modify permission settings |
| `/review` | Code review |

---

## 5. Advanced Configuration

### 5.1 Custom Instruction Files (AGENTS.md)

Codex supports `AGENTS.md` files to provide AI with project context and work specifications, functioning similarly to Claude Code's `CLAUDE.md`.

**Project-level instructions**: Create `AGENTS.md` in the project root directory:

```markdown
# AGENTS.md

## Project Description
This is a FastAPI backend project using PostgreSQL database.

## Code Standards
- All functions must have type annotations
- New API endpoints require corresponding tests
- Run `make lint` to check code style before committing

## Test Commands
- Unit tests: `pytest tests/unit/`
- Integration tests: `pytest tests/integration/`
- Code check: `make lint`
```

**Global instructions**: Create global default rules in `~/.codex/AGENTS.md`, all projects will inherit:

```markdown
# Global Instructions

- Always communicate in English
- Code comments use English
- Prefer functional programming style
- Generated code must include error handling
```

**Subdirectory override**: Creating `AGENTS.override.md` in a specific directory can override parent rules:

```markdown
# services/payments/AGENTS.override.md

- All changes in this directory must be written to audit log
- Amount calculations use Decimal type, no floating point numbers
```

Codex searches for instruction files in the following order: `AGENTS.override.md` > `AGENTS.md` > configured fallback file. The combined total size limit defaults to 32KB, adjustable via `project_doc_max_bytes`.

### 5.2 Adjusting Approval Mode

Codex has three approval modes suitable for different usage scenarios:

#### Suggest Mode (Most Secure)

**All operations require manual confirmation**, including file editing and command execution. Suitable for learning phase or reviewing sensitive code.

```bash
codex --approval-mode suggest
```

#### Auto-Edit Mode (Recommended for Daily Use)

**File editing executes automatically, command execution still requires confirmation**. Good balance between efficiency and security.

```bash
codex --approval-mode auto-edit
```

#### Full-Auto Mode (Fully Autonomous)

**All operations execute automatically**, no confirmation required. Only recommended in isolated environments (such as Docker containers, CI/CD).

> 🔴 **`--full-auto` has been removed.** Use `--sandbox workspace-write` instead:

```bash
codex --sandbox workspace-write
```

> **Security tip**: `--sandbox workspace-write` keeps sandbox protection (restricted to the workspace). If you need completely unrestricted access, use `--dangerously-bypass-approvals-and-sandbox`, but it is **strongly not recommended** for non-isolated environments.

**Automatically reviewed approvals** (`--approve-for-me`, added in 0.147.0 / 2026-08-07): Codex reviews and approves low-risk actions itself before running them — a middle ground between prompting on every step and removing approvals entirely.

```bash
codex --approve-for-me
```

> ⚠️ Codex flags change quickly (`--full-auto` is a removed one). **Trust the output of `codex --help`**, not a flag list copied from any document, including this page.

**Set default mode in config.toml:**

```toml
# Recommended for personal development
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

**Switch mode during session**: Use `/mode` command to switch without restarting:

```text
/mode suggest      # Switch to suggest mode
/mode auto-edit    # Switch to auto-edit mode
/mode full-auto    # Switch to full-auto mode
```

#### Recommended Configuration by Scenario

| Scenario | Approval Mode | Sandbox Mode |
|------|---------|---------|
| Personal daily development | `auto-edit` | `workspace-write` |
| Team shared environment | `suggest` | `workspace-write` |
| CI/CD pipeline | `full-auto` | `workspace-write` |
| Learning and experimentation | `suggest` | `workspace-write` |
| One-time script tasks | `full-auto` | `danger-full-access` |

### 5.3 Configure MCP Servers

Codex supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), which can connect external tools to extend capabilities.

**Add MCP server via command line:**

```bash
codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json
```

**Configure via config.toml:**

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

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

After configuration, restart Codex and use `/mcp` command to view connected servers. MCP tools will automatically appear in Codex's available tools list alongside built-in tools.

**Make Codex itself an MCP server**: Codex can also run in reverse as an MCP server, called by other AI Agents. This is very useful when building multi-agent systems.

### 5.4 Configure Profile (Multi-Environment Management)

If different projects need different settings (work versus personal, say), use profiles. **Since Codex 0.134.0 the old `[profiles.<name>]` tables inside `config.toml` are no longer valid** — a profile is now its own file: `~/.codex/<name>.config.toml`. The three blocks below are the complete new form:

```toml
# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "crs"
model = "gpt-5.6-terra"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
```

```toml
# ~/.codex/work.config.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
```

```toml
# ~/.codex/personal.config.toml
model = "gpt-5.6-mini"
model_reasoning_effort = "medium"
```

Start with a profile:

```bash
codex --profile work "Refactor authentication module"
codex --profile personal "Write a small script"
```

✅ The three behaviours below are **tested on our own machine** (codex-cli 0.155.0, linux-x86_64, isolated HOME, no model request sent) and they are the pitfalls people hit:

- Keeping the legacy table and passing `--profile` is a **hard error**, not a silent ignore:

  ```text
  Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.
  ```

- The top-level `profile = "work"` selector is retired as well:

  ```text
  Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead
  ```
- **Without `--profile`, leftover `[profiles.*]` tables are simply not resolved** — `codex doctor` still reports `config.toml parse ok` and uses the top-level values. "No error" does not mean "it took effect", so delete the legacy tables when migrating.

Also, `--profile` only applies to runtime subcommands (`codex`, `exec`, `review`, `resume`, `queue`, `archive`, `delete`, `unarchive`, `fork`, `mcp`, `sandbox`, `debug prompt-input`); on `doctor` it fails with `--profile only applies to runtime commands ...`. The profile file is a layer above your user config and below project and command-line configuration — see 5.6.

### 5.5 Non-Interactive Mode (Scripts and Automation)

Codex can not only be used interactively but also run as a non-interactive tool in scripts and CI/CD pipelines. Simply pass the prompt parameter:

```bash
# Basic usage: execute task then exit
codex "Add installation instructions to README.md"

# Full-Auto + non-interactive: fully autonomous execution
codex --sandbox workspace-write "Run test suite, fix all failing tests"

# Output transcript to file (for auditing)
codex --sandbox workspace-write --transcript output.jsonl "Refactor error handling module"
```

**Using Codex in CI/CD:**

```yaml
# GitHub Actions example
- name: Auto-fix lint errors
  run: |
    npx @openai/codex --sandbox workspace-write "Run eslint --fix to fix all lint errors, then commit the fixes"
  env:
    CRS_OAI_KEY: ${{ secrets.QCODE_API_KEY }}
```

**Codex SDK**: If you need to invoke Codex in your own programs, you can use the official SDK for programmatic invocation, embedding Codex into your own development tools or workflows.

### 5.6 Configuration Priority

When multiple configuration sources conflict, Codex resolves them in the following priority order (highest to lowest):

1. **Command line arguments** (`--model`, `-c`, etc.)
2. **Project configuration** (`.codex/config.toml`, from project root to current directory, closest takes precedence; it loads only once the folder is trusted, and keys such as `model_provider`, `model_providers`, `profile` and `profiles` are ignored in the project layer)
3. **Profile file** (`~/.codex/<name>.config.toml`, selected by `--profile <name>`)
4. **User configuration** (`~/.codex/config.toml`)
5. **System configuration** (`/etc/codex/config.toml`, Unix systems)
6. **Built-in defaults**

Understanding this priority helps you precisely control behavior at different levels. For example, set general defaults in `~/.codex/config.toml`, override specific settings in the project's `.codex/config.toml`, then use command line arguments for one-time adjustments.

---

## 6. Claude Code vs Codex Comparison

In one line: **Claude Code is interactive pair programming; Codex is autonomous task execution.** Claude Code suits exploratory debugging, complex refactors and understanding an architecture; Codex suits well-specified feature work, bulk migrations and CI/CD automation. Their instruction files are `CLAUDE.md` and `AGENTS.md`, both fully support MCP, and both **share the same QCode.cc plan quota** — switching costs nothing.

The full side-by-side across 13 dimensions (execution model, context window, sandboxing, multi-agent, open source and more) → [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code).

---

## 7. Practical Examples

The following demonstrates Codex usage through several real-world scenarios. Each example includes specific commands and expected effects.

### Example 1: Understanding a New Project

When you take over an unfamiliar codebase:

```bash
cd /path/to/new/project
codex
```

In the interactive interface:

```text
What does this project do? Please analyze the directory structure, main modules, tech stack,
and give a concise architecture diagram (using ASCII art).
```

Codex will scan project files, analyze dependency files like `package.json`, `requirements.txt`, `go.mod`, read key entry files, then provide a comprehensive project overview.

### Example 2: Code Review

```bash
codex "Review all changes from the most recent git commit in the src/ directory. Focus on:
1. Potential bugs (null pointers, boundary conditions)
2. Security risks (SQL injection, XSS, hardcoded keys)
3. Performance issues (N+1 queries, unnecessary loops)
Provide specific code locations and fix suggestions."
```

### Example 3: Batch Refactoring

```bash
codex --sandbox workspace-write "Replace all Python file print() calls with the logging module.
Specific requirements:
1. Import logging at the top of each file
2. Create logger = logging.getLogger(__name__)
3. Replace print() with logger.info()
4. Keep original formatted strings
5. After replacement, run pytest to ensure nothing is broken"
```

Codex will process files one by one, maintaining code consistency, and finally run tests for verification.

### Example 4: Write Complete Test Suite

```bash
codex "Write complete unit tests for src/services/user_service.py. Requirements:
1. Use pytest + pytest-mock
2. Cover all public methods
3. Include both happy path and exception path tests
4. Mock external dependencies (database, HTTP requests)
5. Save test file to tests/unit/test_user_service.py
6. Run tests to confirm all pass"
```

### Example 5: Autonomous Test Fixing

Classic use case for Full-Auto mode — let Codex autonomously fix failing tests:

```bash
codex --sandbox workspace-write "Run all tests. If any fail:
1. Analyze the failure reasons
2. Fix the code (not the tests)
3. Re-run tests
4. Repeat above steps until all tests pass
Finally, provide a fix summary."
```

### Example 6: Implement UI from Design Mockup

```bash
codex -i design.png "Implement this page using React + Tailwind CSS based on this design mockup.
Requirements:
1. Responsive layout (mobile support)
2. Pixel-perfect recreation of the design mockup
3. Reasonable component splitting
4. Add basic interaction states (hover, focus)"
```

### Example 7: Database Migration

```bash
codex "I need to add an avatar_url field (varchar 500, nullable) to the users table.
Please:
1. Create Alembic migration script
2. Update SQLAlchemy model
3. Update related Pydantic schema
4. Update CRUD operation functions
5. Add corresponding API endpoints (GET/PUT)
6. Run migration and confirm success"
```

### Example 8: Auto-Generate Changelog in CI/CD

```bash
codex --sandbox workspace-write "Analyze all git commits from the last release tag to now,
categorize them according to conventional commits specification,
and generate CHANGELOG.md update content.
Include: new features, bug fixes, breaking changes, other improvements."
```

---

## 8. FAQ

### Configuration File Not Found

**Problem**: Codex prompts that configuration file not found or cannot load configuration

**Solution**:

1. Check if configuration directory exists: `ls ~/.codex/`
2. Confirm both files `config.toml` and `auth.json` exist
3. Check if `config.toml` TOML syntax is correct (common errors: missing quotes, typos)
4. Use `codex --config-dump` to view actually loaded configuration

### API Key Authentication Failed

**Problem**: Prompt `401 Unauthorized` or API Key invalid

**Solution**:

1. Confirm API key format is correct (starts with `cr_`)
2. Check if key in `auth.json` is complete (no extra spaces or line breaks)
3. If using environment variable, confirm variable name is `CRS_OAI_KEY` (matches `env_key` in `config.toml`)
4. Log in to [QCode.cc console](https://qcode.cc/dashboard) to confirm key status and remaining quota

### Network Connection Issues

**Problem**: Cannot connect to QCode.cc service, timeout or connection refused

**Solution**:

1. Check if network is normal: `curl -I https://api.qcode.cc`
2. Verify `base_url` configuration is correct (must be `https://api.qcode.cc/openai`)
3. Try backup nodes:
   - Asia backup: `https://asia.qcode.cc/openai`
4. If using company proxy/VPN, confirm proxy settings don't block HTTPS requests

### Model Selection Advice

**Problem**: Unsure which model to choose

**Advice**:

| Your Need | Recommended Model | Reason |
|---------|---------|------|
| Programming tasks | `gpt-5.6-terra` | Code-optimized |
| Complex tasks | `gpt-5.4` | Strong general capability, 1M context |
| Lightweight tasks | `gpt-5.6-mini` | Less quota consumption |
| Top capability | `gpt-5.5` | Latest flagship |

After setting default model in `config.toml`, you can also switch temporarily:

```bash
codex -m gpt-5.4 "Analyze this complex concurrency bug"
```

### Sandbox Restrictions Causing Command Failures

**Problem**: Commands Codex attempts to execute are rejected by sandbox

**Solution**:

1. If it's a network operation (like `npm install`), temporarily enable network:
   ```bash
   codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies"
   ```
2. If you need to write files outside the project directory, temporarily expand writable scope:
   ```bash
   codex --sandbox danger-full-access "Save output to /tmp/result.txt"
   ```
3. Use `/permissions` during session to view and adjust current permissions

### Cost Explanation

**Problem**: How are Codex and Claude Code costs calculated?

**Explanation**:

- Codex and Claude Code **share QCode.cc plan quota**
- The same plan can be used by both tools simultaneously
- Costs are calculated based on actual token consumption, not by tool
- In Full-Auto mode, Codex iterates autonomously for multiple rounds, token consumption for single tasks may be higher, but saves developer's interaction time
- It's recommended to use `/cost` command to view token usage for current session, or check overall quota usage in [QCode.cc console](https://qcode.cc/dashboard)

### Can AGENTS.md and CLAUDE.md Coexist?

**Yes**. If your project is used by both Codex and Claude Code:

- Codex only reads `AGENTS.md`, ignores `CLAUDE.md`
- Claude Code only reads `CLAUDE.md`, ignores `AGENTS.md`
- They don't interfere with each other, you can maintain separate instruction files for different tools
- It's recommended to keep core specifications consistent in both files (such as test commands, code style, etc.)

---

## 10. Related Documentation

- [Environment Variables Configuration](/docs/getting-started/environment) — Environment variable settings for Claude Code
- [Quick Start](/docs/getting-started/quick-start) — Claude Code quick start guide
- [Aider Integration](/docs/ide/aider) — Configuration for another open-source AI programming assistant
- [CLI Tips](/docs/usage/cli-tips) — Advanced command-line usage for Claude Code
- [Workflow Tips](/docs/usage/workflow-tips) — Workflow suggestions for improving AI programming efficiency