Codex CLI: A Complete Guide to the Latest Settings and Features (GPT-5 Ready)

This article provides a comprehensive overview of the Codex CLI, which has been rapidly gaining traction since the beginning of 2025. We'll cover everything from basic setup and useful tips to common pitfalls for Windows users.

By the end of this guide, you'll be ready to integrate Codex CLI into your daily work and development environment.

1. Why is Codex CLI Gaining Attention Now?

GPT-5 Support and Availability with ChatGPT Subscriptions

Codex CLI is a relatively new tool, first appearing in April 2025.
Initially, it required an API key, but since the release of GPT-5 in August 2025, it has become available to ChatGPT Plus/Pro/Team users at no extra cost.

This has significantly lowered the barrier to entry, encouraging many developers to start using it.

2. Basic Codex CLI Setup

Installation

The officially recommended installation methods are as follows:

# With npm
npm install -g @openai/codex

# With Homebrew
brew install codex

It can be installed on both Linux and Windows. However, be aware of the "full path specification" issue on Windows, which is discussed later.

Configure a Global Prompt with AGENTS.md

Codex CLI automatically loads the content of ~/.codex/AGENTS.md in every session.

For example, if you want to prioritize using Serena, you can add the following:

- Always utilize the Serena MCP server as the primary tool for semantic code search, project analysis, and automated refactoring.
- Upon project initialization, activate the current directory as a Serena project before performing any operations.
- Prefer Serena tools over built-in commands whenever semantic understanding of the codebase is required.

A key advantage is that this can be standardized across multiple AI tools like Claude Code and Copilot.

Location on Windows

On Windows, place the AGENTS.md file here:

C:\Users\{Your-Username}\.codex\AGENTS.md

config.toml Basics

The configuration file is located at ~/.codex/config.toml.
It uses the TOML format, as shown below:

model = "gpt-5-codex"
network_access = true

[tools]
web_search = true

3. Useful Features and Configuration Tips

MCP Settings

Codex CLI supports the Model Context Protocol (MCP).
Configuration is done directly in the same config.toml file.

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]

Note: SSE-type MCPs cannot be used directly and require a proxy like mcp-proxy or mcp-remote.

Web Search Functionality

To incorporate the latest information, add the following:

[tools]
web_search = true

Custom Prompts

You can register frequently used prompts.
Place them in the ~/.codex/prompts/ directory.

Typing / will bring up a list of suggestions, similar to slash commands in Claude.

File Mention Feature

You can directly reference specific files within your prompt by writing @path/to/file.

4. Important MCP Configuration for Windows Users

If you follow configuration guides for Linux or macOS, you are likely to encounter the following errors on Windows:

• program not found
• request timed out

The cause is simple: Codex cannot find the executable because PATH resolution fails.

Solution: Specify the Full Path

Use where.exe in PowerShell to find the location of the executable.

where.exe npx
where.exe uvx

Example output:

C:\Program Files\nodejs\npx.cmd
C:\Users\xxxx\AppData\Local\Microsoft\WinGet\Links\uvx.exe

Write this full path directly into your config.toml.

Additionally, setting the SYSTEMROOT environment variable is key to stable operation on Windows.

Example serena MCP Configuration

For Windows (username = xxxx)

[mcp_servers.serena]
command = "C:\\Users\\xxxx\\AppData\\Local\\Microsoft\\WinGet\\Links\\uvx.exe"
args = [
  "--from", "git+https://github.com/oraios/serena",
  "serena-mcp-server",
  "--context", "ide-assistant"
]

[mcp_servers.serena.env]
PYTHONIOENCODING = "utf-8"
SYSTEMROOT = 'C:\\Windows'

For Linux

[mcp_servers.serena]
command = "uvx"
args = [
  "--from", "git+https://github.com/oraios/serena",
  "serena", "start-mcp-server",
  "--context", "codex"
]

5. Codex CLI VS Code Extension

An official extension was released at the end of August 2025.
The advantages over the CLI are:

• Automatically references files open in VS Code.
• Enables integration with Codex Cloud.

It integrates seamlessly with the CLI, allowing you to naturally incorporate it into your regular development workflow.

6. Key Commands

7. Summary

• Codex CLI has become significantly more practical with GPT-5 support.
• It offers rich extensibility with features like MCP and web search.
• For Windows users, "full path specification" and "SYSTEMROOT setting" are crucial.
• Advanced extensions like the serena MCP can be utilized.
• The VS Code extension further enhances the development experience.

Improvements are expected to continue at a rapid pace, so it's a good idea to adopt and get used to it early.