ACP-Agenten

• Wenn plugins.allow gesetzt ist, handelt es sich um ein einschränkendes 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.
• Codex ACP läuft mit einem isolierten CODEX_HOME; OpenClaw kopiert vertrauenswürdige Projekteinträge sowie sichere Modell-/Provider-Routing-Konfiguration aus der Host-Codex-Konfiguration, während Authentifizierung, Benachrichtigungen und Hooks in der Host-Konfiguration bleiben.
• Andere Ziel-Harness-Adapter können bei der ersten Verwendung weiterhin bei Bedarf mit npx abgerufen werden.
• Die Anbieter-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 anderem Weg installiert wurde.

ACP startet einen echten externen Harness-Prozess. OpenClaw besitzt Routing, Status von Hintergrundaufgaben, Zustellung, Bindings und Richtlinien; das Harness besitzt seine Provider-Anmeldung, den Modellkatalog, das Dateisystemverhalten und native Tools.

Bevor Sie OpenClaw als Ursache annehmen, 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 die Verwendung seines Standards.
• Der Berechtigungsmodus passt zur Arbeit. Nicht interaktive Sitzungen können keine nativen Berechtigungsabfragen anklicken, daher benötigen schreib-/ausführungsintensive Coding-Läufe meist ein ACPX-Berechtigungsprofil, das ohne Bedienung fortfahren kann.

• Spawn erstellt oder setzt eine ACP-Laufzeitsitzung fort, zeichnet ACP-Metadaten im OpenClaw-Sitzungsspeicher auf und kann eine Hintergrundaufgabe erstellen, wenn der Lauf übergeordnetem Besitz unterliegt.
• Übergeordnet besessene ACP-Sitzungen werden als Hintergrundarbeit behandelt, selbst wenn die Laufzeitsitzung persistent ist; Abschluss und oberflächenübergreifende Zustellung laufen über den Notifier der übergeordneten Aufgabe, statt wie eine normale benutzerseitige Chat-Sitzung zu agieren.
• Aufgabenwartung schließt terminale oder verwaiste übergeordnet besessene 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 Aufgabeneintrag fehlt.
• Gebundene Folgenachrichten gehen direkt an die ACP-Sitzung, bis das Binding 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 das Binding noch Sitzungsmetadaten.
• close beendet die ACP-Sitzung aus Sicht von OpenClaw und entfernt das Binding. Ein Harness kann seine eigene Upstream-Historie weiterhin behalten, wenn es Fortsetzen unterstützt.
• Das acpx-Plugin bereinigt OpenClaw-eigene Wrapper- und Adapter-Prozessbäume nach close und entfernt veraltete OpenClaw-eigene ACPX-Waisen während des Gateway-Starts.
• Leerlaufende Laufzeit-Worker kommen nach acp.runtime.ttlMinutes für Bereinigung infrage; gespeicherte Sitzungsmetadaten bleiben für /acp sessions verfügbar.

Natürlichsprachliche Auslöser, die an das native Codex- Plugin geleitet werden sollten, wenn es aktiviert ist:

• „Binde diesen Discord-Kanal an Codex.“
• „Hänge diesen Chat an Codex-Thread <id> an.“
• „Zeige Codex-Threads und binde dann diesen.“

Native Codex-Konversationsbindung 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 Modelldurchlauf 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 wünschen. Die eingebettete Codex- Support-Grenze ist im Support-Vertrag für Codex Harness v1 dokumentiert.

• Legacy-Codex-Modellreferenzen - Legacy-Codex-OAuth/Abonnement-Modellroute, durch doctor repariert.
• openai/* - native eingebettete Codex-App-Server-Runtime für OpenAI-Agent-Turns.
• /codex ... - native Codex-Konversationssteuerung.
• /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ßend Folgeanfragen 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 sich, sofern unterstützt, an die aktuelle Konversation oder den aktuellen Thread und routet Folgeanfragen 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 den angeforderten Vorgang 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 die automatische ACP-Thread-Weiterleitung, blendet oder blockiert aber explizite sessions_spawn({ runtime: "acp" })-Aufrufe 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; verwenden Sie andernfalls die standardmäßige Sub-Agent-Runtime. 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; andernfalls gibt OpenClaw 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 einen anderen ACP-Agent starten, übernimmt OpenClaw standardmäßig den Arbeitsbereich des Ziel-Agents. Fehlende geerbte Pfade (ENOENT/ENOTDIR) fallen auf die Backend-Standardeinstellung zurück; andere Zugriffsfehler (z. B. EACCES) erscheinen als Spawn-Fehler.
• Gateway-Verwaltungsbefehle bleiben in gebundenen Konversationen lokal - /acp ...-Befehle werden von OpenClaw verarbeitet, auch wenn normaler Folgetext an die gebundene ACP-Sitzung geroutet wird; /status und /unfocus bleiben ebenfalls lokal, sobald 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.
• Folge-Nachrichten in diesem Thread werden an die gebundene ACP-Sitzung geroutet.
• ACP-Ausgabe wird zurück in denselben Thread zugestellt.
• Unfocus/Schließen/Archivieren/Leerlauf-Timeout oder Ablauf durch maximales Alter 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 die automatische ACP-Thread-Weiterleitung zu pausieren; explizite sessions_spawn({ runtime: "acp" })-Aufrufe funktionieren weiterhin).
• Erstellung von Thread-Sitzungen 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 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 (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.
• Persistente konfigurierte bindings[].type="acp" leiten passende Unterhaltungen an dieselbe ACP-Sitzung weiter.

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

Was OpenClaw an das Harness sendet:

• Normale gebundene Follow-ups 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-Weitergabe abgefangen.
• Von der Laufzeit erzeugte Abschlussereignisse werden pro Ziel materialisiert. OpenClaw-Agenten erhalten den internen Runtime-Context-Umschlag von OpenClaw; externe ACP-Harnesses erhalten einen einfachen Prompt mit dem untergeordneten Ergebnis 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 in OpenClaw nach Möglichkeit strukturiert und werden nicht als vom Benutzer verfasste Chat-Inhalte behandelt.

Einmalige ACP-Sitzungen, die von einem anderen Agent-Lauf gestartet werden, sind Hintergrund-Children, ähnlich wie Subagents:

• Der Parent fordert Arbeit mit sessions_spawn({ runtime: "acp", mode: "run" }) an.
• Das Child läuft in seiner eigenen ACP-Harness-Sitzung.
• Child-Turns laufen auf derselben Hintergrund-Lane wie native Subagent-Spawns, sodass ein langsames ACP-Harness keine unabhängige Arbeit der Hauptsitzung blockiert.
• Abschlussberichte werden ü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 OpenClaw-internen Runtime-Context-Marker sehen.
• Der Parent formuliert das Child-Ergebnis in normaler Assistant-Stimme um, wenn eine benutzersichtbare Antwort sinnvoll ist.

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

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

• Auf die Antwort der Zielsitzung warten.
• Optional anfragende Sitzung und Ziel eine begrenzte Anzahl von Follow-up-Turns austauschen lassen.
• Das Ziel 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 ein sichtbares Follow-up 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 das A2A-Follow-up nur, wenn der Anforderer der Parent seines eigenen, Parent-eigenen einmaligen ACP-Childs ist. In diesem Fall kann A2A zusätzlich zum Aufgabenabschluss den Parent mit dem Ergebnis des Childs aufwecken, die Antwort des Parents zurück an das Child weiterleiten und eine Parent/Child-Echoschleife erzeugen. Das Ergebnis von sessions_send meldet delivery.status="skipped" für diesen Owned-Child-Fall, weil der Abschluss-Pfad 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 Gesprächsverlauf ü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:

• Übergeben Sie eine Codex-Sitzung von Ihrem Laptop an Ihr Telefon - weisen Sie Ihren Agent an, dort weiterzumachen, wo Sie aufgehört haben.
• Setzen Sie eine Coding-Sitzung fort, die Sie interaktiv in der CLI gestartet haben, jetzt headless über Ihren Agent.
• Nehmen Sie Arbeit wieder auf, 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 reine ACP-Feld.
• streamTo gilt nur bei runtime: "acp"; die Standard-Sub-Agent-Runtime ignoriert dieses reine ACP-Feld.
• resumeSessionId ist eine hostlokale ACP/Harness-Resume-ID, kein OpenClaw-Channel-Sitzungsschlüssel; OpenClaw prüft weiterhin die ACP-Spawn-Policy und die Ziel-Agent-Policy vor dem Dispatch, während das ACP-Backend oder Harness die Autorisierung zum Laden dieser Upstream-ID besitzt.
• resumeSessionId stellt den Upstream-ACP-Gesprächsverlauf 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 - ohne stillen 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. 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-Agent.
3. Bitten Sie diesen Agent, 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 keinen Validator-Fehler.
5. Bereinigen Sie die temporäre Bridge-Sitzung.

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