# Codex OpenAI's coding agent for the terminal and IDE, configured through a single config.toml. Schema: 1.0 · Data: ee5de863c30bdbe4fe7dd3e07c7e22ea9bf4ab2248dbc7c35cdbf60bc28be1db ## Configuration ### MCP Status: supported MCP servers are defined as [mcp_servers.] tables in config.toml. Supports stdio and Streamable HTTP, with bearer-token and OAuth auth. - global: `~/.codex/config.toml` (toml) — key: mcp_servers - project: `.codex/config.toml` (toml) — key: mcp_servers — Trusted projects only. - `command`: string — Launcher command for a stdio server. - `args`: string[] — Arguments passed to the stdio command. - `env`: map — 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 — Static HTTP headers for each request. - `env_http_headers`: map — 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. - `default_tools_approval_mode`: "auto" | "prompt" | "writes" | "approve" — Server-wide approval default. add-mcp --auto-approve writes approve. Values: auto, prompt, writes, approve - `tools..approval_mode`: "auto" | "prompt" | "writes" | "approve" — Per-tool override of the server approval default. add-mcp --approve-tools writes approve for the selected tools. Values: auto, prompt, writes, approve - transports: stdio, http - auth: oauth, bearer-token, headers - Tools: supported - Server instructions: supported — Codex reads the MCP `instructions` field as server-wide guidance. - The CLI and IDE extension share this configuration. Manage servers with `codex mcp`. - Project-scoped .codex/config.toml is loaded only for trusted projects. stdio + Streamable HTTP servers ```toml [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" } ``` Source: https://developers.openai.com/codex/mcp Checked: 2026-09-07 ### Skills Status: supported SKILL.md skills following the open Agent Skills standard, discovered from .agents/skills up to the repo root. Invoke with $ or /skills. - project: `.agents/skills//SKILL.md` (markdown) — Scanned from CWD up to repo root. - global: `~/.agents/skills//SKILL.md` (markdown) — User skills applied across all repositories. - enterprise: `/etc/codex/skills//SKILL.md` (markdown) — Admin/system skills shared on the machine. - `name`: string (required) — Skill identifier. - `description`: string (required) — When the skill should and should not trigger. - invocation: $skill-name, /skills, implicit - 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. Minimal SKILL.md ```markdown --- name: skill-name description: Explain exactly when this skill should and should not trigger. --- Skill instructions for Codex to follow. ``` Source: https://developers.openai.com/codex/skills Checked: 2026-06-21 ### Rules Status: supported AGENTS.md instruction files, layered from the Codex home directory down to the working directory, with override files and configurable fallbacks. - project: `AGENTS.md` (markdown) — Project root down to CWD, including nested directories. AGENTS.override.md takes precedence. - global: `~/.codex/AGENTS.md` (markdown) — Global defaults inherited by every repository. ~/.codex/AGENTS.override.md for temporary overrides. - 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. Global guidance (~/.codex/AGENTS.md) ```markdown ## Working agreements - Always run `npm test` after modifying JavaScript files. - Prefer `pnpm` when installing dependencies. ``` Source: https://developers.openai.com/codex/guides/agents-md Checked: 2026-06-21 ### Hooks Status: 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. - global: `~/.codex/config.toml` (toml) — key: hooks — Inline [hooks] table, or a separate hooks.json. - project: `.codex/config.toml` (toml) — key: hooks — Trusted projects only. - `hooks.`: array — Matcher groups for a hook event. - `hooks.[].hooks`: array — Hook handlers for a matcher group (command hooks supported). - `hooks.[].hooks[].command`: string — Command to run for a command hook. - `hooks.[].hooks[].commandWindows`: string — Windows-only command override (alias command_windows). - events: PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SubagentStart, SubagentStop, UserPromptSubmit, Stop - 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. Source: https://developers.openai.com/codex/config-reference Checked: 2026-06-21 ### Commands Status: deprecated Custom prompts (~/.codex/prompts/*.md, invoked /prompts:name) were deprecated and removed in codex-cli 0.117.0. Convert custom prompts to Skills. - invocation: /prompts:name - Codex still ships built-in slash commands (/review, /fork, /plan, /diff, /compact, etc.). - For reusable custom workflows, author Skills instead. Source: https://developers.openai.com/codex/cli/features Checked: 2026-06-21 ### Settings Status: supported config.toml is the single settings file for models, reasoning, sandboxing, approvals, and tools. requirements.toml enforces admin policy. - global: `~/.codex/config.toml` (toml) - project: `.codex/config.toml` (toml) — Trusted projects only; provider/auth/telemetry keys are ignored here. - enterprise: `requirements.toml` (toml) — Admin-enforced constraints on security-sensitive settings. - `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. - 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. Common config.toml ```toml model = "gpt-5.1-codex-max" model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" ``` Source: https://developers.openai.com/codex/config-reference Checked: 2026-06-21 ## Search, browser & identification ### Codex desktop / optional agent-browser command / browse Tool: agent-browser (optional) - Observed September 6, 2026 on macOS arm64 with agent-browser 0.9.1 and HeadlessChrome/145.0.7632.6. - Installed tool invoked through shell by this Codex task; not a built-in Codex browser or hosted search signature. - Local headless navigation; two runs against controlled fixtures; no header overrides configured. - Accept header: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7 (observed; checked 2026-09-06). Exact observed navigation Accept header; wildcard acceptance is not an explicit Markdown preference. Source: [Codex optional agent-browser: two local runs](https://github.com/agent-tooling/clients-dev/blob/main/observations/codex-agent-browser.json) — records: /html, /negotiate, /redirect, /json; checks: #js text in both runs - User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/145.0.7632.6 Safari/537.36 (observed; checked 2026-09-06). Generic headless browser identity; no reliable Codex attribution rule follows from this. Source: [Codex optional agent-browser: two local runs](https://github.com/agent-tooling/clients-dev/blob/main/observations/codex-agent-browser.json) — records: /html, /negotiate, /redirect, /json; checks: #js text in both runs - Explicit Markdown preference: No (observed; checked 2026-09-06). No explicit text/markdown preference in these navigation requests. The negotiation fixture returned HTML. Source: [Codex optional agent-browser: two local runs](https://github.com/agent-tooling/clients-dev/blob/main/observations/codex-agent-browser.json) — records: /html, /negotiate, /redirect, /json; checks: #js text in both runs - JavaScript execution: Yes (observed; checked 2026-09-06). The rendered #js element changed from pending to executed in both runs. Source: [Codex optional agent-browser: two local runs](https://github.com/agent-tooling/clients-dev/blob/main/observations/codex-agent-browser.json) — records: /html, /negotiate, /redirect, /json; checks: #js text in both runs - Redirects: Followed same-origin 302 (observed; checked 2026-09-06). Navigation to /redirect reached the /html fixture in both runs. Source: [Codex optional agent-browser: two local runs](https://github.com/agent-tooling/clients-dev/blob/main/observations/codex-agent-browser.json) — records: /html, /negotiate, /redirect, /json; checks: #js text in both runs - Execution location: Local headless browser (observed; checked 2026-09-06). Browser was launched through the installed optional command-line tool. Source: [Codex optional agent-browser: two local runs](https://github.com/agent-tooling/clients-dev/blob/main/observations/codex-agent-browser.json) — records: /html, /negotiate, /redirect, /json; checks: #js text in both runs ### Codex / local chats / search Tool: codex-web-search (built-in) - Applies to hosted web search, separate from local command networking. - Default mode depends on permissions: cached normally, live with full access. - Documentation checked September 6, 2026; managed settings can restrict modes. - Search mode: cached, live, disabled, indexed (documented; checked 2026-09-06). Cached is the local default; full access defaults to live. Source: [OpenAI local web search](https://learn.chatgpt.com/docs/web-search) — Configure local web search - Provider: OpenAI-maintained index (cached mode) (documented; checked 2026-09-06). Cached mode uses the index rather than arbitrary live page fetches. Source: [OpenAI local web search](https://learn.chatgpt.com/docs/web-search) — Configure local web search - Execution location: Hosted tool (documented; checked 2026-09-06). Local sandbox networking and search controls are separate. Source: [OpenAI local web search](https://learn.chatgpt.com/docs/web-search) — Configure local web search - Accept header: Unknown (unknown). Not established by the reviewed official documentation. - Explicit Markdown preference: Unknown (unknown). Not established by the reviewed official documentation. - User-Agent: Unknown (unknown). Not established by the reviewed official documentation. - Custom headers: Unknown (unknown). Not established by the reviewed official documentation.