ACP-agents

• Als plugins.allow is ingesteld, vormt dit een beperkende plugininventaris en moet deze acpx bevatten, anders wordt de geïnstalleerde ACP-backend opzettelijk geblokkeerd (/acp doctor meldt de ontbrekende vermelding in de toelatingslijst).
• De Codex ACP-adapter wordt met de acpx-plugin meegeleverd en wordt waar mogelijk lokaal gestart.
• Codex ACP wordt uitgevoerd met een geïsoleerde CODEX_HOME. OpenClaw kopieert vertrouwde projectvertrouwensvermeldingen plus veilige routeringsconfiguratie voor modellen/providers (model, model_provider, model_reasoning_effort, sandbox_mode en veilige velden van model_providers.<name>) uit de Codex-hostconfiguratie; authenticatie, meldingen en hooks blijven uitsluitend in de hostconfiguratie.
• Andere adapters voor doelharnassen kunnen bij het eerste gebruik naar behoefte met npx worden opgehaald.
• Authenticatie bij de leverancier moet voor dat harnas al op de host aanwezig zijn.
• Als de host geen npm- of netwerktoegang heeft, mislukt het ophalen van adapters bij de eerste uitvoering totdat caches vooraf zijn gevuld of de adapter op een andere manier is geïnstalleerd.

ACP start een echt extern harnasproces. OpenClaw beheert routering, de status van achtergrondtaken, aflevering, koppelingen en beleid; het harnas beheert de aanmelding bij de provider, de modelcatalogus, het bestandssysteemgedrag en systeemeigen tools.

Controleer het volgende voordat u OpenClaw als oorzaak aanwijst:

• /acp doctor meldt een ingeschakelde, gezonde backend.
• De doel-id is toegestaan door acp.allowedAgents wanneer die toelatingslijst is ingesteld.
• De harnasopdracht kan op de Gateway-host worden gestart.
• Providerauthenticatie is aanwezig voor dat harnas (claude, codex, gemini, opencode, droid, enzovoort).
• Het geselecteerde model bestaat voor dat harnas; model-id's zijn niet overdraagbaar tussen harnassen.
• De aangevraagde cwd bestaat en is toegankelijk; laat cwd anders weg en laat de backend de standaardwaarde gebruiken.
• De machtigingsmodus past bij het werk. Niet-interactieve sessies kunnen niet op systeemeigen machtigingsprompts klikken, dus coderingssessies met veel schrijf- en uitvoerbewerkingen hebben doorgaans een ACPX-machtigingsprofiel nodig dat zonder gebruikersinterface kan doorgaan.

• Starten maakt een ACP-runtimesessie aan of hervat deze, registreert ACP-metagegevens in het sessiearchief van OpenClaw en kan een achtergrondtaak aanmaken wanneer de uitvoering eigendom is van de bovenliggende taak.
• ACP-sessies die eigendom zijn van een bovenliggende taak, worden behandeld als achtergrondwerk, zelfs wanneer de runtimesessie persistent is; voltooiing en aflevering tussen oppervlakken verlopen via de taakmelder van de bovenliggende taak in plaats van als een normale, gebruikersgerichte chatsessie.
• Taakonderhoud sluit beëindigde of verweesde eenmalige ACP-sessies die eigendom zijn van een bovenliggende taak. Persistente ACP-sessies blijven behouden zolang er een actieve gesprekskoppeling bestaat; verouderde persistente sessies zonder actieve koppeling worden gesloten, zodat ze niet ongemerkt kunnen worden hervat nadat de eigenaarstaak is voltooid of de taakregistratie is verdwenen.
• Gekoppelde vervolgberichten gaan rechtstreeks naar de ACP-sessie totdat de koppeling wordt gesloten, de focus verliest, wordt hersteld of verloopt.
• Gateway-opdrachten blijven lokaal. /acp ..., /status en /unfocus worden nooit als normale prompttekst naar een gekoppeld ACP-harnas verzonden.
• cancel breekt de actieve beurt af wanneer de backend annulering ondersteunt; de koppeling of sessiemetagegevens worden niet verwijderd.
• close beëindigt de ACP-sessie vanuit het perspectief van OpenClaw en verwijdert de koppeling. Een harnas kan zijn eigen bovenliggende geschiedenis blijven bewaren als het hervatten ondersteunt.
• De acpx-plugin ruimt door OpenClaw beheerde processtructuren voor wrappers en adapters na close op en verwijdert tijdens het starten van de Gateway verouderde, door OpenClaw beheerde verweesde ACPX-processen.
• Inactieve runtimewerkers komen na acp.runtime.ttlMinutes in aanmerking voor opschoning; opgeslagen sessiemetagegevens blijven beschikbaar voor /acp sessions.

Triggers in natuurlijke taal die naar de systeemeigen Codex-plugin moeten worden gerouteerd wanneer deze is ingeschakeld:

• "Koppel dit Discord-kanaal aan Codex."
• "Koppel deze chat aan Codex-thread <id>."
• "Toon Codex-threads en koppel vervolgens deze."

Native Codex-gesprekskoppeling is het standaardpad voor chatbesturing. Dynamische OpenClaw-tools worden nog steeds via OpenClaw uitgevoerd, terwijl Codex-native tools zoals shell/apply-patch binnen Codex worden uitgevoerd. Voor Codex-native toolgebeurtenissen injecteert OpenClaw per beurt een native hook-relais, zodat pluginhooks before_tool_call kunnen blokkeren, after_tool_call kunnen observeren en Codex-PermissionRequest-gebeurtenissen via OpenClaw-goedkeuringen kunnen routeren. Codex-Stop-hooks worden doorgestuurd naar OpenClaw before_agent_finalize, waar plugins nog één modeldoorgang kunnen aanvragen voordat Codex zijn antwoord voltooit. Het relais blijft bewust terughoudend: het wijzigt geen argumenten van Codex-native tools en herschrijft geen Codex-threadrecords. Gebruik expliciete ACP alleen wanneer je het ACP-runtime-/sessiemodel wilt. De ondersteuningsgrens van de ingebedde Codex is gedocumenteerd in het ondersteuningscontract voor Codex-harnas v1.

• verouderde Codex-modelreferenties - verouderde Codex OAuth-/abonnementsmodelroute die door doctor wordt hersteld.
• openai/* - ingebedde native Codex-app-serverruntime voor OpenAI-agentbeurten.
• /codex ... - native Codex-gespreksbesturing.
• /acp ... of runtime: "acp" - expliciete ACP-/acpx-besturing.

Triggers die naar de ACP-runtime moeten routeren:

• "Voer dit uit als een eenmalige Claude Code ACP-sessie en vat het resultaat samen."
• "Gebruik Gemini CLI voor deze taak in een thread en houd vervolgstappen daarna in diezelfde thread."
• "Voer Codex via ACP uit in een achtergrondthread."

OpenClaw kiest runtime: "acp", bepaalt de agentId van het harnas, koppelt waar ondersteund aan het huidige gesprek of de huidige thread en routeert vervolgberichten naar die sessie totdat deze wordt gesloten of verloopt. Codex volgt dit pad alleen wanneer ACP/acpx expliciet is opgegeven of wanneer de native Codex-plugin niet beschikbaar is voor de gevraagde bewerking.

Voor sessions_spawn wordt runtime: "acp" alleen aangeboden wanneer ACP is ingeschakeld, de aanvrager niet in een sandbox draait en een ACP-runtimebackend is geladen. acp.dispatch.enabled=false pauzeert automatische verzending van ACP-threads, maar verbergt of blokkeert expliciete aanroepen van sessions_spawn({ runtime: "acp" }) niet. Het richt zich op ACP-harnas-id's zoals codex, claude, droid, gemini of opencode. Geef geen normale OpenClaw-configuratie-agent-id uit agents_list door, tenzij dat item expliciet is geconfigureerd met agents.list[].runtime.type="acp"; gebruik anders de standaardruntime voor subagents. Wanneer een OpenClaw-agent is geconfigureerd met runtime.type="acp", gebruikt OpenClaw runtime.acp.agent als de onderliggende harnas-id.

• --bind here en --thread ... sluiten elkaar uit.
• --bind here werkt alleen op kanalen die koppeling aan het huidige gesprek ondersteunen; anders retourneert OpenClaw een duidelijke melding dat dit niet wordt ondersteund. Koppelingen blijven behouden na herstarts van de Gateway.
• Op Discord beheert spawnSessions het aanmaken van onderliggende threads voor --thread auto|here - niet voor --bind here.
• Als je zonder --cwd een andere ACP-agent start, neemt OpenClaw standaard de werkruimte van de doelagent over. Ontbrekende overgenomen paden (ENOENT/ENOTDIR) vallen terug op de standaardwaarde van de backend; andere toegangsfouten (bijvoorbeeld EACCES) worden als startfouten gemeld.
• Gateway-beheeropdrachten blijven lokaal in gekoppelde gesprekken - /acp ...-opdrachten worden door OpenClaw afgehandeld, zelfs wanneer normale vervolgtekst naar de gekoppelde ACP-sessie wordt gerouteerd; /status en /unfocus blijven ook lokaal wanneer opdrachtafhandeling voor dat oppervlak is ingeschakeld.

Wanneer threadkoppelingen zijn ingeschakeld voor een kanaaladapter:

• OpenClaw koppelt een thread aan een ACP-doelsessie.
• Vervolgberichten in die thread worden naar de gekoppelde ACP-sessie gerouteerd.
• ACP-uitvoer wordt teruggeleverd aan dezelfde thread.
• Ontkoppelen/sluiten/archiveren/inactiviteitstime-out of verloop door maximale leeftijd verwijdert de koppeling.
• /acp close, /acp cancel, /acp status, /status en /unfocus zijn Gateway-opdrachten, geen prompts voor het ACP-harnas.

Vereiste functievlaggen voor aan threads gekoppelde ACP:

• acp.enabled=true
• acp.dispatch.enabled is standaard ingeschakeld (stel in op false om automatische verzending van ACP-threads te pauzeren; expliciete aanroepen van sessions_spawn({ runtime: "acp" }) blijven werken).
• Het starten van threadsessies door de kanaaladapter is ingeschakeld (standaard: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Ondersteuning voor threadkoppeling is adapterspecifiek. Als de actieve kanaaladapter geen threadkoppelingen ondersteunt, retourneert OpenClaw een duidelijke melding dat deze niet worden ondersteund of niet beschikbaar zijn.

• Elke kanaaladapter die mogelijkheden voor sessie-/threadkoppeling beschikbaar stelt.
• Huidige ingebouwde ondersteuning: Discord-threads/-kanalen, Telegram-onderwerpen (forumonderwerpen in groepen/supergroepen en privéberichtonderwerpen).
• Plugin-kanalen kunnen via dezelfde koppelingsinterface ondersteuning toevoegen.

Interactieve sessies zijn bedoeld om het gesprek op een zichtbaar chatoppervlak voort te zetten:

• /acp spawn ... --bind here bindt het huidige gesprek aan de ACP-sessie.
• /acp spawn ... --thread ... bindt een kanaalthread/-onderwerp aan de ACP-sessie.
• Blijvend geconfigureerde bindings[].type="acp" routeren overeenkomende gesprekken naar dezelfde ACP-sessie.

Vervolgberichten in het gebonden gesprek worden rechtstreeks naar de ACP-sessie gerouteerd en ACP-uitvoer wordt teruggeleverd aan datzelfde kanaal/diezelfde thread/datzelfde onderwerp.

Wat OpenClaw naar de harnas verzendt:

• Normale gebonden vervolgberichten worden als prompttekst verzonden, met bijlagen alleen wanneer de harnas/backend die ondersteunt.
• Beheeropdrachten van /acp en lokale Gateway-opdrachten worden vóór ACP-verzending onderschept.
• Door de runtime gegenereerde voltooiingsgebeurtenissen worden per doel geconcretiseerd. OpenClaw-agents krijgen de interne runtimecontextenvelop van OpenClaw; externe ACP-harnassen krijgen een gewone prompt met het resultaat van het onderliggende proces en een instructie. De onbewerkte envelop <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> mag nooit naar externe harnassen worden verzonden of als ACP-gebruikerstranscripttekst worden opgeslagen.
• ACP-transcriptvermeldingen gebruiken de voor de gebruiker zichtbare activeringstekst of de gewone voltooiingsprompt. Interne gebeurtenismetadata blijven waar mogelijk gestructureerd in OpenClaw en worden niet behandeld als door de gebruiker geschreven chatinhoud.

Eenmalige ACP-sessies die door een andere agentuitvoering worden gestart, zijn achtergrondprocessen, vergelijkbaar met subagents:

• De oudersessie vraagt om werk met sessions_spawn({ runtime: "acp", mode: "run" }).
• Het onderliggende proces wordt uitgevoerd in een eigen ACP-harnassessie.
• Beurten van het onderliggende proces worden uitgevoerd op dezelfde achtergrondbaan die wordt gebruikt voor ingebouwde starts van subagents, zodat een trage ACP-harnas niet-gerelateerd werk in de hoofdsessie niet blokkeert.
• De voltooiing wordt teruggemeld via het aankondigingspad voor taakvoltooiing. OpenClaw zet interne voltooiingsmetadata om in een gewone ACP-prompt voordat deze naar een externe harnas wordt verzonden, zodat harnassen geen runtimecontextmarkeringen zien die alleen voor OpenClaw bestemd zijn.
• De oudersessie herschrijft het resultaat van het onderliggende proces in een normale assistentstijl wanneer een voor de gebruiker bestemd antwoord nuttig is.

Behandel dit pad niet als een peer-to-peerchat tussen de oudersessie en het onderliggende proces. Het onderliggende proces beschikt al over een voltooiingskanaal terug naar de oudersessie.

sessions_send kan na het starten een andere sessie als doel gebruiken. Voor normale peersessies gebruikt OpenClaw na het injecteren van het bericht een agent-naar-agentvervolgpad (A2A):

• Wacht op het antwoord van de doelsessie.
• Laat de aanvrager en het doel optioneel een begrensd aantal vervolgbeurten uitwisselen.
• Vraag het doel een aankondigingsbericht te produceren.
• Lever die aankondiging af bij het zichtbare kanaal of de zichtbare thread.

Dat A2A-pad is een terugvaloptie voor verzendingen tussen peers waarbij de afzender een zichtbare follow-up nodig heeft. Het blijft ingeschakeld wanneer een niet-gerelateerde sessie een ACP-doel kan zien en berichten kan sturen, bijvoorbeeld bij ruime instellingen voor tools.sessions.visibility.

OpenClaw slaat de A2A-follow-up alleen over wanneer de aanvrager de ouder is van zijn eigen eenmalige ACP-kind waarvan de ouder eigenaar is. In dat geval kan het uitvoeren van A2A boven op de voltooiing van de taak de ouder activeren met het resultaat van het kind, het antwoord van de ouder terugsturen naar het kind en een echo-lus tussen ouder en kind veroorzaken. Het resultaat van sessions_send meldt delivery.status="skipped" voor dat kind waarvan de ouder eigenaar is, omdat het voltooiingspad al verantwoordelijk is voor het resultaat.

Gebruik resumeSessionId om een eerdere ACP-sessie voort te zetten in plaats van opnieuw te beginnen. De agent speelt de gespreksgeschiedenis opnieuw af via session/load, zodat deze verdergaat met de volledige context van wat eraan voorafging.

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

Veelvoorkomende gebruikssituaties:

• Draag een Codex-sessie over van je laptop naar je telefoon; vraag je agent verder te gaan waar je was gebleven.
• Zet een codeersessie die je interactief in de CLI bent begonnen zonder gebruikersinterface voort via je agent.
• Hervat werk dat werd onderbroken door een herstart van de Gateway of een time-out wegens inactiviteit.

Opmerkingen:

• resumeSessionId is alleen van toepassing wanneer runtime: "acp"; de standaardruntime voor subagents negeert dit veld dat alleen voor ACP geldt.
• streamTo is alleen van toepassing wanneer runtime: "acp"; de standaardruntime voor subagents negeert dit veld dat alleen voor ACP geldt.
• resumeSessionId is een hostlokale hervattings-id van ACP/de harness, geen OpenClaw-sessiesleutel voor een kanaal; OpenClaw controleert vóór verzending nog steeds het ACP-startbeleid en het beleid van de doelagent, terwijl de ACP-backend of harness verantwoordelijk is voor de autorisatie om die upstream-id te laden.
• resumeSessionId herstelt de upstream ACP-gespreksgeschiedenis; thread en mode zijn nog steeds normaal van toepassing op de nieuwe OpenClaw-sessie die je aanmaakt, dus voor mode: "session" blijft thread: true vereist.
• De doelagent moet session/load ondersteunen (Codex en Claude Code doen dit).
• Als de sessie-id niet wordt gevonden, mislukt het starten met een duidelijke foutmelding; er is geen stille terugval naar een nieuwe sessie.

Voer na een implementatie van de Gateway een live end-to-endcontrole uit in plaats van te vertrouwen op unittests:

1. Controleer de geïmplementeerde Gateway-versie en commit op de doelhost.
2. Open een tijdelijke ACPX-brugsessie naar een live agent.
3. Vraag die agent sessions_spawn aan te roepen met runtime: "acp", agentId: "codex", mode: "run" en de taak Reply with exactly LIVE-ACP-SPAWN-OK.
4. Controleer accepted=yes, een echte childSessionKey en dat er geen validatiefout is.
5. Ruim de tijdelijke brugsessie op.

Beperk de controle tot mode: "run" en sla streamTo: "parent" over; threadgebonden mode: "session" en paden voor streamdoorgifte zijn afzonderlijke, uitgebreidere integratiecontroles.