Skip to main content
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

2. Codex CLI Installation

2.1 Linux(Ubuntu) Installation

Step 1: Update System Packages
Step 2: Add NodeSource Repository (Node.js 22) Visit Node.js official website for the latest version information.
Step 3: Install Node.js and npm
Step 4: Verify Installation
Step 5: Install Codex CLI Install Codex CLI globally via npm:
Step 6: Verify Installation
🎉 Congratulations! Codex CLI installation is complete!

2.2 macOS Installation

macOS users are recommended to use Homebrew for installation: 1. Install Homebrew
2. Install Node.js
3. Install Codex CLI

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)
3. Permanent Configuration (Recommended) Edit shell configuration file:
Add the following content:
Make configuration effective:

Windows Environment Variables & Model Configuration

PowerShell Environment Variables

Run the following commands in PowerShell. To persist them, add the same lines to $PROFILE or set them through System Properties → Environment Variables.

Reload Your Profile

Configure Models in config.toml

On Windows, the Codex CLI config file lives at C:\Users\<USERNAME>\.codex\config.toml. Use it to persist your model choices and AGCloud endpoint:
Need different models per task? Set CODEX_DEFAULT_MODEL (primary) and CODEX_BACKUP_MODEL (fallback) as environment variables, then reference them inside config.toml using ${CODEX_DEFAULT_MODEL} syntax where supported.

Configure config.toml

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
VS Code Integration For third-party IDEs (such as VS Code), you need to install the corresponding Codex plugin. Installation Steps
  1. Search for “OpenAI Codex” in VS Code extension store
  2. Install the official extension
  3. Configure Codex CLI path in settings
  4. Configure API Key (using the environment variable above)

Other IDE Support

5. Getting Started with Codex CLI

Initialize Project

Common Command Examples 1. Basic Prompt
2. Specify Model
3. Specify Operation Mode
4. Interactive Mode

Usage Scenario Examples

Scenario 1: Code Generation
Scenario 2: Code Review
Scenario 3: Bug Fixing
Scenario 4: Test Generation
Scenario 5: Documentation Generation

6. Troubleshooting and Common Issues

Common Issue Solutions

1. Permission Issues
Encountering permission error “EACCES: permission denied”
Solution:
2. Node Version Issues
Node.js version lower than 22.
Solution:
3. Network Connection Issues
Cannot connect to API.
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
“Invalid API Key” error
Solution:
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:

Verify Configuration

Debug Mode

Enable verbose log output to help diagnose issues:

7. Advanced Usage Tips

1. Custom Prompt Templates Create commonly used prompt templates to improve efficiency:
2. Batch Processing
3. Git Integration
4. Configure Aliases Add aliases in ~/.bashrc or ~/.zshrc:

8. Best Practice Recommendations

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