codex-cli-dispatch - SKILL.md Agent Skill

name: codex-cli-dispatch description: Dispatch coding and development tasks to Codex CLI (codex exec) in background with automatic callback/notification on completion. Use when the user asks to use Codex or Codex CLI for build, fix, review, refactor, or other long-running coding tasks.

Codex CLI Dispatch Skill

Dispatch development tasks to OpenAI's Codex CLI (codex exec) with automatic Telegram notification on completion.

When to Use

User asks to use Codex / OpenAI Codex to build, fix, or review code
User explicitly says "use Codex" or "codex cli"
Tasks that benefit from GPT-5.3-Codex model (OpenAI's coding agent)

Architecture

AGI (main session)
  → exec: dispatch.sh (background)
    → codex exec (headless, sandboxed)
    → on exit: notify via openclaw message send
    → write results to latest.json

Quick Reference

Dispatch a Task

bash /home/ubuntu/clawd/skills/codex-cli-dispatch/scripts/dispatch.sh \
  --prompt "Build a REST API with Express.js" \
  --task-name "express-api" \
  --workdir "/home/ubuntu/projects/express-api" \
  --telegram-group "-5006066016" \
  --model "gpt-5.3-codex" \
  --sandbox "workspace-write"

Parameters

Flag	Required	Default	Description
`--prompt`	Yes	—	Task instructions for Codex
`--task-name`	No	`codex-<timestamp>`	Human-readable task name
`--workdir`	No	`/home/ubuntu/clawd`	Working directory
`--telegram-group`	No	—	Telegram chat ID for notification
`--model`	No	(from config.toml)	Model override
`--sandbox`	No	`workspace-write`	`read-only`, `workspace-write`, or `danger-full-access`
`--full-auto`	No	true	Skip approvals (sandboxed)
`--image`	No	—	Image file(s) to attach

Dispatch Pattern (from AGI)

⚠️ MUST use nohup + background — dispatch.sh blocks until Codex finishes. Short exec timeout will SIGTERM the process.

# 1. Create project dir
mkdir -p /home/ubuntu/projects/my-project
cd /home/ubuntu/projects/my-project && git init

# 2. Dispatch (ALWAYS use nohup + &)
nohup bash /home/ubuntu/clawd/skills/codex-cli-dispatch/scripts/dispatch.sh \
  --prompt "..." \
  --task-name "my-task" \
  --workdir "/home/ubuntu/projects/my-project" \
  --telegram-group "-5006066016" \
  > /tmp/dispatch-codex.log 2>&1 &

Alternative: use exec with background=true so AGI doesn't block.

Result Files

File	Content
`data/codex-results/latest.json`	Last task result (task_name, output, status)
`data/codex-results/task-meta.json`	Task metadata (written before run)
`data/codex-results/task-output.txt`	Raw Codex output

⚠️ Critical Gotchas

Codex needs a git repo — Use --skip-git-repo-check or git init the workdir first
codex exec is headless — No PTY wrapper needed (unlike Claude Code), it exits cleanly
Sandbox modes matter — workspace-write is safe default; danger-full-access for system tasks only
Auth — Codex uses ~/.codex/config.toml credentials. Run codex login if auth fails
Model — Default is gpt-5.3-codex; can override with --model o3 etc.
Output format — Use --json for JSONL event stream if needed for parsing

Code Review Mode

Codex has a built-in code review:

codex exec review --full-auto -C /path/to/repo

⚠️ Critical Gotchas (continued)

Don't poll and wait! dispatch.sh is a blocking script. After starting it with exec background=true, do not process poll. The script will automatically send a Telegram notification when finished. Polling just wastes agent turns (lesson learned: a security scan task was polled 20+ times)
Long tasks may be OOM killed — Codex's gpt-5.3-codex reasoning mode is memory-intensive; long-running scan tasks may be killed by the system (SIGKILL). Consider splitting large tasks or reducing reasoning effort

Debugging

# Check Codex version
codex --version

# Check auth
cat ~/.codex/config.toml

# View last result
cat /home/ubuntu/clawd/data/codex-results/latest.json | jq .