Use this for Codex app, CLI, plugin, MCP, hook, browser, connector, subagent, configuration, authentication, or local runtime issues.
This skill is docs-first. Do not rely on memory or local folklore when current Codex behavior could have changed.
Procedure
- Identify the affected Codex surface:
- app, CLI, IDE extension, web, plugin, MCP, hook, skill, subagent, browser, computer use, connector, auth, sandbox, permissions, automation, or logs
- Check current official OpenAI Codex docs for that surface.
- Prefer the OpenAI developer docs MCP when available.
- If the docs MCP is unavailable, use official OpenAI Codex docs only.
- Inspect local reality after the docs check:
codex --versioncodex doctorwhen broad install/runtime health is relevantcodex features listfor feature flagscodex plugin listand plugin marketplace state for plugin issuescodex mcp listfor MCP issues~/.codex/config.toml~/.codex/hooks.json- relevant app logs and session transcripts
- cached plugin paths only when cache/materialization is the suspected failure
- Separate layers before diagnosing:
- official documented behavior
- installed CLI/app version and feature flags
- local config
- plugin or MCP registration
- cache/materialized runtime files
- target app/browser/connector state
- If docs and local behavior disagree, report the mismatch and preserve uncertainty.
Guardrails
- Do not edit Codex config, hooks, plugins, or caches unless the user asked for a fix.
- Do not delete cache or host-state files without explicit approval.
- Do not assume a plugin list or tool listing proves connector authentication works; use read-only identity or resource checks when available.
- For browser issues, distinguish Codex in-app browser, Chrome extension, and Computer Use.
- For hooks, separate feature enablement from hook entry configuration.
Output
Return:
- observed facts
- official-doc grounding
- local evidence
- likely cause or clearly labeled hypotheses
- exact next fix or verification step