Codex Config Kit: config.toml Templates + Schema Checker

Ready config.toml files for OpenAI Codex and a checker that validates yours against the published Codex config schema, then flags risky and leaky settings. Python 3.9+, standard library only, works offline.

• templates/ (9 files, all schema-valid): - config.safe-default.toml: on-request approvals, workspace-write sandbox without network, cached web search, history cap, and 4 profiles (fast, deep, readonly, online). - config.ci-exec.toml: codex exec --profile ci for pipelines (approvals off, sandbox ON) and a read-only ci-review profile. - config.mcp-servers.toml: filesystem, GitHub (remote, bearer_token_env_var), Postgres (env_vars pass-through), Playwright (off until needed), a docs server with env_http_headers; pinned versions, tool allowlists, timeouts. - config.providers.toml: Azure OpenAI, OpenRouter, a LiteLLM proxy and local Ollama, each with a profile. - config.subagents.toml + agents/reviewer.toml, agents/tester.toml: thread limits, a cheaper default subagent model and two roles. - config.notify-hooks.toml: turn-finished notifications and hooks on. - config.container-full-auto.toml: no approvals and no sandbox, for disposable containers only (the checker flags it unless you pass --allow-full-auto).
• tools/codex_config_check.py: TOML syntax, then every key and value against schema/config-schema.json (OpenAI's published schema, vendored) with did-you-mean hints, then an audit.
• tools/explain.py: a table of the model, provider, effort, approvals, sandbox and web search each profile really ends up with.
• examples/broken-config.toml: 20 real-world mistakes to see the checker work. docs/cheatsheet.md: the keys people use most.

./tools/demo.sh

python3 tools/codex_config_check.py ~/.codex/config.toml
python3 tools/codex_config_check.py .codex/config.toml --json        # for CI

Schema errors: unknown keys (modle, startup_timeout, sandbox inside a profile) with the closest real key, wrong values from older docs (approval_policy = "on-failure", sandbox_mode = "workspace_write", wire_api = "chat"), wrong types and bounds, missing required keys (granular approvals). Audit: never + danger-full-access, never at the top level instead of a CI profile, network on in the sandbox, / or your home as a writable root, a profile that doesn't exist, an undefined model_provider, overriding a reserved provider id, literal tokens in env, http_headers, args or experimental_bearer_token, plain http to remote hosts, unpinned npx/uvx servers, a server with both command and url (or neither), trusting / or ~, and deprecated keys. Exit 1 on errors.

Newer Codex release? Point it at the live schema: --schema /path/to/config-schema.json (see schema/README.md).

Copy the parts you need into ~/.codex/config.toml (or a project's .codex/config.toml), run the checker, then codex --profile NAME. Compare profiles first:

python3 tools/explain.py ~/.codex/config.toml

./run_tests.sh runs 17 test cases (with sub-tests for every template): all 9 templates schema-valid and clean, the broken example triggers every rule (14 errors), schema validator behavior (granular approvals, types, bounds, nested did-you-mean, closed feature set, enums), secret detection with no false positive on env_vars, exit codes, profile resolution and the explain table. Python 3.13 and 3.10.

• The schema is OpenAI's file from 2026-11-13. Codex ships often; newer keys show as "unknown" until you pass a newer --schema.
• The validator implements the JSON Schema features this schema uses, not all of draft-07.
• The audit is opinionated hygiene, not a security review; a clean run doesn't make an unsafe workflow safe.
• Model names in templates are examples; use the models your account offers. Third-party endpoints (Azure, OpenRouter, LiteLLM) must support the Responses API.
• requirements.toml (admin policy) uses a different schema and isn't checked.