Codex Install & Setup

Last updated: 2026-08-12

Introduction

Codex is OpenAI’s coding agent for developers: in the terminal CLI, IDE extension, or desktop app it reads your repo, edits files, runs commands, and interprets results. It is not the same as ChatGPT web chat—the former is a pair programmer; the latter suits one-off Q&A and document drafts.

OpenAI offers Codex CLI, Codex Web, and IDE extensions for VS Code, Cursor, and similar editors. This guide focuses on the CLI; IDE integrations share the same config hierarchy. If you already use the Anthropic stack, skim the Claude Code guide for shared agent-programming patterns, then follow this guide to install Codex.

What problem does Codex solve?

Web ChatGPT	Codex CLI / IDE
Paste code snippets for Q&A	Index project directories and Git state directly
Manually copy diffs into the editor	Edit files and run tests within granted permissions
Good for concepts and drafts	Multi-step bug fixes, refactors, scaffolding

Good fit: developers with a Git workflow who can run tests locally.
Poor fit: pure documentation environments with no version control or shell access.

Before install: environment and account

Item	Minimum	Notes
OS	macOS 13+, Ubuntu 22.04+, Windows 11	WSL2 on Windows gives fuller sandbox support
Git	2.30+	Best experience when started from a git init project root
Account	ChatGPT Plus/Pro/Team or OpenAI API key	Whether your plan includes Codex—check your Platform account
Node.js	18+ (npm path only)	Official script / Homebrew can skip Node
Resources	~200 MB disk; 8 GB RAM recommended	Large repos use more during indexing

Security: do not download so-called “cracked Codex” builds from untrusted sites. The CLI can read, edit, and execute shell commands—unknown binaries are high risk.

Download and install (three paths)

Commands change with releases; verify against Codex CLI docs before running.

Path A: official script (macOS / Linux, recommended)

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Path B: Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Path C: npm or Homebrew

npm install -g @openai/codex          # Node.js 18+ required
brew install --cask codex               # macOS only

After install, run codex --version. If the command is missing, check PATH and restart the terminal, or download a binary from Codex GitHub Releases.

First login and authorization

1. cd to your project root (ideally an existing Git repo).
2. Run codex to enter the interactive UI.
3. Choose authorization:
   • Sign in with ChatGPT: ties to your subscription; quotas vary by plan.
   • API key: billed via OpenAI Platform; good for CI or automation.
4. Confirm sandbox mode and command approval policy—by default Codex should ask before editing files or running shell commands.

If login or downloads are blocked in your region, read the ChatGPT China access guide; billing and authorization still follow your official OpenAI account.

config.toml: from defaults to control

Codex config priority: CLI flags > project config > profile > user config > built-in defaults.

Layer	Path	Typical use
User	~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml)	Default model, global sandbox, custom providers
Project	.codex/config.toml	Team-shared non-secret defaults (loaded only in trusted projects)
Profile	~/.codex/*.config.toml or [profiles.*] in config	Switch models / backends

Full key reference: Codex config docs.

Minimal config for beginners

model = "gpt-5.4"                      # verify model ID in official docs
approval_policy = "on-request"         # ask before file edits / commands
sandbox_mode = "workspace-write"       # writes limited to workspace

Common keys

Key	Typical values	Purpose
model	Official model ID	Default inference model
approval_policy	on-request / never	Whether tool calls need human approval
sandbox_mode	read-only / workspace-write	File-system write scope
model_reasoning_effort	low / high	Reasoning depth (if supported)

Security: keep on-request + workspace-write as a beginner default; try looser policies only in isolated practice repos. To use DeepSeek as a backend, see Configure DeepSeek in Codex.

IDE extension and desktop app

Besides the CLI, Codex is available via VS Code, Cursor, Windsurf, and other IDE extensions, or through codex app for the desktop client. Extensions and CLI share the same config.toml hierarchy.

Teams can commit non-secret defaults in .codex/config.toml; keep secrets in environment variables, never in Git.

Five checks after install

1. codex --version prints a version.
2. Run codex in a small practice repo root and complete login.
3. Run a read-only task (e.g. “list main module responsibilities under src/”) and confirm file indexing works.
4. Run a small write task and confirm approval prompts and sandbox behavior match expectations.
5. If using an API key, verify balance, model access, and rate limits on Platform.

Permissions and security (required reading)

Codex can read files, edit files, and run shell—over-permissioning is like handing your laptop to a stranger.

• Repos: enable only in trusted projects; fork open-source contributions into an isolated directory first.
• Secrets: keep .env, credentials.json in .gitignore; confirm whether tools read ignored files before enabling.
• Commands: stay cautious with rm -rf, package installs, and outbound requests; follow company AI policies.
• Output: generated code still needs code review and CI—do not merge to main without review.

Frequently asked questions

Install script download fails?

Check network and proxy, then try npm or Homebrew; or download from Codex GitHub Releases. On Windows, prefer installing the Linux build inside WSL2 for full sandbox support.

ChatGPT subscription vs API key?

ChatGPT sign-in usually binds Codex quota to your plan; API keys bill separately on Platform. Authorization paths differ—do not mix keys.

codex command not found?

Restart the terminal; follow PATH hints from the installer; for global npm installs, ensure npm prefix -g is on PATH.

Project config.toml not applied?

.codex/config.toml loads only in trusted projects; some keys (e.g. model_provider) must live in user-level ~/.codex/config.toml.

Native Windows vs WSL2?

If daily dev runs in WSL2, install Codex inside WSL for consistent behavior; the Windows installer works in pure PowerShell, but sandbox and path behavior may differ from Linux docs.

First task after install?

Start with a read-only Q&A (understand one module), then a single test fix—see Codex Usage for Beginners.

Official resources

• OpenAI
• ChatGPT
• OpenAI Platform
• Codex CLI docs
• Codex GitHub repo

Next reading

• Codex Usage for Beginners
• Configure DeepSeek in Codex
• Claude Code guide (multi-tool comparison)

Action path

Today: finish install, login, and one read-only Q&A in a practice repo. This week: run a real failing test through “read logs → minimal patch → local verify.” Long term: document team defaults for approval_policy, sandbox policy, and .gitignore checks in CONTRIBUTING.md.