Codex Quick Start

Get Codex CLI installed and configured in 5 minutes -- start AI-powered coding with QCode.cc

Codex Quick Start¶

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 first.

Prerequisites¶

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

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)¶

npm install -g @openai/codex

Option B: Homebrew (macOS)¶

brew install openai-codex

Option C: Build from source¶

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

Verify the installation:

codex --version
# Expected output: codex v0.114.0

Step 2: Configure QCode.cc¶

2.1 Create the config directory¶

mkdir -p ~/.codex

2.2 Write config.toml¶

Create ~/.codex/config.toml:

model_provider = "crs"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

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

Configuration reference:

2.3 Create auth.json¶

Create ~/.codex/auth.json:

{
  "OPENAI_API_KEY": "cr_your_key_here"
}

Replace cr_your_key_here with the API key from your QCode.cc Dashboard.

2.4 Set environment variables¶

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

# 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.

Step 3: Verify the Setup¶

Run a simple task to test the connection:

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 section.

Step 4: Your First Real Task¶

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

cd /path/to/your/project

Example 1: Analyze project structure¶

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

Example 2: Generate code¶

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¶

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)¶

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)¶

codex --auto-edit "Add error handling"

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

full-auto (Full-Auto Mode)¶

codex --full-auto "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¶

Available Models¶

The following models are available through QCode.cc:

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:

# 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.

Using Codex with Claude Code¶

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

# 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.

Next Steps¶

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

• AGENTS.md Configuration Guide -- Customize Codex project behavior
• Codex vs Claude Code: An In-Depth Comparison -- Understand the differences and how to combine both
• Codex Integration Configuration -- Complete configuration reference (including detailed Windows and multi-OS steps)
• CLI Tips & Tricks -- Productivity tips for AI-powered coding

FAQ¶

Q: Installation fails with npm ERR! EACCES¶

Cause: Insufficient permissions for the npm global install directory.

Solution:

# 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
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://asia.qcode.cc/openai
2. Test network connectivity: curl -I https://asia.qcode.cc

3. If the primary endpoint is unavailable, try a fallback:

4. Hong Kong: http://103.218.243.5/openai

5. Shenzhen: http://103.236.53.153/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 for detailed Windows setup steps.