Mastering OpenAI Codex: A Step-by-Step Setup and Usage Guide

What You Need

Before diving into Codex, ensure you have the following prerequisites in place:

Mastering OpenAI Codex: A Step-by-Step Setup and Usage Guide — Source: www.freecodecamp.org

An OpenAI account with access to a paid ChatGPT plan (Plus, Pro, Business, or Enterprise/Edu). Free and Go plans work but have stricter rate limits.
A development environment (macOS, Windows, or Linux) with a terminal or compatible IDE (VS Code, Cursor, Windsurf).
Basic familiarity with command-line interfaces and code review workflows.
GitHub repository access if you plan to use Codex Cloud for background tasks.
API keys or session tokens (generated from your OpenAI account settings).

Step-by-Step Guide to Setting Up and Using Codex

Step 1: Choose Your Surface

Codex runs on four surfaces. Pick the one that matches your workflow:

CLI (command-line interface) – best for quick tasks, automation, and scripting.
IDE Extensions (VS Code, Cursor, Windsurf) – integrates directly into your editor for in-line coding help.
Desktop App (macOS/Windows) – standalone application with a chat interface.
Codex Cloud – runs background tasks against GitHub repositories, ideal for CI/CD and automated reviews.

For most users, starting in the CLI or IDE on small bounded tasks before enabling cloud is the highest-leverage approach.

Step 2: Install and Authenticate

Follow these steps to get Codex running:

Install the CLI tool – Download and run the installer from the official OpenAI Codex documentation. For macOS: brew install openai-codex. For Linux: use the provided .deb or .rpm package.
Authenticate – Run codex auth login in your terminal. This will open a browser window to log into your OpenAI account and generate a session token.
Install IDE extension – Open your VS Code, Cursor, or Windsurf editor. Go to the extensions marketplace and search for “Codex by OpenAI”. Install and reload the window. The extension will automatically pick up your CLI credentials.
Verify installation – Test by running codex --version in the terminal. You should see version 1.3 or later (as of April 2026). For IDE, open a blank file and type a comment like // Ask Codex to write a function – the extension should respond.

Step 3: Run Your First Task

Start with a small, bounded task to understand Codex’s behavior:

In your terminal, navigate to a project directory and run: codex "Write a Python function to reverse a string"
You’ll see Codex generate code, optionally execute it in a sandbox, and present the result. For IDE, select the text and invoke Codex via right-click or command palette (Ctrl+Shift+P → “Codex: Ask”).
Review the output. Codex includes file access, shell execution, and approval flows by default. You’ll be asked to approve any file writes or shell commands.
Experiment with iterative prompting: codex "Now add error handling" – Codex maintains context from the previous interaction unless you reset it.

Step 4: Configure Model Selection

As of April 2026, Codex uses GPT-5.5 as the default model. However, you can choose a different model based on your needs:

GPT-5.5 – flagship general model, excellent for complex agentic tasks and long-context operations (1M tokens MRCR v2 score: 74.0%). But costs ~2× per token vs GPT-5.4.
GPT-5.4 – still available, cheaper per token, suitable for simpler tasks where extreme accuracy isn’t critical.
Custom model selection – Use the --model flag in CLI: codex 'My prompt' --model gpt-5.4. In IDE, look for the model dropdown in the Codex panel.

Tip: For budget-sensitive tasks, start with GPT-5.4 and only switch to 5.5 when you need higher accuracy or longer context.

Step 5: Set Up Workspace Roles (For Teams)

If you're a team lead or admin, separate admin and user access through workspace Role-Based Access Control (RBAC):

Go to the OpenAI Workspace admin panel.
Create roles: e.g., “Developer”, “Admin”, “Reviewer”.
Assign permissions: Developers can generate code but need approval for file writes; Admin can override rate limits; Reviewer can approve merges.
Invite team members by email. They’ll receive an invite to join your workspace.
Set token consumption limits per role to control costs.

Step 6: Integrate Codex Cloud with GitHub

Codex Cloud runs background tasks against your repositories. Here's how to set it up:

Navigate to the Codex Cloud section in your OpenAI dashboard.
Click “Add Repository” and authorize Codex to access your GitHub account (read-only or read-write as needed).
Configure triggers: e.g., “On every pull request, run code review and suggest improvements”.
Define approval workflows – Codex can act as a pre-merge reviewer, generating comments on code quality, security, and adherence to style guides.
Deploy and monitor via the dashboard. Use codex cloud logs in CLI to see task history.

Step 7: Optimize Usage for Cost and Performance

Token consumption is the main cost driver, not prompt count. Follow these tips to stay efficient:

Set a budget cap in workspace settings – e.g., $100 per month per user.
Use shorter contexts – Break large tasks into smaller prompts. Codex remembers conversation history, but you can reset with /new in CLI.
Leverage the sandbox – Codex executes code in a sandboxed environment, which helps avoid unexpected costs from long-running scripts. Monitor execution time; kill tasks that exceed a minute with Ctrl+C.
Review your token usage weekly via the OpenAI dashboard. Identify heavy users or inefficient patterns.

Tips for Success

Start small, then scale – Begin with single-function tasks in CLI or IDE before enabling Cloud or complex multi-file operations. This surfaces friction early.
Treat Codex as a reviewer, not a ghost writer – Use it to generate suggestions and catch issues, but always review code manually. Codex can hallucinate (though GPT-5.5 reduced hallucination rate by ~60% vs prior versions).
Use the 30-60-90 day adoption plan – Phase 1 (Days 1-30): Individual devs experiment on small tasks. Phase 2 (31-60): Enable team-wide usage with RBAC. Phase 3 (61-90): Integrate Codex Cloud into CI/CD pipelines.
Compare alternatives – Codex differs from Claude Code, GitHub Copilot, and self-hosted models. For instance, Copilot focuses on inline completions, while Codex offers full agentic workflow with file access. Choose based on your need for autonomy vs control.
Keep pricing snapshots current – Pricing changes frequently. Always verify against official links before making procurement decisions. As of April 2026, GPT-5.5 costs roughly 2× GPT-5.4 per token.
Use the security checklist – In the full handbook (Section 9), you'll find a checklist for enterprise governance: ensure no sensitive data leaks via prompts, restrict shell execution to sandbox, and audit logs regularly.
Explore the glossary and worked cost example in the appendix to understand terms like MRCR v2 and Terminal-Bench 2.0 – these benchmarks help you gauge Codex’s capabilities for your use case.