{
  "schemaVersion": "1.0",
  "item": {
    "slug": "codex-skill",
    "name": "Codex Skill",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/feiskyer/codex-skill",
    "canonicalUrl": "https://clawhub.ai/feiskyer/codex-skill",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/codex-skill",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=codex-skill",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "slug": "codex-skill",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T17:26:35.918Z",
      "expiresAt": "2026-05-07T17:26:35.918Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=codex-skill",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=codex-skill",
        "contentDisposition": "attachment; filename=\"codex-skill-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "codex-skill"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/codex-skill"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/codex-skill",
    "agentPageUrl": "https://openagent3.xyz/skills/codex-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/codex-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/codex-skill/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Codex Agent Skill",
        "body": "Operate Codex CLI as a managed coding agent — from worktree setup through PR merge."
      },
      {
        "title": "Prerequisites",
        "body": "codex --version  # Verify installed\n# Install: npm i -g @openai/codex  or  brew install codex\ntmux -V          # tmux required for full workflow"
      },
      {
        "title": "CLI Quick Reference",
        "body": "FlagEffectexec \"prompt\"Non-interactive one-shot, exits when done--full-autoAlias for -s workspace-write (auto-approve file edits)-s workspace-writeRead + write files in workspace-s read-onlyAnalysis only, no modifications (default for exec)-s danger-full-accessFull access including network and system--dangerously-bypass-approvals-and-sandboxSkip all prompts + no sandbox (safe in containers/VMs)-m <model>Model selection — only use when user explicitly requests a model (e.g. gpt-5.1-codex-max). Omit to use Codex default.-c \"model_reasoning_effort=high\"Reasoning effort: low, medium, high--jsonStructured JSON Lines output-o <file>Write final output to file-C <dir> / --cd <dir>Set working directory--add-dir <dir>Allow writing to additional directories--skip-git-repo-checkRun in non-git directoriesresume --lastResume last session with new prompt"
      },
      {
        "title": "Quick Mode — Small Tasks",
        "body": "For trivial fixes, one-file changes, or analysis. Use exec (non-interactive):\n\n# Via OpenClaw exec — use background=true + pty=true, NO hard timeout\n# pty=true ensures codex CLI flushes output properly (no buffering issues)\n# (hard timeout kills the process; instead we poll and extend)\nexec(command=\"codex exec --full-auto 'fix the typo in README.md'\",\n     workdir=\"/path/to/project\", background=true, pty=true)\n\n# With high reasoning\nexec(command=\"codex exec -c 'model_reasoning_effort=high' --full-auto 'fix the auth bug'\",\n     workdir=\"/path/to/project\", background=true, pty=true)\n\nAdaptive Timeout (Poll-and-Extend)\n\nDo NOT use timeout= for codex tasks. Instead, use background execution\nwith periodic polling. This prevents premature kills on long-running tasks:\n\nLaunch with background=true (no timeout)\nPoll every ~5 min with process(action=\"poll\", sessionId=<id>, timeout=300000)\nIf process is still running → it's making progress, keep waiting\nIf process exited → check logs, done\nSafety net: if no new output for 12 hours, ask user before killing\n\nPoll loop (agent behavior, not a script):\n\n  poll_interval = 5 min (300000 ms)\n  max_silent_rounds = 144  (= 12 hours with no new output → ask user)\n\n  repeat:\n    result = process(action=\"poll\", sessionId=<id>, timeout=300000)\n    if result.completed:\n      → check exit code, read logs, report result\n      → break\n    else:\n      new_output = process(action=\"log\", sessionId=<id>, limit=20)\n      if new_output changed since last check:\n        silent_rounds = 0          # still producing output, keep going\n      else:\n        silent_rounds += 1\n      if silent_rounds >= max_silent_rounds:\n        → notify user: \"Codex has been silent for 12 hours, kill or keep waiting?\"\n        → wait for user decision\n\nThis way tasks that need 5 min or several hours both work without premature kills.\n\nQuick Mode caveats:\n\nSession output is held in memory only — lost on OpenClaw restart (no disk persistence).\nFor truly critical tasks, prefer Full Mode (tmux + log file).\nIn-memory output is capped by PI_BASH_MAX_OUTPUT_CHARS. Very verbose codex tasks may\nlose early output from process log. Use process log offset:0 limit:50 to check if\nthe beginning is still available; if not, the cap was hit.\nprocess is scoped per agent — you can only see sessions you started."
      },
      {
        "title": "Full Mode — Features, Bugfixes, Refactors",
        "body": "For non-trivial tasks, use the full workflow below. This gives you:\n\nIsolated worktree — no conflicts with other work\ntmux session — mid-task steering without killing the agent\nTask tracking — know what's running at all times\nQuality gates — Definition of Done checklist\nSmart retries — don't waste tokens on repeated failures"
      },
      {
        "title": "Step 1: Create Worktree",
        "body": "Isolate each task in its own worktree and branch:\n\nTASK_ID=\"feat-custom-templates\"\nBRANCH=\"feat/$TASK_ID\"\nREPO_ROOT=$(git rev-parse --show-toplevel)\nWORKTREE=\"/tmp/worktrees/$TASK_ID\"\n\ngit worktree add -b \"$BRANCH\" \"$WORKTREE\" origin/main\ncd \"$WORKTREE\"\n\n# Install dependencies (adapt to your stack)\npnpm install   # or: npm install / go mod tidy / pip install -r requirements.txt"
      },
      {
        "title": "Step 2: Launch Agent in tmux",
        "body": "Start Codex in interactive mode (no exec) so you can steer mid-task.\nImportant: Use tmux pipe-pane to log output — do NOT use | tee because it\nturns stdout into a pipe, which breaks interactive mode (codex detects !isatty(stdout)\nand may disable interactive features, breaking send-keys steering).\n\nLOG_FILE=\"/tmp/worktrees/$TASK_ID/codex-output.log\"\n\n# 1. Create session (starts a shell — codex not launched yet)\ntmux new-session -d -s \"$TASK_ID\" -c \"$WORKTREE\"\n\n# 2. Attach logging BEFORE launching codex — prevents losing early output\n#    stdbuf -oL = line-buffered writes, so tail -f shows progress in real time\n#    (plain cat buffers when writing to a file, causing monitoring lag)\ntmux pipe-pane -t \"$TASK_ID\" -o \"stdbuf -oL cat >> $LOG_FILE\"\n\n# 3. Launch codex via send-keys — all output captured from the start\n#    Exit code is appended to log on completion for reliable status detection\ntmux send-keys -t \"$TASK_ID\" \\\n  'codex -c \"model_reasoning_effort=high\" \\\n   --dangerously-bypass-approvals-and-sandbox \\\n   '\"'\"'Your detailed prompt here.\n\nWhen completely finished:\n1. Commit all changes with descriptive messages\n2. Push the branch: git push -u origin '\"$BRANCH\"'\n3. Create PR: gh pr create --fill\n4. Notify: openclaw system event --text \"Done: '\"$TASK_ID\"'\" --mode now'\"'\"' \\\n   ; echo \"CODEX_EXIT=$?\" >> '\"$LOG_FILE\" Enter\n\nWhy this order (session → pipe-pane → send-keys)?\n\nNo race condition — if you pass the command directly to tmux new-session, output\nproduced before pipe-pane attaches is lost from the log file\nExit code captured — echo \"CODEX_EXIT=$?\" appends the exit code to the log,\nso you can distinguish success from crash (otherwise tmux discards it on session close)\nLine-buffered logging — stdbuf -oL ensures tail -f $LOG_FILE works in real time\n\nWhy interactive mode (no exec)?\n\nAllows mid-task steering via tmux send-keys\nAgent can be redirected without killing and restarting\n--dangerously-bypass-approvals-and-sandbox is safe in container/sandbox environments"
      },
      {
        "title": "Step 3: Register Task",
        "body": "Track all active tasks in a JSON registry:\n\nmkdir -p \"$REPO_ROOT/.clawd\"\nTASKS_FILE=\"$REPO_ROOT/.clawd/active-tasks.json\"\n\n# Initialize if not exists\n[ -f \"$TASKS_FILE\" ] || echo '{\"tasks\":[]}' > \"$TASKS_FILE\"\n\n# Register\njq --arg id \"$TASK_ID\" --arg branch \"$BRANCH\" --arg wt \"$WORKTREE\" \\\n  '.tasks += [{\n    \"id\": $id,\n    \"agent\": \"codex\",\n    \"branch\": $branch,\n    \"worktree\": $wt,\n    \"tmuxSession\": $id,\n    \"status\": \"running\",\n    \"startedAt\": (now|floor),\n    \"pr\": null,\n    \"retries\": 0,\n    \"checks\": {}\n  }]' \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\""
      },
      {
        "title": "Step 4: Monitor & Steer",
        "body": "# --- Status check ---\n\n# Is the agent still running?\ntmux has-session -t \"$TASK_ID\" 2>/dev/null && echo \"running\" || echo \"done\"\n\n# Check exit code (if agent finished — written by the exit-code capture in Step 2)\ngrep \"CODEX_EXIT=\" \"/tmp/worktrees/$TASK_ID/codex-output.log\"\n\n# --- Reading output ---\n\n# Use the LOG FILE, not capture-pane, for long-running tasks.\n# tmux capture-pane only holds ~2000 lines of scrollback — earlier output is silently\n# dropped. The log file (via pipe-pane) retains everything.\n\n# View recent output (clean — strips ANSI escape codes from colors/spinners)\nsed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"/tmp/worktrees/$TASK_ID/codex-output.log\" | tail -100\n\n# Follow output in real time (works because of stdbuf -oL in Step 2)\ntail -f \"/tmp/worktrees/$TASK_ID/codex-output.log\"\n\n# Search for errors (strip ANSI first for clean grep results)\nsed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"/tmp/worktrees/$TASK_ID/codex-output.log\" \\\n  | grep -i \"error\\|fail\\|panic\"\n\n# Quick glance via tmux pane (fine for short tasks, unreliable for long ones)\ntmux capture-pane -t \"$TASK_ID\" -p -S -50\n\n# --- Detecting stuck agents ---\n\n# Check if codex is making file changes (no changes for a long time → may be stuck)\ngit -C \"$WORKTREE\" status --short\n\n# Check if the same error appears repeatedly (loop detection)\nsed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"/tmp/worktrees/$TASK_ID/codex-output.log\" \\\n  | grep -i \"error\" | sort | uniq -c | sort -rn | head -5\n\n# --- Mid-task steering (DON'T kill — redirect!) ---\n\n# Agent going the wrong direction?\ntmux send-keys -t \"$TASK_ID\" \"Stop. Focus on the API layer first, not the UI.\" Enter\n\n# Agent missing context?\ntmux send-keys -t \"$TASK_ID\" \"The schema is in src/types/template.ts. Use that.\" Enter\n\n# Agent's context window filling up?\ntmux send-keys -t \"$TASK_ID\" \"Focus only on these 3 files: api.ts, handler.ts, types.ts\" Enter\n\n# Agent needs test guidance?\ntmux send-keys -t \"$TASK_ID\" \"Run 'npm test -- --grep auth' to verify your changes.\" Enter\n\nMonitoring cadence: Check every 5–10 minutes, not every 30 seconds. Agents need time to work."
      },
      {
        "title": "Step 5: Definition of Done",
        "body": "A PR is NOT ready for review until all checks pass:\n\n✅ PR created              → gh pr list --head \"$BRANCH\"\n✅ No merge conflicts       → gh pr view $PR_NUM --json mergeable -q '.mergeable'\n✅ CI passing               → gh pr checks $PR_NUM\n✅ AI code review passed    → at least one cross-model review (see Step 6)\n✅ UI screenshots included  → (if applicable) screenshot in PR description\n\nQuick inline check:\n\nPR_NUM=$(gh pr list --head \"$BRANCH\" --json number -q '.[0].number')\necho \"PR: #$PR_NUM\"\ngh pr checks \"$PR_NUM\"\ngh pr view \"$PR_NUM\" --json mergeable -q '.mergeable'"
      },
      {
        "title": "Step 6: Multi-Model Code Review",
        "body": "Review with a different model than the one that wrote the code. Different models catch different issues:\n\nDIFF=$(gh pr diff \"$PR_NUM\")\n\n# Option A: Claude reviews Codex's code (best for security & overengineering checks)\necho \"$DIFF\" | claude -p \\\n  --append-system-prompt \"You are a senior code reviewer. Be concise, flag only real issues.\" \\\n  \"Review this PR diff. Focus on: bugs, edge cases, missing error handling,\n   race conditions, security issues. Cite file and line numbers.\n   Output: list of issues with severity (critical/warning/info).\"\n\n# Option B: Different Codex model reviews with analysis focus\necho \"$DIFF\" | codex exec -s read-only \\\n  \"Review this PR diff for logic errors, performance issues, and missing tests.\"\n\nPost review results to PR:\n\ngh pr comment \"$PR_NUM\" --body \"## AI Code Review\n\n$REVIEW_OUTPUT\"\n\nUpdate task registry:\n\njq --arg id \"$TASK_ID\" \\\n  '(.tasks[] | select(.id == $id)).checks.codeReviewPassed = true' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\""
      },
      {
        "title": "Step 7: Notify",
        "body": "If you included the notify command in the agent prompt (Step 2), the agent self-notifies on completion.\n\nOtherwise, notify after DoD passes:\n\nopenclaw system event --text \"✅ PR #$PR_NUM ready for review: $TASK_ID — all checks passed\" --mode now\n\nUpdate task status:\n\njq --arg id \"$TASK_ID\" --argjson pr \"$PR_NUM\" \\\n  '(.tasks[] | select(.id == $id)) |= (.status = \"done\" | .pr = $pr | .completedAt = (now|floor))' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\""
      },
      {
        "title": "Step 8: Cleanup",
        "body": "After PR is merged:\n\ngit worktree remove \"$WORKTREE\" 2>/dev/null\ngit branch -d \"$BRANCH\" 2>/dev/null\n\n# Remove from registry\njq --arg id \"$TASK_ID\" '.tasks = [.tasks[] | select(.id != $id)]' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\""
      },
      {
        "title": "Smart Retry Strategy",
        "body": "When an agent fails, analyze the failure and adapt the prompt — don't just re-run blindly.\n\nFailure TypeSymptomRetry StrategyContext overflowAgent loops, produces garbage, or stops mid-taskNarrow scope: \"Focus only on files X, Y, Z\"Wrong directionAgent implements something unrelated to intentCorrect intent: \"Stop. Customer wanted X, not Y. Spec: ...\"Missing infoAgent makes wrong assumptions about architectureAdd context: \"Auth uses JWT, see src/auth/jwt.ts\"CI failureTests, lint, or typecheck fail after PRAttach CI log: \"Fix these test failures: ...\"Build failureDependencies missing or incompatiblePre-install deps before retry\n\nMax 3 retries. After that, escalate to human.\n\nRETRY=$((RETRY + 1))\nif [ \"$RETRY\" -gt 3 ]; then\n  openclaw system event --text \"🚨 BLOCKED: $TASK_ID failed after 3 retries — needs human help\" --mode now\n  jq --arg id \"$TASK_ID\" '(.tasks[] | select(.id == $id)).status = \"blocked\"' \\\n    \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\"\n  exit 1\nfi\n\n# Capture what went wrong — strip ANSI codes for clean error text\nLOG_FILE=\"/tmp/worktrees/$TASK_ID/codex-output.log\"\nif [ -f \"$LOG_FILE\" ]; then\n  FAILURE_LOG=$(sed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"$LOG_FILE\" | tail -500)\nelse\n  FAILURE_LOG=$(tmux capture-pane -t \"$TASK_ID\" -p -S -200)\nfi\nCI_LOG=$(gh pr checks \"$PR_NUM\" 2>/dev/null || echo \"no PR yet\")\ntmux kill-session -t \"$TASK_ID\" 2>/dev/null\n\n# Mark retry boundary in log (so retries don't blend together)\necho \"=== RETRY $RETRY — $(date -Iseconds) ===\" >> \"$LOG_FILE\"\n\n# Respawn: session first, pipe-pane second, send-keys third (same pattern as Step 2)\ntmux new-session -d -s \"$TASK_ID\" -c \"$WORKTREE\"\ntmux pipe-pane -t \"$TASK_ID\" -o \"stdbuf -oL cat >> $LOG_FILE\"\ntmux send-keys -t \"$TASK_ID\" \\\n  'codex -c \"model_reasoning_effort=high\" \\\n   --dangerously-bypass-approvals-and-sandbox \\\n   '\"'\"'Previous attempt failed. Error output:\n'\"$FAILURE_LOG\"'\n\nCI status: '\"$CI_LOG\"'\n\nFix the issues above and complete the original task.\n[...your enriched instructions here...]\n\nWhen done: commit, push, gh pr create --fill, then run:\nopenclaw system event --text \"Done: '\"$TASK_ID\"' (retry '\"$RETRY\"')\" --mode now'\"'\"' \\\n   ; echo \"CODEX_EXIT=$?\" >> '\"$LOG_FILE\" Enter\n\n# Update registry\njq --arg id \"$TASK_ID\" --argjson r \"$RETRY\" \\\n  '(.tasks[] | select(.id == $id)) |= (.retries = $r | .status = \"running\")' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\""
      },
      {
        "title": "Parallel Execution",
        "body": "Run multiple agents simultaneously on different tasks:\n\n# Helper: launch codex in tmux with proper logging (session → pipe-pane → send-keys)\nlaunch_codex() {\n  local TASK=\"$1\" WORKDIR=\"$2\" PROMPT=\"$3\"\n  local LOG=\"$WORKDIR/codex-output.log\"\n  tmux new-session -d -s \"$TASK\" -c \"$WORKDIR\"\n  tmux pipe-pane -t \"$TASK\" -o \"stdbuf -oL cat >> $LOG\"\n  tmux send-keys -t \"$TASK\" \\\n    \"pnpm install && codex --dangerously-bypass-approvals-and-sandbox '$PROMPT'; echo \\\"CODEX_EXIT=\\$?\\\" >> $LOG\" Enter\n}\n\n# Task 1: Feature\ngit worktree add -b feat/auth /tmp/worktrees/feat-auth origin/main\nlaunch_codex feat-auth /tmp/worktrees/feat-auth \"Implement JWT auth...\"\n\n# Task 2: Bugfix\ngit worktree add -b fix/payments /tmp/worktrees/fix-payments origin/main\nlaunch_codex fix-payments /tmp/worktrees/fix-payments \"Fix payment webhook...\"\n\n# Dashboard: check all agents (use log files, not capture-pane, for reliable output)\ntmux ls\nfor s in $(tmux ls -F '#{session_name}' 2>/dev/null); do\n  LOG=\"/tmp/worktrees/$s/codex-output.log\"\n  echo \"=== $s ===\"\n  if tmux has-session -t \"$s\" 2>/dev/null; then\n    sed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"$LOG\" 2>/dev/null | tail -5 || echo \"(no log yet)\"\n  else\n    EXIT=$(grep \"CODEX_EXIT=\" \"$LOG\" 2>/dev/null | tail -1)\n    echo \"(exited) ${EXIT:-exit code unknown}\"\n  fi\ndone"
      },
      {
        "title": "Reasoning Effort",
        "body": "Control how much the model \"thinks\" before acting:\n\n# High — for complex logic, multi-file refactors\ncodex -c \"model_reasoning_effort=high\" --full-auto \"refactor auth module\"\n\n# Medium — balanced (default)\ncodex exec --full-auto \"add input validation\"\n\n# Low — for trivial/mechanical changes\ncodex -c \"model_reasoning_effort=low\" --full-auto \"rename all instances of foo to bar\""
      },
      {
        "title": "Sandbox Modes",
        "body": "ModeUse Caseread-onlyCode review, analysis, documentationworkspace-write / --full-autoFeature implementation, bug fixes, refactorsdanger-full-accessInstalling dependencies, network access needed--dangerously-bypass-approvals-and-sandboxFull auto in containers (recommended for tmux workflow)"
      },
      {
        "title": "JSON Output",
        "body": "# Structured output for programmatic processing\ncodex exec --full-auto --json \"implement and test the feature\"\n\n# Save to file\ncodex exec --full-auto -o results.txt \"run analysis\""
      },
      {
        "title": "Resume Session",
        "body": "# Resume last session with a follow-up task\ncodex exec resume --last \"now add tests for the feature you just built\""
      },
      {
        "title": "Prompt Quality",
        "body": "Include file paths: \"The entry point is src/index.ts, config in src/config/\"\nInclude schemas/types: Paste relevant type definitions into the prompt\nInclude test commands: \"Verify with: npm test -- --grep auth\"\nInclude commit convention: \"Use conventional commits: feat:, fix:, chore:\"\nInclude error logs: When retrying, always attach the failure output"
      },
      {
        "title": "Scope Management",
        "body": "One task per agent — don't ask for \"refactor everything\"\nPre-install dependencies before launching the agent\nBe specific — \"Add rate limiting to POST /api/users\" not \"improve the API\"\nUse high reasoning effort for complex tasks, low for mechanical ones"
      },
      {
        "title": "When to Interrupt (Ask Human)",
        "body": "Destructive operations (drop tables, force push main)\nSecurity decisions (expose credentials, change auth)\nAmbiguous requirements with significant trade-offs\nAll other decisions: proceed autonomously"
      }
    ],
    "body": "Codex Agent Skill\n\nOperate Codex CLI as a managed coding agent — from worktree setup through PR merge.\n\nPrerequisites\ncodex --version  # Verify installed\n# Install: npm i -g @openai/codex  or  brew install codex\ntmux -V          # tmux required for full workflow\n\nCLI Quick Reference\nFlag\tEffect\nexec \"prompt\"\tNon-interactive one-shot, exits when done\n--full-auto\tAlias for -s workspace-write (auto-approve file edits)\n-s workspace-write\tRead + write files in workspace\n-s read-only\tAnalysis only, no modifications (default for exec)\n-s danger-full-access\tFull access including network and system\n--dangerously-bypass-approvals-and-sandbox\tSkip all prompts + no sandbox (safe in containers/VMs)\n-m <model>\tModel selection — only use when user explicitly requests a model (e.g. gpt-5.1-codex-max). Omit to use Codex default.\n-c \"model_reasoning_effort=high\"\tReasoning effort: low, medium, high\n--json\tStructured JSON Lines output\n-o <file>\tWrite final output to file\n-C <dir> / --cd <dir>\tSet working directory\n--add-dir <dir>\tAllow writing to additional directories\n--skip-git-repo-check\tRun in non-git directories\nresume --last\tResume last session with new prompt\nExecution Modes\nQuick Mode — Small Tasks\n\nFor trivial fixes, one-file changes, or analysis. Use exec (non-interactive):\n\n# Via OpenClaw exec — use background=true + pty=true, NO hard timeout\n# pty=true ensures codex CLI flushes output properly (no buffering issues)\n# (hard timeout kills the process; instead we poll and extend)\nexec(command=\"codex exec --full-auto 'fix the typo in README.md'\",\n     workdir=\"/path/to/project\", background=true, pty=true)\n\n# With high reasoning\nexec(command=\"codex exec -c 'model_reasoning_effort=high' --full-auto 'fix the auth bug'\",\n     workdir=\"/path/to/project\", background=true, pty=true)\n\nAdaptive Timeout (Poll-and-Extend)\n\nDo NOT use timeout= for codex tasks. Instead, use background execution with periodic polling. This prevents premature kills on long-running tasks:\n\nLaunch with background=true (no timeout)\nPoll every ~5 min with process(action=\"poll\", sessionId=<id>, timeout=300000)\nIf process is still running → it's making progress, keep waiting\nIf process exited → check logs, done\nSafety net: if no new output for 12 hours, ask user before killing\nPoll loop (agent behavior, not a script):\n\n  poll_interval = 5 min (300000 ms)\n  max_silent_rounds = 144  (= 12 hours with no new output → ask user)\n\n  repeat:\n    result = process(action=\"poll\", sessionId=<id>, timeout=300000)\n    if result.completed:\n      → check exit code, read logs, report result\n      → break\n    else:\n      new_output = process(action=\"log\", sessionId=<id>, limit=20)\n      if new_output changed since last check:\n        silent_rounds = 0          # still producing output, keep going\n      else:\n        silent_rounds += 1\n      if silent_rounds >= max_silent_rounds:\n        → notify user: \"Codex has been silent for 12 hours, kill or keep waiting?\"\n        → wait for user decision\n\n\nThis way tasks that need 5 min or several hours both work without premature kills.\n\nQuick Mode caveats:\n\nSession output is held in memory only — lost on OpenClaw restart (no disk persistence). For truly critical tasks, prefer Full Mode (tmux + log file).\nIn-memory output is capped by PI_BASH_MAX_OUTPUT_CHARS. Very verbose codex tasks may lose early output from process log. Use process log offset:0 limit:50 to check if the beginning is still available; if not, the cap was hit.\nprocess is scoped per agent — you can only see sessions you started.\nFull Mode — Features, Bugfixes, Refactors\n\nFor non-trivial tasks, use the full workflow below. This gives you:\n\nIsolated worktree — no conflicts with other work\ntmux session — mid-task steering without killing the agent\nTask tracking — know what's running at all times\nQuality gates — Definition of Done checklist\nSmart retries — don't waste tokens on repeated failures\nFull Workflow: Task → Merged PR\nStep 1: Create Worktree\n\nIsolate each task in its own worktree and branch:\n\nTASK_ID=\"feat-custom-templates\"\nBRANCH=\"feat/$TASK_ID\"\nREPO_ROOT=$(git rev-parse --show-toplevel)\nWORKTREE=\"/tmp/worktrees/$TASK_ID\"\n\ngit worktree add -b \"$BRANCH\" \"$WORKTREE\" origin/main\ncd \"$WORKTREE\"\n\n# Install dependencies (adapt to your stack)\npnpm install   # or: npm install / go mod tidy / pip install -r requirements.txt\n\nStep 2: Launch Agent in tmux\n\nStart Codex in interactive mode (no exec) so you can steer mid-task. Important: Use tmux pipe-pane to log output — do NOT use | tee because it turns stdout into a pipe, which breaks interactive mode (codex detects !isatty(stdout) and may disable interactive features, breaking send-keys steering).\n\nLOG_FILE=\"/tmp/worktrees/$TASK_ID/codex-output.log\"\n\n# 1. Create session (starts a shell — codex not launched yet)\ntmux new-session -d -s \"$TASK_ID\" -c \"$WORKTREE\"\n\n# 2. Attach logging BEFORE launching codex — prevents losing early output\n#    stdbuf -oL = line-buffered writes, so tail -f shows progress in real time\n#    (plain cat buffers when writing to a file, causing monitoring lag)\ntmux pipe-pane -t \"$TASK_ID\" -o \"stdbuf -oL cat >> $LOG_FILE\"\n\n# 3. Launch codex via send-keys — all output captured from the start\n#    Exit code is appended to log on completion for reliable status detection\ntmux send-keys -t \"$TASK_ID\" \\\n  'codex -c \"model_reasoning_effort=high\" \\\n   --dangerously-bypass-approvals-and-sandbox \\\n   '\"'\"'Your detailed prompt here.\n\nWhen completely finished:\n1. Commit all changes with descriptive messages\n2. Push the branch: git push -u origin '\"$BRANCH\"'\n3. Create PR: gh pr create --fill\n4. Notify: openclaw system event --text \"Done: '\"$TASK_ID\"'\" --mode now'\"'\"' \\\n   ; echo \"CODEX_EXIT=$?\" >> '\"$LOG_FILE\" Enter\n\n\nWhy this order (session → pipe-pane → send-keys)?\n\nNo race condition — if you pass the command directly to tmux new-session, output produced before pipe-pane attaches is lost from the log file\nExit code captured — echo \"CODEX_EXIT=$?\" appends the exit code to the log, so you can distinguish success from crash (otherwise tmux discards it on session close)\nLine-buffered logging — stdbuf -oL ensures tail -f $LOG_FILE works in real time\n\nWhy interactive mode (no exec)?\n\nAllows mid-task steering via tmux send-keys\nAgent can be redirected without killing and restarting\n--dangerously-bypass-approvals-and-sandbox is safe in container/sandbox environments\nStep 3: Register Task\n\nTrack all active tasks in a JSON registry:\n\nmkdir -p \"$REPO_ROOT/.clawd\"\nTASKS_FILE=\"$REPO_ROOT/.clawd/active-tasks.json\"\n\n# Initialize if not exists\n[ -f \"$TASKS_FILE\" ] || echo '{\"tasks\":[]}' > \"$TASKS_FILE\"\n\n# Register\njq --arg id \"$TASK_ID\" --arg branch \"$BRANCH\" --arg wt \"$WORKTREE\" \\\n  '.tasks += [{\n    \"id\": $id,\n    \"agent\": \"codex\",\n    \"branch\": $branch,\n    \"worktree\": $wt,\n    \"tmuxSession\": $id,\n    \"status\": \"running\",\n    \"startedAt\": (now|floor),\n    \"pr\": null,\n    \"retries\": 0,\n    \"checks\": {}\n  }]' \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\"\n\nStep 4: Monitor & Steer\n# --- Status check ---\n\n# Is the agent still running?\ntmux has-session -t \"$TASK_ID\" 2>/dev/null && echo \"running\" || echo \"done\"\n\n# Check exit code (if agent finished — written by the exit-code capture in Step 2)\ngrep \"CODEX_EXIT=\" \"/tmp/worktrees/$TASK_ID/codex-output.log\"\n\n# --- Reading output ---\n\n# Use the LOG FILE, not capture-pane, for long-running tasks.\n# tmux capture-pane only holds ~2000 lines of scrollback — earlier output is silently\n# dropped. The log file (via pipe-pane) retains everything.\n\n# View recent output (clean — strips ANSI escape codes from colors/spinners)\nsed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"/tmp/worktrees/$TASK_ID/codex-output.log\" | tail -100\n\n# Follow output in real time (works because of stdbuf -oL in Step 2)\ntail -f \"/tmp/worktrees/$TASK_ID/codex-output.log\"\n\n# Search for errors (strip ANSI first for clean grep results)\nsed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"/tmp/worktrees/$TASK_ID/codex-output.log\" \\\n  | grep -i \"error\\|fail\\|panic\"\n\n# Quick glance via tmux pane (fine for short tasks, unreliable for long ones)\ntmux capture-pane -t \"$TASK_ID\" -p -S -50\n\n# --- Detecting stuck agents ---\n\n# Check if codex is making file changes (no changes for a long time → may be stuck)\ngit -C \"$WORKTREE\" status --short\n\n# Check if the same error appears repeatedly (loop detection)\nsed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"/tmp/worktrees/$TASK_ID/codex-output.log\" \\\n  | grep -i \"error\" | sort | uniq -c | sort -rn | head -5\n\n# --- Mid-task steering (DON'T kill — redirect!) ---\n\n# Agent going the wrong direction?\ntmux send-keys -t \"$TASK_ID\" \"Stop. Focus on the API layer first, not the UI.\" Enter\n\n# Agent missing context?\ntmux send-keys -t \"$TASK_ID\" \"The schema is in src/types/template.ts. Use that.\" Enter\n\n# Agent's context window filling up?\ntmux send-keys -t \"$TASK_ID\" \"Focus only on these 3 files: api.ts, handler.ts, types.ts\" Enter\n\n# Agent needs test guidance?\ntmux send-keys -t \"$TASK_ID\" \"Run 'npm test -- --grep auth' to verify your changes.\" Enter\n\n\nMonitoring cadence: Check every 5–10 minutes, not every 30 seconds. Agents need time to work.\n\nStep 5: Definition of Done\n\nA PR is NOT ready for review until all checks pass:\n\n✅ PR created              → gh pr list --head \"$BRANCH\"\n✅ No merge conflicts       → gh pr view $PR_NUM --json mergeable -q '.mergeable'\n✅ CI passing               → gh pr checks $PR_NUM\n✅ AI code review passed    → at least one cross-model review (see Step 6)\n✅ UI screenshots included  → (if applicable) screenshot in PR description\n\n\nQuick inline check:\n\nPR_NUM=$(gh pr list --head \"$BRANCH\" --json number -q '.[0].number')\necho \"PR: #$PR_NUM\"\ngh pr checks \"$PR_NUM\"\ngh pr view \"$PR_NUM\" --json mergeable -q '.mergeable'\n\nStep 6: Multi-Model Code Review\n\nReview with a different model than the one that wrote the code. Different models catch different issues:\n\nDIFF=$(gh pr diff \"$PR_NUM\")\n\n# Option A: Claude reviews Codex's code (best for security & overengineering checks)\necho \"$DIFF\" | claude -p \\\n  --append-system-prompt \"You are a senior code reviewer. Be concise, flag only real issues.\" \\\n  \"Review this PR diff. Focus on: bugs, edge cases, missing error handling,\n   race conditions, security issues. Cite file and line numbers.\n   Output: list of issues with severity (critical/warning/info).\"\n\n# Option B: Different Codex model reviews with analysis focus\necho \"$DIFF\" | codex exec -s read-only \\\n  \"Review this PR diff for logic errors, performance issues, and missing tests.\"\n\n\nPost review results to PR:\n\ngh pr comment \"$PR_NUM\" --body \"## AI Code Review\n\n$REVIEW_OUTPUT\"\n\n\nUpdate task registry:\n\njq --arg id \"$TASK_ID\" \\\n  '(.tasks[] | select(.id == $id)).checks.codeReviewPassed = true' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\"\n\nStep 7: Notify\n\nIf you included the notify command in the agent prompt (Step 2), the agent self-notifies on completion.\n\nOtherwise, notify after DoD passes:\n\nopenclaw system event --text \"✅ PR #$PR_NUM ready for review: $TASK_ID — all checks passed\" --mode now\n\n\nUpdate task status:\n\njq --arg id \"$TASK_ID\" --argjson pr \"$PR_NUM\" \\\n  '(.tasks[] | select(.id == $id)) |= (.status = \"done\" | .pr = $pr | .completedAt = (now|floor))' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\"\n\nStep 8: Cleanup\n\nAfter PR is merged:\n\ngit worktree remove \"$WORKTREE\" 2>/dev/null\ngit branch -d \"$BRANCH\" 2>/dev/null\n\n# Remove from registry\njq --arg id \"$TASK_ID\" '.tasks = [.tasks[] | select(.id != $id)]' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\"\n\nSmart Retry Strategy\n\nWhen an agent fails, analyze the failure and adapt the prompt — don't just re-run blindly.\n\nFailure Type\tSymptom\tRetry Strategy\nContext overflow\tAgent loops, produces garbage, or stops mid-task\tNarrow scope: \"Focus only on files X, Y, Z\"\nWrong direction\tAgent implements something unrelated to intent\tCorrect intent: \"Stop. Customer wanted X, not Y. Spec: ...\"\nMissing info\tAgent makes wrong assumptions about architecture\tAdd context: \"Auth uses JWT, see src/auth/jwt.ts\"\nCI failure\tTests, lint, or typecheck fail after PR\tAttach CI log: \"Fix these test failures: ...\"\nBuild failure\tDependencies missing or incompatible\tPre-install deps before retry\n\nMax 3 retries. After that, escalate to human.\n\nRETRY=$((RETRY + 1))\nif [ \"$RETRY\" -gt 3 ]; then\n  openclaw system event --text \"🚨 BLOCKED: $TASK_ID failed after 3 retries — needs human help\" --mode now\n  jq --arg id \"$TASK_ID\" '(.tasks[] | select(.id == $id)).status = \"blocked\"' \\\n    \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\"\n  exit 1\nfi\n\n# Capture what went wrong — strip ANSI codes for clean error text\nLOG_FILE=\"/tmp/worktrees/$TASK_ID/codex-output.log\"\nif [ -f \"$LOG_FILE\" ]; then\n  FAILURE_LOG=$(sed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"$LOG_FILE\" | tail -500)\nelse\n  FAILURE_LOG=$(tmux capture-pane -t \"$TASK_ID\" -p -S -200)\nfi\nCI_LOG=$(gh pr checks \"$PR_NUM\" 2>/dev/null || echo \"no PR yet\")\ntmux kill-session -t \"$TASK_ID\" 2>/dev/null\n\n# Mark retry boundary in log (so retries don't blend together)\necho \"=== RETRY $RETRY — $(date -Iseconds) ===\" >> \"$LOG_FILE\"\n\n# Respawn: session first, pipe-pane second, send-keys third (same pattern as Step 2)\ntmux new-session -d -s \"$TASK_ID\" -c \"$WORKTREE\"\ntmux pipe-pane -t \"$TASK_ID\" -o \"stdbuf -oL cat >> $LOG_FILE\"\ntmux send-keys -t \"$TASK_ID\" \\\n  'codex -c \"model_reasoning_effort=high\" \\\n   --dangerously-bypass-approvals-and-sandbox \\\n   '\"'\"'Previous attempt failed. Error output:\n'\"$FAILURE_LOG\"'\n\nCI status: '\"$CI_LOG\"'\n\nFix the issues above and complete the original task.\n[...your enriched instructions here...]\n\nWhen done: commit, push, gh pr create --fill, then run:\nopenclaw system event --text \"Done: '\"$TASK_ID\"' (retry '\"$RETRY\"')\" --mode now'\"'\"' \\\n   ; echo \"CODEX_EXIT=$?\" >> '\"$LOG_FILE\" Enter\n\n# Update registry\njq --arg id \"$TASK_ID\" --argjson r \"$RETRY\" \\\n  '(.tasks[] | select(.id == $id)) |= (.retries = $r | .status = \"running\")' \\\n  \"$TASKS_FILE\" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json \"$TASKS_FILE\"\n\nParallel Execution\n\nRun multiple agents simultaneously on different tasks:\n\n# Helper: launch codex in tmux with proper logging (session → pipe-pane → send-keys)\nlaunch_codex() {\n  local TASK=\"$1\" WORKDIR=\"$2\" PROMPT=\"$3\"\n  local LOG=\"$WORKDIR/codex-output.log\"\n  tmux new-session -d -s \"$TASK\" -c \"$WORKDIR\"\n  tmux pipe-pane -t \"$TASK\" -o \"stdbuf -oL cat >> $LOG\"\n  tmux send-keys -t \"$TASK\" \\\n    \"pnpm install && codex --dangerously-bypass-approvals-and-sandbox '$PROMPT'; echo \\\"CODEX_EXIT=\\$?\\\" >> $LOG\" Enter\n}\n\n# Task 1: Feature\ngit worktree add -b feat/auth /tmp/worktrees/feat-auth origin/main\nlaunch_codex feat-auth /tmp/worktrees/feat-auth \"Implement JWT auth...\"\n\n# Task 2: Bugfix\ngit worktree add -b fix/payments /tmp/worktrees/fix-payments origin/main\nlaunch_codex fix-payments /tmp/worktrees/fix-payments \"Fix payment webhook...\"\n\n# Dashboard: check all agents (use log files, not capture-pane, for reliable output)\ntmux ls\nfor s in $(tmux ls -F '#{session_name}' 2>/dev/null); do\n  LOG=\"/tmp/worktrees/$s/codex-output.log\"\n  echo \"=== $s ===\"\n  if tmux has-session -t \"$s\" 2>/dev/null; then\n    sed 's/\\x1b\\[[0-9;]*[a-zA-Z]//g' \"$LOG\" 2>/dev/null | tail -5 || echo \"(no log yet)\"\n  else\n    EXIT=$(grep \"CODEX_EXIT=\" \"$LOG\" 2>/dev/null | tail -1)\n    echo \"(exited) ${EXIT:-exit code unknown}\"\n  fi\ndone\n\nCodex-Specific Features\nReasoning Effort\n\nControl how much the model \"thinks\" before acting:\n\n# High — for complex logic, multi-file refactors\ncodex -c \"model_reasoning_effort=high\" --full-auto \"refactor auth module\"\n\n# Medium — balanced (default)\ncodex exec --full-auto \"add input validation\"\n\n# Low — for trivial/mechanical changes\ncodex -c \"model_reasoning_effort=low\" --full-auto \"rename all instances of foo to bar\"\n\nSandbox Modes\nMode\tUse Case\nread-only\tCode review, analysis, documentation\nworkspace-write / --full-auto\tFeature implementation, bug fixes, refactors\ndanger-full-access\tInstalling dependencies, network access needed\n--dangerously-bypass-approvals-and-sandbox\tFull auto in containers (recommended for tmux workflow)\nJSON Output\n# Structured output for programmatic processing\ncodex exec --full-auto --json \"implement and test the feature\"\n\n# Save to file\ncodex exec --full-auto -o results.txt \"run analysis\"\n\nResume Session\n# Resume last session with a follow-up task\ncodex exec resume --last \"now add tests for the feature you just built\"\n\nBest Practices\nPrompt Quality\nInclude file paths: \"The entry point is src/index.ts, config in src/config/\"\nInclude schemas/types: Paste relevant type definitions into the prompt\nInclude test commands: \"Verify with: npm test -- --grep auth\"\nInclude commit convention: \"Use conventional commits: feat:, fix:, chore:\"\nInclude error logs: When retrying, always attach the failure output\nScope Management\nOne task per agent — don't ask for \"refactor everything\"\nPre-install dependencies before launching the agent\nBe specific — \"Add rate limiting to POST /api/users\" not \"improve the API\"\nUse high reasoning effort for complex tasks, low for mechanical ones\nWhen to Interrupt (Ask Human)\nDestructive operations (drop tables, force push main)\nSecurity decisions (expose credentials, change auth)\nAmbiguous requirements with significant trade-offs\nAll other decisions: proceed autonomously"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/feiskyer/codex-skill",
    "publisherUrl": "https://clawhub.ai/feiskyer/codex-skill",
    "owner": "feiskyer",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/codex-skill",
    "downloadUrl": "https://openagent3.xyz/downloads/codex-skill",
    "agentUrl": "https://openagent3.xyz/skills/codex-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/codex-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/codex-skill/agent.md"
  }
}