Mastering OpenAI Codex: A Complete Guide from Setup to Engineering Workflows

In the current explosion of AI-powered developer tools, OpenAI Codex has emerged as one of the hottest coding agents in the developer community, thanks to its natively co-designed model-and-framework architecture. It doesn't just generate code snippets — it can understand an entire codebase, execute multi-step tasks, auto-fix bugs, and generate pull requests. Yet many developers still view Codex as little more than "advanced code completion," falling short of unlocking its true engineering potential. This article starts from the underlying principles and walks you through the complete journey — from installation and configuration to real-world engineering adoption — helping you truly master Codex at a deep level.

1. Understanding Codex: More Than Just Code Completion

1.1 The Three-Layer Architecture of Codex

To use Codex effectively, you first need to understand its design philosophy. Developer Gabriel Chua offers an insightful perspective — Codex is composed of three tightly integrated layers:

• Model Layer: Delivers the core intelligence. Built on flagship coding models like GPT-5.5, it performs structured reasoning before responding, understanding code logic, architectural design, and best practices.
• Framework Layer: An open-source execution framework that bridges the model to the real environment. It enables "execution" rather than merely "suggestion," using techniques like "compaction" to manage the context window, allowing the model to actually manipulate files, run commands, and test code.
• Interface Layer: Provides diverse interaction methods, including a desktop app, CLI terminal, IDE extensions, and a web-based cloud interface.

Key Insight: The model and framework weren't bolted together as an afterthought — they were co-designed from the ground up. This is the essence of Native Coding — not shoehorning a model into an existing tool, but designing everything in tandem from the lowest layer up.

1.2 How Codex Compares to Other Coding Agents

• Reasoning Time: Codex can spend 10 minutes or more on a task, far exceeding other agents that typically range from seconds to a few minutes. This translates to deeper, more thorough thinking.
• Output Quality: Codex aims to deliver "first-shot" production-grade code, rather than half-baked output that requires multiple iterations.
• Model Integration: Codex uses native integration, whereas most other agents rely on plugin-style invocations.
• Use Cases: Codex excels at complex tasks and production code, while other agents are better suited for rapid prototyping and simple tasks.

1.3 Capability Boundaries

What Codex can do: write production-grade code, understand complex codebases, perform code review and optimization, debug and fix issues, automate development tasks, and plan multi-step projects.

Important Reminder: You still need to review the code Codex writes. It's not magic — it's a tool.

2. Four Usage Surfaces and Installation

Codex offers four usage forms (officially called "Surfaces"). Understanding their differences is key to mastering Codex.

2.1 CLI Installation (Most Flexible, Cross-Platform)

The CLI is the most feature-complete open-source surface, ideal for terminal workflows and automation integration.

# Install via npm

npm install -g @openai/codex

# Or install via Homebrew (macOS)

brew install codex

# Upgrade to the latest version

npm install -g @openai/codex@latest

# Log in and authorize

codex login

# Or log in using an API Key

codex login --with-api-key

Once installed, simply run codex in your terminal to launch the full-screen terminal UI.

2.2 Desktop App Installation (Most Recommended for macOS Users)

The desktop app supports parallel workflows, Git Worktrees, and automation — making it the best choice for macOS users:

1. Visit the official site at https://chatgpt.com/codex to download the installer
2. Log in with your ChatGPT account or OpenAI API Key
3. Select your project folder
4. Choose a work mode (Local/Worktree/Cloud) and send your first message

2.3 IDE Extension Installation (Most Seamless)

Codex officially supports mainstream IDEs including VS Code, Cursor, and Windsurf:

# VS Code command-line installation

code --install-extension openai.chatgpt

# Cursor command-line installation

cursor --install-extension openai.chatgpt

Alternatively, search for "Codex" or "ChatGPT" directly in your IDE's extension marketplace. After installation, log in with your ChatGPT account or API Key.

2.4 Web Cloud (Lightest Weight)

Access Codex directly through the ChatGPT sidebar on the web — no software installation required. Tasks run in an isolated cloud environment, making it perfect for low-spec devices.

How to Choose? Use the IDE extension for daily development, the desktop app for complex tasks, the CLI for automation scripts, and the web cloud for access anywhere. All four surfaces can be used simultaneously with synchronized data.

3. Core Workflows in Practice

3.1 Three CLI Usage Modes

Interactive Mode (Default): Launches the full-screen terminal UI with support for continuous conversation.

# Start interactive mode

codex

# Launch with a prompt directly

codex "Help me refactor the validation logic in the auth module"

# Full auto mode (no confirmation required, use with caution)

codex --full-auto "Fix all lint warnings"

Non-Interactive Mode (Scriptable): Ideal for CI/CD integration and automation scenarios.

# Execute a single command, output as JSON

codex exec --json "Analyze the architecture of this file" > result.json

# Output the last message to a file

codex exec --output-last-message report.txt "Generate API documentation"

# Ephemeral session (not saved)

codex exec --ephemeral "Quick ad-hoc analysis task"

Resuming Sessions: Continue previously unfinished work.

# List all sessions

codex resume --all

# Resume the last session

codex resume --last

# Fork a session into a new thread (for branching exploration)

codex fork --last

3.2 Three Desktop App Work Modes

• Local Mode: Works directly in your project directory. Changes are immediately reflected in the file system. Best for quick prototyping and small edits.
• Worktree Mode (Recommended): Creates an independent Git worktree for each task. Changes are fully isolated and won't affect the main branch, supporting parallel development of multiple features. Worktrees are automatically cleaned up after 4 days or when exceeding 10 active worktrees.
• Cloud Mode: Tasks execute in the cloud. You can shut down your local machine, and the resulting diff will be applied locally once complete.

3.3 Practical Examples: Six Typical Workflows

Example 1: Navigating an Unfamiliar Codebase

Please analyze the overall architecture of this project. Explain the core modules, data flow, and dependency relationships.

Pay special attention to the authentication logic under the src/auth directory.

Example 2: Bug Fixing

Running tests reveals an error on line 42 of user.service.ts:

TypeError: Cannot read property 'email' of null

Please identify the root cause and fix it, and add corresponding unit tests.

Example 3: Writing Test Cases

Write unit tests for all exported functions in src/utils/validator.ts.

Requirements: Cover happy paths, edge cases, and error scenarios. Use the Jest framework.

Example 4: Generating Code from a Screenshot

Pass an image directly in the CLI:

codex --image "ui-mockup.png" "Implement this page based on the UI mockup using React + Tailwind CSS"

Example 5: Code Review

/review

Please review all changes on the current branch, focusing on:

1. Potential security vulnerabilities

2. Performance issues

3. Code style consistency

4. Missing edge cases

Example 6: Delegating Refactoring to the Cloud

Refactor all class components in the project to functional components using React Hooks.

Ensure all existing tests continue to pass. Create a PR when finished.

4. Advanced Configuration and Deep Customization

4.1 Core Configuration File: config.toml

Codex uses a TOML configuration file with multi-layer priority support:

# ~/.codex/config.toml — Global configuration

# Default model selection

model = "gpt-5.5"

# Reasoning effort: low (fast) / medium / high (deep thinking)

model_reasoning_effort = "high"

# File opener

file_opener = "vscode"

# Sandbox mode: read-only / workspace-write / full-access

sandbox_mode = "workspace-write"

# Approval policy: suggest / auto-edit / full-auto

approval_policy = "suggest"

Project-level configuration can be placed in .codex/config.toml within the project, which overrides global settings.

4.2 AGENTS.md: The Project Brief

This is one of Codex's most important configuration files. Create an AGENTS.md in your project root and write project-specific guidelines:

# AGENTS.md - Project Brief

## Project Overview

This is a Next.js 14-based e-commerce platform backend service.

## Tech Stack

- Runtime: Node.js 20

- Framework: Next.js 14 (App Router)

- Database: PostgreSQL + Prisma ORM

- Testing: Vitest + Testing Library

## Code Conventions

- Use functional components only; class components are prohibited

- API routes must be placed under app/api/

- All database operations must go through Prisma Client; raw SQL is prohibited

- Error handling must use the custom AppError class

- All public functions must have JSDoc comments

## Directory Structure Conventions

- app/ - Next.js App Router pages and APIs

- lib/ - Utility functions and shared logic

- prisma/ - Database schema and migrations

- tests/ - Test files, mirroring the app/ directory structure

## Known Issues & Conventions

- The userId field was changed to ULID format after the v2 migration; be mindful of backward compatibility with legacy data

- The payment module's retry logic has a special state machine — do not modify it casually

Best Practice: Write AGENTS.md as if you were creating an onboarding document for a new team member. The clearer the context, constraints, and conventions you provide, the more accurate Codex's output will be.

4.3 Rules Files: Fine-Grained Execution Permissions

Rules files let you define exactly which commands Codex is allowed to execute:

{

  "name": "project-rules",

  "commands": [

    {

      "pattern": "npm test",

      "approval": "auto"

    },

    {

      "pattern": "git commit *",

      "approval": "suggest"

    },

    {

      "pattern": "rm *",

      "approval": "never"

    }

  ]

}

4.4 Local Environment Configuration: local-env.toml

Define project-specific environment scripts and shortcuts in the .codex/ directory:

# .codex/local-env.toml

[setup]

# Automatically runs when creating a new worktree

commands = [

    "npm install",

    "npm run build",

    "cp .env.example .env"

]

[setup.macos]

commands = ["brew install ffmpeg"]

[setup.linux]

commands = ["apt-get install -y ffmpeg"]

[actions]

# Shortcut buttons displayed in the App's top bar

run = "npm start"

test = "npm test"

lint = "npm run lint"

[actions.deploy]

command = "npm run deploy"

icon = "rocket"

You can commit this file to Git so the entire team shares the same configuration.

4.5 Model Selection and Reasoning Effort

# Specify a model in the CLI

codex --model gpt-5.5 "Complex architecture design"

# Adjust reasoning effort

codex --config model_reasoning_effort=low "Simple CSS change"

codex --config model_reasoning_effort=high "Design a microservices decomposition plan"

# Switch models within interactive mode

/model gpt-5.5

Model Selection Guide:

• GPT-5.5: The latest flagship with strong reasoning and execution capabilities. Ideal for complex engineering, long-context tasks, and multi-stage projects.
• GPT-5.4-mini: Lightweight and fast. Best for simple edits and rapid iteration.
• GPT-5.3-codex: Specialized for coding. Still holds an edge for pure programming tasks.

5. Deep Dive: IDE Extension Usage

5.1 Key Shortcuts and Slash Commands

In your IDE, the following shortcuts can significantly boost your productivity:

• Cmd+Shift+C: Open the Codex panel
• Cmd+Shift+Enter: Code completion
• Cmd+Shift+R: Rewrite selected code
• Cmd+Shift+E: Explain selected code

Commonly used slash commands:

/explain    Explain the selected code

/fix        Fix issues in the selected code

/test       Generate tests for the selected code

/review     Review the selected code

/plan       Plan before executing (recommended for complex tasks)

5.2 Automatic Context Mechanism

The IDE extension automatically passes the following context to Codex: the list of currently open files, the selected text range in the editor, and the current working directory information. The more code you select, the more accurate Codex's responses will be.

5.3 IDE and Desktop App Synergy

When both are open on the same project: Auto Context syncs automatically, thread states are visible in both directions, and file changes are reflected in real time. This is a remarkably powerful combination — use the desktop app for complex tasks and the IDE for fine-tuned adjustments.

6. Automation and Skills

6.1 Desktop App Automations

Turn repetitive work into automated tasks for unattended execution:

• Automated Code Review: Automatically run /review after every commit
• Documentation Updates: Monitor code changes and automatically update API docs
• Test Gap Filling: Periodically scan low-coverage modules and automatically add tests
• Scheduled Checks: Run daily dependency security vulnerability scans

On the security front, automations use the strictest approval policy by default. It's recommended to pair them with sandbox mode.

6.2 Agent Skills: Packaging Reusable Capabilities

Skills are the key to engineering-grade Codex adoption. They allow you to encapsulate frequently used operations into reusable, shareable units:

• When to Create a Skill: Whenever you find yourself reusing the same prompt, it's time to package it as a Skill.
• Where to Store Them: Place them in the project's .codex/skills/ directory, or publish them to the community for broader sharing.
• Recommended Resources: openai/skills (official), agentskills/agentskills (community), agentskills.io (community marketplace).

7. Best Practices Summary

Based on the experience of OpenAI's internal engineers, here are the key principles:

1. Write Requirements Like You'd Write an Issue

Don't tell Codex "fix that function for me." Instead, spell it out clearly: what's the background, which files are involved, what's the goal, and what constraints exist. The richer the context, the more precise the output.

2. Plan First for Complex Tasks

Use the /plan command or Worktree mode to let Codex formulate a plan before executing. Avoid the illusion of "getting it right in one shot" — for genuinely complex tasks, a step-by-step approach is far more controllable.

3. Leverage "Best of N"

Have Codex generate multiple approaches at once, then evaluate them as you would during a code review — picking the best one or combining the strengths of several.

4. Protect Your Flow State

When you spot a minor issue while deep in coding, don't immediately switch context. Delegate it as a task to Codex and review the PR later when you have bandwidth. This is one of the workflows most championed by OpenAI's internal engineers.

5. Establish Team-Level Configuration

Commit AGENTS.md, .codex/local-env.toml, and .codex/config.toml to your Git repository so the entire team shares a consistent set of AI collaboration standards.

6. Choose the Right Work Mode for the Job

Use the IDE extension for quick queries, Worktree mode for complex refactoring, Cloud mode for long-running delegated tasks, and non-interactive CLI mode for automation scenarios.

8. Conclusion and Forward-Looking Thoughts

Codex represents a paradigm shift in developer tools — from "assistance" to "collaboration." Its three-layer native architecture (Model Layer + Framework Layer + Interface Layer) means AI is no longer a bolted-on plugin but a "virtual team member" deeply integrated into the development workflow.

Recommended Learning Path:

1. Start with the CLI to understand basic interactions and slash commands
2. Configure AGENTS.md so Codex understands your project
3. Try Worktree mode to experience the power of parallel development
4. Explore the Skills ecosystem to build a reusable capability library
5. Introduce Automations to streamline your workflows

Food for Thought: Coding agents are converging toward general-purpose agents. When AI can reliably execute complex engineering tasks spanning 7+ hours, the developer's role will shift from "the person who writes code" to "the person who designs systems, defines constraints, and reviews outcomes." This isn't a threat — it's the true liberation of developer productivity.

Mastering Codex isn't just about learning a tool — it's about building a new mental model for engineering collaboration in the AI era. Start building with it today.