Skip to main content
AI Choice EngineAI Choice Engine
Browse decision tools
← All setup guides

OpenAI · Setup guide

How to set up OpenAI Codex

Install Codex CLI, authenticate with the account or API path your team uses, and start inside a sandboxed repository task with approval boundaries visible.

OpenAI Codex

terminal · checked August 14, 2026

~10 minBeginner
Start installOpen OpenAI CodexCompare itBuyer guide

The “Open OpenAI Codex” link goes to the vendor site. It is not an affiliate-tracked link on this page — no commission is claimed for that click. Affiliate disclosure.

Critical: finish install before closing the window

Keep the installer terminal open until you see a success message. If you used an admin window, do not close it until verification works. Then open a new Terminal or PowerShell window and run the verify step — PATH updates rarely apply to shells that were already open, especially on Windows.

Before you begin

  • macOS, Windows, Linux, or WSL for the supported CLI path.
  • Node.js if installing through npm, or use the official standalone installer.
  • Bubblewrap (`bwrap`) on Linux or WSL2 for the documented sandbox path — install it before the first sandboxed run.

Authentication

codex login (ChatGPT) or API key via stdin

Account: ChatGPT Plus/Pro/Business/Edu/Enterprise, or OpenAI API key

Interactive + plan limits: codex login. API spend/CI: printenv OPENAI_API_KEY | codex login --with-api-key. Codex cloud features require ChatGPT sign-in — API keys do not unlock them.

Install or open it

1. Get the harness ready

These steps are written for beginners. On Mac, Terminal is the black/white text window where you type commands. On Windows, use PowerShell or Terminal. Use the OS tabs to hide steps that are not for your computer, then copy one command at a time.

  1. 01

    Open Terminal on a Mac

    Mac

    Click the Spotlight search icon (magnifying glass) at the top-right of the menu bar, or press Command (⌘) + Space. Type Terminal and press Return. A text window opens — that is where you paste the install commands below. Leave it open.

  2. 02

    Open Terminal or PowerShell on Windows

    Windows

    Press the Windows key, type Terminal or PowerShell, then press Enter. Use that window for the commands below. If Windows asks for permission to run a script or install software, read the prompt before approving.

  3. 03

    How to paste a command

    Copy one command at a time from this page. Click inside the terminal window, paste (Mac: ⌘+V, Windows: Ctrl+V or right-click → Paste), then press Return / Enter. Wait until the prompt comes back before running the next command. You do not need to type the leading $ if you see one in other docs.

  4. 04

    Do not close the installer until verified

    Keep the installer terminal (or admin PowerShell) open until the install finishes without errors. Closing early can leave a half-written binary or an incomplete PATH update — especially on Windows.

  5. 05

    Open a new terminal after installers

    PATH updates often only apply to new shells — especially on Windows. Do not close the install session until the installer finishes, then open a fresh Terminal/PowerShell before running --version checks.

  6. 06

    Inspect before you pipe an installer

    Commands like curl … | bash download and run a script immediately. Prefer the official package manager when offered. If you use a curl installer, you can download the script first, open it in a text editor, then run it — never paste installers from random blogs.

  7. 07

    Install without Node (Mac / Linux)

    Official primary path — no Node required. Prefer this over random npm package names. Do not install the unrelated npm package named simply “codex”.

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

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    Codex CLI
  8. 08

    Install on Windows (PowerShell)

    Windows

    Official Windows installer. Open a new terminal after it finishes.

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

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    Codex CLI
  9. 09

    Alternative: npm (@openai/codex only)

    If you already use Node 16+, install the official scoped package. Never use npm install -g codex (that is a different 2012 project).

    bash
    npm install -g @openai/codex

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    Codex CLI
  10. 10

    Verify the binary

    Confirm the command is available before starting a repository session. Open a new terminal if it says “command not found”.

    bash
    codex --version

    You should see: A version string. If missing, open a new terminal or re-run the official installer (not the unrelated npm package named “codex”).

    If this fails
    • The command is not found after npm installation. Check the global npm bin directory and PATH, then reopen the terminal or use the standalone installer.
    Codex CLI reference

Repository or project

2. Start in the right place

Keep the first repository small, clean, and easy to roll back while you learn the harness’s permissions and context model.

  1. 01

    Prepare a branch

    Start in a clean branch and ensure the repository’s tests can run without production credentials.

    bash
    git status --short

    You should see: The prompt shows you are inside the intended folder (check with `pwd`).

    If this fails
    • “No such file or directory” or you are still in your home folder. Create or clone the practice folder first, then `cd` into it before starting the tool.
  2. 02

    Start read-only, then widen the sandbox

    `workspace-write` can edit files in the repo. `on-request` still allows those writes after a prompt — it is not a read-only mode. First session: `--sandbox read-only`. Switch to workspace-write only after you have seen the approval prompts.

    bash
    codex --sandbox read-only --ask-for-approval on-request

    You should see: The tool starts in this folder and waits for your first prompt (or shows a short first-run / sign-in screen).

    If this fails
    • Nothing happens, or you land in the wrong folder. Confirm you are inside the practice repo (`pwd`), that you signed in, and that you opened a new terminal after install.
    Codex developer commands

First run

Review before allowing a patch

Use this task to test the workflow before handing over a larger repository or production responsibility.

  1. 01Ask Codex to explain the repository and identify the test command.
  2. 02Ask for a plan to update one small unit test.
  3. 03Approve only the test-file edit, run the test, and inspect the diff.

Why this is safe: The sandbox and approval mode make the first write boundary visible while the task stays small and testable.

Stop and review if

  • The agent requests network, destructive shell, or production access for a local test.
  • The sandbox warning indicates the expected isolation is unavailable.
  • The proposed diff changes unrelated files or dependencies.

The operating boundary

Privacy, data, and cost

The setup is incomplete until you know what the harness can see, what account pays for it, and who approves a risky action.

Privacy

ChatGPT consumer plans and API organisation settings differ on training and retention. Codex cloud and local CLI share account policy — confirm OpenAI data controls before private repos.

Training on code: tier dependent

Confirm the current account, API, and organisation terms before using private code in cloud-connected workflows.

Sensitive repos: Use the narrowest sandbox and approval mode, keep secrets out of the working tree, and do not grant production credentials to the first session.

Pricing

ChatGPT plans include Codex with plan limits/credits; signing in with an API key bills Platform usage separately and skips cloud features.

Model: hybrid

Watch out: A single agentic task can consume many credits. Do not confuse ChatGPT subscription access with API-key billing. GPT-5.4 and GPT-5.4 mini retire from ChatGPT-authenticated Codex on 2026-08-31 (migrate those seats to GPT-5.6 Terra / Luna) — API-key Codex and the OpenAI Platform API are unaffected.

Estimate a seat stack

When setup goes wrong

  • The command is not found after npm installation.

    Check the global npm bin directory and PATH, then reopen the terminal or use the standalone installer.

  • You installed npm package “codex” and nothing works like OpenAI Codex.

    Uninstall that unrelated 2012 package and install the official scoped package or curl installer: npm uninstall -g codex && npm install -g @openai/codex (or use chatgpt.com/codex/install.sh).

  • Linux sandboxing is unavailable or `bwrap` is missing.

    Debian/Ubuntu: `sudo apt update && sudo apt install bubblewrap`. Fedora: `sudo dnf install bubblewrap`. Then `bwrap --version` and retry `codex --sandbox read-only`. Review Codex sandbox docs if AppArmor still blocks it.

  • The account is authenticated but usage is unavailable.

    Confirm whether the session is using ChatGPT/Codex access or an API key, then check that account’s plan and billing.

Next steps

After the first successful run

Keep the pilot small, then compare surfaces and budget before a team rollout.

Compare harnessesBuyer guideOpen-source agents hubAI stack cost calculatorGPU inference (rent)Local GPU sizingBuyer guidesLocal open-source AI guide

Setup details change quickly. The page was checked August 14, 2026; use the official source below before installing in a managed or production environment.

Codex CLIRead the launch guideCompare all harnesses