OpenAI Codex CLI Complete Installation Guide: From npm Setup to Your First AI-Generated Code
OpenAI Codex CLI Complete Installation Guide
OpenAI Codex CLI is an open-source command-line tool that brings the power of AI-assisted coding directly to your terminal. It interprets natural language prompts, reads your codebase, proposes changes, and can even execute commands — all within a configurable sandbox environment for safety. This guide walks you through every step from installation to generating your first code.
Prerequisites
- Node.js 22 or higher — Codex CLI requires a modern Node.js runtime- An OpenAI API key — with access to models like
o4-minioro3- Git — recommended for version-controlled projects- Operating System: macOS or Linux (Windows users should use WSL2)Verify your Node.js version before proceeding:node —version
Must output v22.0.0 or higher
Step 1: Install OpenAI Codex CLI via npm
Install the Codex CLI globally using npm:
npm install -g @openai/codex
Verify the installation was successful:
codex --version
If you encounter permission errors on macOS or Linux, avoid using sudo. Instead, configure npm's global directory:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
Add the export line to your ~/.bashrc or ~/.zshrc for persistence.
Step 2: Configure Your OpenAI API Key
Codex CLI authenticates via the OPENAI_API_KEY environment variable. Set it in your shell profile:
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export OPENAI_API_KEY=“YOUR_API_KEY”
Reload your shell configuration:
source ~/.bashrc
Alternatively, create a .env file in your project root:
echo ‘OPENAI_API_KEY=YOUR_API_KEY’ > .env
Codex CLI will automatically detect the .env file when run from that directory.
Verify API Key Configuration
codex “Say hello”
Should return a response without authentication errors
Step 3: Understand and Configure Sandbox Security Modes
One of Codex CLI's most important features is its approval policy system, which controls how much autonomy the AI agent has. There are three modes:
| Mode | Flag | File Edits | Command Execution | Best For |
|---|---|---|---|---|
| **Suggest** | --approval-mode suggest | Requires approval | Requires approval | Maximum safety, reviewing each change |
| **Auto Edit** | --approval-mode auto-edit | Auto-applied | Requires approval | Rapid prototyping with safe commands |
| **Full Auto** | --approval-mode full-auto | Auto-applied | Auto-executed in sandbox | Automated pipelines, CI/CD tasks |
# Explicit suggest mode (default)
codex --approval-mode suggest "Refactor the utils module"When using **Full Auto** mode, Codex applies network-disabled, directory-scoped sandboxing. On macOS it uses Apple Seatbelt, on Linux it uses Docker-based isolation:
# Full auto with sandboxed execution
codex --approval-mode full-auto "Write and run tests for auth.js"
## Step 4: Select Your Model
Codex CLI defaults to o4-mini but supports other OpenAI models. Choose a model based on task complexity:
# Use the default o4-mini (fast, cost-effective)
codex "Add input validation to the signup form"
Use o3 for complex reasoning tasks
codex —model o3 “Redesign the database schema for multi-tenancy”
Step 5: Generate Your First Code
Navigate to your project directory and run your first real prompt:
cd ~/projects/my-app
Generate a new utility function
codex “Create a TypeScript utility function that debounces
any async function with configurable delay and max wait time”
Codex will read your project context, propose a file to create or edit, and show a diff for your approval. Press Enter to accept or Esc to reject.
Interactive Session Example
Launch Codex without a prompt for an interactive multi-turn session:
codex
Now type prompts interactively:
> Find all API endpoints that lack authentication middleware
> Add rate limiting to the /api/upload route
Project-Level Configuration with codex.md
Create a codex.md file in your repository root to provide persistent context:
# codex.md
This is a Next.js 15 project with App Router.
Use TypeScript strict mode. Follow the existing patterns in src/lib/.
Tests use Vitest. Run tests with: npm run test
Database: PostgreSQL via Prisma ORM.
Codex automatically reads this file and follows its instructions on every invocation.
Pro Tips for Power Users
- Pipe input directly:
cat error.log | codex “Explain this error and suggest a fix”- Quiet mode for scripts: Usecodex -q “Generate a migration”to print only the final output, ideal for CI pipelines.- Multi-turn context: In interactive mode, Codex retains full conversation context. Build complex changes step by step.- Custom instructions per project: Usecodex.mdin any subdirectory for scoped instructions that override the root file.- Cost control: Stick witho4-minifor routine tasks. Reserveo3for architectural decisions or complex debugging.- Git integration: Run Codex inside a Git repo so you can always review diffs withgit diffand revert withgit checkout .
Troubleshooting Common Errors
| Error | Cause | Solution |
|---|---|---|
EACCES: permission denied | npm global install without permission | Configure npm prefix as shown in Step 1 or use npx @openai/codex |
401 Unauthorized | Missing or invalid API key | Verify echo $OPENAI_API_KEY outputs your key correctly |
Node.js version not supported | Running Node.js below v22 | Install Node.js 22+ via nvm install 22 |
ECONNREFUSED or network timeout | Firewall or proxy blocking API calls | Check proxy settings: export HTTPS_PROXY=http://your-proxy:port |
| Sandbox execution fails on Linux | Docker not installed or running | Install Docker and ensure the daemon is active: sudo systemctl start docker |
Is OpenAI Codex CLI free to use?
The CLI tool itself is free and open-source (Apache 2.0 license). However, it requires an OpenAI API key, and API usage is billed based on token consumption. The default model o4-mini is the most cost-effective option for everyday tasks.
Can Codex CLI work with non-JavaScript projects?
Yes. Codex CLI is language-agnostic. It reads your project files regardless of language — Python, Rust, Go, Java, C++, and more are all supported. It analyzes your codebase structure and generates context-appropriate code in whatever language your project uses.
How does the sandbox protect my system in Full Auto mode?
In Full Auto mode, Codex executes commands inside a restricted sandbox. On macOS, it uses Apple’s Seatbelt framework to disable network access and restrict filesystem writes to the current working directory and temporary folders. On Linux, it uses containerized execution via Docker. This prevents any AI-initiated command from accessing the internet or modifying files outside your project scope.