Codex

CLI

OpenAI

OpenAI's coding agent for the terminal and IDE, configured through a single config.toml.

MCP

Supported

MCP servers are defined as [mcp_servers.<name>] tables in config.toml. Supports stdio and Streamable HTTP, with bearer-token and OAuth auth.

Verified 2026-06-21Docs

Transportsstdiohttp

Authoauthbearer-tokenheaders

Config files

Path	Scope	Format	Key
`~/.codex/config.toml`	Global	toml	mcp_servers
`.codex/config.toml` Trusted projects only.	Project	toml	mcp_servers

Fields

Field	Type	Description
`command`	string	Launcher command for a stdio server.
`args`	string[]	Arguments passed to the stdio command.
`env`	map<string, string>	Environment variables forwarded to the stdio server.
`env_vars`	(string \| { name, source })[]	Additional env vars to allow/forward. source = local \| remote.
`cwd`	string	Working directory for the stdio server process.
`url`	string	Endpoint for a Streamable HTTP server.
`bearer_token_env_var`	string	Env var name holding a bearer token sent in Authorization.
`http_headers`	map<string, string>	Static HTTP headers for each request.
`env_http_headers`	map<string, string>	HTTP headers populated from environment variables.
`enabled`	boolean	Disable a server without removing its config.
`startup_timeout_sec`	number	Server startup timeout (default 10s).
`tool_timeout_sec`	number	Per-tool execution timeout (default 60s).
`enabled_tools`	string[]	Allow list of tool names exposed by the server.
`disabled_tools`	string[]	Deny list applied after enabled_tools.
`scopes`	string[]	OAuth scopes to request when authenticating.

Capabilities

ToolsSupported

Server instructionsSupported

Examples

stdio + Streamable HTTP servers

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

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

•The CLI and IDE extension share this configuration. Manage servers with `codex mcp`.
•Project-scoped .codex/config.toml is loaded only for trusted projects.

Skills

Supported

SKILL.md skills following the open Agent Skills standard, discovered from .agents/skills up to the repo root. Invoke with $ or /skills.

Verified 2026-06-21Docs

Invoke$skill-name/skillsimplicit

Config files

Path	Scope	Format	Key
`.agents/skills/<name>/SKILL.md` Scanned from CWD up to repo root.	Project	markdown	—
`~/.agents/skills/<name>/SKILL.md` User skills applied across all repositories.	Global	markdown	—
`/etc/codex/skills/<name>/SKILL.md` Admin/system skills shared on the machine.	Enterprise	markdown	—

Fields

Field	Type	Description
`name`*	string	Skill identifier.
`description`*	string	When the skill should and should not trigger.

Examples

Minimal SKILL.md

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

•Codex scans .agents/skills in every directory from CWD up to the repository root.
•Optional agents/openai.yaml adds UI metadata and policy.allow_implicit_invocation.
•Disable a skill via [[skills.config]] (path + enabled) in config.toml.

Rules

Supported

AGENTS.md instruction files, layered from the Codex home directory down to the working directory, with override files and configurable fallbacks.

Verified 2026-06-21Docs

Config files

Path	Scope	Format	Key
`AGENTS.md` Project root down to CWD, including nested directories. AGENTS.override.md takes precedence.	Project	markdown	—
`~/.codex/AGENTS.md` Global defaults inherited by every repository. ~/.codex/AGENTS.override.md for temporary overrides.	Global	markdown	—

Examples

Global guidance (~/.codex/AGENTS.md)

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.

•Codex reads AGENTS.override.md before AGENTS.md at each level; only one file per directory is used.
•Files merge root-first; closer files override earlier guidance.
•project_doc_max_bytes (default 32 KiB) caps combined size; project_doc_fallback_filenames adds alternate names.

Hooks

Supported

Lifecycle hooks loaded from hooks.json or an inline [hooks] table in config.toml. Gated behind the features.hooks flag; command hooks are executed.

Verified 2026-06-21Docs

EventsPreToolUsePermissionRequestPostToolUsePreCompactPostCompactSessionStartSubagentStartSubagentStopUserPromptSubmitStop

Config files

Path	Scope	Format	Key
`~/.codex/config.toml` Inline [hooks] table, or a separate hooks.json.	Global	toml	hooks
`.codex/config.toml` Trusted projects only.	Project	toml	hooks

Fields

Field	Type	Description
`hooks.<event>`	array	Matcher groups for a hook event.
`hooks.<event>[].hooks`	array	Hook handlers for a matcher group (command hooks supported).
`hooks.<event>[].hooks[].command`	string	Command to run for a command hook.
`hooks.<event>[].hooks[].commandWindows`	string	Windows-only command override (alias command_windows).

•Enable with features.hooks = true (deprecated alias: features.codex_hooks).
•Command hooks are supported; prompt and agent hook handlers are parsed but skipped.
•Admins can enforce managed hooks via requirements.toml and allow_managed_hooks_only.

Commands

Deprecated

Custom prompts (~/.codex/prompts/*.md, invoked /prompts:name) were deprecated and removed in codex-cli 0.117.0. Convert custom prompts to Skills.

Verified 2026-06-21Docs

Invoke/prompts:name

•Codex still ships built-in slash commands (/review, /fork, /plan, /diff, /compact, etc.).
•For reusable custom workflows, author Skills instead.

Settings

Supported

config.toml is the single settings file for models, reasoning, sandboxing, approvals, and tools. requirements.toml enforces admin policy.

Verified 2026-06-21Docs

Config files

Path	Scope	Format	Key
`~/.codex/config.toml`	Global	toml	—
`.codex/config.toml` Trusted projects only; provider/auth/telemetry keys are ignored here.	Project	toml	—
`requirements.toml` Admin-enforced constraints on security-sensitive settings.	Enterprise	toml	—

Fields

Field	Type	Description
`model`	string	Model slug Codex uses for turns.
`model_reasoning_effort`	"minimal" \| "low" \| "medium" \| "high" \| "xhigh"	Reasoning effort for supported models.
`approval_policy`	"untrusted" \| "on-request" \| "never" \| "granular"	When Codex asks for command approval.
`sandbox_mode`	"read-only" \| "workspace-write" \| "danger-full-access"	Filesystem/network sandbox for tool calls.
`default_permissions`	string	Named permissions profile (:read-only, :workspace, :danger-full-access, or custom).
`web_search`	"disabled" \| "cached" \| "live"	Web search mode (default cached).
`file_opener`	"vscode" \| "vscode-insiders" \| "windsurf" \| "cursor" \| "none"	URI scheme used to open citations from Codex output.

Examples

Common config.toml

model = "gpt-5.1-codex-max"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

•Project-scoped .codex/config.toml can't override provider, auth, notification, or telemetry keys.
•Install the Even Better TOML extension and add #:schema https://developers.openai.com/codex/config-schema.json for autocompletion.