Skip to main content
AI Choice Engine
← 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 October 2, 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, native Windows, Linux or WSL2 for the CLI. WSL1 is unsupported from v0.115.0.
  • Node.js if installing through npm, or use the official standalone installer.
  • Install bubblewrap (bwrap) on Linux/WSL2 for reliable sandboxing. A bundled fallback depends on unprivileged user namespaces; native Windows has a separate sandbox.

Authentication

codex login (ChatGPT) or API key via stdin

Account: A supported ChatGPT plan (availability varies, including Free/Go desktop access) or an OpenAI API key for local work

Check codex login status before changing authentication. ChatGPT plan access: codex login. API billing: printenv OPENAI_API_KEY | codex login --with-api-key. API keys support local desktop/CLI/IDE work; GitHub review, Slack and other cloud features require ChatGPT sign-in. Keep API credentials out of prompts and repository files.

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)

    Use a supported Node.js installation and the official scoped @openai/codex package; consult its current package requirements. The standalone installer does not need Node. The unscoped npm package codex is unrelated.

    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
  11. 11

    Other surfaces (desktop, IDE and cloud)

    This walkthrough uses CLI. Codex also supports its desktop app, cloud, VS Code/Cursor/Windsurf, JetBrains and Xcode surfaces, with account/client-dependent capabilities. Start from OpenAI’s current IDE docs at https://developers.openai.com/codex/ide.

    Codex IDE

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` permits repository writes within its scope; approval mode does not make those writes read-only or guarantee a prompt for each edit. Start with `--sandbox read-only`. After reviewing the plan, end that session and deliberately start a workspace-write session for an approved narrow patch.

    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. 03For this read-only session, inspect the plan without editing. End it before starting a separate workspace-write session for an approved test-file change; verify the result in an environment allowed by the project.

Why this is safe: The first session uses a read-only sandbox. A separate deliberate sandbox change makes the later write boundary explicit while the proposed task stays small.

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

The sign-in method determines policy. ChatGPT-authenticated Codex follows the workspace’s data controls, permissions and applicable retention/residency settings. API-key sessions follow the API organisation’s settings. Local execution still sends selected context for inference: https://learn.chatgpt.com/docs/auth.

Training on code: tier dependent

Verify the selected workspace or API organisation’s terms and any model-specific restrictions before private code is sent. A local sandbox limits tool execution; it does not make cloud inference offline.

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 use Codex credits at rates separate from API prices. Plus is $20/month; Pro tiers $100/$200/$500; Business Standard $25/user monthly or $20 with annual billing. GPT-6.1 Sol is rolling out on eligible paid plans, with Enterprise/Edu admin enablement; Free/Go desktop Luna access is rollout-dependent. API-key login bills Platform usage separately and excludes cloud features such as GitHub review.

Model: hybrid

Watch out: A task can consume many credits. Fast bills at 2.5x included subscription credits or 2x purchased/pay-as-you-go credits; Astra Ultrafast at 8x or 6x respectively, with separate plan eligibility. These are billing multipliers, not speed ratios. Pro has no five-hour limit; Plus/Business message estimates are not fixed caps and weekly/shared usage may still apply. GPT-5.4/mini retired from ChatGPT-authenticated Codex on August 31; GPT-5.5 retires on 2026-10-14, while API availability is unaffected. Choose a supported gpt-6-sol or Luna-family replacement available to your account: https://learn.chatgpt.com/docs/pricing.

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 October 2, 2026; use the official source below before installing in a managed or production environment.

Codex CLIRead the launch guideCompare all harnesses