skills.rest
VsevolodUstinov
VsevolodUstinovCOMMUNITY
Explore all skills by this author →
Website𝕏@sevaustinovGitHub

worker-relay

Runs Codex CLI or Claude Code as supervised asynchronous workers with routed notifications and session resume.

24|4|Updated Feb 20, 2026
Search Tags:#claude code#codex#task delegation#session resume#systemd#openclaw#async worker
One-click install
npx skills add https://github.com/VsevolodUstinov/openclaw-worker-relay --skill worker-relay-vsevolodustinov
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: worker-relay
Source: https://github.com/VsevolodUstinov/openclaw-worker-relay
Command: npx skills add https://github.com/VsevolodUstinov/openclaw-worker-relay --skill worker-relay-vsevolodustinov

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Delegating coding tasks to external CLI agents like Codex or Claude Code normally blocks your session, loses routing context, and provides no progress visibility. Worker Relay runs these agents as supervised background workers while OpenClaw retains ownership of routing, progress notifications, result delivery, wake-up, and multi-turn continuation. ## Core Features & Use Cases - Supervised async execution: Launch Codex or Claude Code through one run-task.py entrypoint with durable Linux detachment via a transient user systemd service, heartbeat pings, and completion notifications to the exact originating WhatsApp or Telegram session. - Session resume and provider control: Resume provider-native sessions/threads, select explicit modes (Terra, Sonnet, Sol, Fable, Fast), and optionally fall back across providers only when the primary is unavailable before useful work. - Subscription-auth isolation: Inherited API credentials are stripped so workers use saved ChatGPT or Claude subscription logins instead of API billing. - Use Case: From a WhatsApp group chat, ask your agent to have Codex implement a feature in a repository; Worker Relay validates the route, detaches the worker, delivers the result back to the chat, and wakes the supervisor to continue the next phase autonomously. ## Quick Start Ask your OpenClaw agent to delegate a coding task to Codex or Claude, for example: "Use Codex to implement input validation in my project at /home/user/app and notify me when done."

Frequently Asked Questions about worker-relay

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run Claude Code or Codex as a background task from OpenClaw?▼

Invoke run-task.py with --detach, a task prompt, project path, and the exact source session key. The runner validates routing, creates a transient user systemd service, and returns DETACHED_LAUNCH_ACCEPTED; results arrive via routed notification and supervisor wake.

What is the difference between Worker Relay, a native subagent, and direct CLI?▼

Worker Relay supervises an external CLI worker through a full async lifecycle with routing and delivery. A native OpenClaw subagent runs inside OpenClaw, and direct CLI is an explicit interactive bypass; any request to call Claude or Codex selects Worker Relay by default.

Can I resume a previous Codex or Claude session?▼

Yes, pass --resume with a session or thread id recorded in ~/.openclaw/claude_sessions.json. The id must belong to the same engine; cross-provider resume is rejected, and exit code 42 signals a failed resume.

Does Worker Relay use my API keys for billing?▼

No. The runner strips ANTHROPIC_API_KEY, OPENAI_API_KEY, CODEX_API_KEY, CODEX_ACCESS_TOKEN, and inherited CODEX_HOME so workers authenticate with the saved Claude or ChatGPT subscription login instead of API credentials.

When does provider fallback trigger between Codex and Claude?▼

Fallback runs only when --fallback-engine is explicitly set and the primary provider is unavailable before useful work, such as auth, rate-limit, or network failures. It never retries timeouts, ordinary task failures, or completed runs, and cannot combine with --resume.

Why did my detached worker disappear after launch?▼

Handwritten nohup or background shell launches can be killed when the OpenClaw tool scope exits. Always launch through run-task.py --detach, which moves the worker into a transient user systemd service that survives tool cleanup.

Related Skills

Explore More Software Engineering Skills→
QcasaresQcasares

coding-agent

Integrate Kiro CLI with OpenClaw to run background coding agents.

Community
Intermediate
EpiphyticEpiphytic
2

nurture

Review and fix code implementations for correctness and test coverage.

Official
Advanced
nikhilvallishayeenikhilvallishayee
83

Checker

Detect edge cases and challenge assumptions through three verification questions.

Community
Basic
Threat-Vector-SecurityThreat-Vector-Security
11

coding-backend-orchestration

Launch and manage external coding backends when explicitly requested.

Official
Intermediate