Codex CLI Task

Codex Code Task (Async)

Run OpenAI Codex CLI in background — zero OpenClaw tokens while it works. Results delivered to WhatsApp or Telegram automatically.

Important: Codex = General AI Agent

Codex is NOT just a coding tool. In codex exec mode it is a general-purpose AI agent with file access, shell execution, optional web search, and deep reasoning.

Use it for:

• Research — web search, synthesis, competitive analysis, user experience reports
• Coding — create tools, scripts, APIs, refactor codebases
• Analysis — read and analyze files, data, logs, source code
• Content — write docs, reports, summaries
• Automations — complex multi-step workflows with filesystem access

Give it prompts the same way you'd talk to a smart human — natural language, focused on WHAT you need, not HOW to do it.

NOT for:

• Quick questions
• Tasks needing real-time back-and-forth

Quick Start

What "run tests" means for this skill (critical)

When user asks things like:

• "run all tests"
• "run tests"
• "check if everything is working"

it means run the full E2E operator validation flow for run-task.py routing + notifications.

It does NOT mean plain pytest/unittest discovery by default.

Required behavior:

1. Run routing validation first (--validate-only).
2. Launch smoke/E2E scenario via nohup and file-based prompt.
3. Wait for completion through normal async flow, not same-turn blocking.
4. Report PASS/FAIL against E2E criteria: routing, heartbeat, mid-task update, completion delivery.

Use the canonical protocol: references/testing-protocol.md and the section below Full E2E Test (reference).

Async Boundary Rule (mandatory)

run-task.py is asynchronous orchestration.

After a successful nohup launch, the correct behavior is:

1. Send a short launch acknowledgment (PID/log/session)
2. Stop this turn immediately
3. Continue only when wake/completion event arrives in the same session

Do not keep waiting in the same turn for Codex completion. Do not poll and then summarize in the same turn unless user explicitly asked for active live monitoring.

Anti-pattern:

• ❌ Launch run-task.py and keep responding as if completion should appear in this turn

Correct pattern:

• ✅ Launch run-task.py → acknowledge launch → stop → wait for wake

Launch Confirmation Gate (mandatory)

Never claim "launched" until you have positive launch proof.

Required proof checklist:

1. nohup command returned a PID
2. process is alive (ps -p <PID>)
3. run log contains 🔧 Starting OpenAI Codex... or equivalent startup marker
4. routing was validated (--validate-only) for Telegram thread runs

If launch fails with ❌ Invalid routing:

• resolve via sessions_list
• rerun with explicit routing/session arguments if needed
• re-check proof checklist
• only then send launch acknowledgment

Pre-launch planning note (mandatory)

Before launching Codex, post a short plan in chat:

• how you plan to solve the task
• what result you expect from this run
• any clarifying assumptions
• whether you expect one iteration or staged follow-up

If staged: explicitly say this run is "phase 1" and what signal decides phase 2.

Telegram Thread Safety (must-follow)

For Telegram thread runs, run-task.py is designed to either route correctly or fail immediately.

Mandatory step before launch

Resolve the current runtime session key first, then launch with it.

• Get current key via sessions_list or runtime context
• If key is agent:main:main:<thread|topic>:<THREAD_ID> → use it directly in --session
• Never derive --session from chat_id / sender heuristics

Rules

• Use only --session "agent:main:main:<thread|topic>:<THREAD_ID>" for thread tasks
• Never use agent:main:telegram:user:<id> for thread tasks
• If routing metadata is inconsistent, script exits with ❌ Invalid routing
• Default mode is --telegram-routing-mode auto
• Force strict thread-only behavior with --telegram-routing-mode thread-only
• Force non-thread behavior with --telegram-routing-mode allow-non-thread or --allow-main-telegram

This is intentional: abort fast > silent misroute

⚠️ ALWAYS launch via nohup — exec timeout will kill the process otherwise.

⚠️ NEVER put the task text directly in the shell command — save the prompt to a file first, then use $(cat file).

WhatsApp

# Step 1: Save prompt to a temp file
write /tmp/codex-prompt.txt with your task text

# Step 2: Launch with $(cat ...)
nohup python3 {baseDir}/run-task.py \
  --task "$(cat /tmp/codex-prompt.txt)" \
  --project ~/projects/my-project \
  --session "agent:main:whatsapp:group:<JID>" \
  --timeout 900 \
  > /tmp/codex-run.log 2>&1 &

Telegram (thread-safe default)

nohup python3 {baseDir}/run-task.py \
  --task "$(cat /tmp/codex-prompt.txt)" \
  --project ~/projects/my-project \
  --session "agent:main:main:<thread|topic>:<THREAD_ID>" \
  --timeout 900 \
  > /tmp/codex-run.log 2>&1 &

Do NOT use agent:main:telegram:user:<id> for thread tests/runs.

Telegram Threaded Mode (1:1 DM with threads)

When OpenClaw is used in Telegram threaded mode, each thread has its own session key like agent:main:main:thread:369520 or agent:main:main:topic:369520.

Fail-safe routing (NEW): run-task.py now enforces strict thread routing.

• If --session contains :thread:<id> or :topic:<id>, the script refuses to start unless Telegram target + thread session UUID are resolved.
• It auto-resolves missing values from sessions_list when possible.
• If the session is inactive and not returned by API, it falls back to local session files: ~/.openclaw/agents/main/sessions/*-topic-<thread_id>.jsonl.
• If provided --notify-session-id mismatches the session key, it exits with error.
• Result: misrouted launches/heartbeats to main chat are blocked before Codex starts.

Use --notify-session-id to wake the exact thread session:

nohup python3 {baseDir}/run-task.py \
  --task "$(cat /tmp/codex-prompt.txt)" \
  --project ~/projects/my-project \
  --session "agent:main:main:<thread|topic>:369520" \
  --timeout 900 \
  > /tmp/codex-run.log 2>&1 &

All 5 notification types route to the DM thread when --session key contains :thread:<id> or :topic:<id> ✅

• --notify-session-id — optional override. Usually auto-resolved from session metadata/files.
• --notify-thread-id — optional override. Usually auto-extracted from --session.
• --reply-to-message-id — optional debug field; avoid for DM thread routing.
• --validate-only — resolve routing and exit (no Codex run). Use this to verify thread launch args safely.
• --notify-channel — optional channel hint (telegram/whatsapp); target is always auto-resolved from session metadata.
• --timeout — max runtime in seconds (default: 7200 = 2 hours)
• --completion-mode — optional legacy hint (single default, iterate if explicitly needed)
• --max-iterations — optional budget hint when using iterate mode
• --trace-live — emit live technical trace markers into the same chat/thread (debug mode)
• Always redirect stdout/stderr to a log file

Why file-based prompts?

Research/complex prompts contain single quotes, double quotes, markdown, backticks — any of these break shell argument parsing. Saving to a file and reading with $(cat ...) avoids all quoting issues.

Channel Detection

The detect_channel() function determines where to send notifications:

1. Deterministic auto-resolve — target is resolved from session metadata/session key (no manual target flag)
2. WhatsApp auto-detect — if the session key contains @g.us (WhatsApp group JID), WhatsApp is used
3. Fail fast on unresolved Telegram target — script exits with ❌ Invalid routing instead of silent misroute

def detect_channel(session_key):
    if NOTIFY_CHANNEL_OVERRIDE and NOTIFY_TARGET_OVERRIDE:
        return NOTIFY_CHANNEL_OVERRIDE, NOTIFY_TARGET_OVERRIDE
    jid = extract_group_jid(session_key)
    if jid:
        return "whatsapp", jid
    return None, None

How It Works

┌─────────────┐     nohup      ┌──────────────┐
│    Agent    │ ──────────────▶│  run-task.py  │
│ (OpenClaw)  │                │  (detached)   │
└─────────────┘                └──────┬───────┘
                                      │
                                      ▼
                               ┌──────────────┐
                               │    Codex      │
                               │ codex exec    │
                               └──────┬───────┘
                                      │
                          ┌───────────┼───────────┐
                          ▼           ▼           ▼
                    Every 60s    On complete   On error/timeout
                    ┌────────┐  ┌──────────┐  ┌──────────────┐
                    │ ⏳ ping │  │ ✅ result │  │ ❌/⏰/💥 error│
                    │ silent │  │ channel  │  │   channel    │
                    └────────┘  └──────────┘  └──────────────┘

WhatsApp notification flow

1. Heartbeat pings every 60s → WhatsApp direct
2. Final result → WhatsApp direct + sessions_send
3. Agent receives completion payload → processes it → sends summary

Iterative continuation mode (wake behavior)

--completion-mode is optional and acts as a hint:

• single = one run → continuation summary → stop
• iterate = continuation summary + exactly one next iteration when gaps remain

Wake payload frames continuation as the same ongoing OpenClaw conversation after Codex replies to the previous launch.

In iterate mode:

• react briefly to Codex result
• evaluate goal completion
• if gaps remain: explain next fix and launch exactly one follow-up iteration
• if complete: report final outcome and stop

Deterministic wake guard (anti-duplicate)

• Each run carries run_id and wake_id
• run-task.py keeps per-project state in /tmp/codex-orchestrator-state-<hash>.json
• Duplicate/stale wakes are skipped before delivery

No silent launch policy (always-on)

• Silent launch is forbidden (not only in debug mode).
• On wake, agent must first post a visible decision turn:
  • [TRACE][AGENT][WAKE_RECEIVED] ...
  • [TRACE][AGENT][DECISION] continue|stop ...
• Only after that visible decision may the next Codex iteration be launched.

Telegram notification flow (DM Threaded Mode — full pipeline)

1. 🚀 Launch notification → thread ✅ (silent; HTML; <blockquote expandable> for prompt; via send_telegram_direct; includes Resume: <thread-id|new>)
2. ⏳ Heartbeat (every 60s) → thread ✅ (silent; plain text; via send_telegram_direct)
3. 📡 Codex mid-task updates → thread ✅ (on-disk Python script /tmp/codex-notify-{pid}.py; Codex calls file; prefix "📡 🟢 Codex: " auto-added)
4. ✅/❌/⏰/💥 Result notification → thread ✅ (HTML; <blockquote expandable> for result; via send_telegram_direct)
5. 🤖 Agent continuation reply → delivered to chat via openclaw agent --deliver ✅ (same session continuation is visible to user)

send_telegram_direct() is the core mechanism for all thread-targeted notifications from external scripts. It calls api.telegram.org directly with message_thread_id — bypasses the OpenClaw message tool entirely (which cannot route to DM threads from outside a session context).

Fallback — if agent wake fails (session locked/busy): already_sent=True is set after the direct send, so no duplicate is sent.

Key detail: Telegram vs WhatsApp delivery

WhatsApp: Raw result sent directly (human sees it immediately) + sessions_send wakes agent for analysis.

Telegram: Result sent via send_telegram_direct → then agent is woken via openclaw agent --session-id --deliver so the continuation turn is visible in chat by default. This is the intended “same agent, same conversation” behavior after Codex completion.

Why not sessions_send for Telegram? sessions_send is blocked in the HTTP /tools/invoke deny list by architectural design. The openclaw agent CLI bypasses this limitation.

Telegram DM Threads vs Forum Groups

Telegram has two distinct thread models. The key difference for run-task.py is how to route messages to the thread.

The core problem with external scripts:

• The OpenClaw message tool's threadId parameter is Discord-specific — ignored for Telegram
• Target format "chatId:topic:threadId" is rejected by the message tool's target resolver
• Session auto-routing works only inside active sessions — external scripts have no session context
• Solution: send_telegram_direct() bypasses the message tool entirely; calls api.telegram.org directly with message_thread_id

DM Threaded Mode (bot-user private chat with threads):

• All notifications use send_telegram_direct(chat_id, text, thread_id=..., parse_mode=...) ✅
• thread_id auto-extracted from session key *:thread:<id> or *:topic:<id> by extract_thread_id()
• Launch + finish: parse_mode="HTML" with <blockquote expandable> for prompt/result
• Heartbeats + mid-task: parse_mode=None (plain text, avoid Markdown parse errors)
• parse_mode="Markdown" trap: finish messages contain **text** (CommonMark bold); Telegram MarkdownV1 rejects this with HTTP 400 — messages silently don't arrive
• replyTo trap: combining replyTo + message_thread_id can cause Telegram to reject the request or route incorrectly
• Agent continuation reply: openclaw agent --session-id <uuid> --deliver publishes the wake turn to chat so the user sees the same ongoing assistant conversation

Forum Groups (supergroup with Forum topics enabled):

• Same send_telegram_direct() approach works; message_thread_id is standard Bot API for Forum topics
• Auto-detected from session key pattern *:thread:<id> or *:topic:<id>

Codex mid-task updates:

• Do NOT embed bot tokens or curl commands in the task prompt
• run-task.py writes /tmp/codex-notify-{pid}.py to disk before launching Codex
• Task prompt prepended with [Automation context: ... python3 /tmp/codex-notify-{pid}.py 'msg' ...]
• Codex calls the file as a normal local script
• Script automatically prepends "📡 🟢 Codex: " to all messages; cleaned up in finally block

Reliability Features

Timeout (default 2 hours)

• --timeout 7200 → after 7200s: SIGTERM → wait 10s → SIGKILL
• Timeout notification sent to channel with tool call count and last activity
• Partial output saved to file