OpenClaw Skill — Codex CLI Integration

openclaw-skill-codex-cli

Async OpenAI Codex task runner for OpenClaw — delegate heavy work to Codex, get results delivered automatically to your chat.

An OpenClaw skill that lets your agent run OpenAI Codex CLI tasks in the background. The agent sends work to Codex, goes back to chatting, and gets notified automatically when the work is done — with heartbeat pings every minute while it runs.

---

Why This Exists

1. Codex is a full-powered AI agent

Codex is not just a code editor assistant. In codex exec mode it is a full autonomous agent: it can read and write files, run shell commands, optionally search the web, and produce detailed results without human interaction.

This makes it ideal for delegating complex tasks: background research, codebase analysis, multi-file refactoring, document generation, data processing. You write a prompt, launch it, and come back to the result.

2. Multi-layer agent orchestration

OpenClaw acts as your technical PM — it understands the goal, breaks it down, and decides what to delegate. Codex acts as a senior developer who can execute complex tasks autonomously, spawn its own sub-agents for parallel work, and deliver structured results back.

This is the first practical layer of real agent orchestration:

You (human)
    ↓
OpenClaw agent (PM — coordinates, prioritizes, communicates)
    ↓
OpenAI Codex CLI (executor — executes, codes, researches)

The result comes back up the chain automatically.

3. Cost efficiency

OpenClaw tokens are not spent while Codex is running in the detached background process. You only pay OpenClaw cost for the short turn that launches the task and the short turn that processes the result when it comes back.

Codex billing follows your Codex authentication/setup.

---

How It Works

┌──────────────────┐      nohup       ┌──────────────────────┐
│   OpenClaw        │ ───────────────▶ │   run-task.py         │
│   (your agent)    │                  │   (detached process)  │
└──────────────────┘                  └──────────┬───────────┘
         ▲                                        │
         │                                        ▼
         │                             ┌──────────────────────┐
         │                             │   OpenAI Codex CLI    │
         │                             │   codex exec "task"   │
         │                             │   --json              │
         │                             └──────────┬───────────┘
         │                                        │
         │                          ┌─────────────┼─────────────┐
         │                          ▼             ▼             ▼
         │                     Every 60s     On complete    On error/timeout
         │                     ┌─────────┐  ┌──────────┐  ┌────────────┐
         │                     │ 📡 ping  │  │ ✅ result │  │ ❌/⏰ notif│
         │                     │ channel  │  │ channel   │  │  channel   │
         │                     └─────────┘  └─────┬────┘  └─────┬──────┘
         │                                        │              │
         └────────────────────────────────────────┴──────────────┘
                              sessions_send → agent wakes with result

Notification flow:

1. Task launches — the originating channel gets a launch confirmation with task details
2. Every 60 seconds — a background heartbeat ping (📡 prefix) shows live status: tool calls, token count when available, current activity
3. On completion — result delivered two ways:
   • direct message to the originating channel (human sees it immediately)
   • sessions_send or equivalent wake path to the OpenClaw session (agent wakes up, processes the result, sends a summary)
4. Same behavior on error, timeout, or crash — you always get notified

The dual delivery ensures both you and your agent see the result.

In Action

Real WhatsApp chat showing the full flow this project is based on — task launch, progress updates, and result delivery:

---

Requirements

• OpenClaw running locally (default port 18789)
• OpenAI Codex CLI (codex) installed and authenticated
• Python 3.10+ with requests (pip install requests)
• WhatsApp and Telegram connected to OpenClaw
• Other channels may work in principle, but may require lightweight AI-assisted adaptation in notify_session() / channel routing logic

---

Security Considerations

This section addresses the same types of concerns as the original project. All behaviors described here are intentional, necessary, and declared in the skill metadata.

Gateway Token Access

What happens: run-task.py and scripts/openclaw_notify.py read the OpenClaw gateway authentication token from ~/.openclaw/openclaw.json (JSON key path: gateway.auth.token).

Why it's needed: The token authenticates HTTP API calls to the local OpenClaw gateway (http://localhost:18789) for two purposes:

1. Sending channel notifications (heartbeats, results, errors)
2. Waking the agent with results via sessions_send

Scope: The token is used only for localhost API calls within the current machine. It is never logged, stored in a secondary location, or transmitted to any external host or service.

Declared in: SKILL.md frontmatter requires.config

---

Config Changes Required

What's needed: Two values in ~/.openclaw/openclaw.json must be set by the user:

{
  "gateway": { "tools": { "allow": ["sessions_send"] } },
  "tools": { "sessions": { "visibility": "all" } }
}

Why: By default, the OpenClaw HTTP API blocks sessions_send for safety. Allowing it enables the skill to inject results into the agent's session queue so the agent wakes up and processes the result. tools.sessions.visibility: "all" makes sessions addressable by session key.

Who makes these changes: The user, manually, one time during setup. The skill itself does NOT read or write openclaw.json (except reading the auth token).

Scope: Both settings affect only the local OpenClaw gateway.

Declared in: SKILL.md frontmatter requires.config

---

Persistent Files Written

The skill writes to these locations:

Session registry (codex_sessions.json): Stores task labels, project directories, Codex thread_id values, output file paths, and completion status. Used to resume previous Codex sessions. Auto-created if missing. Permissions set to 0o600 on every write.

PID files (pids/): One file per running task, containing the process PID, task description, and start timestamp. Automatically deleted when the task completes or exits. Stale PID files are cleaned up on next task launch.

No data is sent to any external service by this registry/pid mechanism.

Declared in: SKILL.md frontmatter config.stateDirs: ["~/.openclaw"]

---

--dangerously-bypass-approvals-and-sandbox Flag

What it does: Disables Codex CLI's approval prompts and sandbox restrictions for tool use (file writes, bash commands, etc.).

Why it's required: The skill launches Codex in non-interactive exec mode via nohup, detached from any terminal. There is no user present to answer prompts. Any prompt that appears would stall the process indefinitely until the timeout kills it. --dangerously-bypass-approvals-and-sandbox is the mechanism Codex