ACP-Router

ACP-Harness-Router

Wenn die Benutzerabsicht „Führe dies in Claude Code/Cursor/Copilot/OpenClaw/OpenCode/Gemini/Grok Build/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode (ACP-Harness) aus“ ist, verwende keine Subagenten-Runtime oder PTY-Scraping. Leite durch ACP-bewusste Abläufe.

Codex ist speziell: Einfache Chat-/Konversationsbindung und -steuerung sollten das native Codex-App-Server-Plugin (/codex bind, /codex threads, /codex resume) anstelle des standardmäßigen ACP-Pfads verwenden. Verwende ACP für Codex nur, wenn der Benutzer explizit ACP//acp/acpx nennt oder wenn Hintergrund-Kindersitzungen durch sessions_spawn erzeugt werden, bei denen noch keine native Codex-Runtime-Spawn verfügbar ist.

Absichtserkennung

Löse diese Fähigkeit aus, wenn der Benutzer OpenClaw auffordert:

• etwas in Claude Code / Cursor / Copilot / OpenClaw / OpenCode / Gemini / Grok Build / Qwen / Kiro / Kimi / iFlow / Droid / Kilocode auszuführen
• Codex explizit über ACP, /acp oder acpx auszuführen
• bestehende Harness-Arbeit fortzusetzen
• Anweisungen an eine externe Coding-Harness weiterzuleiten
• eine externe Harness-Konversation in einer thread-ähnlichen Konversation zu führen

Zwingender Preflight für Thread-Anfragen von Coding-Agenten:

• Bevor ein Thread für ACP-Harness-Arbeit erstellt wird, lies diese Fähigkeit zuerst im selben Durchgang.
• Befolge danach den unten stehenden „OpenClaw ACP Runtime-Pfad“; verwende message(action="thread-create") nicht für den ACP-Harness-Thread-Spawn.

Modusauswahl

Wähle einen dieser Pfade:

1. OpenClaw ACP Runtime-Pfad (Standard): Verwende sessions_spawn / ACP-Runtime-Tools.
2. Direkter acpx-Pfad (Telefon-Spiel): Verwende die acpx-CLI über exec, um die Harness-Sitzung direkt zu steuern.

Verwende den direkten acpx-Pfad, wenn eine dieser Bedingungen zutrifft:

• Der Benutzer fordert explizit die direkte acpx-Steuerung an.
• Der ACP-Runtime/Plugin-Pfad ist nicht verfügbar oder nicht gesund.
• Die Aufgabe besteht darin, „nur Eingabeaufforderungen an die Harness weiterzuleiten“ und es werden keine OpenClaw ACP-Lebenszyklusfunktionen benötigt.

Verwende nicht:

• subagents-Runtime für die Harness-Steuerung.
• /acp-Befehlsdelegierung als Anforderung an den Benutzer.
• PTY-Scraping unterstützter ACP-Harness-CLIs, wenn acpx verfügbar ist.

AgentId-Zuordnung

Verwende diese Standardeinstellungen, wenn der Benutzer eine Harness direkt nennt:

• „openclaw“ -> agentId: "openclaw"
• „claude“ oder „claude code“ -> agentId: "claude"
• „codex“ -> agentId: "codex" nur für explizite ACP/acpx-Anfragen oder Hintergrund-ACP-Runtime-Spawn
• „copilot“ oder „github copilot“ -> agentId: "copilot"
• „cursor“ oder „cursor cli“ -> agentId: "cursor"
• „droid“ oder „factory droid“ -> agentId: "droid"
• „opencode“ -> agentId: "opencode"
• „gemini“ oder „gemini cli“ -> agentId: "gemini"
• „grok build“ oder „grok-build“ -> agentId: "grok-build"
• „iflow“ -> agentId: "iflow"
• „kilocode“ -> agentId: "kilocode"
• „kimi“ oder „kimi cli“ -> agentId: "kimi"
• „kiro“ oder „kiro cli“ -> agentId: "kiro"
• „qwen“ oder „qwen code“ -> agentId: "qwen"

Diese Standardeinstellungen stimmen mit den aktuellen integrierten acpx-Aliasen überein.

grok-build ist ein ACPX-Agent-Ziel, nicht die xAI-Modell-ID xai/grok-build-0.1. Leite grok-build über agentId; verwende die voll qualifizierte xAI-Referenz nur in einem OpenClaw model-Feld.

Wenn die Richtlinie die gewählte ID ablehnt, melde den Richtlinienfehler klar und frage nach der erlaubten ACP-Agenten-ID.

OpenClaw ACP Runtime-Pfad

Erforderliches Verhalten:

1. Lies bei ACP-Harness-Thread-Spawn-Anfragen diese Fähigkeit zuerst im selben Durchgang, bevor du Tools aufrufst.
2. Verwende sessions_spawn mit:
   • runtime: "acp"
   • thread: true
   • mode: "session" (es sei denn, der Benutzer möchte explizit einen Einmalvorgang)
3. Verwende für die ACP-Harness-Thread-Erstellung nicht message mit action=thread-create; sessions_spawn ist der einzige Pfad zur Thread-Erstellung.
4. Füge die angeforderte Arbeit in task ein, damit die ACP-Sitzung sie sofort erhält.
5. Setze agentId explizit, es sei denn, der ACP-Standardagent ist bekannt.
6. Bitte den Benutzer nicht, Slash-Befehle oder die CLI auszuführen, wenn dieser Pfad direkt funktioniert.

Beispiel:

Benutzer: „Erzeuge eine Test-Codex-ACP-Sitzung im Thread und sag ihr, sie soll Hallo sagen“

Aufruf:

{
  "task": "Sage Hallo.",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

Thread-Spawn-Wiederherstellungsrichtlinie

Wenn der Benutzer darum bittet, eine Coding-Harness in einem Thread zu starten, behandle dies als ACP-Runtime-Anfrage und versuche, sie Ende-zu-Ende zu erfüllen.

Erforderliches Verhalten, wenn das ACP-Backend nicht verfügbar ist:

1. Bitte den Benutzer nicht sofort, einen alternativen Pfad zu wählen.
2. Versuche zuerst eine automatische lokale Reparatur:
   • Überprüfe, ob das plugin-lokale, festgepinnte acpx im ACPX-Plugin-Paket installiert ist.
   • Überprüfe ${ACPX_CMD} --version.
3. Starte nach der Neuinstallation/Reparatur das Gateway neu und biete explizit an, diesen Neustart für den Benutzer durchzuführen.
4. Wiederhole den ACP-Thread-Spawn einmal nach der Reparatur.
5. Nur wenn Reparatur+Wiederholung fehlschlägt, melde den konkreten Fehler und biete dann Ausweichoptionen an.

Wenn du Ausweichmöglichkeiten anbietest, behalte ACP an erster Stelle:

• Option 1: ACP-Spawn nach Anzeige des genauen fehlgeschlagenen Schritts wiederholen.
• Option 2: Direkter acpx-Telefon-Spiel-Ablauf.

Verwende für diese Anfragen nicht standardmäßig die Subagenten-Runtime.

ACPX-Installations- und Versionsrichtlinie (direkter acpx-Pfad)

Für dieses Repository müssen direkte acpx-Aufrufe derselben festgepinnten Richtlinie folgen wie das @openclaw/acpx-Erweiterungspaket.

1. Bevorzuge das plugin-lokale Binary, nicht den globalen PATH:
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx
2. Löse die festgepinnte Version aus der Erweiterungsabhängigkeit auf:
   • node -e "console.log(require(process.env.ACPX_PLUGIN_ROOT + '/package.json').dependencies.acpx)"
3. Wenn das Binary fehlt oder die Version nicht übereinstimmt, installiere die plugin-lokale, festgepinnte Version:
   • cd "$ACPX_PLUGIN_ROOT" && npm install --omit=dev --no-save acpx@<pinnedVersion>
4. Überprüfe vor der Verwendung:
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx --version
5. Wenn die Installation/Reparatur ACPX-Artefakte geändert hat, starte das Gateway neu und biete an, den Neustart durchzuführen.
6. Führe npm install -g acpx nur aus, wenn der Benutzer explizit eine globale Installation wünscht.

Setze und verwende diese Variablen wieder:

ACPX_PLUGIN_ROOT="<bundled-acpx-plugin-root>"
ACPX_CMD="$ACPX_PLUGIN_ROOT/node_modules/.bin/acpx"

Direkter acpx-Pfad („Telefon-Spiel“)

Verwende diesen Pfad, um Harness-Sitzungen ohne /acp oder Subagenten-Runtime zu steuern.

Regeln

1. Verwende exec-Befehle, die ${ACPX_CMD} aufrufen.
2. Verwende einen stabilen Sitzungsnamen pro Konversation wieder, sodass nachfolgende Eingabeaufforderungen im selben Harness-Kontext bleiben.
3. Bevorzuge --format quiet für sauberen Assistententext, der an den Benutzer weitergeleitet wird.
4. Verwende exec (Einmalvorgang) nur, wenn der Benutzer ein Einmalverhalten wünscht.
5. Halte das Arbeitsverzeichnis explizit (--cwd), wenn der Aufgabenbereich vom Repository-Kontext abhängt.

Sitzungsbenennung

Verwende einen stabilen Namen, zum Beispiel:

• oc-<harness>-<conversationId>

Wobei conversationId die Thread-ID ist, falls verfügbar, andernfalls die Kanal-/Konversations-ID.

Befehlsvorlagen

Persistente Sitzung (erstellen, falls nicht vorhanden, dann auffordern):

${ACPX_CMD} codex sessions show oc-codex-<conversationId> \
  || ${ACPX_CMD} codex sessions new --name oc-codex-<conversationId>

${ACPX_CMD} codex -s oc-codex-<conversationId> --cwd <workspacePath> --format quiet "<prompt>"

Einmalvorgang:

${ACPX_CMD} codex exec --cwd <workspacePath> --format quiet "<prompt>"

Laufenden Durchgang abbrechen:

${ACPX_CMD} codex cancel -s oc-codex-<conversationId>

Sitzung schließen:

${ACPX_CMD} codex sessions close oc-codex-<conversationId>

Harness-Aliase in acpx

• claude
• codex
• copilot
• cursor
• droid
• gemini
• grok-build
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

Integrierte Adapter-Befehle in acpx

Die Standardeinstellungen sind:

• openclaw -> openclaw acp
• claude -> gebündelt @agentclientprotocol/[email protected]
• codex -> gebündelt @agentclientprotocol/[email protected] über OpenClaws isolierten CODEX_HOME-Wrapper
• copilot -> copilot --acp --stdio
• cursor -> cursor-agent acp
• droid -> droid exec --output-format acp
• gemini -> gemini --acp
• grok-build -> grok agent stdio
• iflow -> iflow --experimental-acp
• kilocode -> npx -y @kilocode/cli acp
• kimi -> kimi acp
• kiro -> kiro-cli acp
• opencode -> npx -y opencode-ai acp
• qwen -> qwen --acp

Wenn ~/.acpx/config.json agents überschreibt, ersetzen diese Überschreibungen die Standardeinstellungen. Wenn deine lokale Cursor-Installation ACP immer noch als agent acp bereitstellt, setze dies explizit als cursor-Agentenüberschreibung.

Fehlerbehandlung

• acpx: command not found:
  • Installiere bei Thread-Spawn-ACP-Anfragen sofort das plugin-lokale, festgepinnte acpx im ACPX-Plugin-Paket.
  • Starte das Gateway nach der Installation neu und biete an, den Neustart automatisch durchzuführen.
  • Wiederhole dann einmal.
  • Frage nicht zuerst nach Installationserlaubnis, es sei denn, die Richtlinie verlangt dies explizit.
  • Installiere kein globales acpx, es sei denn, es wird explizit angefordert.
• Adapter-Befehl fehlt (z. B. claude-agent-acp nicht gefunden):
  • Stelle bei Thread-Spawn-ACP-Anfragen zuerst die integrierten Standardeinstellungen wieder her, indem fehlerhafte ~/.acpx/config.json-Agentenüberschreibungen entfernt werden.
  • Wiederhole dann einmal, bevor du eine Ausweichmöglichkeit anbietest.
  • Wenn der Benutzer binary-basierte Überschreibungen wünscht, installiere genau das konfigurierte Adapter-Binary.
• NO_SESSION: Führe ${ACPX_CMD} <agent> sessions new --name <sessionName> aus und wiederhole dann die Eingabeaufforderung.
• Warteschlange belegt: Entweder auf Abschluss warten (Standard) oder --no-wait verwenden, wenn asynchrones Verhalten explizit gewünscht ist.

Ausgabe-Weiterleitung

Wenn du an den Benutzer weiterleitest, gib die endgültige Assistententextausgabe des acpx-Befehls zurück. Vermeide es, rohes lokales Tool-Rauschen weiterzuleiten, es sei denn, der Benutzer hat nach ausführlichen Protokollen gefragt.