A AI Agents Guide
← All guides
OpenAI · PRACTICAL GUIDE

OpenAI Codex

A coding agent available through the CLI, desktop app, IDE extension, and web. Codex can inspect repositories, edit files, run commands, and work within approval and sandbox controls.

Before you start
Use a trusted project, back up your work, and review changes and commands before accepting them.

What it is and what it does

Codex is an AI coding agent that can work from your terminal, desktop app, IDE, or web. It can inspect repositories, edit files, run development commands, and use configured tools. Treat it as a collaborator that needs context and supervision; verify changes before relying on them.

Install

Use the official installer for your platform, or install the CLI with npm.

Windows

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Official CLI installer. npm is also supported: npm install -g @openai/codex

macOS

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Official CLI installer. Homebrew is also supported: brew install --cask codex

Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Official CLI installer. npm is also supported: npm install -g @openai/codex

Official source: OpenAI Codex repository ↗

First time setup

  1. Run codex in your terminal.
  2. Select Sign in with ChatGPT if you have an eligible ChatGPT plan, or configure API key access if you are using the API path.
  3. Review approval and sandbox settings before allowing changes.
  4. Add AGENTS.md when the project needs persistent instructions.
Access: ChatGPT sign in is supported with Plus, Pro, Business, Edu, and Enterprise plans. API key access is also available with separate API usage and setup.

Run in a project folder

  1. Change into the repository root.
  2. Check git status.
  3. Run codex and start with a read only project overview.
Good first task: Ask for a read only project overview before requesting edits.

Copy ready prompts

Replace bracketed details with your goal, constraints, or error message.

01 · Explore

Explain this repo and how to run it. Do not edit.

02 · Debug

Investigate [bug], explain its cause, then fix minimally.

03 · Build

Implement [feature] using the existing architecture. Ask before adding dependencies.

04 · Review

Review my diff for bugs and security issues. Do not edit.

05 · Test

Add tests for [behavior] and run focused tests.

06 · Refine

Refactor [module] for [goal], preserving behavior.

07 · Diagnose

Diagnose [command/error] and fix its root cause.

08 · Document

Update docs for [feature] using verified behavior.

Common errors and fixes

codex not found

Restart the terminal and check that the installed CLI directory is on PATH.

Sign in fails

Run codex again and complete browser authentication, or check the selected API configuration.

Action blocked

Review the current approval and sandbox settings, then allow only the action you understand.

Codex will not start

If your config uses the old approval_policy = "untrusted" setting, remove it. Current Codex versions no longer support that policy.

Tips for best results

  • Commit first.
  • Request a plan.
  • Define success criteria.
  • Inspect diffs.
  • Run the relevant checks.
Review loop: Describe task → inspect plan → review diff → run checks → focused follow up.
Last verified: October 8, 2026. Features and installation methods change over time. Refer to the official source for current support.