Codex CLI Quick Start (2026): Setup in 5 Min

Install Codex CLI and connect it to QCode.cc in about 5 minutes: one-click script or manual config.toml + auth.json, then a first task. Same key as Claude Code.

Need an API key? Sign up →·Endpoints & base URLs →

⚡ 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. 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, choose a plan and get your key first (a key works the same whichever option you pick).

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

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

brew install --cask 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
# 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¶

mkdir -p ~/.codex

2.2 Write config.toml¶

Create ~/.codex/config.toml:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

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

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¶

To pass the key through an environment variable instead, replace requires_openai_auth = true in [model_providers.qcode] with env_key = "QCODE_API_KEY" and export that variable. Use one or the other: the official documentation states that Codex ignores env_key when requires_openai_auth = true. The full configuration for the environment-variable variant:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
env_key = "QCODE_API_KEY"

Then set the environment variable:

# Temporary (current terminal session only)
export QCODE_API_KEY="cr_your_key_here"

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

# Permanent (Zsh users)
echo 'export QCODE_API_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.

Permissions and the Sandbox¶

Codex uses two options to control what it can do (--sandbox) and when it asks you (--ask-for-approval). The details below come from the official OpenAI documentation (as of 2026-10-15).

Default: workspace writable, approvals on request¶

codex "Refactor the auth module"

• In a Git repository this is the preset you get with no options: Codex reads files, edits files and runs commands inside the workspace, and asks first before writing outside it or using the network
• Best for: daily development (recommended default)

Read-only: look but don't change¶

codex --sandbox read-only --ask-for-approval on-request "Analyze the auth module and suggest a refactor"

• Read-only sandbox -- does not modify any files
• Best for: learning code, evaluating approaches

Non-interactive and automation¶

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

• codex exec runs non-interactively and prints results to standard output (or JSONL with --json)
• The sandbox is limited to the workspace and won't affect the system outside it
• Best for: CI/CD integration, batch tasks

You can also set the defaults in config.toml: approval_policy = "on-request" and sandbox_mode = "workspace-write". The --suggest, --auto-edit and approval_mode forms from older tutorials are not in the current official option list; when in doubt, trust codex --help.

Command Reference¶

Available Models¶

The following models are available through QCode.cc:

QCode does not currently offer gpt-6-luna / gpt-5.6-luna. Please use another GPT model. QCode bills per token; per-model rates are on qcode.cc/models.

No gpt-6.1-sol in the /model menu? With the configuration above, the Codex /model menu shows the model list built into the client, so it depends on your Codex version: gpt-6.1-sol appears in the menu from Codex 0.160.0 onward. Upgrade to the latest release (npm install -g @openai/codex@latest, or brew upgrade --cask codex with Homebrew). It also works without upgrading: model = "gpt-6.1-sol" in config.toml (or codex --model gpt-6.1-sol) does not depend on the menu. Conversely, gpt-6-luna may appear in the menu, but QCode does not currently offer it and selecting it returns an error.

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. If you use the environment-variable variant, confirm the provider has env_key = "QCODE_API_KEY" (and no requires_openai_auth = true) and that it is exported: echo $QCODE_API_KEY
3. Confirm the key hasn't expired: check on the QCode.cc Dashboard
4. Check the TOML syntax and the provider name 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 current endpoint is unavailable, try another one:

4. Asia 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 for detailed Windows setup steps.

Enterprise →