tool

Codex — Coding Agent Cheatsheet

Practical operating guide for OpenAI Codex: install the local CLI, choose models, tune sandbox and approval policies, and run repository tasks safely.

2026-09-25 (3 weeks ago)
5 steps
~45 min total
@openai/codex 0.156.x

codex
openai
coding-agent
cli
sandbox
approvals

Codex — Coding Agent Cheatsheet

One-line: Codex is OpenAI’s local coding-agent CLI and app workflow for repository tasks, with model selection, trusted-project configuration, sandbox modes, and approval policies designed for safe automation.

Installation

Install Codex from the official OpenAI repository or package channels.

# npm install path from the official repository
npm i -g @openai/codex

# macOS cask path documented by OpenAI
brew install --cask codex

# Start in a repository
cd path/to/project
codex

First-run checklist:

Sign in or provide the API credentials your organization requires.
Trust only repositories you own or have reviewed before allowing writes.
Keep default sandboxing until the task proves it needs broader access.
Put durable defaults in ~/.codex/config.toml; use project overrides only for trusted repos.

Step-by-Step Setup & Optimization

Step 1 — Pick the right interface

Goal: The Codex surface that matches how you workTime: ~5 minLevel: beginner

Interface	Best for
`codex` CLI	Terminal-native repo edits, tests, and PR prep.
Codex IDE extension	Editor-integrated review and implementation loops.
`codex app`	Desktop workflow when you want a local app surface.
Codex Web	Cloud task delegation from ChatGPT/Codex surfaces.

You know which interface you’re using and why — CLI, IDE, app, or web.

Step 2 — Configure model and project defaults

Goal: Model, approval, and sandbox defaults set at the right config levelTime: ~10 minLevel: intermediate

Codex reads personal defaults from ~/.codex/config.toml and can read project overrides from .codex/config.toml after trust is established.

model = "gpt-6-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Use CLI flags for one-off overrides:

codex --model gpt-6-sol --sandbox workspace-write
codex --oss

~/.codex/config.toml (or .codex/config.toml) holds your model, approval_policy, and sandbox_mode values.

Step 3 — Set sandbox and approval policy intentionally

Goal: A sandbox mode chosen deliberately, not by defaultTime: ~5 minLevel: intermediate

Mode	When to use
`read-only`	Exploration, review, threat modeling, unknown repos.
`workspace-write`	Normal coding tasks; writes stay in the active workspace.
`danger-full-access`	Rare local-only experiments after backups and human review.

Network access is intentionally constrained by default in workspace mode. Enable it only for tasks that require package installs, API calls, or remote docs.

Your sandbox mode matches the task — read-only for review, workspace-write for normal work.

Step 4 — Run task loops with evidence

Goal: Codex executing one planned slice at a time with checks after editsTime: ~15 minLevel: intermediate

Ask Codex to produce a plan, then execute a single slice:

Summarize the failing test, propose a 3-step fix, then implement only step 1.

After edits, run the smallest relevant check first, then the broader suite:

pnpm test path/to/file.test.ts
pnpm type-check
pnpm test

The smallest relevant check passed after the slice, then the broader suite.

Step 5 — Review before merge

Goal: A diff you approved line by line before it landsTime: ~10 minLevel: intermediate

Use the generated diff as a proposal, not a final answer. Check for over-broad rewrites, hidden config changes, generated files, and unapproved network or filesystem assumptions.

You read the full diff and found no over-broad rewrites or hidden config changes.

Best Practices

Do

✅ Keep Codex in workspace-write for day-to-day development.
✅ Use read-only for unfamiliar repositories and security review.
✅ Store stable preferences in ~/.codex/config.toml.
✅ Use project .codex/config.toml only after trusting the repo.
✅ Ask for small plans and evidence-backed test runs.
✅ Commit after each known-good milestone.

Don’t

❌ Use danger-full-access as a default.
❌ Enable network access just because a package install failed once.
❌ Let Codex edit secrets, credentials, or production deployment config without review.
❌ Mix unrelated issues in one agent task.
❌ Assume model choice fixes missing tests or unclear acceptance criteria.

Quick Command Reference

Command	Use
`npm i -g @openai/codex`	Install the CLI from the official npm package.
`brew install --cask codex`	Install the documented macOS cask.
`codex`	Start Codex in the current repository.
`codex login`	Authenticate with a ChatGPT account, API key, or token.
`codex doctor`	Diagnostic report for a broken install, auth, or config.
`codex exec "<task>"`	Non-interactive run for scripts and CI-style jobs.
`codex review`	Run a code review non-interactively.
`codex --model <model>`	Override the configured model for one run.
`codex --sandbox read-only`	Explore without allowing writes.
`codex --sandbox workspace-write`	Allow normal workspace edits.
`codex --oss`	Use the local open-source model provider when configured.

Expected Outcomes

After setup, you should have:

A verified Codex install and a known authentication path.
Personal configuration for model, approval, and sandbox defaults.
A clear rule for when project-level .codex/ configuration is trusted.
A repeatable task loop that produces diffs, tests, and reviewable evidence.
A safer escalation path for network access or broader filesystem privileges.

Reference

Sources & deeper reading