ACP-Agenten

• Wenn plugins.allow festgelegt ist, handelt es sich um ein restriktives Plugin-Inventar, das acpx enthalten muss. Andernfalls wird das installierte ACP-Backend absichtlich blockiert (/acp doctor meldet den fehlenden Eintrag in der Zulassungsliste).
• Der Codex-ACP-Adapter wird mit dem acpx-Plugin ausgeliefert und nach Möglichkeit lokal gestartet.
• Codex ACP wird mit einem isolierten CODEX_HOME ausgeführt. OpenClaw kopiert vertrauenswürdige Projekt-Vertrauenseinträge sowie sichere Modell-/Provider-Routing-Konfigurationen (model, model_provider, model_reasoning_effort, sandbox_mode und sichere model_providers.<name>-Felder) aus der Codex-Konfiguration des Hosts; Authentifizierung, Benachrichtigungen und Hooks verbleiben ausschließlich in der Hostkonfiguration.
• Andere Ziel-Harness-Adapter können bei der ersten Verwendung bei Bedarf mit npx abgerufen werden.
• Die Authentifizierung beim Hersteller muss für dieses Harness bereits auf dem Host vorhanden sein.
• Wenn der Host weder über npm noch über Netzwerkzugriff verfügt, schlagen Adapterabrufe beim ersten Start fehl, bis die Caches vorab gefüllt wurden oder der Adapter auf andere Weise installiert wurde.

ACP startet einen echten externen Harness-Prozess. OpenClaw verwaltet Routing, den Zustand von Hintergrundaufgaben, Zustellung, Bindungen und Richtlinien; das Harness verwaltet seine Provider-Anmeldung, seinen Modellkatalog, sein Dateisystemverhalten und seine nativen Tools.

Bevor Sie OpenClaw als Ursache ansehen, überprüfen Sie Folgendes:

• /acp doctor meldet ein aktiviertes, funktionsfähiges Backend.
• Die Ziel-ID ist durch acp.allowedAgents zugelassen, wenn diese Zulassungsliste festgelegt ist.
• Der Harness-Befehl kann auf dem Gateway-Host gestartet werden.
• Für dieses Harness ist eine Provider-Authentifizierung vorhanden (claude, codex, gemini, opencode, droid usw.).
• Das ausgewählte Modell ist für dieses Harness verfügbar – Modell-IDs sind nicht zwischen Harnesses übertragbar.
• Das angeforderte cwd ist vorhanden und zugänglich; lassen Sie andernfalls cwd weg, damit das Backend seinen Standardwert verwendet.
• Der Berechtigungsmodus passt zur Aufgabe. Nicht interaktive Sitzungen können nicht auf native Berechtigungsaufforderungen klicken. Daher benötigen Coding-Ausführungen mit vielen Schreib- oder Ausführungsvorgängen normalerweise ein ACPX-Berechtigungsprofil, das ohne Benutzerinteraktion fortfahren kann.

• Beim Starten wird eine ACP-Laufzeitsitzung erstellt oder fortgesetzt, ACP-Metadaten werden im OpenClaw-Sitzungsspeicher erfasst und es kann eine Hintergrundaufgabe erstellt werden, wenn der Lauf einer übergeordneten Aufgabe gehört.
• ACP-Sitzungen, die einer übergeordneten Aufgabe gehören, werden auch dann als Hintergrundarbeit behandelt, wenn die Laufzeitsitzung persistent ist; Abschluss und oberflächenübergreifende Zustellung erfolgen über die Benachrichtigungsfunktion der übergeordneten Aufgabe, statt sich wie eine normale benutzerseitige Chatsitzung zu verhalten.
• Die Aufgabenverwaltung schließt beendete oder verwaiste, einer übergeordneten Aufgabe gehörende einmalige ACP-Sitzungen. Persistente ACP-Sitzungen bleiben erhalten, solange eine aktive Konversationsbindung besteht; veraltete persistente Sitzungen ohne aktive Bindung werden geschlossen, damit sie nicht unbemerkt fortgesetzt werden können, nachdem die zugehörige Aufgabe abgeschlossen wurde oder ihr Aufgabeneintrag nicht mehr vorhanden ist.
• Gebundene Folgenachrichten werden direkt an die ACP-Sitzung gesendet, bis die Bindung geschlossen, der Fokus aufgehoben, sie zurückgesetzt oder abgelaufen ist.
• Gateway-Befehle bleiben lokal. /acp ..., /status und /unfocus werden niemals als normaler Prompt-Text an ein gebundenes ACP-Harness gesendet.
• cancel bricht den aktiven Durchlauf ab, wenn das Backend den Abbruch unterstützt; die Bindung oder die Sitzungsmetadaten werden dadurch nicht gelöscht.
• close beendet die ACP-Sitzung aus Sicht von OpenClaw und entfernt die Bindung. Ein Harness kann seinen eigenen vorgelagerten Verlauf weiterhin beibehalten, wenn es die Fortsetzung unterstützt.
• Das acpx-Plugin bereinigt nach close die OpenClaw-eigenen Wrapper- und Adapter-Prozessbäume und beendet beim Start des Gateways veraltete verwaiste OpenClaw-eigene ACPX-Prozesse.
• Inaktive Laufzeit-Worker können nach dem integrierten Inaktivitätszeitraum bereinigt werden; gespeicherte Sitzungsmetadaten bleiben für /acp sessions verfügbar.

Auslöser in natürlicher Sprache, die an das native Codex-Plugin weitergeleitet werden sollten, wenn es aktiviert ist:

• „Binden Sie diesen Discord-Kanal an Codex.“
• „Verknüpfen Sie diesen Chat mit dem Codex-Thread <id>.“
• „Zeigen Sie Codex-Threads an und binden Sie dann diesen.“

Die native Codex-Konversationsbindung ist der standardmäßige Pfad zur 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 fügt OpenClaw pro Durchlauf ein natives Hook-Relay ein, damit Plugin-Hooks before_tool_call blockieren, after_tool_call beobachten und Codex- PermissionRequest-Ereignisse über OpenClaw-Genehmigungen weiterleiten können. Codex- Stop-Hooks werden an OpenClaw before_agent_finalize weitergeleitet, wo Plugins einen weiteren Modelldurchlauf anfordern können, bevor Codex seine Antwort abschließt. Das Relay bleibt bewusst konservativ: Es verändert weder Argumente Codex-nativer Tools noch schreibt es Codex-Thread-Datensätze um. Verwenden Sie explizites ACP nur, wenn Sie das ACP-Laufzeit-/Sitzungsmodell verwenden möchten. Die Grenze der eingebetteten Codex-Unterstützung ist im Supportvertrag für Codex Harness v1 dokumentiert.

• Veraltete Codex-Modellreferenzen – veraltete Codex-OAuth-/Abonnement-Modellroute, die durch doctor repariert wird.
• openai/* – eingebettete native Codex-App-Server-Laufzeit für OpenAI-Agentendurchläufe.
• /codex ... – native Codex-Konversationssteuerung.
• /acp ... oder runtime: "acp" – explizite ACP-/acpx-Steuerung.

Auslöser, die an die ACP-Laufzeit weitergeleitet werden 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 führen Sie Folgenachrichten anschließend im selben Thread fort.“
• „Führen Sie Codex über ACP in einem Hintergrund-Thread aus.“

OpenClaw wählt runtime: "acp", löst das Harness agentId auf, bindet es, sofern unterstützt, an die aktuelle Konversation oder den aktuellen Thread und leitet Folgenachrichten bis zum Schließen oder Ablaufen an diese Sitzung weiter. Codex folgt diesem Pfad nur, wenn ACP/acpx explizit angegeben wurde oder das native Codex-Plugin für den angeforderten Vorgang nicht verfügbar ist.

Für sessions_spawn wird runtime: "acp" nur angeboten, wenn ACP aktiviert ist, die anfragende Instanz nicht in einer Sandbox ausgeführt wird und ein ACP-Laufzeit-Backend geladen ist. acp.dispatch.enabled=false pausiert die automatische ACP-Thread-Weiterleitung, blendet explizite sessions_spawn({ runtime: "acp" })-Aufrufe jedoch weder aus noch blockiert es sie. Das Ziel sind ACP-Harness-IDs wie codex, claude, droid, gemini oder opencode. Übergeben Sie keine normale OpenClaw-Konfigurations-Agenten-ID aus agents_list, sofern dieser Eintrag nicht ausdrücklich mit agents.entries.*.runtime.type="acp" konfiguriert ist; verwenden Sie andernfalls 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 eine Bindung an die aktuelle Konversation anbieten; andernfalls gibt OpenClaw eine eindeutige Meldung aus, dass dies nicht unterstützt wird. Bindungen bleiben über Gateway-Neustarts hinweg bestehen.
• Bei Discord steuert spawnSessions die Erstellung untergeordneter Threads für --thread auto|here – nicht für --bind here.
• Wenn Sie ohne --cwd einen anderen ACP-Agenten starten, übernimmt OpenClaw standardmäßig den Arbeitsbereich des Ziel-Agenten. Fehlende übernommene Pfade (ENOENT/ENOTDIR) greifen auf den Backend-Standard zurück; andere Zugriffsfehler (z. B. EACCES) werden als Startfehler ausgegeben.
• Gateway-Verwaltungsbefehle bleiben in gebundenen Konversationen lokal – /acp ...-Befehle werden von OpenClaw verarbeitet, auch wenn normaler Folgenachrichtentext an die gebundene ACP-Sitzung weitergeleitet wird; /status und /unfocus bleiben ebenfalls lokal, sofern 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 weitergeleitet.
• ACP-Ausgaben werden an denselben Thread zurückgesendet.
• Aufheben des Fokus, Schließen, Archivieren, eine Inaktivitätsüberschreitung oder das Ablaufen des Höchstalters entfernt die Bindung.
• /acp close, /acp cancel, /acp status, /status und /unfocus sind Gateway-Befehle und keine Prompts für das ACP-Harness.

Erforderliche Funktionsschalter für threadgebundenes ACP:

• acp.enabled=true
• acp.dispatch.enabled ist standardmäßig aktiviert (setzen Sie false, um die automatische ACP-Thread-Weiterleitung zu pausieren; explizite sessions_spawn({ runtime: "acp" })-Aufrufe funktionieren weiterhin).
• Das Starten von Thread-Sitzungen durch Kanaladapter ist aktiviert (Standard: true):
  • Discord/Telegram: session.threadBindings.spawnSessions=true

Die Unterstützung für Thread-Bindungen ist adapterspezifisch. Wenn der aktive Kanaladapter keine Thread-Bindungen unterstützt, gibt OpenClaw eine eindeutige Meldung aus, dass diese nicht unterstützt oder nicht verfügbar sind.

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

Interaktive Sitzungen sind dafür vorgesehen, die Unterhaltung auf einer sichtbaren Chatoberfläche fortzusetzen:

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

Folgenachrichten in der gebundenen Unterhaltung werden direkt an die ACP- Sitzung weitergeleitet, und ACP-Ausgaben werden an denselben Kanal/Thread/dasselbe Thema zurückgesendet.

Was OpenClaw an das Harness sendet:

• Normale gebundene Folgeanfragen werden als Prompt-Text gesendet, mit Anhängen nur dann, wenn die Harness-/Backend-Unterstützung dafür vorhanden ist.
• /acp-Verwaltungsbefehle und lokale Gateway-Befehle werden vor der ACP-Weiterleitung abgefangen.
• Zur Laufzeit erzeugte Abschlussereignisse werden für jedes Ziel materialisiert. OpenClaw-Agenten erhalten den internen Laufzeitkontext-Umschlag von OpenClaw; externe ACP-Harnesses erhalten einen einfachen Prompt mit dem Ergebnis des untergeordneten Prozesses und einer Anweisung. Der unverarbeitete <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>>-Umschlag darf niemals an externe Harnesses gesendet oder als Text eines ACP-Benutzertranskripts gespeichert werden.
• ACP-Transkripteinträge verwenden den für Benutzer sichtbaren Auslösetext oder den einfachen Abschlussprompt. Interne Ereignismetadaten bleiben in OpenClaw nach Möglichkeit strukturiert und werden nicht als vom Benutzer verfasster Chat-Inhalt behandelt.

Einmalige ACP-Sitzungen, die von einem anderen Agentenlauf erzeugt werden, sind untergeordnete Hintergrundprozesse, ähnlich wie Unteragenten:

• Der übergeordnete Prozess fordert mit sessions_spawn({ runtime: "acp", mode: "run" }) Arbeit an.
• Der untergeordnete Prozess wird in seiner eigenen ACP-Harness-Sitzung ausgeführt.
• Untergeordnete Durchläufe werden auf derselben Hintergrundspur wie native Unteragentenstarts ausgeführt, sodass ein langsames ACP-Harness nicht die Arbeit anderer Hauptsitzungen blockiert.
• Der Abschluss wird über den Ankündigungspfad für Aufgabenabschlüsse zurückgemeldet. OpenClaw wandelt interne Abschlussmetadaten in einen einfachen ACP-Prompt um, bevor dieser an ein externes Harness gesendet wird, sodass Harnesses keine OpenClaw-spezifischen Laufzeitkontextmarkierungen sehen.
• Der übergeordnete Prozess formuliert das Ergebnis des untergeordneten Prozesses in normaler Assistentensprache neu, wenn eine für Benutzer sichtbare Antwort sinnvoll ist.

Behandeln Sie diesen Pfad nicht als Peer-to-Peer-Chat zwischen dem übergeordneten und dem untergeordneten Prozess. Der untergeordnete Prozess verfügt bereits über einen Abschlusskanal zurück zum übergeordneten Prozess.

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

• Auf die Antwort der Zielsitzung warten.
• Optional eine begrenzte Anzahl von Folgedurchläufen zwischen anfragender und Zielinstanz zulassen.
• Das Ziel auffordern, eine Ankündigungsnachricht zu erstellen.
• Diese Ankündigung an den sichtbaren Kanal oder Thread zustellen.

Dieser A2A-Pfad dient als Rückfalloption für Peer-Sendungen, bei denen der Absender eine sichtbare Folgeantwort benötigt. Er bleibt aktiviert, wenn eine nicht zugehörige Sitzung ein ACP-Ziel sehen und ihm Nachrichten senden kann, beispielsweise bei umfassenden tools.sessions.visibility-Einstellungen.

OpenClaw überspringt die A2A-Folgeaktion nur, wenn die anfragende Instanz der übergeordnete Prozess ihres eigenen, übergeordneten einmaligen ACP-Kinds ist. In diesem Fall kann die Ausführung von A2A zusätzlich zum Aufgabenabschluss den übergeordneten Prozess mit dem Ergebnis des untergeordneten Prozesses aktivieren, die Antwort des übergeordneten Prozesses zurück an den untergeordneten Prozess weiterleiten und eine Echo-Schleife zwischen übergeordnetem und untergeordnetem Prozess erzeugen. Das Ergebnis von sessions_send meldet für diesen Fall eines eigenen untergeordneten Prozesses delivery.status="skipped", da der Abschlusspfad bereits für das Ergebnis zuständig ist.

Verwenden Sie resumeSessionId, um eine frühere ACP-Sitzung fortzusetzen, anstatt neu zu beginnen. Der Agent spielt seinen Gesprächsverlauf über session/load erneut ab und setzt somit mit dem vollständigen bisherigen Kontext fort.

{  "task": "Fahren Sie dort fort, wo wir aufgehört haben – beheben Sie die verbleibenden Testfehler",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Häufige Anwendungsfälle:

• Eine Codex-Sitzung vom Laptop auf das Smartphone übergeben – weisen Sie Ihren Agenten an, dort fortzufahren, wo Sie aufgehört haben.
• Eine Programmiersitzung fortsetzen, die Sie interaktiv in der CLI begonnen haben, nun ohne Benutzeroberfläche über Ihren Agenten.
• Arbeit wiederaufnehmen, die durch einen Neustart des Gateway oder ein Inaktivitätszeitlimit unterbrochen wurde.

Hinweise:

• resumeSessionId gilt nur, wenn runtime: "acp"; die standardmäßige Unteragenten-Laufzeit ignoriert dieses ausschließlich für ACP bestimmte Feld.
• streamTo gilt nur, wenn runtime: "acp"; die standardmäßige Unteragenten-Laufzeit ignoriert dieses ausschließlich für ACP bestimmte Feld.
• resumeSessionId ist eine hostlokale ACP-/Harness-Fortsetzungs-ID und kein OpenClaw-Kanalsitzungsschlüssel; OpenClaw prüft vor der Weiterleitung weiterhin die ACP-Startrichtlinie und die Richtlinie des Zielagenten, während das ACP-Backend oder Harness für die Autorisierung zum Laden dieser vorgelagerten ID zuständig ist.
• resumeSessionId stellt den vorgelagerten ACP-Gesprächsverlauf wieder her; thread und mode gelten weiterhin wie gewohnt für die neue OpenClaw-Sitzung, die Sie erstellen, daher erfordert mode: "session" weiterhin thread: true.
• 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 einer eindeutigen Fehlermeldung fehl – es erfolgt kein stiller Rückfall auf eine neue Sitzung.

Führen Sie nach einer Gateway-Bereitstellung eine aktive End-to-End-Prüfung durch, anstatt sich auf Unit-Tests zu verlassen:

1. Die bereitgestellte Gateway-Version und den Commit auf dem Zielhost überprüfen.
2. Eine temporäre ACPX-Bridge-Sitzung zu einem aktiven Agenten öffnen.
3. Diesen Agenten auffordern, sessions_spawn mit runtime: "acp", agentId: "codex", mode: "run" und der Aufgabe Reply with exactly LIVE-ACP-SPAWN-OK aufzurufen.
4. accepted=yes, einen echten childSessionKey und das Ausbleiben eines Validierungsfehlers überprüfen.
5. Die temporäre Bridge-Sitzung bereinigen.

Behalten Sie das Gate für mode: "run" bei und überspringen Sie streamTo: "parent" – Thread-gebundene mode: "session"- und Stream-Relay-Pfade sind separate, umfangreichere Integrationsdurchläufe.