| name | codex-exec |
| description | Use when running Codex workers or validators non-interactively through codex exec with evidence.
Triggers: |
| skill_api_version | 1 |
| user-invocable | false |
| hexagonal_role | driving-adapter |
| practices | ["pragmatic-programmer","continuous-delivery"] |
| consumes | [] |
| produces | ["codex-run-output"] |
| context_rel | [{"kind":"supplier-to","with":"codex-sandbox-evidence"}] |
| context | {"window":"inherit","intent":{"mode":"none"},"sections":{"exclude":["HISTORY"]},"intel_scope":"none"} |
| metadata | {"tier":"orchestration","dependencies":["ntm","caam"],"stability":"stable","triggers":["codex exec","spawn a codex worker","run codex non-interactively","codex validator","headless codex","codex resume","drive codex from a script","factory worker on Codex"]} |
| output_contract | Runs codex exec on the OAuth/Pro sub; final agent message to stdout (or --output-last-message FILE / --json JSONL). |
codex-exec
Drive headless Codex worker and validator agents with codex exec on the ChatGPT Pro subscription (OAuth) — the Codex side of the flywheel. The one inviolable rule: subscription billing, never per-token API billing.
⚠️ Critical Constraints
- Never API-bill a worker. Do NOT set
OPENAI_API_KEY in a worker's env, and do NOT use codex login --with-api-key. Why: that flips Codex from flat-rate sub billing to per-token API billing — the Codex twin of the banned claude -p. A factory cycle on API keys silently burns real money. (Mirror of the "never claude -p for workers" rule.)
- WRONG:
OPENAI_API_KEY=sk-... codex exec -C "$REPO" "<task>"
- CORRECT:
codex login status # Logged in using ChatGPT then codex exec -C "$REPO" -s workspace-write "<task>"
- Confirm the sub before dispatch. Run
codex login status and require Logged in using ChatGPT. Why: a worker that "runs fine" on a leaked API token bills per token; the check is the only thing standing between a green run and a surprise invoice.
- Pick the sandbox deliberately.
-s read-only for validators, -s workspace-write for workers that must edit, -s danger-full-access only inside an already-sandboxed host. Why: codex exec runs model-generated shell commands; the sandbox is the blast radius.
--dangerously-bypass-approvals-and-sandbox is for externally-sandboxed hosts only. Why: it removes every guardrail in one flag; use it only when the OS/container is the sandbox.- Don't strand work in
--ephemeral. It skips session persistence, so there is nothing to resume. Why: a crashed ephemeral run cannot be recovered or continued.
- Multi-account lanes go through
caam, not env-var juggling. Why: caam exec codex <profile> -- keeps each Pro lane isolated; hand-setting CODEX_HOME invites cross-account token bleed.
Why This Exists
codex exec runs Codex non-interactively: it takes a prompt (argument or stdin), executes against a working directory under a sandbox policy, and prints the final agent message. It is the Codex analogue of an NTM Claude pane — the right tool for factory/loop workers and validators that need a second vendor lane.
