Installation, configuration and usage guide - Support for direct API connection in China
OpenAI Codex CLI Complete Tutorial
Codex is an AI coding assistant developed by OpenAI. It helps developers write, debug, and improve code using natural language instructions.
📖 Contents Covered:This guide explains how to install and set up the OpenAI Codex CLI using the AGCloud Aggregation API, enabling direct usage in China without the need for a proxy. It supports Windows, Linux, and macOS, and can be integrated with third-party IDEs like VS Code.
1. Codex CLI Introduction and System Requirements
Codex AI is an AI-powered coding assistant developed by OpenAI. It can understand natural language instructions and help developers with software tasks such as writing code, fixing bugs, refactoring, and generating pull requests. Codex works across tools like terminals, IDEs, and web interfaces, and is designed to make software development faster and more efficient by acting as an intelligent partner that can read and modify your codebase in context.
System Requirements
| Item | Requirement |
|---|
| Officially Supported Systems | macOS and Linux (Recommended) |
| Windows Users | Strongly recommend using Windows Subsystem for Linux (WSL) |
| Node.js Version | Node.js 18+ (Required) |
| npm Version | npm 10 or higher |
2. Codex CLI Installation
2.1 Linux(Ubuntu) Installation
Step 1: Update System Packages
sudo apt update && sudo apt upgrade -y
Step 2: Add NodeSource Repository (Node.js 22)
Visit Node.js official website for the latest version information.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
Step 3: Install Node.js and npm
sudo apt install nodejs -y
Step 4: Verify Installation
node --version # Should display v22.x.x
npm --version # Should display 10.x.x or higher
Step 5: Install Codex CLI
Install Codex CLI globally via npm:
sudo npm install -g @openai/codex@latest
Step 6: Verify Installation
codex --version # Should display version number, e.g., 0.40.0
🎉 Congratulations! Codex CLI installation is complete!
2.2 macOS Installation
macOS users are recommended to use Homebrew for installation:
1. Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. Install Node.js
3. Install Codex CLI
npm install -g @openai/codex@latest
2.3 Windows (WSL) Installation
Windows users need to install WSL first, then follow the Ubuntu installation steps.
1. Install WSL
Open PowerShell as administrator and run:
For detailed instructions, refer to Microsoft WSL Installation Documentation
2. Continue After Restarting
After restarting, follow the Ubuntu installation steps above to complete Codex CLI installation.
3. Codex CLI Configuration Tutorial
1. Get You API Key
**Recommended: Use AGCloud Aggregation API (Direct Connection in China)**Visit https://developer.aiandgpu.com to get API Key
- ✅ Direct connection in China, no proxy needed
- ✅ Supports multiple OpenAI models
- ✅ Affordable pricing, pay-as-you-go
2. Temporary Configuration (Valid for Current Session)
export OPEN_API_KEY="<YOUR_API_KEY>"
3. Permanent Configuration (Recommended)
Edit shell configuration file:
# Check your shell
echo $SHELL
# /bin/zsh or /bin bash
# For bash users
nano ~/.bashrc
# For zsh users
nano ~/.zshrc
Add the following content:
export OPEN_API_KEY="<YOUR_API_KEY>"
Make configuration effective:
# bash users
source ~/.bashrc
# zsh users
source ~/.zshrc
Default configuration file path:~/.codex/config.toml
Official configuration documentation:Codex Configuration Documentation
Configuration Explanation:
model: Model name to use (e.g., gpt-4, gpt-3.5-turbo, etc.)
model_provider: Model provider configuration
base_url: API base address (using AGCloud Aggregation API)
env_key: Environment variable name
wire_api: API type (chat or completions)
Basic Configuration Options
model = "gpt-5.2"
model_provider = "agcloud"
temperature = 0.7
max_tokens = 2000
model_reasoning_effort = "medium"
[model_providers.agcloud]
name = "OpenAI Compatible"
base_url = "https://aiandgpu.com/v1"
env_key = "OPEN_API_KEY"
wire_api = "responses"
[ui]
theme = "dark" # or "light"
show_token_count = true
VS Code Integration
For third-party IDEs (such as VS Code), you need to install the corresponding Codex plugin.
Installation Steps
- Search for “OpenAI Codex” in VS Code extension store
- Install the official extension
- Configure Codex CLI path in settings
- Configure API Key (using the environment variable above)
Other IDE Support
| IDE | Support Status | Description |
|---|
| VS Code | Official Support | Full plugin support |
| JetBrains Series | Community Support | Integrated through terminal |
| Vim/Neovim | Community Support | Supported through plugins |
5. Getting Started with Codex CLI
Initialize Project
# Navigate to project directory
cd /path/to/your/project
# Start Codex
codex
Common Command Examples
1. Basic Prompt
codex "Fix this bug: add error handling at line 42 in main.py"
2. Specify Model
codex -m gpt-4 "Build a simple web server"
3. Specify Operation Mode
codex --mode full-auto "Deploy ML model to Vercel"
4. Interactive Mode
# Start interactive session
codex
# Use commands in interactive mode
> Help me refactor this function
> Add unit tests
> Optimize performance
| Command | Function Description |
|---|
/help | Display help information |
/exit or Ctrl+C | Exit Codex |
/clear | Clear conversation history |
/config | View current configuration |
/model <name> | Switch model |
/tokens | View token usage |
Usage Scenario Examples
Scenario 1: Code Generation
codex "Create a Python function to calculate the nth Fibonacci number"
Scenario 2: Code Review
codex "Review auth.js file and find potential security issues"
Scenario 3: Bug Fixing
codex "Fix memory leak issue in app.py"
Scenario 4: Test Generation
codex "Generate complete unit tests for user_service.py"
Scenario 5: Documentation Generation
codex "Generate API documentation for the entire project"
6. Troubleshooting and Common Issues
Common Issue Solutions
1. Permission Issues
Encountering permission error “EACCES: permission denied”
Solution:
# Method 1: Use sudo
sudo npm install -g @openai/codex
# Method 2: Modify npm global directory permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
2. Node Version Issues
Node.js version lower than 22.
Solution:
# Use nvm to manage Node.js versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22
3. Network Connection Issues
Solution:
- Confirm API Key is configured correctly
- Check if
base_url configuration is correct
- Use AGCloud to ensure direct connection in China
- Verify network connection:
curl https://aiandgpu.com/v1/models
4. Invalid API Key
Solution:
# Check environment variable
echo $OPEN_API_KEY
# Reset API Key
export OPEN_API_KEY="<YOUR_API_KEY>"
# Verify configuration
codex --help
5.Model configuration missing
Unexpected status 404 Not Found: Model configuration missing.
Solution: See: https://aiandgpu.com/v1/models listed models whether contain the model that you choosed. And then:
# Select specific model in terminal
codex --model gpt-5-codex
# Or switch other model in codex CLI
/model
Verify Configuration
# Check environment variable
echo $OPEN_API_KEY
# Check Codex configuration
codex --help
# Test API connection
codex "Hello, Codex!"
# View version information
codex --version
# View configuration file
cat ~/.codex/config.toml
Debug Mode
Enable verbose log output to help diagnose issues:
# Enable debug mode
export DEBUG=codex:*
codex "test command"
# View log file
tail -f ~/.codex/logs/codex.log
7. Advanced Usage Tips
1. Custom Prompt Templates
Create commonly used prompt templates to improve efficiency:
# ~/.codex/templates/review.txt
Please review the following code, focusing on:
1. Code readability and maintainability
2. Performance optimization opportunities
3. Potential security vulnerabilities
4. Whether it follows best practices
# Use template
codex --template review.txt file.py
2. Batch Processing
# Batch process multiple files
for file in src/*.py; do
codex "Add type annotations to $file"
done
3. Git Integration
# Review uncommitted changes
git diff | codex "Review these code changes"
# Generate commit message
git diff --cached | codex "Generate a clear commit message"
4. Configure Aliases
Add aliases in ~/.bashrc or ~/.zshrc:
alias cdx="codex"
alias cdx-review="codex --mode review"
alias cdx-test="codex --mode test"
alias cdx-doc="codex --mode documentation"
8. Best Practice Recommendations
| Recommendation | Description |
|---|
| Clear Prompts | Provide clear, specific instructions, explaining expected output format and requirements |
| Context Information | Provide sufficient context, such as project tech stack, coding standards, etc. |
| Iterative Optimization | Gradually improve code through multiple rounds of dialogue, rather than expecting perfection in one go |
| Code Review | Always review AI-generated code to ensure it meets project standards |
| Version Control | Use Git to track changes for easy rollback and comparison |
| Security Awareness | Don’t send sensitive information (keys, passwords, etc.) to AI |
| Cost Control | Monitor token usage to avoid unnecessary API calls |
9. Resource Links
9.1 Official Resources
9.2 Third-Party Resources
Summary
Through this guide, you have successfully:
- ✅ Understood basic concepts and features of OpenAI Codex CLI
- ✅ Installed Codex CLI on Linux/macOS/Windows systems
- ✅ Configured AGCloud Aggregation API (direct connection in China)
- ✅ Mastered basic usage methods and common commands
- ✅ Understood IDE integration methods
- ✅ Learned troubleshooting and problem solving
- ✅ Mastered advanced usage tips and best practices
🚀 You can now start enjoying the efficient coding experience brought by Codex CLI!
Need Help?
If you encounter problems during use:
- Check GitHub Issues
- Visit OpenAI Community
- Refer to Official Documentation
- © 2025 OpenAI Codex CLI Tutorial | Complete Installation Configuration Guide
- Thank you for using Codex CLI - Let AI be your programming assistant
- Recommended to use AGCloud for stable direct connection API service in China