ACP-Agenten

• Wenn plugins.allow gesetzt ist, ist dies ein restriktives Plugin-Inventar und 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.
• Codex ACP läuft mit einem isolierten CODEX_HOME; OpenClaw kopiert nur vertrauenswürdige Projekteinträge aus der Codex-Konfiguration des Hosts und vertraut dem aktiven Workspace, während Authentifizierung, Benachrichtigungen und Hooks in der Host-Konfiguration verbleiben.
• Andere Ziel-Harness-Adapter können beim ersten Verwenden weiterhin bei Bedarf mit npx abgerufen werden.
• Vendor-Authentifizierung muss für dieses Harness weiterhin auf dem Host vorhanden sein.
• Wenn der Host keinen npm- oder Netzwerkzugang 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, Bindings und Policy; das Harness besitzt seine Provider-Anmeldung, den Modellkatalog, 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 verwenden Sie den Standardwert des Backends.
• Der Berechtigungsmodus passt zur Arbeit. Nicht interaktive Sitzungen können keine nativen Berechtigungsabfragen anklicken, daher benötigen schreib-/ausführungsintensive Coding-Läufe in der Regel ein ACPX-Berechtigungsprofil, das headless fortfahren kann.

• Spawn erstellt oder setzt eine ACP-Runtime-Sitzung fort, zeichnet ACP-Metadaten im OpenClaw-Sitzungsspeicher auf und kann eine Hintergrundaufgabe erstellen, wenn der Lauf dem Parent gehört.
• Parent-eigene ACP-Sitzungen werden als Hintergrundarbeit behandelt, auch wenn die Runtime-Sitzung persistent ist; Abschluss und oberflächenübergreifende Zustellung laufen über den Parent-Aufgaben-Notifier, statt sich wie eine normale benutzerseitige Chat-Sitzung zu verhalten.
• Die Aufgabenwartung schließt terminale oder verwaiste Parent-eigene One-Shot-ACP-Sitzungen. Persistente ACP-Sitzungen bleiben erhalten, solange ein aktives Unterhaltungs-Binding besteht; veraltete persistente Sitzungen ohne aktives Binding werden geschlossen, damit sie nicht stillschweigend fortgesetzt werden können, nachdem die besitzende Aufgabe erledigt ist oder ihr Aufgabendatensatz nicht mehr existiert.
• Gebundene Follow-up-Nachrichten gehen direkt an die ACP-Sitzung, bis das Binding geschlossen, unfokussiert, 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 Binding noch Sitzungsmetadaten.
• close beendet die ACP-Sitzung aus Sicht von OpenClaw und entfernt das Binding. Ein Harness kann weiterhin seine eigene Upstream-Historie behalten, wenn es Fortsetzen unterstützt.
• Das acpx-Plugin bereinigt von OpenClaw besessene Wrapper- und Adapter-Prozessbäume nach close und räumt veraltete von OpenClaw besessene ACPX-Waisen beim Gateway-Start auf.
• Inaktive Runtime-Worker können nach acp.runtime.ttlMinutes bereinigt werden; gespeicherte Sitzungsmetadaten bleiben für /acp sessions verfügbar.

Trigger in natürlicher Sprache, die zum nativen Codex-Plugin geroutet werden sollten, wenn es aktiviert ist:

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

Native Codex-Konversationsbindung ist der standardmäßige Pfad für Chat-Steuerung. 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 durch OpenClaw-Genehmigungen leiten können. Codex-Stop-Hooks werden an OpenClaw before_agent_finalize weitergeleitet, wo Plugins einen weiteren Modelldurchlauf anfordern können, bevor Codex seine Antwort finalisiert. Das Relay bleibt bewusst konservativ: Es mutiert keine Codex-nativen Tool-Argumente und schreibt keine Codex-Thread-Datensätze um. Verwenden Sie explizites ACP nur, wenn Sie das ACP-Laufzeit-/Sitzungsmodell möchten. Die eingebettete Codex- Support-Grenze ist im Codex-Harness-v1-Supportvertrag dokumentiert.

• openai-codex/* - Legacy-Codex-OAuth-/Abonnement-Modellroute, die durch doctor repariert wird.
• openai/* - native eingebettete Codex-App-Server-Laufzeit für OpenAI-Agent-Turns.
• /codex ... - native Codex-Konversationssteuerung.
• /acp ... oder runtime: "acp" - explizite ACP/acpx-Steuerung.

Trigger, die zur ACP-Laufzeit 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 die Harness-agentId auf, bindet, sofern unterstützt, an die aktuelle Konversation oder den aktuellen 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 Anfragende nicht sandboxed ist und ein ACP-Laufzeit- Backend geladen ist. acp.dispatch.enabled=false pausiert den automatischen ACP-Thread-Versand, blendet explizite sessions_spawn({ runtime: "acp" })-Aufrufe aber nicht aus und blockiert sie nicht. 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 standardmäßige Sub-Agent-Laufzeit. 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 Konversation ankündigen; OpenClaw gibt andernfalls eine klare Nicht-unterstützt-Meldung zurück. Bindungen bleiben über Gateway-Neustarts hinweg bestehen.
• Auf Discord steuert spawnSessions die Erstellung untergeordneter Threads für --thread auto|here - nicht --bind here.
• Wenn Sie ohne --cwd zu einem anderen ACP-Agent spawnen, übernimmt OpenClaw standardmäßig den Workspace des Ziel-Agents. Fehlende geerbte Pfade (ENOENT/ENOTDIR) fallen auf den Backend-Standard zurück; andere Zugriffsfehler (z. B. EACCES) werden als Spawn-Fehler angezeigt.
• Gateway-Verwaltungsbefehle bleiben in gebundenen Konversationen lokal - /acp ...-Befehle werden von OpenClaw verarbeitet, auch wenn normaler Nachfolgetext 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.
• Nachfolgende Nachrichten in diesem Thread werden an die gebundene ACP-Sitzung geroutet.
• ACP-Ausgabe wird an denselben Thread zurückgeliefert.
• Unfocus/close/archive/idle-timeout oder Ablauf des Maximalalters 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 (auf false setzen, um automatischen ACP-Thread-Versand zu pausieren; explizite sessions_spawn({ runtime: "acp" })-Aufrufe funktionieren weiterhin).
• Channel-Adapter-Thread-Sitzungs-Spawns aktiviert (Standard: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Unterstützung für Thread-Bindungen ist adapterspezifisch. Wenn der aktive Kanal- Adapter Thread-Bindungen nicht 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 (Forumsthemen in Gruppen/Supergruppen und DM-Themen).
• Plugin-Kanäle können Unterstützung über dieselbe Bindungsschnittstelle hinzufügen.

Interaktive Sitzungen sollen die Unterhaltung auf einer sichtbaren Chat- Oberfläche fortsetzen:

• /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-Ausgaben werden zurück an denselben Kanal/Thread/dasselbe Thema zugestellt.

Was OpenClaw an den Harness sendet:

• Normale gebundene Folgenachrichten werden als Prompt-Text gesendet, plus Anhänge nur, wenn der Harness/das Backend sie unterstützt.
• /acp-Verwaltungsbefehle und lokale Gateway-Befehle werden vor der ACP-Weiterleitung abgefangen.
• Zur Laufzeit erzeugte Abschlussereignisse werden pro Ziel materialisiert. OpenClaw-Agenten erhalten OpenClaws interne Laufzeitkontext-Hülle; externe ACP-Harnesses erhalten einen einfachen Prompt mit dem Ergebnis des untergeordneten Elements und der Anweisung. Die rohe <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>>-Hülle sollte niemals an externe Harnesses gesendet oder als ACP-Benutzer-Transkripttext 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 vom Benutzer verfasster Chat-Inhalt behandelt.

Einmalige ACP-Sitzungen, die von einem anderen Agentenlauf gestartet werden, sind Hintergrund- untergeordnete Elemente, ähnlich wie Sub-Agenten:

• Das übergeordnete Element fordert Arbeit mit sessions_spawn({ runtime: "acp", mode: "run" }) an.
• Das untergeordnete Element läuft in einer eigenen ACP-Harness-Sitzung.
• Durchläufe des untergeordneten Elements laufen auf derselben Hintergrund-Lane wie native Sub-Agent-Starts, sodass ein langsamer ACP-Harness nicht unabhängige Arbeit der Hauptsitzung blockiert.
• Abschlussmeldungen laufen über den Ankündigungspfad für Aufgabenabschlüsse zurück. OpenClaw wandelt interne Abschlussmetadaten in einen einfachen ACP-Prompt um, bevor es sie an einen externen Harness sendet, sodass Harnesses keine nur für OpenClaw bestimmten Laufzeitkontextmarker sehen.
• Das übergeordnete Element formuliert das Ergebnis des untergeordneten Elements in normaler Assistentenstimme neu, wenn eine benutzersichtbare Antwort nützlich ist.

Behandeln Sie diesen Pfad nicht als Peer-to-Peer-Chat zwischen übergeordnetem und untergeordnetem Element. Das untergeordnete Element hat bereits einen Abschlusskanal zurück zum übergeordneten Element.

sessions_send kann nach dem Start eine andere Sitzung adressieren. Für normale Peer-Sitzungen verwendet OpenClaw nach dem Einfügen der Nachricht einen Agent-zu-Agent-(A2A)-Folgepfad:

• Auf die Antwort der Zielsitzung warten.
• Optional Anforderer und Ziel eine begrenzte Anzahl von Folge-Turns austauschen lassen.
• Das Ziel bitten, 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 Absender eine sichtbare Folgeantwort benötigt. Er bleibt aktiviert, wenn eine unabhängige 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 Anforderer das übergeordnete Element seines eigenen, vom übergeordneten Element verwalteten einmaligen ACP-untergeordneten Elements ist. In diesem Fall kann A2A zusätzlich zum Aufgabenabschluss das übergeordnete Element mit dem Ergebnis des untergeordneten Elements wecken, die Antwort des übergeordneten Elements zurück an das untergeordnete Element weiterleiten und eine Echo-Schleife zwischen übergeordnetem und untergeordnetem Element erzeugen. Das sessions_send-Ergebnis meldet delivery.status="skipped" für diesen Fall eines verwalteten untergeordneten Elements, weil der Abschlusspfad bereits für das Ergebnis zuständig ist.

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

{  "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, nun headless über Ihren Agenten.
• Arbeit wieder aufnehmen, die durch einen Gateway-Neustart oder ein Leerlauf-Timeout unterbrochen wurde.

Hinweise:

• resumeSessionId gilt nur, wenn runtime: "acp" gesetzt ist; die Standard-Sub-Agent-Laufzeit ignoriert dieses nur für ACP bestimmte Feld.
• streamTo gilt nur, wenn runtime: "acp" gesetzt ist; die Standard-Sub-Agent-Laufzeit ignoriert dieses nur für ACP bestimmte Feld.
• resumeSessionId ist eine hostlokale ACP-/Harness-Wiederaufnahme-ID, kein OpenClaw-Kanalsitzungsschlüssel; OpenClaw prüft weiterhin die ACP-Start-Policy und die Zielagenten-Policy vor der Weiterleitung, während das ACP-Backend oder der Harness die Autorisierung zum 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 Zielagent muss session/load unterstützen (Codex und Claude Code tun dies).
• Wenn die Sitzungs-ID nicht gefunden wird, schlägt der Start mit einem klaren Fehler fehl - kein stiller Fallback auf eine neue Sitzung.

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

1. Prüfen Sie die bereitgestellte 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. Prüfen Sie accepted=yes, einen echten childSessionKey und dass kein Validator-Fehler vorliegt.
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.