OpenAI Codex CLI

OpenAI Codex CLI installation guide — install a terminal-based AI coding assistant on Windows, macOS, and Linux, connected to New API. Supports sandbox policies and atomic patch editing.

Project Overview

Codex CLI is a coding agent from OpenAI that runs locally on your computer.

Official website: https://chatgpt.com/codex
Project homepage: https://github.com/openai/codex

Demo

Features

Feature Category	Description
Terminal-based coding assistant	Codex CLI is a terminal-based interactive coding assistant for editing code, generating patches, and running commands from the command line.
Tool-driven architecture	Provides tools such as `apply_patch`, `shell`, `update_plan`, and `multi_tool_use` for controlled changes to repository files and operations.
Atomic patch editing	Uses a dedicated patch format to atomically add/update/delete files through `apply_patch`, making auditing and rollback easier.
Sandbox and approvals	Supports sandbox policies (such as `workspace-write` and `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 exactly one `in_progress` step at all times to maintain clear progress.
Interaction conventions	Sends a brief preamble before important actions, keeping the tone friendly, concise, and providing progress updates.
Security constraints	Follows strict rules (does not arbitrarily modify unrelated files, does not add copyright headers, does not run destructive commands), and requires user approval for sensitive operations.
Testing and formatting	Recommends running relevant tests and formatting tools after changes, but is not responsible for fixing issues unrelated to the current task.
Output and style	Final output follows CLI rendering conventions (for example, `**` headings and backticks for paths/commands), keeping the structure concise and scannable.
Parallel execution	Supports running multiple tools in parallel through `multi_tool_use.parallel` to improve efficiency.

AI Model Configuration

Illustrated Guide for Windows

1. Open the terminal

windows_open_terminal

2. Install WSL

For the best performance on Windows, install and use Windows Subsystem for Linux (WSL2).

Install WSL2 and restart your Windows computer

wsl --install

Restart your Windows computer after the installation is complete.

Windows notes

PowerShell is recommended instead of CMD
If you encounter permission issues, try running as Administrator
Some antivirus software may flag it incorrectly; add it to the allowlist if needed

Download Node Version Manager (NVM)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

Install Node.js 22 with NVM

Open a new PowerShell tab and launch WSL:

wsl

Install Node.js (version requirements may change over time, so install the version required by the OpenAI website):

nvm install 22

3. Install Codex CLI

Install Codex CLI

npm i -g @openai/codex

This command downloads and installs the latest version of Codex CLI from the official npm registry.

4. Update the configuration file

One-click update for the Codex CLI configuration file

iex (irm 'https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.ps1')

windows-configure

5. Start using Codex CLI

You can now start using Codex CLI.

Launch Codex CLI

Start WSL2:

wsl

Launch Codex CLI directly:

codex

Use it in a specific project:

cd mnt/c/path/to/your/project
codex

Press Enter to launch Codex CLI.

Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Require manual approval before Codex modifies files

Select a model

/model

Note: After changing the endpoint address, all models used (including official preset models) will call the custom endpoint instead of using quota from your official account.

Illustrated Guide for macOS

1. Install Homebrew (skip if already installed)

Homebrew is the package manager for software missing from macOS.

Official website: https://brew.sh

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install the Node.js environment

Node.js installation steps

Update Homebrew:

brew update

Install Node.js:

brew install node

macOS notes

If you encounter permission issues, you may need to use sudo
The first run may require approval in System Preferences
Terminal or iTerm2 is recommended

Verify that the installation succeeded

After installation, open Terminal and run the following commands:

node --version
npm --version

If version numbers are displayed, the installation was successful.

3. Install Codex CLI

Install Codex CLI

Open Terminal and run the following command:

# Install Codex CLI globally
npm install -g @openai/codex

If you encounter permission issues, you can use sudo:

sudo npm install -g @openai/codex

Verify the Codex CLI installation

After installation, run the following command to verify that it was installed successfully:

codex --version

If a version number is displayed, congratulations! Codex CLI has been installed successfully.

4. Update the configuration file

One-click update for the Codex CLI configuration file

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash

macos-configure

5. Start using Codex CLI

You can now start using Codex CLI.

Launch Codex CLI

Launch Codex CLI directly:

codex

Use it in a specific project:

cd /path/to/your/project
codex

Press Enter to launch Codex CLI.

Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Require manual approval before Codex modifies files

Note: After changing the endpoint address, all models used (including official preset models) will call the custom endpoint instead of using quota from your official account.

6. Common macOS issues

Permission error during installation

Try the following solutions:

Install with sudo: sudo npm install -g @openai/codex
Or configure npm to use a user directory: npm config set prefix ~/.npm-global

macOS security settings block execution

If the system blocks Codex CLI from running:

Open "System Preferences" → "Security & Privacy"
Click "Open Anyway" or "Allow"
Or run this in Terminal: sudo spctl --master-disable

Illustrated Guide for Linux

1. Install the Node.js environment

Codex CLI requires a Node.js environment to run.

Node.js installation steps

Add the NodeSource repository:

sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

Install Node.js:

sudo apt-get install -y nodejs

Linux notes

Some distributions may require additional dependencies
Use sudo if you encounter permission issues
Make sure your user has write permission to npm's global directory

Verify that the installation succeeded

After installation, open Terminal and run the following commands:

node --version
npm --version

If version numbers are displayed, the installation was successful.

2. Install Codex CLI

Install Codex CLI

Open Terminal and run the following command:

# Install Codex CLI globally
npm install -g @openai/codex

If you encounter permission issues, you can use sudo:

sudo npm install -g @openai/codex

Verify the Codex CLI installation

After installation, run the following command to verify that it was installed successfully:

codex --version

If a version number is displayed, congratulations! Codex CLI has been installed successfully.

3. Update the configuration file

One-click update for the Codex CLI configuration file

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash

macos-configure

4. Start using Codex CLI

You can now start using Codex CLI.

Launch Codex CLI

Launch Codex CLI directly:

codex

Use it in a specific project:

# Go to your project directory
cd /path/to/your/project

# Launch Codex CLI
codex

Press Enter to launch Codex CLI.

Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Require manual approval before Codex modifies files

Note: After changing the endpoint address, all models used (including official preset models) will call the custom endpoint instead of using quota from your official account.

5. Common Linux issues

Permission error during installation

Try the following solutions:

Install with sudo: sudo npm install -g @openai/codex
Or configure npm to use a user directory: npm config set prefix ~/.npm-global
Then add it 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"

On this page