How to Install OpenAI Codex CLI on macOS: 2026 Guide

The most direct way to install OpenAI Codex CLI on macOS is the official standalone installer. Homebrew, npm, and signed release archives remain supported alternatives. Whichever path you choose, keep only one active installation, authenticate through the supported login flow, and use Codex permission profiles instead of giving an agent blanket access to your Mac.

curl -fsSL https://chatgpt.com/codex/install.sh | sh
command -v codex
codex --version
codex login
codex

Confirm macOS and processor architecture

OpenAI’s current source documentation lists macOS 12 or later and supports Apple silicon and Intel release builds. Confirm the machine before a managed rollout.

sw_vers
uname -m

# arm64 means Apple silicon
# x86_64 means Intel

Git is optional but recommended for repository-aware workflows. Start Codex from the repository it should work in so the current directory, Git state, AGENTS.md, and repository-scoped skills resolve correctly.

Choose one installation method

Standalone installer

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

Homebrew

brew install --cask codex
brew info --cask codex
command -v codex
codex --version

npm

node --version
npm install -g @openai/codex
command -v codex
codex --version

The npm package currently declares Node.js 16 or later, but teams should use a supported current Node release under their own lifecycle policy. Codex itself is maintained as a native Rust CLI; npm is a delivery mechanism.

Detect and remove conflicting installations

Multiple copies can produce a confusing state in which an update succeeds but the shell still starts another binary. Inspect every result and the symlink target before removing anything.

which -a codex
ls -l "$(command -v codex)"

brew list --cask codex 2>/dev/null || true
npm list -g @openai/codex --depth=0 2>/dev/null || true

Use the uninstall command for the install you intentionally replace. Do not delete ~/.codex during a package cleanup: it contains configuration, authentication state, logs, sessions, and skills.

Authenticate safely

For interactive work, run codex login and complete the ChatGPT browser flow. API-key authentication follows different billing and workspace controls and should be used only when that is the approved operating model.

codex login
codex login status

# API-key path without saving the key in a shell startup file
read -rsp "OpenAI API key: " OPENAI_API_KEY && echo
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

Do not place keys in .zshrc, .bashrc, a repository, a skill, or a prompt. For trusted automation, use a scoped secret store and expose the credential only to the exact step that needs it.

Understand the macOS sandbox and permissions

Codex uses macOS Seatbelt profiles through sandbox-exec. The sandbox and approval policy are separate controls: the sandbox defines what a command can reach, while approvals determine when Codex must ask. Use /permissions to select or inspect the active permission profile and /status to verify the session.

• Use a read-only profile for explanation, planning, or audit work.
• Use a workspace profile when the task requires edits inside the selected repository.
• Add network or external-directory access only for a concrete task and narrow destination.
• Keep protected paths, secrets, SSH material, browser profiles, and unrelated personal folders outside the accessible scope.

macOS may separately request access to protected folders such as Desktop, Downloads, or Music. That operating-system prompt is not evidence that Codex needs broad access. Decline it unless the current task requires the exact folder.

Set durable project guidance

Use AGENTS.md for repository conventions such as commands, boundaries, coding style, and validation. Use ~/.codex/config.toml for user-level client settings. Keep task-specific instructions in the prompt and reusable workflows in skills.

cd /path/to/repository
codex

# Inside Codex, inspect the active state:
/status
/permissions
/model

The current model catalog depends on the surface, account, workspace policy, and authentication method. Use /model rather than pinning a model name from an old guide. Higher reasoning settings can take longer and use more tokens; start with the default and increase only when the task benefits from deeper analysis.

Skills, plugins, and MCP on macOS

A skill packages a reusable workflow, a plugin distributes skills and optional connectors, and MCP connects Codex to live tools or data. These layers do not grant one another permissions automatically.

• Personal skills: $HOME/.agents/skills/<name>/SKILL.md
• Repository skills: .agents/skills/<name>/SKILL.md
• Durable client configuration: ~/.codex/config.toml
• Repository instructions: AGENTS.md

Install and authorize only the MCP servers needed for a real workflow. Treat remote output as untrusted, keep credentials out of committed configuration, and require confirmation for external writes.

Use Codex interactively and non-interactively

Run codex for an interactive terminal session. Use codex exec for bounded automation and make the expected output and permissions explicit.

# Interactive session
codex

# Read-only review example
codex exec --sandbox read-only "Review the current diff and report risks. Do not modify files."

# Built-in review workflow
codex review --uncommitted

Do not expose non-interactive Codex execution to untrusted public input. A prompt can request actions, but the surrounding script must still constrain credentials, filesystem access, network destinations, outputs, and failure handling.

Update, validate, and roll back

1. Record command -v codex and codex --version before an update.
2. Use the update mechanism matching the install source.
3. Run codex --version, codex login status, and codex doctor after the change.
4. Open a test repository under a read-only permission profile.
5. Verify shell execution, Git discovery, AGENTS.md, required skills, and approved MCP servers.
6. Keep the previous package or documented reinstall command until the pilot passes.

For related guidance from ITECS, see ITECS AI consulting.

Primary Sources

• OpenAI Codex repository and installation quickstart
• OpenAI Codex system requirements and release installation
• OpenAI: Codex authentication
• OpenAI: Codex permission profiles
• OpenAI: agent approvals and security
• OpenAI: Codex CLI command reference

Editorial review: Installation, authentication, command, sandbox, and skill claims were checked against the current Codex manual and official OpenAI repository on August 15, 2026. Recheck system requirements, installer behavior, permission profiles, and commands before fleet deployment.