Codex: Perfect Start Checklist with Official OpenAI Agent

Codex is the official coding agent from OpenAI. It stands out with sandbox, native GitHub integration, Rust core, and headless mode. But it has its quirks — here's the checklist for a perfect start.

1. Installation — Choose Your Way

MethodCommandPros
npm (universal)npm install -g @openai/codexAlways latest, works everywhere with Node.js
Homebrew (macOS)brew install openai/codex/codexAuto-updates via brew, native binary
Linux (curl)curl -fsSL https://codex.openai.com/install.sh | bashBinary without Node.js, for servers/containers
GitHub ReleasesDownload from GitHubSpecific version, offline install

Recommendation: npm install -g @openai/codex — easiest to update.

2. Authentication — Two Required Steps

OpenAI Account (for models)

codex auth login
# Opens browser → sign in to OpenAI account
# Needs access to GPT-4o / o1 / o3-mini

Without this — only local/free models (if custom endpoints configured).

GitHub Token (for PR/issue integration)

# Option 1: via gh CLI
codex auth login --github
# or
export GITHUB_TOKEN=$(gh auth token)

# Option 2: Personal Access Token
# GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
# Scopes: repo, workflow, read:org
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Without GitHub token — no PR creation, issue reading, CI integration.

3. Config: ~/.codex/config.toml

Create file (globally or in project):

[model]
provider = "openai"          # or "anthropic"
model = "gpt-4o"             # gpt-4o, o1-preview, o3-mini
# model = "claude-3.5-sonnet"  # for Anthropic
base_url = "https://api.openai.com/v1"
api_key = "$OPENAI_API_KEY"  # or via auth login

[sandbox]
enabled = true
# Windows: "windows-sandbox" (Hyper-V)
# Linux/macOS: "namespace" (auto)

[permissions]
allow = ["read", "write", "bash", "grep", "glob"]

[github]
token = "$GITHUB_TOKEN"
# auto-detects from gh CLI if not set

[hooks]
# pre_model_request = "echo 'Request: $REQUEST_ID'"
# post_model_request = "echo 'Response: $REQUEST_ID'"

Tip: Keep secrets in env vars, not in config.

4. First Run — TUI Mode

cd your-project
codex
# Opens TUI with panels:
# ┌─ Chat ─────────────────────┐
# │ Your message...            │
# ├─ Files ────────────────────┤
# │ src/                       │
# │  main.py                   │
# ├─ Terminal ─────────────────┤
# │ $ _                        │
# └────────────────────────────┘
# 
# Hotkeys:
# Ctrl+C  — interrupt generation
# /help   — commands list
# /compact — compress context
# /help sandbox — sandbox info

5. Headless Mode — For CI/CD & Scripts

Most powerful feature for automation:

# JSON output for parsing
codex -p "Create REST API on FastAPI" --output-format json
# {"result": "...", "files_changed": [...], "commands_run": [...]}

# In GitHub Actions
- name: Run Codex
  run: |
    codex -p "$TASK" --output-format json |
    jq -r '.result' > output.md

# Streaming output (real-time)
codex -p "Refactor this code" --stream

# With GitHub token
codex -p "Create PR with tests" --github-token $GITHUB_TOKEN --output-format json

6. Model Selection: GPT-4o vs Claude vs o1

ModelBest ForSpeedCost
GPT-4oGeneral code, refactoring, tests, docsFastMedium
Claude 3.5 SonnetComplex refactoring, architecture, securityMediumHigh (needs Anthropic key)
o1-previewComplex algorithms, math, planningSlowVery high
o3-miniFast reasoning, code review, simple tasksVery fastLow

Tip: GPT-4o default for 90% tasks. o3-mini for quick fixes. Claude for architecture.

7. Sandbox: Windows vs Linux/macOS

  • Windows: Hyper-V sandbox service (codex-windows-sandbox-service). Requires Pro/Enterprise Windows. Hypervisor-level isolation — max security.
  • Linux/macOS: Namespace-based isolation. Works everywhere with unprivileged user namespaces (most modern distros).
  • Disable: [sandbox] enabled = false in config (not recommended).

8. GitHub Integration — Setup Once

# Auto-pick from gh CLI
codex auth login --github

# Or env variable
export GITHUB_TOKEN=$(gh auth token)
# In .bashrc / .zshrc for persistence

After this: codex -p "Create PR with fix" --github-token $GITHUB_TOKEN works automatically.

9. Aliases for Speed

# ~/.bashrc / ~/.zshrc
alias cx='codex'
alias cxp='codex -p'
alias cxj='codex -p --output-format json'
alias cxs='codex -p --stream'
alias cxg='codex -p --github-token $GITHUB_TOKEN'

# Quick models
alias cx-4o='codex -m gpt-4o'
alias cx-claude='codex -m claude-3.5-sonnet'
alias cx-o3='codex -m o3-mini'

10. Common Beginner Mistakes

  • Skip auth login → only local models. Do codex auth login immediately.
  • Forget GitHub token → lose 50% features (PR, issues, CI). Setup immediately.
  • Disable sandbox → lose main security feature. Don't disable.
  • Don't use headless → lose CI/CD integration. Try --output-format json.
  • Build from source unnecessarily — Bazel is complex. Use binary/brew/npm.

First Day Checklist ✅

  1. [ ] npm install -g @openai/codex (or brew)
  2. [ ] codex auth login (OpenAI)
  3. [ ] codex auth login --github (GitHub)
  4. [ ] Create ~/.codex/config.toml with model
  5. [ ] codex in project folder — first TUI run
  6. [ ] Try codex -p "Hello" --output-format json
  7. [ ] Configure GitHub token for PR
  8. [ ] Test sandbox: codex -p "ls -la /root" (should deny)
  9. [ ] Add aliases to .bashrc/.zshrc
  10. [ ] Read docs