OpenAI Codex CLI and Cloud Agent: A Practical Guide

OpenAI Codex is no longer one product but a family: a terminal agent, an editor extension and a cloud agent inside ChatGPT, all sharing the same account and similar conventions. This guide walks through a practical setup, from first install to scripted and cloud workflows, as of November 2026. Commands and options evolve quickly; the authoritative reference is OpenAI's developer documentation at developers.openai.com.

The three ways to run Codex

Tasks can move between surfaces – for example, start in the cloud and pull the result into a local session to finish – but the workflow details depend on the current release.

Setting up the CLI in six steps

Step 1: Install and sign in

1. Install the CLI with npm (npm install -g @openai/codex) or Homebrew on macOS.
2. Run codex inside a project directory.
3. Sign in with your ChatGPT account, which uses your plan's included usage, or configure an API key for usage-based billing. API keys are often the better choice for CI and automation.
4. Confirm that the project is a Git repository. Version control is your undo button when an agent makes changes you do not want.

Step 2: Choose approval and sandbox settings

The CLI separates two questions: what the agent is technically able to do (sandbox) and when it must ask you (approvals). Presets range roughly from read-only, through a default that lets Codex edit files and run commands inside the working directory while asking before anything beyond it such as network access, to full access without prompts.

• Read-only for exploring an unfamiliar codebase or planning.
• Default workspace access for everyday feature work and bug fixes.
• Full access only inside disposable environments such as containers or CI runners, never on a laptop holding production credentials.

You can switch settings during a session and set defaults in the configuration file, ~/.codex/config.toml.

Step 3: Give it project context with AGENTS.md

Codex reads AGENTS.md files: a global one in your Codex home directory for personal preferences, one at the repository root, and nested ones in subdirectories for local rules. Include build and test commands, a short repository map, conventions and boundaries. The format and how to share it with other agents are explained in AGENTS.md and CLAUDE.md explained.

Step 4: Work in effective loops

1. Ask for a plan first on anything beyond a small fix, and correct it before edits start.
2. Give verifiable goals: “Make pnpm test billing pass and add a test for refunds over the original amount.”
3. Attach evidence: stack traces, failing test names or screenshots help more than descriptions.
4. Review the diff before committing; ask Codex to explain any change you do not understand.
5. Commit in small steps so you can roll back a bad turn without losing good work.

Step 5: Connect tools via MCP

Codex supports the Model Context Protocol. MCP servers are configured in config.toml and give the agent access to things like documentation, issue trackers or databases. Add only servers you trust, with minimal scopes; anything a server returns can influence the agent's actions. Background: MCP explained for product teams.

Step 6: Script it with codex exec

codex exec runs a task non-interactively and prints the result, which makes Codex usable in scripts and CI pipelines. Typical uses:

• Generating release notes from merged pull requests.
• Fixing lint errors on a scheduled branch.
• Producing a first-pass review summary for large pull requests.

Run it in an isolated runner, use an API key with a spending limit, and keep a human approval step before anything merges.

Delegating work to Codex cloud

1. Connect your GitHub account in ChatGPT's Codex settings and choose repositories.
2. Configure an environment: setup script, dependencies, environment variables. If tests cannot run in the container, Codex cannot verify its own work.
3. Submit tasks, ideally several small independent ones in parallel.
4. Review each result's diff and logs, request changes, then open a pull request.

Cloud tasks suit well-specified backlog items. Exploratory or architecture-heavy work usually goes better interactively.

Team conventions worth agreeing on

• Which sandbox and approval preset is the default on developer machines.
• Which repositories may be connected to Codex cloud, and who approves new ones.
• Which MCP servers are approved for shared use.
• That every Codex-generated pull request is labeled and reviewed like any other change.
• Who maintains the root AGENTS.md and how changes to it are reviewed.

Troubleshooting checklist

• Agent uses wrong commands: fix or add them in AGENTS.md.
• Cloud tasks fail on setup: reproduce the setup script in a clean container locally.
• Repeated loops on one error: stop, narrow the task, restart with the key finding stated up front.
• Usage limits hit early: trim long instruction files, avoid pasting huge logs, move automation to API billing.

For mobile projects built with Codex, the release side has its own hurdles, covered in from ChatGPT Codex to the App Store. Comparing Codex with alternatives? See Claude Code vs. OpenAI Codex. And if your team wants guided practice, the Codex workshop format from neooutput works through these steps on your own repositories.