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: | Task Launch & Progress | Result Delivery | Agent Verification | |:---:|:---:|:---:| |  |  |  | --- ## Requirements - [OpenClaw](https://docs.openclaw.ai) running locally (default port `18789`) - [OpenAI Codex CLI](https://developers.openai.com/codex) (`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: ```json { "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: | File | Purpose | Permissions | |------|---------|-------------| | `~/.openclaw/codex_sessions.json` | Session registry for task tracking and resumption | `0o600` (owner r/w only) | | `<skill-dir>/pids/<timestamp>.pid` | PID file for the running task | Default umask | | `/tmp/codex-<timestamp>.txt` | Final output file from Codex | Default umask | **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