Installation

Get Codex running in your terminal in under 2 minutes.

Prerequisites

• Node.js 22+ (only needed for the npm installer — Codex itself is a native Rust binary)
• macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2 (Windows 10 best-effort)
• A terminal you love

Quick Install

Install globally via npm:

npm install -g @openai/codex

Homebrew works on macOS:

brew install --cask codex

Upgrade to latest:

npm i -g @openai/codex@latest

Windows users: Windows 11 via WSL2 is the officially supported path. Windows 10 (October 2018+) is supported on a best-effort basis.

Authentication

First time you run codex, you’ll see an auth prompt. Two options:

ChatGPT OAuth — Sign in with your ChatGPT account. Works if you have Plus, Pro, Team, Edu, or Enterprise. No API key management, billing is tied to your subscription.

API Key — Use OPENAI_API_KEY environment variable. Pay-as-you-go pricing. Better for CI/CD and automation.

export OPENAI_API_KEY="sk-..."
codex

Use OAuth for daily interactive work. Use API key for scripts and pipelines.

First Run

Navigate to your project and start Codex:

cd your-project
codex

You get an interactive TUI. Type your request, Codex reads your codebase, proposes changes.

Run inside a Git repo. This way you can git diff and git checkout . to revert anything.

Verify

Check that everything works:

codex --version

Tip: Add an AGENTS.md file to give Codex context about your codebase.

Approval Modes

Pick one based on how much you trust Codex with your codebase:

Preset	Policy	What Happens	When to Use
Read-only	untrusted	Ask before everything	New users, unfamiliar codebases
Auto	on-request	Ask for risky actions	Daily work (default)
Full Access	never	No prompts	CI/CD, well-tested codebases

Start with Auto (the default). Use --full-auto when you want no prompts with workspace-write sandbox.

Set in config.toml:

approval_policy = "on-request"

Or via CLI flag:

codex --ask-for-approval never

Sandbox Modes

Codex runs in a sandbox. Two options:

read-only — Codex can read files but not modify anything. Good for exploration and code review.

workspace-write — Codex can edit files in your project. Required for actual coding work.

sandbox_mode = "workspace-write"

The sandbox prevents Codex from touching files outside your project root.

Your First Task

Try something simple:

Analyze README.md and list what's missing or outdated

Codex will:

1. Read your README
2. Check your actual project structure
3. List gaps between docs and reality

No code changes, just analysis. Good way to see how Codex reasons.

Another starter:

Find all TODO comments in this repo and summarize them

Switching Models

Default model is gpt-5.4. Switch mid-session:

/model gpt-5.3-codex

Or set permanently:

model = "gpt-5.4"

Use gpt-5.3-codex for complex refactors. Use gpt-5.4-mini for quick tasks.

Troubleshooting

“Command not found” — npm global bin isn’t in PATH. Run npm bin -g and add that to your PATH.

Auth fails — Check your subscription tier. Free ChatGPT doesn’t include Codex.

Sandbox errors — You might be outside a Git repo. Codex prefers working in version-controlled directories.

Related

• AGENTS.md — Teach Codex your project conventions
• Models — Pick the right model for your task
• config.toml — Full configuration reference