ACP-Agenten

• Wenn plugins.allow festgelegt ist, handelt es sich um eine restriktive Plugin-Liste, die 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 Projektvertrauenseinträge sowie sichere Konfigurationen für die Modell-/Provider-Weiterleitung (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 Adapter für Ziel-Harnesses können bei der ersten Verwendung bei Bedarf mit npx abgerufen werden.
• Die Authentifizierung beim jeweiligen Hersteller muss für dieses Harness bereits auf dem Host eingerichtet 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 Weiterleitung, Status der Hintergrundaufgaben, Zustellung, Bindungen und Richtlinien; das Harness verwaltet seine Provider-Anmeldung, seinen Modellkatalog, sein Dateisystemverhalten und seine nativen Werkzeuge.

Bevor Sie OpenClaw als Ursache vermuten, prüfen Sie Folgendes:

• /acp doctor meldet ein aktiviertes, fehlerfreies Backend.
• Die Ziel-ID ist durch acp.allowedAgents zugelassen, wenn diese Zulassungsliste festgelegt ist.
• Der Harness-Befehl kann auf dem Gateway-Host gestartet werden.
• Die Provider-Authentifizierung für dieses Harness ist 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; alternativ lassen Sie cwd weg, damit das Backend seinen Standardwert verwendet.
• Der Berechtigungsmodus ist für die Aufgabe geeignet. Nicht interaktive Sitzungen können keine nativen Berechtigungsaufforderungen anklicken. Coding-Durchläufe mit vielen Schreib- oder Ausführungsvorgängen benötigen daher üblicherweise 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 gegebenenfalls wird eine Hintergrundaufgabe erstellt, wenn der Durchlauf einer übergeordneten Aufgabe gehört.
• ACP-Sitzungen im Besitz einer übergeordneten Aufgabe werden selbst dann als Hintergrundarbeit behandelt, wenn die Laufzeitsitzung persistent ist. Abschluss und oberflächenübergreifende Zustellung erfolgen über die Benachrichtigungsfunktion der übergeordneten Aufgabe, statt wie bei einer gewöhnlichen benutzerseitigen Chatsitzung.
• Die Aufgabenverwaltung schließt beendete oder verwaiste einmalige ACP-Sitzungen im Besitz einer übergeordneten Aufgabe. Persistente ACP-Sitzungen bleiben erhalten, solange eine aktive Unterhaltungsbindung besteht. Veraltete persistente Sitzungen ohne aktive Bindung werden geschlossen, damit sie nicht unbemerkt fortgesetzt werden können, nachdem die zugehörige Aufgabe beendet oder ihr Aufgabeneintrag entfernt wurde.
• Gebundene Folgenachrichten werden direkt an die ACP-Sitzung gesendet, bis die Bindung geschlossen, deaktiviert, zurückgesetzt oder abgelaufen ist.
• Gateway-Befehle bleiben lokal. /acp ..., /status und /unfocus werden niemals als gewöhnlicher Prompttext an ein gebundenes ACP-Harness gesendet.
• cancel bricht die aktive Interaktion 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 aufbewahren, wenn es die Fortsetzung unterstützt.
• Das acpx-Plugin bereinigt nach close OpenClaw-eigene Wrapper- und Adapter-Prozessbäume und entfernt beim Start des Gateway veraltete, OpenClaw-eigene ACPX-Waisenprozesse.
• Inaktive Laufzeit-Worker können nach acp.runtime.ttlMinutes bereinigt werden; gespeicherte Sitzungsmetadaten bleiben für /acp sessions verfügbar.

Natürlichsprachige Auslöser, die bei aktiviertem Plugin an das native Codex-Plugin weitergeleitet werden sollen:

• „Diesen Discord-Kanal an Codex binden.“
• „Diesen Chat mit dem Codex-Thread <id> verbinden.“
• „Codex-Threads anzeigen und anschließend diesen binden.“

Die native Codex-Konversationsbindung ist der standardmäßige Pfad für die 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 ACP nur dann ausdrücklich, wenn Sie das ACP-Laufzeit-/Sitzungsmodell wünschen. Die Unterstützungsgrenze für eingebettetes Codex ist im Supportvertrag für Codex Harness v1 dokumentiert.

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

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

OpenClaw wählt runtime: "acp", löst die Harness-agentId auf, bindet die Sitzung sofern unterstützt an die aktuelle Konversation oder den aktuellen Thread und leitet weitere Nachrichten bis zum Schließen oder Ablauf an diese Sitzung weiter. Codex folgt diesem Pfad nur, wenn ACP/acpx explizit angegeben ist 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, der Anfordernde 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 Aufrufe von sessions_spawn({ runtime: "acp" }) jedoch weder aus noch blockiert sie. Als Ziele dienen ACP-Harness-IDs wie codex, claude, droid, gemini oder opencode. Übergeben Sie keine normale OpenClaw-Konfigurations-Agenten-ID aus agents_list, es sei denn, dieser Eintrag ist ausdrücklich mit agents.list[].runtime.type="acp" konfiguriert; 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 bei Kanälen, die Bindungen an die aktuelle Konversation anbieten; andernfalls gibt OpenClaw eine eindeutige Meldung aus, dass dies nicht unterstützt wird. Bindungen bleiben über Gateway-Neustarts hinweg erhalten.
• Bei Discord steuert spawnSessions die Erstellung untergeordneter Threads für --thread auto|here – nicht für --bind here.
• Wenn Sie ohne --cwd eine Sitzung für einen anderen ACP-Agenten erzeugen, übernimmt OpenClaw standardmäßig den Arbeitsbereich des Zielagenten. Fehlende übernommene Pfade (ENOENT/ENOTDIR) fallen auf die Backend-Standardeinstellung zurück; andere Zugriffsfehler (z. B. EACCES) werden als Erzeugungsfehler ausgegeben.
• Gateway-Verwaltungsbefehle bleiben in gebundenen Konversationen lokal – /acp ...-Befehle werden von OpenClaw verarbeitet, selbst wenn normaler nachfolgender Text 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.
• Weitere Nachrichten in diesem Thread werden an die gebundene ACP-Sitzung weitergeleitet.
• ACP-Ausgaben werden an denselben Thread zurückgesendet.
• Aufheben des Fokus, Schließen, Archivieren, Überschreiten des Inaktivitätszeitlimits oder Ablauf des Höchstalters entfernt die Bindung.
• /acp close, /acp cancel, /acp status, /status und /unfocus sind Gateway-Befehle, keine Prompts an das ACP-Harness.

Erforderliche Funktionsschalter für Thread-gebundenes ACP:

• acp.enabled=true
• acp.dispatch.enabled ist standardmäßig aktiviert (setzen Sie es auf false, um die automatische ACP-Thread-Weiterleitung zu pausieren; explizite Aufrufe von sessions_spawn({ runtime: "acp" }) funktionieren weiterhin).
• Das Erzeugen von Thread-Sitzungen durch den Kanaladapter ist aktiviert (Standard: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.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 die Funktion nicht unterstützt wird oder nicht verfügbar ist.

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

Interaktive Sitzungen sind für fortlaufende Unterhaltungen auf einer sichtbaren Chatoberfläche vorgesehen:

• /acp spawn ... --bind here bindet die aktuelle Unterhaltung an die ACP-Sitzung.
• /acp spawn ... --thread ... bindet einen Kanal-Thread bzw. ein Thema 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 die Umgebung sendet:

• Normale gebundene Folgenachrichten werden als Eingabeaufforderungstext gesendet, ergänzt um Anhänge, sofern die Umgebung bzw. das Backend diese unterstützt.
• /acp-Verwaltungsbefehle und lokale Gateway-Befehle werden vor der ACP-Weiterleitung abgefangen.
• Von der Laufzeit erzeugte Abschlussereignisse werden für jedes Ziel materialisiert. OpenClaw-Agenten erhalten die interne Laufzeitkontext-Hülle von OpenClaw; externe ACP-Umgebungen erhalten eine einfache Eingabeaufforderung mit dem Ergebnis des untergeordneten Prozesses und einer Anweisung. Die rohe <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>>-Hülle darf niemals an externe Umgebungen gesendet oder als Text eines ACP-Benutzertranskripts gespeichert werden.
• ACP-Transkripteinträge verwenden den für Benutzer sichtbaren Auslösertext oder die einfache Abschluss-Eingabeaufforderung. Interne Ereignismetadaten bleiben nach Möglichkeit in OpenClaw strukturiert und werden nicht als vom Benutzer verfasster Chatinhalt behandelt.

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

• Die übergeordnete Sitzung fordert mit sessions_spawn({ runtime: "acp", mode: "run" }) Arbeit an.
• Der untergeordnete Prozess wird in einer eigenen ACP-Umgebungssitzung ausgeführt.
• Untergeordnete Durchläufe werden in derselben Hintergrundspur ausgeführt, die auch für native Unteragentenstarts verwendet wird, sodass eine langsame ACP-Umgebung nicht die nicht zusammenhängende Arbeit der Hauptsitzung blockiert.
• Der Abschluss wird über den Ankündigungspfad für Aufgabenabschlüsse zurückgemeldet. OpenClaw wandelt interne Abschlussmetadaten in eine einfache ACP-Eingabeaufforderung um, bevor sie an eine externe Umgebung gesendet werden, sodass Umgebungen keine ausschließlich OpenClaw-internen Laufzeitkontextmarkierungen sehen.
• Die übergeordnete Sitzung 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 übergeordnetem und untergeordnetem Prozess. Der untergeordnete Prozess verfügt bereits über einen Abschlusskanal zurück zur übergeordneten Sitzung.

sessions_send kann nach dem Start eine andere Sitzung ansprechen. 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 der anfordernden Sitzung und der Zielsitzung den Austausch einer begrenzten Anzahl von Folgedurchläufen ermöglichen.
• 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 Übertragungen zwischen Peers, bei denen der Absender eine sichtbare Rückmeldung benötigt. Er bleibt aktiviert, wenn eine nicht zugehörige Sitzung ein ACP-Ziel sehen und ihm Nachrichten senden kann, beispielsweise bei weit gefassten Einstellungen für tools.sessions.visibility.

OpenClaw überspringt die A2A-Rückmeldung nur, wenn der Anfragende der übergeordneten Sitzung seines eigenen, von dieser übergeordneten Sitzung verwalteten einmaligen ACP-Kindprozesses entspricht. In diesem Fall kann die Ausführung von A2A zusätzlich zum Aufgabenabschluss die übergeordnete Sitzung mit dem Ergebnis des Kindprozesses aktivieren, die Antwort der übergeordneten Sitzung an den Kindprozess zurückleiten und eine Echo- Schleife zwischen übergeordneter Sitzung und Kindprozess erzeugen. Das Ergebnis von sessions_send meldet für diesen Fall eines verwalteten Kindprozesses delivery.status="skipped", da der Abschlusspfad bereits für das Ergebnis verantwortlich ist.

Verwenden Sie resumeSessionId, um eine vorherige ACP-Sitzung fortzusetzen, anstatt eine neue zu starten. Der Agent spielt seinen Gesprächsverlauf über session/load erneut ein und setzt daher mit dem vollständigen bisherigen Kontext fort.

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

Häufige Anwendungsfälle:

• Übergeben Sie eine Codex-Sitzung von Ihrem Laptop an Ihr Telefon – weisen Sie Ihren Agenten an, dort fortzufahren, wo Sie aufgehört haben.
• Setzen Sie eine Programmiersitzung, die Sie interaktiv in der CLI begonnen haben, nun ohne Benutzeroberfläche über Ihren Agenten fort.
• Nehmen Sie Arbeiten wieder auf, die durch einen Neustart des Gateway oder eine Zeitüberschreitung wegen Inaktivität unterbrochen wurden.

Hinweise:

• resumeSessionId gilt nur bei runtime: "acp"; die standardmäßige Subagent-Laufzeitumgebung ignoriert dieses ausschließlich für ACP vorgesehene Feld.
• streamTo gilt nur bei runtime: "acp"; die standardmäßige Subagent-Laufzeitumgebung ignoriert dieses ausschließlich für ACP vorgesehene Feld.
• resumeSessionId ist eine hostlokale Fortsetzungs-ID für ACP bzw. das Testsystem und kein OpenClaw-Sitzungsschlüssel eines Kanals; OpenClaw prüft vor der Weiterleitung weiterhin die ACP-Startregeln und die Richtlinie des Ziel-Agenten, während das ACP-Backend oder das Testsystem 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 Ziel-Agent muss session/load unterstützen (Codex und Claude Code unterstützen dies).
• Wenn die Sitzungs-ID nicht gefunden wird, schlägt der Start mit einer eindeutigen Fehlermeldung fehl – es erfolgt kein stiller Fallback auf eine neue Sitzung.

Führen Sie nach der Bereitstellung eines Gateway eine vollständige Live-Prüfung durch, anstatt sich auf Unit-Tests zu verlassen:

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

Beschränken Sie diese Prüfung auf mode: "run" und lassen Sie streamTo: "parent" aus – an Threads gebundene Pfade mit mode: "session" und Stream-Weiterleitung sind separate, umfangreichere Integrationsprüfungen.