How to Use OpenAI Codex on Mac: Complete Setup Guide 2026

February 8, 2026 · 7 min read

OpenAI Codex is a powerful AI coding agent that runs directly in your terminal. Instead of switching between a chat window and your editor, you describe what you want in plain English and Codex writes the code, edits files, and runs commands right where you work. Whether you are building a new feature, debugging a tricky issue, or scaffolding an entire project, Codex brings the full power of OpenAI's models to your command line.

This guide walks you through everything you need to install, configure, and start using OpenAI Codex on your Mac -- from the initial npm install to advanced workflow tips. If you want to skip the manual setup entirely, we will also show you how Beam can launch Codex in one click with zero configuration.

What is OpenAI Codex?

OpenAI Codex is OpenAI's official command-line coding assistant. It is a CLI tool that connects to OpenAI's latest models -- including GPT-5.3-Codex and GPT-5.2-Codex -- and translates natural language instructions into real code changes. You type a request like "add input validation to the signup form" or "refactor this function to use async/await," and Codex reads your project files, generates the code, and applies the changes directly.

What sets Codex apart from browser-based AI tools is that it operates inside your terminal, right next to your existing workflow. It can read your project structure, understand your codebase context, and execute shell commands to test its own output. There is no copy-pasting between a chat window and your editor. Codex works with the files on your disk, runs your test suite, and iterates until things pass.

Codex also supports multiple autonomy levels. You can run it in suggest mode where it proposes changes for your approval, auto-edit mode where it writes files but asks before running commands, or full-auto mode where it handles everything end-to-end inside a sandbox. This makes it suitable for everything from careful refactoring to rapid prototyping.

Prerequisites

Before installing Codex, make sure you have the following ready on your Mac:

To check your Node.js version, open a terminal and run:

node --version

If you see v18.0.0 or higher, you are ready. If Node.js is not installed or you have an older version, the easiest way to install it on Mac is with Homebrew:

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

Step 1: Install Codex

With Node.js ready, installing Codex is a single command. Open your terminal and run:

npm install -g @openai/codex

This installs the codex command globally on your system so you can run it from any directory. The installation typically takes under a minute. Once complete, verify it worked:

codex --version

You should see a version number printed to the terminal, confirming that Codex is installed and available on your PATH.

Step 2: Configure Your API Key

Codex needs your OpenAI API key to communicate with OpenAI's models. If you do not have an API key yet, go to platform.openai.com/api-keys and create one. Make sure your account has billing enabled and some credits loaded.

The simplest way to configure your key is to add it as an environment variable in your shell profile. Since macOS uses zsh by default, open your ~/.zshrc file and add this line:

# Add to ~/.zshrc
export OPENAI_API_KEY="sk-your-api-key-here"

Then reload your shell configuration:

source ~/.zshrc

You can verify the key is set correctly by running:

echo $OPENAI_API_KEY

Step 3: Launch Codex

Navigate to your project directory and start Codex:

cd ~/Projects/my-app
codex

Codex starts an interactive session in your terminal. You will see a prompt where you can type natural language instructions. Codex reads your project files to understand the codebase context, then generates and applies changes based on your requests.

Here are some example prompts to try in your first session:

When you pass a prompt directly as an argument, Codex runs in a one-shot mode -- it processes your request and exits. If you run codex without a prompt, it opens an interactive session where you can have a back-and-forth conversation, similar to a chat interface but right inside your terminal.

Codex defaults to GPT-5.3-Codex, OpenAI's most capable agentic coding model. You can specify a different model when launching:

# Use GPT-5.3-Codex (default, most capable)
codex --model gpt-5.3-codex

# Use GPT-5.1-Codex-Mini for quick, lightweight tasks
codex --model gpt-5.1-codex-mini

The Easy Way: Use Beam

If the command-line setup feels like too many steps, Beam makes it dramatically simpler. Beam is a terminal organizer for macOS that includes one-click AI agent launching -- including OpenAI Codex.

Here is how it works:

1Download Beam from getbeam.dev and open it.

2Right-click inside any terminal window to open the context menu.

3Select Start AI Agent → OpenAI Codex.

That is it. Beam checks if Codex is installed on your system. If it is not, Beam automatically installs it for you via npm, then launches it in the current terminal. No manual npm commands, no editing shell config files, no troubleshooting PATH issues.

This is especially valuable for developers who are new to terminal-based AI tools. Instead of reading through documentation and debugging environment issues, you get a working Codex session in seconds. Beam handles the plumbing so you can focus on the coding.

Organizing Codex Sessions with Beam

Once you start using Codex regularly, you will quickly find yourself running multiple sessions across different projects. One Codex instance for the backend, another for the frontend, maybe a third for writing tests. Without organization, your terminal becomes a mess of unnamed tabs with no way to find anything.

Beam solves this with workspaces -- separate, named terminal windows that group related terminals together. Each workspace can contain multiple tabs and split panes, giving you a complete workspace for each project.

Setting Up a Codex Workspace

Here is a practical setup for full-stack development with Codex:

With this layout, you can jump between your backend Codex session and your frontend Codex session instantly using ⌘1 and ⌘2. No hunting through a dozen unnamed tabs.

Save and Restore Your Layout

Once you have your workspaces and tabs arranged, press ⌘S to save the layout. Give it a name like "Codex Full Stack." Tomorrow, when you sit down to work, press ⌘⇧L and select your saved layout. Everything is restored exactly as you left it.

Use the Full Stack Dev Template

Beam includes built-in workspace templates that set up common layouts automatically. The Full Stack Dev template creates workspaces for frontend, backend, and infrastructure -- each pre-configured with useful tabs. Press ⌘⇧N to open the template picker, or use the Quick Switcher (⌘P) and search for "Full Stack."

Templates can even auto-run commands when they load. You could create a custom template that launches Codex in one pane and starts your dev server in another, giving you a complete AI-assisted development environment with a single keyboard shortcut.

Tips for Getting the Most Out of Codex

Codex is a powerful tool, but like any AI assistant, the quality of your output depends heavily on how you use it. Here are practical tips to get the best results.

Be Specific with Your Prompts

Vague prompts produce vague results. Instead of "fix the bug," tell Codex exactly what is happening: "the /api/users endpoint returns a 500 error when the email field is missing -- add input validation that returns a 400 with a descriptive error message." The more context you provide, the better Codex can target its changes.

Keep Your Context Focused

Codex reads your project directory to understand context. If you are working on a monorepo, navigate into the specific package or module you want Codex to focus on rather than running it from the repo root. A smaller, more focused context leads to faster and more accurate responses.

# Instead of this:
cd ~/Projects/monorepo
codex "fix the auth bug"

# Do this:
cd ~/Projects/monorepo/packages/auth-service
codex "fix the email validation in signup handler"

Use Different Models for Different Tasks

Not every task needs the most powerful model. Use GPT-5.1-Codex-Mini for quick edits, explanations, and straightforward code generation. Switch to GPT-5.3-Codex for complex refactoring, architectural decisions, or when you need Codex to reason across multiple files. You can change models mid-session with the /model command.

# Switch models during an interactive session
/model gpt-5.3-codex

Choose the Right Autonomy Level

Codex supports three modes that control how much it does without asking:

• Suggest -- Codex proposes changes but does not apply them until you approve. Best for learning what Codex can do and for sensitive codebases.
• Auto-edit -- Codex writes and edits files automatically but asks before running shell commands. A good balance for daily use.
• Full-auto -- Codex handles everything, including running commands, in a sandboxed environment. Best for rapid prototyping and greenfield projects.

Start with suggest mode until you are comfortable, then graduate to auto-edit for productivity.

Combine Codex with Split Panes

In Beam, use split panes (⌘D for vertical, ⌘⇧D for horizontal) to run Codex on one side and your dev server or test runner on the other. This way you can watch Codex make changes and immediately see the results without switching tabs.

Conclusion

OpenAI Codex brings the intelligence of GPT models directly into your terminal workflow. It reads your codebase, understands natural language instructions, and applies changes right where you work -- no copy-pasting, no context switching. Combined with Beam, you get a complete AI-powered development environment: organized workspaces for each project, one-click Codex launching, saved layouts you can restore in seconds, and keyboard shortcuts that keep you in flow.

The setup is straightforward: install Node.js, install Codex via npm, set your API key, and start coding. Or skip all of that and let Beam handle the installation with a single right-click. Either way, you will be writing code with AI assistance in minutes.