Codex CLI Reference: Hooks, Config, Permissions

Updated September 30, 2026 by Alex Sorokoletov

An independent reference for Codex CLI (OpenAI), with every table generated from the open-source repository at the v0.159.2 release tag and refreshed with each release. Each page answers the questions the official documentation leaves open: exact event order, payload fields, defaults, and what each setting blocks.

Pages

• Codex CLI Hooks Reference: All 12 Codex CLI hook events with stdin fields, stdout JSON, timeouts and matchers, plus hooks.json vs config.toml, exit code 2 blocking and the review prompt.
• Codex CLI Plugins Reference: Codex CLI plugin.json fields, what a plugin bundles (skills, MCP servers, apps, hooks), marketplace sources, codex plugin commands and Claude Code support.
• Codex CLI config.toml Reference: Codex CLI config.toml location and layer precedence, profiles, custom model providers and wire_api, MCP servers, every top-level key and every feature flag.
• Codex CLI Permissions and Sandbox Reference: Codex CLI sandbox modes, approval policies and permission profiles (:read-only, :workspace, :danger-full-access), which one wins, --yolo, requirements.toml.

Common Codex CLI questions

• Does Codex CLI have hooks like Claude Code?
• How do I enable hooks in Codex?
• Where do I put hooks.json for Codex?
• What is a Codex plugin?
• What is the difference between Codex plugins and skills?
• How do I install a Codex plugin from GitHub?
• Where is Codex config.toml located?
• What overrides config.toml?
• How do I add a custom model provider such as OpenRouter, Azure or a local model?
• What are Codex sandbox modes?
• What is the difference between sandbox mode and approval policy?
• How do I stop Codex from always asking for approval?

How these pages stay current

Tables on every page are regenerated from the Codex CLI source with each release: hook events and payload schemas, configuration keys with their types and defaults, and permission modes. The version and date under each title are the release the tables were read from. Prose explains behaviour the tables cannot show, such as the order events fire in and which exit codes block, and cites the exact source files it relies on. Where the OpenAI documentation and the code disagree, these pages follow the code and link both. Each page ends with a Sources list that links every file its tables were read from, pinned to the release tag, so any row can be checked against the exact code that shipped.

Release history

What changed in each Codex CLI release, including new hooks, settings and permission modes, is tracked in the Codex CLI version tracker.