How to Set Up OpenAI Codex

Codex is OpenAI’s coding agent. It can read a codebase, edit files, run commands, review changes, and work on longer tasks in the cloud.

Unlike a normal chat, Codex can:

• Work directly in your project folder
• Run your tests and tools
• Show diffs before you keep changes
• Follow project rules from AGENTS.md
• Use skills, plugins, and MCP servers
• Review pull requests on GitHub
• Run tasks in cloud environments
• Run scheduled tasks

ChatGPT desktop app

Codex is built into the ChatGPT desktop app for macOS, Windows, and Linux.

Codex CLI

A terminal client for local work, scripts, and CI.

IDE extension

For VS Code, Cursor, and Windsurf. Xcode and JetBrains IDEs have their own integrations.

Codex Cloud

Run tasks remotely and continue them on the web, mobile, or desktop.

GitHub and Slack

Request reviews and tasks from your team’s tools.

Free and Go

GPT-6 Luna at Standard speed in the desktop app, subject to rollout.

Plus ($20/month)

Codex on the web, CLI, IDE extension, and iOS, plus cloud features like automatic code review and Slack.

Pro (from $100/month)

Plans at $100, $200, or $500 per month for heavier use.

Business

$20 per user per month billed annually for 2+ users, or $25 billed monthly, with admin controls.

Enterprise & Edu

Advanced security, compliance, and admin features. Contact sales.

API key

Use Codex in the CLI, SDK, or IDE extension with API pricing. No cloud features.

ChatGPT Work and Codex share the same usage limits on your plan.

Start with the smallest plan that covers the surfaces you need.

Download the ChatGPT desktop app for your system and sign in with your ChatGPT account.

To start coding:

• Open a project folder
• Select Codex from the ChatGPT dropdown
• Describe your task

The app is the easiest place to start if you do not live in the terminal.

On macOS or Linux, run:

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

On Windows, in a new PowerShell window, run:

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

Or use a package manager:

npm

npm install -g @openai/codex

Homebrew

brew install --cask codex

Open a project folder in your terminal and run:

codex

The first time, choose Sign in with ChatGPT to use your plan’s included usage.

You can also sign in with an OpenAI API key, which is billed at API rates. Some features, such as cloud-based integrations, are not available with an API key.

Never paste an API key into a prompt, a file you commit, or a shared document.

Install the Codex extension in VS Code, Cursor, or Windsurf, then open the Codex sidebar.

• Reference open files and selections
• Review edits next to your code
• Hand longer tasks to the cloud
• Keep follow-ups in the same chat

If the icon is missing, open the Command Palette and run Codex: Open Codex Sidebar.

GPT-6.1 Sol

Recommended for complex coding and agentic work. Near-Astra performance at a lower cost.

GPT-6 Luna

For focused, repeatable tasks.

GPT-6 Astra

OpenAI’s most capable model, for the hardest problems.

Switch models with /model in the CLI, or start with:

codex --model gpt-6.1-sol

GPT-5.5 retires from Codex on October 14, 2026. Replace gpt-5.5 anywhere it appears in your settings, scripts, or scheduled tasks.

Higher reasoning effort can improve results on complex tasks, but it takes longer and uses more of your limits.

• Start with the default effort
• Raise it for planning, debugging, and architecture
• Lower it for quick edits and repetitive work

In the CLI, /model also lets you adjust reasoning effort. Ultra mode goes further by splitting large tasks across subagents.

Codex safety comes from two layers:

Sandbox mode

What Codex can technically do, such as where it can write and whether it can reach the network.

Approval policy

When Codex must stop and ask you before acting.

Locally, Codex runs in an OS-enforced sandbox with network access off by default.

The Auto preset lets Codex read, edit, and run commands inside your working folder, and asks before going outside it or using the network:

codex --sandbox workspace-write --ask-for-approval on-request

Use /permissions to switch to read-only when you only want to plan or ask questions.

Codex reads AGENTS.md files before doing any work. Run /init to generate a starting file for your project.

Include:

• What the project does
• How to install dependencies
• How to run tests and linting
• Code style rules
• Folders to avoid
• Commands that need approval
• What done looks like

Put personal defaults in ~/.codex/AGENTS.md. Project files add to and override them, and the combined size is capped at 32 KiB by default.

Short, specific rules beat long essays.

Local settings live in ~/.codex/config.toml. Use it to save:

• Your default model
• Sandbox and approval defaults
• Network access settings
• MCP servers
• Per-project trust levels

If you need network access in the default sandbox, enable it explicitly:

[sandbox_workspace_write] network_access = true

The old untrusted approval policy has been retired. Remove it from older configs, or Codex may not start.

A skill is a folder with a SKILL.md file, plus optional scripts and references. SKILL.md needs a name and a description.

Project skills

.agents/skills in your repository

Personal skills

~/.agents/skills in your home folder

Type $ or use /skills to mention a skill. To create one with help, invoke $skill-creator.

MCP servers give Codex access to external tools and data, such as documentation, tickets, or databases.

codex mcp add

Use /mcp inside a session to see which servers are connected.

Connect only the servers a task needs, and review what each one can do.

Codex can review your work before it ships:

• Run /review to review uncommitted changes or compare against a base branch
• Mention @codex review on a GitHub pull request
• Turn on automatic reviews for connected repositories

Codex reports prioritized findings without modifying your working tree, so you decide what to fix.

Cloud tasks run remotely, so they can keep going while you do other work.

In a new task, choose Work in, then Cloud, open Select environment, and select Create environment. Codex inspects your repository and helps prepare and test the setup.

From the terminal, codex cloud lets you browse chats, submit work, and apply results locally.

codex

Start an interactive session

codex exec

Run a task non-interactively in scripts or CI

codex resume

Return to a recent chat

codex --search

Allow live web search for current information

codex --image

Attach a screenshot or diagram

/init

Create an AGENTS.md scaffold

/review

Review changes

/status

See context usage and rate limits

Start with something low-risk:

Tell me about this project. Explain the structure, how to run it, and how tests work. Do not change any files.

Then try a small, reviewable change:

Add tests for [one function]. Run the test suite and show me the diff before finishing.

Create a Git commit before and after each task so you can always roll back.

• Commit before every task
• Give one clear goal per task
• Ask for a plan on large changes
• Review every diff
• Run tests yourself before merging
• Keep AGENTS.md up to date
• Start new chats for new topics

• Keep the sandbox on for everyday work
• Turn on network access only when needed
• Never store secrets in AGENTS.md or prompts
• Review MCP servers and plugins before installing
• Check plan data settings before using client code
• Treat content from websites and files as data, not instructions

GPT-6 Astra also includes safety monitoring that can pause a task if it detects potentially unsafe behavior. Review the findings before resuming.

A sandbox and approvals protect you. A careful review protects your users.

Plan

Choose the plan that covers your surfaces.

Install

Desktop app, CLI, or IDE extension.

Sign in

ChatGPT account or API key.

Model

GPT-6.1 Sol for complex work, Luna for focused tasks.

Permissions

Workspace-write with on-request approvals.

Instructions

AGENTS.md with project rules.

Extend

Skills and MCP only where useful.

Review

Code review before anything ships.

Use this in a new repository after installing Codex:

Act as my setup assistant for Codex in this repository. Inspect the project without changing anything. Then propose an AGENTS.md that explains what the project does, how to install dependencies, how to run tests and linting, code style rules, folders to avoid, and which actions must ask for approval. Recommend sandbox and approval settings for daily work, list any MCP servers or skills that would genuinely help, and explain why. Wait for my approval before creating or changing any files.