ACP-Agenten

• Wenn plugins.allow gesetzt ist, handelt es sich um ein restriktives Plugin-Inventar und es muss acpx enthalten; andernfalls wird das installierte ACP-Backend absichtlich blockiert und /acp doctor meldet den fehlenden Allowlist-Eintrag.
• Der Codex-ACP-Adapter wird mit dem acpx-Plugin bereitgestellt und nach Möglichkeit lokal gestartet.
• Andere Ziel-Harness-Adapter können bei der ersten Verwendung weiterhin bei Bedarf mit npx abgerufen werden.
• Die Vendor-Authentifizierung muss für dieses Harness weiterhin auf dem Host vorhanden sein.
• Wenn der Host keinen npm- oder Netzwerkzugriff hat, schlagen Adapterabrufe beim ersten Start fehl, bis Caches vorgewärmt sind oder der Adapter auf andere Weise installiert wurde.

ACP startet einen echten externen Harness-Prozess. OpenClaw besitzt Routing, Hintergrundaufgabenstatus, Zustellung, Bindungen und Richtlinie; das Harness besitzt seine Provider-Anmeldung, den Modellkatalog, das Dateisystemverhalten und native Tools.

Bevor Sie OpenClaw verantwortlich machen, prüfen Sie:

• /acp doctor meldet ein aktiviertes, fehlerfreies Backend.
• Die Ziel-ID ist durch acp.allowedAgents erlaubt, wenn diese Allowlist gesetzt ist.
• Der Harness-Befehl kann auf dem Gateway-Host starten.
• Provider-Authentifizierung ist für dieses Harness vorhanden (claude, codex, gemini, opencode, droid usw.).
• Das ausgewählte Modell existiert für dieses Harness - Modell-IDs sind nicht zwischen Harnesses portierbar.
• Das angeforderte cwd existiert und ist zugänglich, oder lassen Sie cwd weg und überlassen Sie dem Backend seinen Standardwert.
• Der Berechtigungsmodus passt zur Arbeit. Nicht interaktive Sitzungen können keine nativen Berechtigungsaufforderungen anklicken, daher benötigen schreib-/ausführungsintensive Coding-Läufe in der Regel ein ACPX-Berechtigungsprofil, das ohne Benutzerinteraktion fortfahren kann.

• Starten erstellt oder setzt eine ACP-Runtime-Sitzung fort, zeichnet ACP-Metadaten im OpenClaw-Sitzungsspeicher auf und kann eine Hintergrundaufgabe erstellen, wenn der Lauf parent-owned ist.
• Parent-owned ACP-Sitzungen werden als Hintergrundarbeit behandelt, auch wenn die Runtime-Sitzung persistent ist; Abschluss und oberflächenübergreifende Zustellung laufen über den Parent-Task-Notifier, statt sich wie eine normale benutzerorientierte Chat-Sitzung zu verhalten.
• Die Aufgabenwartung schließt terminale oder verwaiste parent-owned One-Shot-ACP-Sitzungen. Persistente ACP-Sitzungen bleiben erhalten, solange eine aktive Unterhaltungsbindung besteht; veraltete persistente Sitzungen ohne aktive Bindung werden geschlossen, damit sie nicht stillschweigend fortgesetzt werden können, nachdem die besitzende Aufgabe abgeschlossen ist oder ihr Aufgabendatensatz fehlt.
• Gebundene Folgenachrichten gehen direkt an die ACP-Sitzung, bis die Bindung geschlossen, aus dem Fokus genommen, zurückgesetzt oder abgelaufen ist.
• Gateway-Befehle bleiben lokal. /acp ..., /status und /unfocus werden nie als normaler Prompt-Text an ein gebundenes ACP-Harness gesendet.
• cancel bricht den aktiven Turn ab, wenn das Backend Abbruch unterstützt; es löscht weder die Bindung noch die Sitzungsmetadaten.
• close beendet die ACP-Sitzung aus Sicht von OpenClaw und entfernt die Bindung. Ein Harness kann seine eigene Upstream-Historie weiterhin behalten, wenn es Fortsetzen unterstützt.
• Inaktive Runtime-Worker kommen nach acp.runtime.ttlMinutes für die Bereinigung infrage; gespeicherte Sitzungsmetadaten bleiben für /acp sessions verfügbar.

Natürlichsprachliche Auslöser, die zum nativen Codex-Plugin routen sollten, wenn es aktiviert ist:

• "Binden Sie diesen Discord-Kanal an Codex."
• "Hängen Sie diesen Chat an den Codex-Thread <id> an."
• "Zeigen Sie Codex-Threads an und binden Sie dann diesen."

Die native Codex-Unterhaltungsbindung ist der standardmäßige Chat-Steuerungspfad. Dynamische OpenClaw-Tools werden weiterhin über OpenClaw ausgeführt, während Codex-native Tools wie Shell/Apply-Patch innerhalb von Codex ausgeführt werden. Für Codex-native Tool-Ereignisse injiziert OpenClaw pro Turn ein natives Hook-Relay, damit Plugin-Hooks before_tool_call blockieren, after_tool_call beobachten und Codex-PermissionRequest-Ereignisse über OpenClaw-Genehmigungen routen können. Codex-Stop-Hooks werden an OpenClaw before_agent_finalize weitergeleitet, wo Plugins einen weiteren Modelllauf anfordern können, bevor Codex seine Antwort finalisiert. Das Relay bleibt bewusst konservativ: Es verändert keine Codex-nativen Tool-Argumente und schreibt keine Codex-Thread-Datensätze um. Verwenden Sie explizites ACP nur, wenn Sie das ACP-Runtime-/Sitzungsmodell möchten. Die Support-Grenze für eingebettetes Codex ist im Codex-Harness-v1-Supportvertrag dokumentiert.

• openai-codex/* - PI-Codex-OAuth-/Abonnement-Route.
• openai/* plus agentRuntime.id: "codex" - eingebettete native Runtime des Codex App-Servers.
• /codex ... - native Codex-Unterhaltungssteuerung.
• /acp ... oder runtime: "acp" - explizite ACP-/acpx-Steuerung.

Trigger, die zur ACP-Runtime routen sollten:

• "Führen Sie dies als einmalige Claude Code ACP-Sitzung aus und fassen Sie das Ergebnis zusammen."
• "Verwenden Sie Gemini CLI für diese Aufgabe in einem Thread und behalten Sie anschließende Nachfragen in demselben Thread."
• "Führen Sie Codex über ACP in einem Hintergrund-Thread aus."

OpenClaw wählt runtime: "acp", löst das Harness-agentId auf, bindet bei Unterstützung an die aktuelle Unterhaltung oder den Thread und routet Nachfragen bis zum Schließen/Ablauf an diese Sitzung. Codex folgt diesem Pfad nur, wenn ACP/acpx explizit ist oder das native Codex- Plugin für die angeforderte Operation nicht verfügbar ist.

Für sessions_spawn wird runtime: "acp" nur angekündigt, wenn ACP aktiviert ist, der Anforderer nicht sandboxed ist und ein ACP-Runtime- Backend geladen ist. acp.dispatch.enabled=false pausiert den automatischen ACP-Thread-Dispatch, verbirgt oder blockiert aber keine expliziten sessions_spawn({ runtime: "acp" })-Aufrufe. Es zielt auf ACP-Harness-IDs wie codex, claude, droid, gemini oder opencode. Übergeben Sie keine normale OpenClaw-Konfigurations-Agent-ID aus agents_list, es sei denn, dieser Eintrag ist explizit mit agents.list[].runtime.type="acp" konfiguriert; andernfalls verwenden Sie die Standard-Runtime für Sub-Agents. Wenn ein OpenClaw-Agent mit runtime.type="acp" konfiguriert ist, verwendet OpenClaw runtime.acp.agent als zugrunde liegende Harness-ID.

• --bind here und --thread ... schließen sich gegenseitig aus.
• --bind here funktioniert nur auf Kanälen, die Bindung an die aktuelle Unterhaltung ankündigen; andernfalls gibt OpenClaw eine klare Nicht-unterstützt-Meldung zurück. Bindungen bleiben über Gateway-Neustarts hinweg bestehen.
• Auf Discord steuert spawnSessions die Erstellung von Kind-Threads für --thread auto|here - nicht --bind here.
• Wenn Sie ohne --cwd zu einem anderen ACP-Agent spawnen, übernimmt OpenClaw standardmäßig den Arbeitsbereich des Ziel-Agent. Fehlende geerbte Pfade (ENOENT/ENOTDIR) fallen auf den Backend-Standard zurück; andere Zugriffsfehler (z. B. EACCES) erscheinen als Spawn-Fehler.
• Gateway-Verwaltungsbefehle bleiben in gebundenen Unterhaltungen lokal - /acp ...-Befehle werden von OpenClaw verarbeitet, selbst wenn normaler Folgetext an die gebundene ACP-Sitzung geroutet wird; /status und /unfocus bleiben ebenfalls lokal, wann immer die Befehlsverarbeitung für diese Oberfläche aktiviert ist.

Wenn Thread-Bindungen für einen Kanaladapter aktiviert sind:

• OpenClaw bindet einen Thread an eine Ziel-ACP-Sitzung.
• Folgenachrichten in diesem Thread werden an die gebundene ACP-Sitzung geroutet.
• ACP-Ausgabe wird an denselben Thread zurückgeliefert.
• Unfocus/Schließen/Archivieren/Idle-Timeout oder Ablauf durch Höchstalter entfernt die Bindung.
• /acp close, /acp cancel, /acp status, /status und /unfocus sind Gateway-Befehle, keine Prompts an das ACP-Harness.

Erforderliche Feature-Flags für Thread-gebundenes ACP:

• acp.enabled=true
• acp.dispatch.enabled ist standardmäßig aktiviert (setzen Sie false, um den automatischen ACP-Thread-Dispatch zu pausieren; explizite sessions_spawn({ runtime: "acp" })-Aufrufe funktionieren weiterhin).
• Thread-Sitzungs-Spawns im Kanaladapter aktiviert (Standard: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Thread-Bindungsunterstützung ist adapterspezifisch. Wenn der aktive Kanal- adapter keine Thread-Bindungen unterstützt, gibt OpenClaw eine klare Nicht-unterstützt-/Nicht-verfügbar-Meldung zurück.

• Jeder Kanaladapter, der Sitzungs-/Thread-Bindungsfähigkeit bereitstellt.
• Aktuelle integrierte Unterstützung: Discord-Threads/-Kanäle, Telegram-Themen (Forumthemen in Gruppen/Supergruppen und DM-Themen).
• Plugin-Kanäle können Unterstützung über dieselbe Bindungsschnittstelle hinzufügen.

Interaktive Sitzungen sind dafür gedacht, auf einer sichtbaren Chat- Oberfläche weiter zu kommunizieren:

• /acp spawn ... --bind here bindet die aktuelle Unterhaltung an die ACP-Sitzung.
• /acp spawn ... --thread ... bindet einen Kanal-Thread/ein Thema an die ACP-Sitzung.
• Dauerhaft konfigurierte bindings[].type="acp" leiten passende Unterhaltungen an dieselbe ACP-Sitzung weiter.

Folgenachrichten in der gebundenen Unterhaltung werden direkt an die ACP-Sitzung geleitet, und ACP-Ausgabe wird an denselben Kanal/Thread/dasselbe Thema zurückgeliefert.

Was OpenClaw an das Harness sendet:

• Normale gebundene Folgenachrichten werden als Prompt-Text gesendet, plus Anhänge nur dann, wenn Harness/Backend sie unterstützt.
• /acp-Verwaltungsbefehle und lokale Gateway-Befehle werden vor der ACP-Weiterleitung abgefangen.
• Von der Runtime erzeugte Abschlussereignisse werden pro Ziel materialisiert. OpenClaw-Agenten erhalten den internen Runtime-Kontext-Umschlag von OpenClaw; externe ACP-Harnesses erhalten einen einfachen Prompt mit dem Kindeergebnis und der Anweisung. Der rohe <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>>-Umschlag sollte niemals an externe Harnesses gesendet oder als ACP-Benutzertranskripttext persistiert werden.
• ACP-Transkripteinträge verwenden den benutzersichtbaren Auslösetext oder den einfachen Abschluss-Prompt. Interne Ereignismetadaten bleiben, wo möglich, in OpenClaw strukturiert und werden nicht als benutzerverfasster Chat-Inhalt behandelt.

Einmalige ACP-Sitzungen, die von einem anderen Agentenlauf gestartet werden, sind Hintergrund- Kindprozesse, ähnlich wie Sub-Agents:

• Der Elternteil fordert Arbeit mit sessions_spawn({ runtime: "acp", mode: "run" }) an.
• Das Kind läuft in seiner eigenen ACP-Harness-Sitzung.
• Kind-Turns laufen auf derselben Hintergrund-Lane, die von nativen Sub-Agent-Spawns verwendet wird, sodass ein langsames ACP-Harness nicht unabhängige Arbeit der Hauptsitzung blockiert.
• Der Abschluss wird über den Task-Completion-Ankündigungspfad zurückgemeldet. OpenClaw wandelt interne Abschlussmetadaten in einen einfachen ACP-Prompt um, bevor sie an ein externes Harness gesendet werden, sodass Harnesses keine nur für OpenClaw bestimmten Runtime-Kontextmarker sehen.
• Der Elternteil formuliert das Kindeergebnis in normaler Assistentenstimme um, wenn eine benutzersichtbare Antwort sinnvoll ist.

Behandeln Sie diesen Pfad nicht als Peer-to-Peer-Chat zwischen Elternteil und Kind. Das Kind hat bereits einen Abschlusskanal zurück zum Elternteil.

sessions_send kann nach dem Spawn eine andere Sitzung ansprechen. Für normale Peer-Sitzungen verwendet OpenClaw nach dem Injizieren der Nachricht einen Agent-zu-Agent- (A2A)-Folgepfad:

• Auf die Antwort der Zielsitzung warten.
• Optional anfragende und Ziel-Sitzung eine begrenzte Anzahl von Folgeturns austauschen lassen.
• Die Zielsitzung auffordern, eine Ankündigungsnachricht zu erzeugen.
• Diese Ankündigung an den sichtbaren Kanal oder Thread zustellen.

Dieser A2A-Pfad ist ein Fallback für Peer-Sends, bei denen der Sender eine sichtbare Folgenachricht benötigt. Er bleibt aktiviert, wenn eine nicht verwandte Sitzung ein ACP-Ziel sehen und ihm Nachrichten senden kann, zum Beispiel unter breiten tools.sessions.visibility-Einstellungen.

OpenClaw überspringt die A2A-Folge nur, wenn der Anfragende der Elternteil seines eigenen, vom Elternteil verwalteten, einmaligen ACP-Kindes ist. In diesem Fall kann A2A zusätzlich zur Task Completion den Elternteil mit dem Kindeergebnis wecken, die Antwort des Elternteils zurück an das Kind weiterleiten und eine Eltern/Kind-Echoschleife erzeugen. Das sessions_send-Ergebnis meldet delivery.status="skipped" für diesen verwalteten Kindfall, weil der Abschlusspfad bereits für das Ergebnis verantwortlich ist.

Verwenden Sie resumeSessionId, um eine frühere ACP-Sitzung fortzusetzen, statt neu zu starten. Der Agent spielt seinen Unterhaltungsverlauf über session/load erneut ein, sodass er mit dem vollständigen Kontext des Vorherigen weiterarbeitet.

{
  "task": "Continue where we left off - fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

Häufige Anwendungsfälle:

• Eine Codex-Sitzung von Ihrem Laptop auf Ihr Telefon übergeben – weisen Sie Ihren Agenten an, dort weiterzumachen, wo Sie aufgehört haben.
• Eine Coding-Sitzung fortsetzen, die Sie interaktiv in der CLI gestartet haben, jetzt headless über Ihren Agenten.
• Arbeit wiederaufnehmen, die durch einen Gateway-Neustart oder ein Idle-Timeout unterbrochen wurde.

Hinweise:

• resumeSessionId gilt nur bei runtime: "acp"; die Standard-Sub-Agent-Runtime ignoriert dieses nur für ACP vorgesehene Feld.
• streamTo gilt nur bei runtime: "acp"; die Standard-Sub-Agent-Runtime ignoriert dieses nur für ACP vorgesehene Feld.
• resumeSessionId ist eine host-lokale ACP-/Harness-Fortsetzungs-ID, kein OpenClaw-Kanalsitzungsschlüssel; OpenClaw prüft weiterhin die ACP-Spawn-Richtlinie und die Ziel-Agent-Richtlinie vor der Weiterleitung, während das ACP-Backend oder Harness die Autorisierung für das Laden dieser Upstream-ID verwaltet.
• resumeSessionId stellt den Upstream-ACP-Unterhaltungsverlauf wieder her; thread und mode gelten weiterhin normal für die neue OpenClaw-Sitzung, die Sie erstellen, sodass mode: "session" weiterhin thread: true erfordert.
• Der Ziel-Agent muss session/load unterstützen (Codex und Claude Code tun dies).
• Wenn die Sitzungs-ID nicht gefunden wird, schlägt der Spawn mit einem klaren Fehler fehl – kein stillschweigender Fallback auf eine neue Sitzung.

Führen Sie nach einem Gateway-Deployment eine Live-End-to-End-Prüfung aus, statt Unit-Tests zu vertrauen:

1. Verifizieren Sie die deployte Gateway-Version und den Commit auf dem Zielhost.
2. Öffnen Sie eine temporäre ACPX-Bridge-Sitzung zu einem Live-Agenten.
3. Bitten Sie diesen Agenten, sessions_spawn mit runtime: "acp", agentId: "codex", mode: "run" und der Aufgabe Reply with exactly LIVE-ACP-SPAWN-OK aufzurufen.
4. Verifizieren Sie accepted=yes, einen echten childSessionKey und keinen Validatorfehler.
5. Bereinigen Sie die temporäre Bridge-Sitzung.

Belassen Sie das Gate bei mode: "run" und überspringen Sie streamTo: "parent" – thread-gebundenes mode: "session" und Stream-Relay-Pfade sind separate umfangreichere Integrationsdurchläufe.