Configure Codex: AGENTS.md, config.toml, Skills, and MCP

💡 What this guide covers: every new Codex session feels like onboarding a new colleague: how to start the project, run tests, and avoid protected directories. Store project rules in AGENTS.md, personal preferences in config.toml, and extend capabilities with Skills and MCP. Set it up once, reuse it, and learn which older instructions are now out of date.

More Codex articles: Save Effort · Codex

Where people get stuck

• Starting over every time: new coding-assistant sessions largely start fresh. Previously explained background, preferences, and project conventions don’t automatically carry over.
• Not recording project rules: explaining the same project repeatedly is inefficient. Keep the README, AGENTS.md, and test commands up to date.
• Too many rules: some 2025 tutorials recommended dozens or hundreds of instructions in AGENTS.md. In September 2026, OpenAI urged developers to revisit them: they use context and may conflict.
• Copying third-party settings: tutorials may change providers, permissions, or API endpoints. Don’t copy an old configuration wholesale. Check current official parameters, especially for permissions and third-party model URLs.

The division is simple: stable preferences belong in configuration; project background belongs in documentation.

1. AGENTS.md: an onboarding guide for Codex

What it is

• AGENTS.md is an optional project instruction file: a lightweight guide or quick-start card.
• Codex reads it automatically when it is in the directory from which Codex starts. That is usually the project root.
• Use /status to see whether the current directory’s AGENTS.md is participating.
• It turns repeated reminders into knowledge the team and Codex can reuse.

Three places to put it

1. Project level: run /init in Codex to generate a file in the current directory. Then add real project rules:

This project uses pnpm.
Development command: pnpm dev.
Test command: pnpm test.
Do not edit dist or generated.
Route all API requests through src/lib/api.ts.

Those lines save repeated explanations. /init provides scaffolding; your project-specific rules provide the value.

2. Global level: put AGENTS.md in the Codex home directory, ~/.codex, for rules across projects. Examples include preferred tools, response style, official-documentation-first research, particular MCP services, code style, or checks after edits.

3. Subdirectory level: if a repository contains a frontend, backend, and several services, give each relevant directory its own file. The root file explains the project; local files add details for that area.

Keep temporary, project-specific requirements in the project file and long-term, general rules in the global file.

What to include

Focus on information that changes how work gets done:

• Project overview: what the project does.
• Tech stack and directory structure: where different files live.
• Common commands: install, start, lint, test, and build.
• CLI tools: GitHub CLI or other integrated tools.
• MCP services: which servers Codex should use.
• Code style.
• Protected directories and files, and precautions for edits.
• Release process and important business boundaries.
• Development workflow: the usual steps for implementing a feature.
• Final reporting: files changed, tests run, and tests not run.

Use specific paths. Instead of “Code is in src,” write “Frontend pages are in src/pages, API requests in src/api. After editing, run npm run lint and npm test.”

Six principles for writing AGENTS.md

1. Keep it short and focused. Most files OpenAI has seen are under 100 lines. Too many rules obscure priorities; conflicting rules waste time.
2. Make verification possible. Explain the checks: code-analysis tools, relevant tests, builds, and how to fix errors. If you keep manually explaining verification, record it—for example, compiling the project or taking a screenshot. For every requirement, ask how Codex can verify it. Without a check, it cannot easily know it succeeded.
3. Start simply. Include the project purpose, code locations, build and test instructions, and common commands. Add team conventions, special directory rules, and feature workflows only when you find yourself repeating them. Keep the file tied to real work, not an impressive-looking document nobody maintains.
4. Keep updating it. Record fixes for recurring mistakes. If Codex takes too long to discover a test command, add that command. Prioritize common commands, pitfalls, special task requirements, and quick verification methods. Pair each rule with a check.
5. Keep general guidance in the main file and details elsewhere. AGENTS.md enters context every time. Put task details in files such as execplans.md for large plans, frontend.md, architecture.md, and code-review-guidelines.md; see safe changes and review. Add a task-documentation section pointing to the right file for each situation. This is progressive discovery: read the short overview, then fetch relevant details. The main file becomes a map.
6. Revisit every rule regularly. The next section explains why.

A 2026 reminder: give stronger models room to work

OpenAI’s September 2026 article, Rethinking Skills and Prompts for GPT-6 Astra, says stronger models need less hand-holding. After a year of accumulating instructions, review them whenever you change models.

• Ask whether each rule is still necessary. Repository instructions apply repeatedly, so revisit them.
• Don’t require a stack of documents before every edit. Reading the entire project map for a typo wastes time. Newer models can judge what they need.

Document links remain useful when tied to a situation. Keep the documents current too.

• Remove reminders like “Always run tests.” Older models needed reminders to test and inspect results. GPT-6 Astra does this itself; repeating the instruction can lead to unnecessary tests.
• Explicitly authorize safe workflows. Astra is careful but may hesitate over how far to proceed. Give permission for a workflow you know is safe, such as local testing:

The local tests use disposable fixtures and have no production access. Run them, fix failures caused by the requested change, and rerun affected tests without asking for approval at each step.

• Avoid overly forceful boundary wording. Earlier models may have acted without permission, prompting strong “ask first” rules. Astra has better judgment and won’t proceed when safety is unclear. Overly strong language may make it stop where you actually wanted it to continue.
• Have it audit the instructions. Ask Astra to inspect your AGENTS.md and Skills using the article’s recommendations.

Does this contradict the verification advice above? No. Explaining how to check—specific commands or screenshot methods—is still useful. What can go is the repeated urging to test before every change. If other people or models such as Sol or Luna also use the repository, consider whether they still need the reminders.

Three templates to adapt

Template 1: Next.js and pnpm

# AGENTS.md

## Project
This is a Next.js project using pnpm.

## Common commands
- Install: pnpm install
- Development: pnpm dev
- Lint: pnpm lint
- Tests: pnpm test
- Build: pnpm build

## Editing rules
- Do not change the database schema unless explicitly requested.
- Do not add dependencies without explaining why.
- Read README and package.json before editing.
- Report changed files and commands run when finished.

This is an operating procedure for the AI. Over time, consistent project rules matter more than one beautifully written prompt.

Template 2: a small Python project

A minimal version needs only four items:

# Project standards
- Language: Python 3.11+
- Style: PEP 8
- Tests: pytest
- Comments: Chinese

A fuller beginner version:

# AGENTS.md

## Project
This Python project is for practicing small game development.

## Development standards
- Use Python 3.11+.
- Keep code simple and prioritize readability.
- Update README when adding features.
- Run tests or start the program to verify code changes whenever possible.

## Interaction preferences
- Explain the approach before editing.
- Ask before deleting files, restructuring directories, or installing dependencies.
- Reply in Chinese.

## Codex-specific notes
- Permissions: automatic approval, with confirmation for key actions.
- Default model: qwen3.6-plus, or gpt-5.5.
- Skill path: ./.codex/skills, if present.

The final section is only text for the model. Set actual permissions and the default model in config.toml or the interface, as explained below.

Template 3: an English project guide

# Project Guide for Codex

## Commands
Install: pnpm install
Dev: pnpm dev
Test: pnpm test
Lint: pnpm lint
Build: pnpm build

## Rules
Do not edit dist/
Do not edit generated files
Keep changes minimal
Run tests after touching business logic
Use existing components before creating new ones

## Architecture
API clients live in src/lib/api
Shared UI components live in src/components
Route pages live in src/pages
Auth logic lives in src/auth

## Before finishing
Explain changed files
Mention tests run
Mention tests not run

2. config.toml: personal preferences

Where it goes and how to open it

• Personal defaults: ~/.codex/config.toml.
• Project or subdirectory overrides: .codex/config.toml in the repository. For safety, Codex loads project .codex/ settings only when you trust the project. An untrusted project’s local configuration, hooks, and rules are skipped. User and system settings still load.
• In VS Code: gear icon → Codex Settings → Open config.toml.
• The CLI and IDE share the same configuration. Change it once for both. It can define the default model and provider, approvals, sandbox, and MCP servers.
• Codex CLI is written in Rust and uses TOML for configuration.

Configuration priority, highest first

1. CLI arguments and --config overrides.
2. Project .codex/config.toml settings from the root to the working directory; nearer files take priority, in trusted projects only.
3. The profile selected with --profile name, stored at ~/.codex/name.config.toml.
4. User settings at ~/.codex/config.toml.
5. Cloud-provided defaults from the signed-in workspace.
6. System settings, /etc/codex/config.toml on Unix.
7. Built-in defaults.

Managed computers may enforce restrictions through requirements.toml, such as banning approval_policy = "never" or sandbox_mode = "danger-full-access". Some settings in online tutorials may therefore have no effect for you.

Common settings

# Default model
model = "gpt-5.6"

# Reasoning effort
model_reasoning_effort = "high"

# Ask only when higher permissions are needed
approval_policy = "on-request"

# Allow workspace edits, not arbitrary writes outside it
sandbox_mode = "workspace-write"

# Communication style: friendly / pragmatic / none
personality = "friendly"

• Approval policy: the default is on-request. Codex keeps working and asks when it needs more access. For on-request versus never and permission combinations, see safe code changes. The old approval_policy = "untrusted" value is retired; follow official migration guidance.
• Sandbox: workspace mode allows edits inside the current directory, not outside it.
• Permission presets: :read-only, :workspace, and :danger-full-access. You can also define a [permissions.name] table and choose it with default_permissions.
• Communication style: switch temporarily with /personality.
• Native Windows sandbox: use sandbox = "elevated" under [windows], as recommended. Use "unelevated" if admin rights are unavailable or setup fails.

Terminal shortcuts, tui.keymap:

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

An empty list removes a binding.

Command environment variables, shell_environment_policy, controls which variables reach commands run by Codex:

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

A confusing detail: ignore_default_excludes defaults to true. Variables containing KEY, SECRET, or TOKEN in their names are therefore not automatically filtered. Set it to false to enable that filtering.

Log directory:

log_dir = "/absolute/path/to/codex-logs"

Setting log_dir explicitly also creates a plain-text codex-tui.log there. For a temporary setting:

codex -c log_dir=./.codex-log

Logs help with troubleshooting.

Web search: check your version’s configuration

• Older configuration: web_search_request = true enabled search. Check whether the field is deprecated after updating Codex.
• Current official configuration: local conversations have search enabled by default, using OpenAI’s maintained search cache. It returns pre-indexed results rather than fetching live pages, reducing the risk of instructions injected through webpage content. web_search_request is marked Deprecated.

Use the top-level web_search setting:

web_search = "cached"      # Default: return cached search results
# web_search = "indexed"   # Access external pages only when allowed by the search index
# web_search = "live"      # Fetch current web data, equivalent to --search
# web_search = "disabled"  # Disable web search

• With --yolo or other full-access sandbox settings, the default changes to live.
• In every mode, treat search results as untrusted content.
• For recent information, announcements, or new-version documentation, ask directly:

Enable web search, find the latest articles about Next.js 15, and add the current articles to the footer.

Profiles: switch working setups

Define profiles for different tasks. A fast profile might use the fastest model with lower reasoning effort. Start it with --profile fast. Its file is ~/.codex/fast.config.toml. Keep shared defaults in config.toml and put only the differences in the profile file, as officially recommended.

Feature flags: [features]

• Under [features], use flag_name = true or false. Omit it to keep the default.
• Enable a flag temporarily with codex --enable flag_name. Repeat --enable for several flags.

Terminal notifications

Notifications tell you when background work finishes, saving you from watching the terminal. Some people find them distracting, especially with several tasks producing sounds and pop-ups. Choose what suits you.

Connecting Chinese third-party models

Many Chinese providers offer OpenAI-compatible APIs. Changing configuration and environment variables may let Codex use them, but OpenAI compatibility does not guarantee Codex compatibility.

• Newer Codex versions depend on the Responses API and do not support wire_api = "chat". A provider that supports only Chat Completions may connect but fail to run tasks. Many providers have not adapted, so choices are limited.
• Examples include Qwen through Alibaba Cloud Bailian, SiliconFlow, Zhipu AI, and other compatible-API platforms. Check current Responses API support, models, and authentication requirements first.

Open the configuration file from App settings and edit:

model = "qwen3.6-plus"
model_provider = "bailian"

[model_providers.bailian]
name = "bailian"
env_key = "BAILIAN_API_KEY"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"

Set BAILIAN_API_KEY locally. On Windows, right-click This PC → Properties → Environment Variables. Fully quit and reopen Codex; restart the computer if it still cannot find the variable.

Test it with:

Using Chinese, write a Python script that prints “Hello 国内大模型”, then run it.

If it understands the Chinese request, generates code, and runs it successfully, the configuration is working.

Don’t judge compatibility from a model name alone. Confirm that the selected model supports the provider’s current Responses API, then run the minimal task above. Follow the provider’s console for available models and versions.

If it works, use it. If it doesn’t, try another provider. Again, don’t copy third-party URLs and permissions blindly; check current official parameters.

3. Custom prompts: save repeated requests

If you always want unit tests and minimal unrelated changes, save a prompt instead of typing it each time:

1. Create a prompts folder in the Codex home directory.
2. Add a Markdown file such as add_test.md.
3. Quit and restart the CLI.
4. Type prompts in the input, select add_test.md, and Codex brings the full instructions into the current session.

Contents of add_test.md:

Generate unit tests for every changed file.
Use the project's existing test runner and keep the diff as small as possible.

The point is simple: write repeated requests once and reuse them.

4. Skills: package repeated workflows

What a Skill is

A Skill is a prompt stored in Markdown, optionally packaged with resources and scripts. It works best for a specific workflow or guidance for using particular applications.

The problem with installing too many

Each Skill’s name and description enters the model’s context so it knows when to use it. Installing large collections creates problems:

• Long descriptions may be truncated to fit, leaving the model less information to choose from.
• Conflicting descriptions or “always use this” language can load instructions that don’t help the task.

Four official recommendations

A common creation method is $skill-creator, whose guidance was recently updated to avoid these problems.

1. Keep descriptions short and specific about when to use them.

The first triggers for almost anything related to databases. The second targets migration work.

2. Use progressive disclosure. Reading a Skill consumes context, triggers compaction sooner, and can introduce irrelevant guidance. If a Skill has several workflows, make its root document a small router pointing to supporting documents and scripts. Don’t force it to read what it doesn’t need.

3. Don’t write an exact recipe for everything. Models now handle nuance and ambiguity better. Overly specific step-by-step instructions that once helped can now get in the way.

4. Consider other models. Repository Skills also guide other contributors’ agents. Instructions useful for Sol or Luna may constrain GPT-6 Astra too much.

Where to install Skills and which to choose

• Personal Skills: ${CODEX_HOME:-$HOME/.codex}/skills, normally ~/.codex/skills. Project Skills: ./.codex/skills.
• Superpowers: a set of rules requiring a process: clarify the goal, define acceptance criteria, write code, and check the result. Checkpoints cannot be skipped, helping stabilize complex work. Download it from GitHub into the skills directory. It is essentially documentation, so Claude Code, Cursor, and Gemini can use it too.
• Check third-party Skills before installing: read SKILL.md and installation scripts. Confirm triggers, permissions, dependencies, and download URLs. Stars and recommendation lists are no substitute.
• Install what you need. Don’t begin with a pile of plugins.

For a full example of building a Skill, see $harness-author in long tasks and project workflows: package long-task planning into a Skill and improve it through retrospectives.

5. MCP: connect external tools

What it is

MCP is a protocol connecting models to additional tools and context. Codex supports stdio and HTTP. Connections can provide design files, task systems, monitoring, and third-party services. Codex understands the request and chooses calls; the MCP service supplies the actual data.

Common uses

• Figma: build frontend pages from designs.
• Jira and Linear: read assigned tasks, implement changes, and mark tickets complete in one workflow.
• Context7: fetch current framework documentation and use third-party APIs correctly.
• Datadog: retrieve production logs to investigate performance.
• Other services can provide designs, orders, task status, or business data.

List preferred MCP servers in AGENTS.md. Their settings can also go in config.toml, making them available at startup.

Understand the flow with a cupcake order

Imagine an example order service that answers who ordered how many cupcakes. The service name, customer, and order below are illustrative; configure a real integration using its own API.

1. Save project files and exit the session. Restarting does not roll back code already written to disk.
2. Run codex mcp add ... with the service’s parameters. This adds a global service named cupcake MCP.
3. Open config.toml to see the new settings. You can edit it manually, but codex mcp add is usually easier and avoids formatting mistakes.
4. Start a new session: “Add a section at the bottom of the agents.md page that fetches Rachel’s cupcake order.”
5. Have Codex call the order tool and connect the returned data to the page. If it returns “Rachel, seven marble cupcakes, store pickup,” check each field rather than letting the model fill in order details itself.

The flow is: understand the task → choose external capabilities and call MCP → use the result in real code changes. In practice, the result might be a design, ticket, document, or system status.

Context7: don’t rely only on old training data

Models have knowledge cutoffs, while frameworks and APIs keep changing. Context7 supplies current framework documentation and can be installed with codex mcp add.

Suppose you want an input on the agents.md page where users enter a short prompt to generate their own file. Ask Codex to look up the current Responses API usage through Context7 before implementing the form and request logic.

• Process: Codex gets documentation first, then explores repository files, including the existing page. Only after combining requirements, references, and code does it build the generator.
• Verification: inspect each diff, open the implementation to confirm the Responses API is connected, and submit the form to test success and failure. File counts and lines added do not prove the feature works.

Teams can expose internal documentation through MCP too, keeping development aligned with actual implementation rather than outdated material.

To avoid reminding it about Context7 every time, add this to your global AGENTS.md:

Whenever feature work involves an external library or API, look up the relevant documentation in Context7 first.

When MCP isn’t necessary

You could supply large-task plans and progress through MCP, but a Markdown file that the model can read and the team can commit to Git is often enough. It stays with the project and everyone can read, edit, and reuse it. See long-task planning.

MCP issues have been common on Windows. See troubleshooting.

Summary

• AGENTS.md: project background, commands, directories, and boundaries. Keep it short and specific, route to specialized documents, and remove outdated rules.
• config.toml: stable preferences such as model, reasoning effort, approvals, sandbox, search, profiles, and flags.
• prompts/: repeated requests.
• Skills: repeated workflows, with short descriptions and on-demand loading.
• MCP: external data and current documentation when needed.

Useful customization puts stable preferences in configuration and project background in documentation. Your prompts don’t need to keep growing.

Official documentation to keep handy

• Codex configuration guide in Chinese
• Rethinking Skills and Prompts for GPT-6 Astra
• Iterating Development Workflows with Codex