# Codex Quick Start

> ⚡ **Recommended: one-click setup** — `curl -fsSL https://qcode.cc/install/codex.sh | bash` (Windows: `irm https://qcode.cc/install/codex.ps1 | iex`) installs the CLI, writes the `~/.codex` config and verifies connectivity. See [One-Click Setup Script](/docs/getting-started/one-click-install). Keep reading for manual setup.

If you're already using Claude Code, this guide will have you up and running with Codex CLI in **5 minutes**. Both tools share QCode.cc plan quota and use the same API key, so once configured you can switch freely between them.

If you don't have a QCode.cc account yet, [sign up and choose a plan](https://qcode.cc/pricing) first.

---

## Prerequisites

Before you begin, make sure your environment meets these requirements:

| Requirement | Version | How to check |
|-------------|---------|-------------|
| Node.js | v22 or later | `node --version` |
| npm | v10 or later | `npm --version` |
| Git | Any version | `git --version` |
| OS | macOS / Linux / Windows (WSL) | - |
| QCode.cc key | API key starting with `cr_` | [Dashboard](https://qcode.cc/dashboard) |

> **Note**: Codex's kernel-level sandbox works best on Linux. macOS and Windows WSL are fully supported as well, though some sandbox features may be limited.

---

## Step 1: Install Codex CLI

Choose one of the following installation methods:

### Option A: npm global install (recommended)

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

# Users in China can speed this up with the Taobao mirror
npm install -g @openai/codex --registry=https://registry.npmmirror.com
```

### Option B: Homebrew (macOS)

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

### Option C: Build from source

```bash
git clone https://github.com/openai/codex.git
cd codex
cargo build --release
cp target/release/codex ~/.local/bin/
```

Verify the installation:

```bash
codex --version
# should print a version (trust `codex --version` on this machine, not a stale number from the web)
```

---

## Step 2: Configure QCode.cc

### 2.1 Create the config directory

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

### 2.2 Write config.toml

Create `~/.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"
```

Configuration reference:

| Field | Description |
|-------|-------------|
| `model_provider` | Use custom provider `crs` |
| `model` | Default model, `gpt-5.6-terra` recommended; see “Available models” below |
| `model_reasoning_effort` | Reasoning depth. Options: `low` / `medium` / `high` |
| `base_url` | QCode.cc Asia-Pacific endpoint |
| `wire_api` | API protocol, set to `responses` |
| `env_key` | Environment variable name for the API key |

### 2.3 Create auth.json

Create `~/.codex/auth.json`:

```json
{
  "OPENAI_API_KEY": "cr_your_key_here"
}
```

> Replace `cr_your_key_here` with the API key from your [QCode.cc Dashboard](https://qcode.cc/dashboard).

### 2.4 Set environment variables

As an alternative to `auth.json` (use either method):

```bash
# Temporary (current terminal session only)
export CRS_OAI_KEY="cr_your_key_here"

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

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

> **Tip**: This is the same key you use for Claude Code. If you're already using Claude Code, you'll find the key in the same place on the [Dashboard](https://qcode.cc/dashboard).

---

## Step 3: Verify the Setup

Run a simple task to test the connection:

```bash
codex "print hello world"
```

If Codex starts up normally and returns a response, configuration is successful.

### Checklist

- Codex starts without errors
- API requests are routed through QCode.cc (no network timeouts)
- Model responses work correctly (understands your instructions)

If you run into issues, jump to the [FAQ](#faq) section.

---

## Step 4: Your First Real Task

Let's try a practical scenario to experience what Codex can do. Navigate to a project directory:

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

### Example 1: Analyze project structure

```bash
codex "Analyze this project's directory structure and tech stack, and give a brief overview"
```

### Example 2: Generate code

```bash
codex "Create a utils/date-formatter.ts file with these features:
  1. Format a date as YYYY-MM-DD
  2. Calculate the number of days between two dates
  3. Determine whether a date is a business day
  4. Add complete JSDoc comments and unit tests for each function"
```

### Example 3: Batch modifications

```bash
codex "Convert all .js files under src/ to .ts files and add type annotations"
```

Codex will autonomously complete the task in a sandboxed environment, then present a change summary for your review.

---

## Three Permission Modes

Codex provides three permission modes to control the level of automation:

### suggest (Suggest Mode)

```bash
codex --suggest "Refactor the auth module"
```

- Analyzes and suggests only -- **does not modify any files**
- You need to manually apply the suggested changes
- Best for: learning code, evaluating approaches

### auto-edit (Auto-Edit Mode)

```bash
codex --auto-edit "Add error handling"
```

- **Automatically edits files**, but asks for confirmation before running commands
- Best for: daily development (recommended default mode)

### Fully automatic (`--sandbox workspace-write`)

```bash
codex --sandbox workspace-write "Run tests and fix all failures"
```

- Automatically edits files + runs commands, **no confirmation required**
- All operations run inside the sandbox and won't affect your system
- Best for: CI/CD integration, batch tasks

> You can also set the default mode in `config.toml`: `approval_mode = "auto-edit"`

---

## Command Reference

| Command | Description |
|---------|-------------|
| `codex "your instruction"` | Start Codex with a task |
| `codex --model gpt-5.4` | Specify a model |
| `codex --sandbox workspace-write "instruction"` | Full-auto mode |
| `codex --suggest "instruction"` | Suggest only, no execution |
| `codex --auto-edit "instruction"` | Auto-edit, commands need confirmation |
| `codex --version` | Show version |
| `codex --help` | Show help |

### Available Models

The following models are available through QCode.cc:

| Model | Description | Recommended For |
|-------|-------------|-----------------|
| `gpt-5.6-terra` | GPT-5.6 flagship | Coding / complex tasks (recommended ★) |
| `gpt-5.6-sol` / `gpt-5.6-luna` | GPT-5.6 flagship family | High-end capability |
| `gpt-5.5` | Previous flagship, 1M context | Daily complex tasks |
| `gpt-5.4` | Stable, 1M context | Daily tasks / cost-effective |
| `gpt-5.6-mini` / `gpt-5.6-nano` | Light & fast | Lightweight tasks |

---

## Project Configuration: AGENTS.md

Create an `AGENTS.md` file in your project root to define how Codex should behave in that project -- similar to Claude Code's `CLAUDE.md`:

```markdown
# AGENTS.md

- Use TypeScript strict mode
- Code style follows ESLint + Prettier
- Test framework: Vitest
- Run `npm run lint && npm test` before committing
- Component files use PascalCase naming
```

> For detailed configuration, see the [AGENTS.md Configuration Guide](/docs/usage/agents-md).

---

## Using Codex with Claude Code

Since both tools share QCode.cc quota, the best practice is to use them together:

```bash
# Terminal 1: Use Claude Code to analyze the problem
$ claude
> Where's the performance bottleneck? Help me analyze the approach.

# Terminal 2: Use Codex for batch execution
$ codex "Optimize all database queries under src/api/ according to this plan:
  1. Add query caching
  2. Fix N+1 queries
  3. Add index suggestion comments"
```

> For more combined patterns, see [Codex vs Claude Code: An In-Depth Comparison](/docs/getting-started/codex-vs-claude-code).

---

## Next Steps

Configuration is complete -- you're ready to start using Codex. Recommended reading:

- [AGENTS.md Configuration Guide](/docs/usage/agents-md) -- Customize Codex project behavior
- [Codex vs Claude Code: An In-Depth Comparison](/docs/getting-started/codex-vs-claude-code) -- Understand the differences and how to combine both
- [Codex Integration Configuration](/docs/ide/codex) -- Complete configuration reference (including detailed Windows and multi-OS steps)
- [CLI Tips & Tricks](/docs/usage/cli-tips) -- Productivity tips for AI-powered coding

---

## FAQ

### Q: Installation fails with `npm ERR! EACCES`

**Cause**: Insufficient permissions for the npm global install directory.

**Solution**:

```bash
# Option A: Use sudo (not recommended long-term)
sudo npm install -g @openai/codex

# Option B: Configure npm to use a user directory (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex
```

### Q: Getting `API key not found` or authentication failure

**Troubleshooting steps**:

1. Confirm the key in `~/.codex/auth.json` starts with `cr_`
2. Confirm the `CRS_OAI_KEY` environment variable is set: `echo $CRS_OAI_KEY`
3. Confirm the key hasn't expired: check on the [QCode.cc Dashboard](https://qcode.cc/dashboard)
4. Verify `env_key` is spelled correctly in `config.toml`

### Q: Connection timeout or network error

**Troubleshooting steps**:

1. Confirm `base_url` is set to `https://api.qcode.cc/openai`
2. Test network connectivity: `curl -I https://api.qcode.cc`
3. If the primary endpoint is unavailable, try a fallback:
   - Backup endpoint: `https://asia.qcode.cc/openai`

### Q: Is the Codex key the same as the Claude Code key?

**Yes**. Both use the same QCode.cc API key with shared quota. You don't need a separate key.

### Q: Does it work on Windows?

**Yes**, but we recommend using WSL (Windows Subsystem for Linux). Native Windows support is also improving. See [Codex Integration Configuration](/docs/ide/codex) for detailed Windows setup steps.