Codex Troubleshooting skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Codex Troubleshooting"
  short_description: "From cryptic Codex error to named root cause"
  default_prompt: "$codex-troubleshooting Codex won't start after I updated it, here's the error"

# Detailed fixes by category

Read only the section that matches the classification from the main workflow.

## Config and layers

Resolution order, highest first: CLI flags and `-c` overrides; project
`.codex/config.toml` files from root to working directory (trusted projects only);
the profile file chosen with `--profile` (`~/.codex/<name>.config.toml`); user
`~/.codex/config.toml`; cloud-managed defaults; `/etc/codex/config.toml`; built-in
defaults. Admin requirements (`requirements.toml`, Agent Security, MDM) then constrain
the result and fall back to a compatible value with a notice.

Steps:

1. `/debug-config` and read the layer list bottom to top.
2. `codex exec --strict-config "say ok"` (or start the TUI with `--strict-config`) to
   get a file:line error for keys the installed version does not know (typos, keys
   from newer docs, removed keys). `codex doctor` does not flag unknown keys.
3. Check for `CODEX_HOME`: `echo $CODEX_HOME`. A non-default value means a different
   config, auth and sessions directory than the one you edited.
4. `-c` values are TOML: strings need inner quotes, e.g. `-c model='"gpt-6.1-sol"'`;
   unparseable values become literal strings, which can silently set the wrong type.
5. Legacy items to remove: `approval_policy = "untrusted"`, `[profiles.<name>]` tables
   and `profile = "<name>"` (since 0.134.0), `--full-auto` in scripts (use
   `--sandbox workspace-write` or `--approve-for-me`), `wire_api = "chat"`,
   `personality = "friendly"|"pragmatic"` (no longer selects a style).
6. Permission profiles and `sandbox_mode` do not compose: if any loaded layer sets
   `sandbox_mode` (or you pass `--sandbox`), `default_permissions` is ignored unless
   managed `allowed_permission_profiles` forces profiles.

## Authentication

- `codex login status` shows the active method. Workload-identity processes reject
  `codex login`/`codex logout` because the environment controls auth.
- Device code login (`codex login --device-auth`) must be enabled in ChatGPT security
  settings (personal) or workspace permissions (admin).
- Port forwarding fallback: the login callback listens on `localhost:1455`.
- Copying `~/.codex/auth.json` works only with file storage; with keyring storage the
  file may not exist.
- `forced_login_method` and `forced_chatgpt_workspace_id` can block a login that looks
  correct; check managed config.
- Corporate proxies: `CODEX_CA_CERTIFICATE` (takes precedence) or `SSL_CERT_FILE`
  pointing to a PEM bundle.
- MFA is required before Codex access if the account has email and password login.

## Models

- `codex debug models` renders the catalog the installed CLI uses; `/model` shows what
  the account can use.
- Some models require a minimum CLI version (GPT-6.1 Terra needs 0.159.0+).
- After a retirement, search every place a model id can hide:
  `rg -n 'model\s*=|--model|-m ' ~/.codex .codex .github scripts`.
- Custom agents (`.codex/agents/*.toml`) and scheduled tasks can pin models too.

## Sandbox and approvals

- Reproduce outside the agent: `codex sandbox <command>` (newer releases:
  `codex sandbox macos|linux|windows [--log-denials] <command>`); check
  `codex sandbox --help`.
- Writable roots: current workspace plus temp dirs; `--add-dir <dir>` adds more;
  `/status` lists them.
- Protected even when writable: `.git` (including a worktree's resolved git dir),
  `.agents`, `.codex`, `.aws`.
- macOS may prompt for access to Desktop, Documents, Downloads, Music: approve in the
  system dialog or keep work out of those folders.
- WSL1 is unsupported since 0.115 (Linux sandbox moved to `bwrap`); use WSL2.
- Windows: prefer MXC (`[features] prefer_mxc = true`) with `windows.sandbox =
  "elevated"` as fallback; `/setup-default-sandbox` sets up the elevated sandbox.
- "Approve for me" missing: check for `features.guardian_approval = false`, the
  approval policy and reviewer, and admin allowlists.
- With `-a never`, failures go straight back to the model; nothing is asked. Expect
  more failed commands, not escalations.

## Network

- Default: command network off in `workspace-write`.
- `sandbox_workspace_write.network_access = true` enables it; with
  `features.network_proxy` enabled, only allowlisted domains work.
- Domain rules alone do nothing without the proxy; the proxy alone does nothing when
  network access is off.
- Hostnames resolving to private IPs stay blocked unless explicitly allowed
  (`allow_local_binding = false` default). Local dev servers need an exact `localhost`
  or IP allow rule.
- Web search, MCP connections and model traffic do not go through the command proxy.
- When a managed environment allows a domain but it is still blocked, a
  higher-priority policy wins; compare effective policies rather than widening the
  global baseline.

## MCP servers

Checklist:

1. `codex mcp list`, then `codex mcp get <name>` for its effective config.
2. Run the exact `command` and `args` by hand in a terminal; it should wait silently on
   stdin. Anything printed to stdout that is not protocol JSON breaks the connection.
3. Timeouts: `startup_timeout_sec` (default 10), `tool_timeout_sec` (default 60);
   `mcp_optional_startup_grace_ms` (default 1000) is how long the initial tool catalog
   waits for optional servers.
4. Environment: stdio servers get `env` values and the variables named in `env_vars`.
5. HTTP servers: `bearer_token_env_var`, `http_headers`, `env_http_headers`, or OAuth
   via `codex mcp login <name>` (`--scopes` if needed).
6. Admin `mcp_servers` allowlists disable servers whose name and identity do not match.
7. Tool filters: `enabled_tools` then `disabled_tools`.
8. Too many tools or servers degrade tool choice and cost tokens; disable what the task
   does not need.

## Discovery: AGENTS.md, skills, hooks

- AGENTS.md: per directory, `AGENTS.override.md` beats `AGENTS.md` beats fallback
  names; empty files are skipped; chain capped by `project_doc_max_bytes` (32 KiB).
  Restart to pick up edits.
- Project root defaults to the nearest `.git`; `project_root_markers` changes it.
- Skills: `.agents/skills` from the working directory up to the repo root,
  `~/.agents/skills`, `/etc/codex/skills`, bundled. Folder name and `name:` should
  match. Disabled entries in `[[skills.config]]` hide a skill. If many skills are
  installed, descriptions are shortened and some may be omitted with a warning
  (`skills.max_context_tokens`, max 10000).
- Hooks: `features.hooks` must be on (default true); new or changed hooks need trust
  in `/hooks`; project hooks need a trusted project; `SessionStart` hooks can run
  before MCP servers are ready.

## Performance

| Cause | Check | Fix |
|---|---|---|
| High reasoning effort | `/status` | Lower effort for routine work |
| Huge context | `/status`, `codex debug prompt-input` size | Trim AGENTS.md, MCP servers, skills; `/compact` |
| Slow MCP start | doctor `mcp` row, logs | Pre-install packages, lower server count |
| Test loops | transcript | Ask for targeted tests first, full suite at the end |
| Background commands | `/ps` | `/stop` stuck terminals |
| Provider streaming stalls (custom provider) | logs | `stream_idle_timeout_ms`, `stream_max_retries` on the provider |
| Out-of-date CLI | `codex doctor` update note | `codex update` |