OpenAI Codex CLI
OpenAI Codex CLI Installation Tutorial — Install a terminal AI coding assistant on Windows, macOS, Linux, connecting to New API. Supports sandbox policies and atomic patch editing.
Project Introduction
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
- Official Homepage: https://chatgpt.com/codex
- Project Homepage: https://github.com/openai/codex
Demo
Features
| Category | Feature
title: OpenAI Codex CLI
description: OpenAI Codex CLI Installation Tutorial — Install a terminal AI coding assistant on Windows, macOS, Linux, connecting to New API. Supports sandbox policies and atomic patch editing.
Project Introduction
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
- Official Homepage: https://chatgpt.com/codex
- Project Homepage: https://github.com/openai/codex
Demo
Features
| Category | Feature
| Terminal-based Coding Assistant | Codex CLI is a terminal-based interactive coding assistant for editing code, generating patches, and running commands in the command line. |
| Tool-Driven Architecture | Provides tools such as apply_patch, shell, update_plan, and multi_tool_use for controlled modification of repository files and operations. |
| Atomic Patch Editing | Uses a specialized patch format to atomically add/update/delete files via apply_patch, facilitating auditing and rollback. |
| Sandbox and Approval | Supports sandbox policies (e.g., workspace-write, read-only) and approval modes (on-request, on-failure, never) to control write and network access permissions. |
| Plan Tracking | update_plan is used to list steps and track status, requiring only one in_progress step at all times to maintain clear progress. |
| Interaction Protocol | Sends brief introductory explanations before important operations, maintaining a friendly, concise tone and providing progress updates. |
| Security Constraints | Adheres to strict rules (no arbitrary changes to unrelated files, no adding copyright headers, no executing destructive commands), requiring user approval for sensitive operations. |
| Testing and Formatting | Recommends running relevant tests and formatting tools after modifications, but is not responsible for fixing issues unrelated to the current task. |
| Output and Style | Final output adheres to CLI rendering specifications (e.g., ** for headings, backticks for paths/commands), maintaining a scannable and concise structure. |
| Parallel Execution | Supports running multiple tools in parallel via multi_tool_use.parallel to improve efficiency. |
AI Model Configuration Method
Windows Graphical Guide
1. Open Terminal
2. Install WSL
For optimal performance on Windows, please install and use Windows Subsystem for Linux (WSL2).
Install WSL2, Restart Windows Computer
wsl --installRestart your Windows computer after installation.
Windows Notes
- It is recommended to use PowerShell instead of CMD.
- If you encounter permission issues, try running as administrator.
- Some antivirus software may report false positives; you need to add an exception.
Download Node Version Manager (NVM)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
NVM Installs Node.js 22
Open a new PowerShell window in the tab bar and open WSL:
wslInstall Node.js (version numbers are time-sensitive; please install the corresponding version according to the OpenAI official website requirements):
nvm install 22
3. Install Codex CLI
Install Codex CLI
npm i -g @openai/codexThis command will download and install the latest version of Codex CLI from the official npm repository.
4. Modify Configuration File
One-Click Modification of Codex CLI Configuration File
iex (irm 'https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.ps1')
5. Start Using Codex CLI
Now you can start using Codex CLI!
Launch Codex CLI
Launch WSL2:
wslLaunch Codex CLI directly:
codexUse in a specific project:
cd mnt/c/path/to/your/project
codexPress Enter to launch Codex CLI.
Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Codex requires manual authorization to modify files.
Select Model
/model
Note: After modifying the API address, all models (including officially preset models) will call your configured, legally authorized self-owned or organizational access point. Please use your own deployed New API, or confirm that the service provider has a New API service with legal upstream authorization and compliance obligations. Do not connect API addresses or keys from unknown sources to a production environment.
macOS Graphical Guide
1. Install Homebrew (Skip if already installed)
Homebrew is the missing package manager for macOS.
Official Website: https://brew.sh
Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. Install Node.js Environment
Node.js Environment Installation Steps
Update Homebrew:
brew updateInstall Node.js:
brew install nodemacOS Notes
- If you encounter permission issues, you might need to use
sudo. - The first run may require permission in System Preferences.
- It is recommended to use Terminal or iTerm2.
Verify Successful Installation
After installation, open the terminal and enter the following commands:
node --version
npm --versionIf version numbers are displayed, the installation was successful.
3. Install Codex CLI
Install Codex CLI
Open the terminal and run the following command:
# Install Codex CLI globally
npm install -g @openai/codexIf you encounter permission issues, you can use sudo:
sudo npm install -g @openai/codex
Verify Codex CLI Installation
After installation, enter the following command to check if the installation was successful:
codex --versionIf a version number is displayed, congratulations! Codex CLI has been successfully installed.
4. Modify Configuration File
One-Click Modification of Codex CLI Configuration File
curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
5. Start Using Codex CLI
Now you can start using Codex CLI!
Launch Codex CLI
Launch Codex CLI directly:
codexUse in a specific project:
cd /path/to/your/project
codexPress Enter to launch Codex CLI.
Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Codex requires manual authorization to modify files.
Note: After modifying the API address, all models (including officially preset models) will call your configured, legally authorized self-owned or organizational access point.
6. macOS Common Issues and Solutions
Permission Error During Installation
Try the following solutions:
- Install with
sudo:sudo npm install -g @openai/codex - Or configure
npmto use the user directory:npm config set prefix ~/.npm-global
macOS Security Settings Prevent Running
If the system prevents Codex CLI from running:
- Open "System Preferences" → "Security & Privacy"
- Click "Open Anyway" or "Allow"
- Or run in Terminal:
sudo spctl --master-disable
Linux Graphical Guide
1. Install Node.js Environment
Codex CLI requires a Node.js environment to run.
Node.js Environment Installation Steps
Add NodeSource repository:
sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -Install Node.js:
sudo apt-get install -y nodejsLinux Notes
- Some distributions may require additional dependencies.
- If you encounter permission issues, use sudo.
- Ensure your user has write permissions in npm's global directory.
Verify Successful Installation
After installation, open the terminal and enter the following commands:
node --version
npm --versionIf version numbers are displayed, the installation was successful.
2. Install Codex CLI
Install Codex CLI
Open the terminal and run the following command:
# Install Codex CLI globally
npm install -g @openai/codexIf you encounter permission issues, you can use sudo:
sudo npm install -g @openai/codex
Verify Codex CLI Installation
After installation, enter the following command to check if the installation was successful:
codex --versionIf a version number is displayed, congratulations! Codex CLI has been successfully installed.
3. Modify Configuration File
One-Click Modification of Codex CLI Configuration File
curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
4. Start Using Codex CLI
Now you can start using Codex CLI!
Launch Codex CLI
Launch Codex CLI directly:
codexUse in a specific project:
# Enter your project directory
cd /path/to/your/project
# Launch Codex CLI
codexPress Enter to launch Codex CLI.
Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Codex requires manual authorization to modify files.
Note: After modifying the API address, all models (including officially preset models) will call your configured, legally authorized self-owned or organizational access point.
5. Linux Common Issues and Solutions
Permission Error During Installation
Try the following solutions:
- Install with
sudo:sudo npm install -g @openai/codex - Or configure
npmto use the user directory:npm config set prefix ~/.npm-global - Then add to PATH:
export PATH=~/.npm-global/bin:$PATH
Missing Dependency Libraries
Some Linux distributions require additional dependencies:
# Ubuntu/Debian
sudo apt install build-essential# CentOS/RHEL
sudo dnf groupinstall "Development Tools"How is this guide?
Claude Code
Claude Code configuration guide — use Anthropic's terminal-based coding agent with New API. Supports code understanding, multi-file editing, and IDE integration.
Factory Droid CLI
Factory Droid CLI setup guide — install and configure this AI software engineering agent with New API. Supports end-to-end development from planning to testing.