Beginner's Guide

Codex on Windows

Get OpenAI's coding agent running on your Windows machine — CLI, VS Code, and everything in between

OpenAI Codex Windows CLI & VS Code 2026

What Is OpenAI Codex?

Codex is OpenAI's coding agent. It can read your files, write code, run terminal commands, catch errors, and iterate until the job is done — all on your local machine or in the cloud. Think of it as a developer sitting beside you who never gets tired and can handle everything from quick fixes to building entire features.

Codex is available in several forms:

  • Codex CLI — an open-source command-line tool (built in Rust) that runs directly in your terminal
  • Codex VS Code Extension — an IDE extension that puts Codex right in your editor sidebar
  • Codex in ChatGPT — a cloud-based version that runs tasks on OpenAI's servers

This guide focuses on getting the CLI and VS Code extension working on Windows. Whether you're new to coding agents or just new to using them on Windows, we'll walk through every step.

Windows has a few extra steps. Codex was originally built for macOS and Linux. On Windows, the best experience comes from running Codex inside WSL (Windows Subsystem for Linux). We'll cover all three options: VS Code extension, CLI via WSL, and native Windows.

What You Need to Get Started

Before diving in, make sure you have these basics covered:

Windows 10 or 11

Any recent version of Windows 10 (build 19041+) or Windows 11 will work. You'll need administrator access to install WSL if you go that route.

A ChatGPT Account

Sign up at chatgpt.com if you don't have one. Codex is included with ChatGPT subscriptions (Plus, Pro, Business, Enterprise). There's a limited free tier too.

Visual Studio Code (for the extension)

Download VS Code from code.visualstudio.com. Make sure it's up to date — the Codex extension requires a recent version.

Node.js 22+ (for the CLI)

The CLI requires Node.js 22 or newer. We'll install this inside WSL in the CLI section — don't worry about it yet if you're only using the VS Code extension.

WSL2 with Ubuntu (Recommended for CLI)

Windows Subsystem for Linux gives you a real Linux environment inside Windows. This is the recommended way to run the Codex CLI. We'll walk you through installation below.

Plans & Pricing

Codex is bundled with ChatGPT subscriptions. You don't need a separate subscription — if you have ChatGPT, you have Codex. Here are the tiers that matter for individuals:

Free

$0 /month
  • Limited Codex access (trial)
  • Basic model access
  • Good for trying it out
  • Rate limits apply

Plus

$20 /month
  • Full Codex access
  • 2x Codex rate limits
  • GPT-4o, o4-mini, o3 models
  • Free API credits included
  • Best value for most users

Pro

$200 /month
  • Everything in Plus
  • Unlimited Codex usage
  • GPT-5 access
  • o3-pro deep reasoning
  • Highest rate limits

API key option: You can also use Codex with an OpenAI API key instead of a ChatGPT subscription. This is pay-as-you-go pricing based on token usage. Set the OPENAI_API_KEY environment variable and Codex will use your API credits. ChatGPT Plus and Pro subscribers get free API credits each month.

Option A: The VS Code Extension

The fastest way to get started with Codex on Windows. The VS Code extension gives you the full Codex agent right in your editor sidebar — no terminal setup needed.

Open the Extensions Panel

In VS Code, press Ctrl+Shift+X to open the Extensions panel, or click the puzzle-piece icon in the sidebar.

Search for "Codex"

Type Codex in the search box. Look for "Codex — OpenAI's coding agent" by OpenAI (extension ID: openai.chatgpt). Click Install.

Sign In

After installing, click the Codex icon in the sidebar. You'll be prompted to sign in with your ChatGPT account or enter an OpenAI API key. Follow the browser authentication flow.

Start Chatting

Open a project folder in VS Code, then type a request in the Codex panel. Try something simple like Explain what this project does or Find all TODO comments in this codebase.

Enable WSL mode for better results. If you have WSL installed, open VS Code settings (Ctrl+,), search for codex wsl, and enable "Run Codex in Windows Subsystem for Linux". This gives Codex a proper Linux sandbox with fewer approval prompts and better command execution.

VS Code Extension Modes

The extension has three modes you can switch between using the dropdown under the chat input:

  • Chat — Conversational mode. Codex won't read files or run commands on its own. Safe for planning and discussion.
  • Agent (default) — Codex can read files, make edits, and run commands in your project automatically. It still asks permission before touching files outside your workspace or accessing the network.
  • Agent (Full Access) — Full permissions including network access. Use with caution.

Helpful Features

  • File references: Type @filename.tsx in your prompt to give Codex specific file context
  • Image input: Hold Shift and drag-and-drop a screenshot into the prompt to include it as context
  • Cloud tasks: Offload larger jobs to Codex Cloud and track progress from the extension
  • Reasoning effort: Adjust from Low to High under the chat input. Higher effort = better results on complex tasks but slower and uses more tokens

Option B: The CLI via WSL (Recommended)

The Codex CLI is the most powerful way to use Codex. It runs in your terminal and gives you fine-grained control over autonomy levels, sandboxing, and configuration. On Windows, the recommended approach is to run it inside WSL (Windows Subsystem for Linux).

Step 1: Install WSL2

Open PowerShell as Administrator (right-click the Start button → "Terminal (Admin)" or "PowerShell (Admin)") and run:

# Install WSL2 with Ubuntu (default distribution) wsl --install -d Ubuntu

Restart your computer when prompted. After rebooting, the Ubuntu terminal will open automatically and ask you to create a Linux username and password. Pick something simple — you'll use this for sudo commands.

Already have WSL? Make sure it's WSL2 (not WSL1). Run wsl --list --verbose in PowerShell. If the VERSION column shows 1, upgrade with wsl --set-version Ubuntu 2.

Step 2: Install Node.js via NVM

Codex CLI requires Node.js 22 or newer. The version in Ubuntu's default repositories is too old, so we use NVM (Node Version Manager). Open your Ubuntu terminal and run:

# Install NVM curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash # Reload your shell config source ~/.bashrc # Install Node.js 22 (LTS) nvm install 22 # Verify node --version # Should show v22.x.x

Step 3: Install the Codex CLI

# Install Codex globally npm install -g @openai/codex # Verify codex --version

Step 4: Authenticate

Run codex to launch the interactive mode. Codex will open a browser window for you to sign in with your ChatGPT account. Since WSL doesn't have a browser, you may need to install wslu first:

# Install wslu for browser support from WSL sudo apt update && sudo apt install -y wslu # Now launch Codex — it will open your Windows browser codex

Alternatively, you can skip browser auth entirely by using an API key:

# Set your API key (add this to ~/.bashrc to persist) export OPENAI_API_KEY="sk-your-key-here" # Launch Codex codex

Step 5: Open VS Code from WSL

For the best experience, open VS Code directly from your WSL terminal. This launches VS Code in WSL mode (you'll see a green "WSL: Ubuntu" badge in the bottom-left corner), so both the editor and the Codex CLI share the same Linux filesystem:

# Navigate to your project cd ~/code/my-project # Open VS Code in WSL mode code .

VS Code will install the WSL extension automatically the first time you run code . from WSL. This extension lets VS Code run its backend inside Linux while you use the Windows UI.

Option C: Native Windows (PowerShell)

You can run the Codex CLI directly in PowerShell without WSL. This is the simplest setup, but it comes with trade-offs.

# Install Node.js 22+ from nodejs.org first, then: npm install -g @openai/codex # Launch Codex codex

Native Windows support is experimental. Some things to know:

— Codex uses a Windows sandbox (Restricted Tokens + Firewall rules) instead of Linux-native sandboxing. This works but may trigger more approval prompts.
— --full-auto mode may not work reliably because Codex expects Linux commands like ls and cat.
— Some antivirus software may flag Codex's sandbox behavior.
— For anything beyond light use, WSL is strongly recommended.

The Three Modes

Whether you use the CLI or the VS Code extension, Codex has three autonomy levels. Think of them as trust settings — how much freedom you give the agent.

Suggest

Suggest

Codex reads your code and proposes changes but won't do anything without your approval.

  • Reads files: yes
  • Edits files: asks first
  • Runs commands: asks first
  • Best for: learning, reviewing
Auto Edit

Auto Edit

Codex reads and writes files automatically. It still asks before running shell commands.

  • Reads files: yes
  • Edits files: automatic
  • Runs commands: asks first
  • Best for: daily coding
Full Auto

Full Auto

Codex does everything autonomously in a sandboxed environment with no network access.

  • Reads files: yes
  • Edits files: automatic
  • Runs commands: automatic
  • Best for: trusted tasks

In the CLI, set the mode with a flag:

# Suggest mode (most cautious) codex --approval-mode suggest # Auto Edit mode (middle ground) codex --approval-mode auto-edit # Full Auto mode (most autonomous) codex --full-auto

In the VS Code extension, switch modes using the dropdown under the chat input.

Start with Suggest mode while you're learning. Once you're comfortable with what Codex does, move to Auto Edit. Save Full Auto for tasks where you trust the outcome, like running tests or formatting code.

Using Codex: Your First Session

Interactive Mode (CLI)

Navigate to a project directory and type codex to start an interactive session. You'll see a text input where you can type requests in plain English:

# Start Codex in your project cd ~/code/my-project codex # Now type your request at the prompt, for example: > Explain what this project does and list its main dependencies > Find all the places where we handle user authentication > Add input validation to the signup form

Codex will read your codebase, propose changes, and ask for approval (depending on your mode). You can iterate back and forth just like a conversation.

Non-Interactive Mode (Scripting)

For automation and scripts, use the exec subcommand:

# Summarize a repository codex exec "summarize this repo's architecture" # Get JSON output for piping to other tools codex exec --json "list all API endpoints" | jq # Resume a previous session to continue work codex exec resume --last "now fix the issues you found"

Full Auto for Trusted Tasks

# Fix failing tests autonomously codex --full-auto "run the test suite and fix any failures" # Generate boilerplate codex --full-auto "create a new React component called UserProfile with TypeScript"

Useful In-Session Commands

While inside an interactive Codex session, type / to see all available slash commands:

Command What It Does
/model Switch between models (o4-mini, o3, GPT-5, etc.)
/permissions Change approval mode mid-session
/diff View the git diff of all changes Codex has made
/compact Summarize the conversation to free up context window
/plan Switch to plan mode — Codex will outline an approach before coding

Configuration & Custom Instructions

The Config File

Codex stores its settings in ~/.codex/config.toml. You can edit this file directly or change settings with slash commands. Here's what a basic config looks like:

# ~/.codex/config.toml # Model selection (default: o4-mini) model = "o4-mini" # Reasoning effort: minimal | low | medium | high | xhigh reasoning_effort = "medium" # Approval policy approval_policy = "auto-edit" # Sandbox mode sandbox_mode = "workspace-write"

You can also add project-specific settings by creating a .codex/config.toml file in your project root. Codex will merge it with your global config.

AGENTS.md — Project Instructions

This is one of the most powerful features. Create an AGENTS.md file in your project root and Codex will read it at the start of every session. Use it to tell Codex about your project's conventions, tech stack, and preferences:

# AGENTS.md ## Project This is a Next.js 14 app with TypeScript and Tailwind CSS. The database is PostgreSQL via Prisma ORM. ## Conventions - Use functional components with hooks (no class components) - All API routes go in app/api/ - Use Zod for input validation - Write tests with Vitest ## Do Not - Modify the database schema without asking first - Use any and disable TypeScript checks - Install new dependencies without listing them first

Cross-tool compatibility: AGENTS.md works with Codex. GitHub Copilot uses AGENTS.md too (or its own .github/copilot-instructions.md). Claude Code reads CLAUDE.md. You can maintain separate files or one shared file depending on your workflow.

MCP Servers

Codex supports the Model Context Protocol (MCP) for connecting to external tools — databases, APIs, documentation servers, etc. Configure them in your config.toml:

# Add an MCP server [mcp_servers.my-docs] command = "npx" args = ["@modelcontextprotocol/server-filesystem", "/path/to/docs"]

Windows Tips & Best Practices

Keep Projects on the Linux Filesystem

If you're using WSL, store your code in your Linux home directory (~/code/) rather than on the Windows filesystem (/mnt/c/Users/...). Working on mounted Windows paths is significantly slower due to filesystem translation overhead. It can also cause permission confusion and symlink issues.

# Good — native Linux filesystem (fast) cd ~/code/my-project codex # Bad — mounted Windows drive (slow) cd /mnt/c/Users/YourName/Documents/my-project codex

Use Windows Terminal

The default Windows console host can have rendering issues with Codex's TUI (terminal user interface). Windows Terminal handles colors, Unicode, and resize events much better. It comes pre-installed on Windows 11. On Windows 10, install it from the Microsoft Store.

VS Code WSL Mode

When you open VS Code from a WSL terminal with code ., VS Code runs in WSL mode. You'll see a green "WSL: Ubuntu" badge in the bottom-left corner. In this mode, VS Code's terminal, file explorer, and extensions all operate on the Linux filesystem. This is the ideal setup for using both the Codex CLI (in the integrated terminal) and the Codex extension together.

Accessing Linux Files from Windows

Need to open a WSL file in a Windows app? Your Linux filesystem is accessible at \\wsl$\Ubuntu\home\yourname\ in File Explorer. You can also pin this as a quick-access location.

Prevent Windows PATH Pollution

By default, WSL includes your Windows PATH, which can cause confusion with duplicate tool names. To keep things clean, add this to /etc/wsl.conf inside your Ubuntu instance:

# /etc/wsl.conf [interop] appendWindowsPath = false

Then restart WSL with wsl --shutdown in PowerShell and reopen it.

Troubleshooting

Here are the most common issues Windows users run into and how to fix them:

Problem Solution
Excessive approval prompts on native Windows Switch to WSL. The Linux sandbox generates far fewer prompts because Codex can use native sandboxing.
--full-auto fails or produces wrong results on native Windows Codex expects Linux commands (ls, cat, etc.). Use WSL where these are available natively.
Sandbox setup errors (Landlock/seccomp) Update WSL: run wsl --update in PowerShell. Older kernels may lack required security features.
Terminal rendering looks broken Use Windows Terminal instead of the default console. Also try the /theme command inside Codex to switch themes.
Browser auth hangs in WSL Install wslu (sudo apt install wslu) so WSL can open your Windows browser. Or use an API key instead.
MCP servers not detected in VS Code + WSL Known limitation with the VS Code extension in WSL. Use the CLI for MCP server workflows instead.
Ctrl+C copies instead of interrupting In Windows Terminal, Ctrl+C interrupts by default. In other terminals, use Ctrl+Shift+C to copy.
Slow file operations in WSL Move your project to the Linux filesystem (~/code/) instead of /mnt/c/. See the tips section above.

Still stuck? The Codex CLI is open source. Check the GitHub Issues page for known Windows-specific bugs, or file a new issue with your system details.