acp-router_skill

Overview

This skill routes plain-language requests to Pi, Claude Code, Codex, OpenCode, Gemini CLI, or ACP harness work into either the OpenClaw ACP runtime or direct acpx-driven sessions. It detects intent to run or continue harness work and chooses the appropriate path while enforcing installation, session, and failure-recovery policies. The goal is reliable, predictable harness control without using subagent runtimes or PTY scraping.

How this skill works

The router inspects user intent for harness-related requests and maps named harnesses to default agentIds (pi, claude, codex, opencode, gemini). It prefers the OpenClaw ACP runtime path via sessions_spawn (runtime: "acp", thread: true, mode: "session") and embeds the task so the session receives it immediately. If the runtime is unavailable or the user requests direct control, it drives the harness using a pinned plugin-local acpx binary and deterministic session names.

When to use it

• User asks to run or continue work in Pi/Claude Code/Codex/OpenCode/Gemini harnesses
• Start a threaded harness session where follow-up prompts must stay in context
• Relay prompts directly to an external coding harness without subagent lifecycle needs
• When ACP runtime is unhealthy or unavailable and a deterministic fallback is required

Best practices

• Always set agentId explicitly unless a different ACP default is known
• Prefer OpenClaw ACP runtime (sessions_spawn) for end-to-end lifecycle and thread behavior
• Use plugin-local pinned acpx binary at ./extensions/acpx/node_modules/.bin/acpx for direct calls
• Name direct sessions deterministically (oc-<harness>-<conversationId>) so follow-ups reuse context
• Verify and repair acpx installation automatically before offering fallback; avoid global installs unless requested

Example use cases

• User: "spawn a test codex session in thread and tell it to say hi" — use sessions_spawn with task:"Say hi." and agentId:"codex"
• User: "Keep a Claude thread going to iterate on this function" — create an ACP session thread so the harness retains conversation history
• User: "Just relay these prompts to pi via CLI" — use acpx with a stable session name and --format quiet, creating the session if missing
• User: "Start a one-shot OpenCode run in my repo" — run acpx <agent> exec with --cwd set to workspace path