Codex Complete Tutorial

From Installation to Mastery — Complete Usage Guide for OpenAI Codex CLI with QCode.cc

Updated 2026-09-18
On This Page

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

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

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

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

npm install -g @openai/codex

Tip: If you encounter permission issues, macOS/Linux users can add sudo, or use 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:

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 page and place them in the PATH directory. This method doesn't depend on Node.js.

# 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

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 and npm @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:

# 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

Windows (PowerShell):

mkdir $HOME\.codex

macOS:

mkdir -p ~/.codex

Linux:

mkdir -p ~/.codex

Step 2: Create config.toml

Write the following content to ~/.codex/config.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 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:

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

Replace cr_xxxxxxxxxx with your QCode.cc API key. 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:

Windows (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)

macOS:

# Temporary setting
export CRS_OAI_KEY="cr_xxxxxxxxxx"

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

Linux:

# 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

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

{
  "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:

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:

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

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:

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:

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:

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:

Review @src/app.py and optimize error handling

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

!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:

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

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

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

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

codex --approval-mode suggest

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

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:

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.

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:

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

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

/mode suggest      # Switch to suggest mode
/mode auto-edit    # Switch to auto-edit mode
/mode full-auto    # Switch to full-auto mode
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), which can connect external tools to extend capabilities.

Add MCP server via command line:

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

Configure via config.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:

# ~/.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"
# ~/.codex/work.config.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
# ~/.codex/personal.config.toml
model = "gpt-5.6-mini"
model_reasoning_effort = "medium"

Start with a profile:

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 resolvedcodex 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:

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

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


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:

cd /path/to/new/project
codex

In the interactive interface:

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

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

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

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:

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

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

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

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 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:

  4. Asia backup: https://asia.qcode.cc/openai

  5. 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:

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

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

Related Documents

Roo Code Setup
Use QCode.cc from the Roo Code VS Code extension: pick the Anthropic provider, tick the custom base URL, and Claude works
Connect SillyTavern to QCode
Chat with QCode.cc's Claude / GPT models in SillyTavern; an honest note on whether gpt-image-2 image generation can be connected, plus alternatives
Aider Integration
Configure Aider with QCode.cc: Claude over the Anthropic endpoint (anthropic/ prefix), GPT and Chinese models over the OpenAI-compatible endpoint
🚀
Get Started with QCode — Claude Code & Codex
One plan for both Claude Code and Codex, Asia-Pacific low latency
View Pricing Plans → Create Account
Team of 3+?
Enterprise: dedicated domain + sub-key management + ban protection, from ¥250/person/mo
Learn Enterprise →