ACP-agents

• Als plugins.allow is ingesteld, vormt dit een beperkende Plugin-inventaris en moet deze acpx bevatten, anders wordt de geïnstalleerde ACP-back-end opzettelijk geblokkeerd (/acp doctor meldt het ontbrekende item in de toelatingslijst).
• De Codex ACP-adapter wordt geleverd met de Plugin acpx en wordt waar mogelijk lokaal gestart.
• Codex ACP wordt uitgevoerd met een geïsoleerde CODEX_HOME. OpenClaw kopieert vertrouwde projectvertrouwensvermeldingen en 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 doelomgevingen kunnen bij het eerste gebruik op aanvraag worden opgehaald met npx.
• Authenticatie bij de leverancier moet voor die omgeving al op de host bestaan.
• 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 omgevingsproces. OpenClaw beheert routering, de status van achtergrondtaken, aflevering, koppelingen en beleid; de omgeving beheert de eigen provideraanmelding, modelcatalogus, het bestandssysteemgedrag en de systeemeigen tools.

Controleer het volgende voordat je OpenClaw de schuld geeft:

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

• Spawnen maakt een ACP-runtimesessie of hervat deze, legt ACP-metadata vast in het OpenClaw-sessiearchief en kan een achtergrondtaak maken wanneer de run eigendom is van de bovenliggende taak.
• ACP-sessies die eigendom zijn van de bovenliggende taak, worden als achtergrondwerk behandeld, zelfs wanneer de runtimesessie persistent is; voltooiing en levering tussen oppervlakken verlopen via de taakmelder van de bovenliggende taak, in plaats van als een normale, voor de gebruiker zichtbare 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 gespreksbinding bestaat; verouderde persistente sessies zonder actieve binding worden gesloten, zodat ze niet stilzwijgend kunnen worden hervat nadat de bijbehorende taak is voltooid of de taakregistratie ervan is verdwenen.
• Gebonden vervolgberichten gaan rechtstreeks naar de ACP-sessie totdat de binding wordt gesloten, de focus verliest, wordt gereset of verloopt.
• Gateway-opdrachten blijven lokaal. /acp ..., /status en /unfocus worden nooit als normale prompttekst naar een gebonden ACP-harnas verzonden.
• cancel breekt de actieve beurt af wanneer de backend annulering ondersteunt; de binding of sessiemetadata wordt niet verwijderd.
• close beëindigt de ACP-sessie vanuit het perspectief van OpenClaw en verwijdert de binding. Een harnas kan zijn eigen bovenliggende geschiedenis blijven bewaren als het hervatten ondersteunt.
• De acpx-Plugin ruimt na close de processtructuren van wrappers en adapters op die eigendom zijn van OpenClaw, en ruimt tijdens het opstarten van de Gateway verouderde, verweesde ACPX-processen op die eigendom zijn van OpenClaw.
• Inactieve runtimeworkers komen na de ingebouwde inactiviteitsperiode in aanmerking voor opruiming; opgeslagen sessiemetadata blijft beschikbaar voor /acp sessions.

Triggers in natuurlijke taal die naar de native Codex-Plugin moeten routeren wanneer deze is ingeschakeld:

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

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

• verouderde Codex-modelreferenties - verouderde modelroute voor Codex OAuth/abonnement, hersteld door doctor.
• 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 vervolgberichten daarna in diezelfde thread."
• "Voer Codex via ACP uit in een achtergrondthread."

OpenClaw kiest runtime: "acp", bepaalt het harnas agentId, bindt 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 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 wordt uitgevoerd en een ACP-runtimebackend is geladen. acp.dispatch.enabled=false pauzeert automatische ACP-threadverzending, maar verbergt of blokkeert expliciete aanroepen van sessions_spawn({ runtime: "acp" }) niet. Het is gericht op ACP-harnas-id's zoals codex, claude, droid, gemini of opencode. Geef geen normale agent-id uit de OpenClaw-configuratie van agents_list door, tenzij die vermelding expliciet is geconfigureerd met agents.entries.*.runtime.type="acp"; gebruik anders de standaardruntime voor sub-agents. 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 binding aan het huidige gesprek aanbieden; anders retourneert OpenClaw een duidelijk bericht dat dit niet wordt ondersteund. Bindingen blijven behouden na herstarts van de Gateway.
• Op Discord bepaalt spawnSessions of onderliggende threads voor --thread auto|here kunnen worden gemaakt - niet voor --bind here.
• Als je zonder --cwd naar een andere ACP-agent spawnt, neemt OpenClaw standaard de werkruimte van de doelagent over. Ontbrekende overgenomen paden (ENOENT/ENOTDIR) vallen terug op de backendstandaard; andere toegangsfouten (bijvoorbeeld EACCES) worden als spawnfouten weergegeven.
• Gateway-beheeropdrachten blijven lokaal in gebonden gesprekken - opdrachten van /acp ... worden door OpenClaw verwerkt, zelfs wanneer normale vervolgtekst naar de gebonden ACP-sessie wordt gerouteerd; /status en /unfocus blijven ook lokaal wanneer opdrachtverwerking voor dat oppervlak is ingeschakeld.

Wanneer threadbindingen zijn ingeschakeld voor een kanaaladapter:

• OpenClaw bindt een thread aan een ACP-doelsessie.
• Vervolgberichten in die thread worden naar de gebonden ACP-sessie gerouteerd.
• ACP-uitvoer wordt teruggeleverd aan dezelfde thread.
• Focusverlies/sluiten/archiveren/inactiviteitstime-out of het verstrijken van de maximale leeftijd verwijdert de binding.
• /acp close, /acp cancel, /acp status, /status en /unfocus zijn Gateway-opdrachten, geen prompts voor het ACP-harnas.

Vereiste functievlaggen voor threadgebonden ACP:

• acp.enabled=true
• acp.dispatch.enabled is standaard ingeschakeld (stel false in om automatische ACP-threadverzending te pauzeren; expliciete aanroepen van sessions_spawn({ runtime: "acp" }) blijven werken).
• Het spawnen van threadsessies door kanaaladapters is ingeschakeld (standaard: true):
  • Discord/Telegram: session.threadBindings.spawnSessions=true

Ondersteuning voor threadbinding is adapterspecifiek. Als de actieve kanaaladapter geen threadbindingen ondersteunt, retourneert OpenClaw een duidelijk bericht dat dit niet wordt ondersteund of niet beschikbaar is.

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

Interactieve sessies zijn bedoeld om op een zichtbaar chatoppervlak te blijven communiceren:

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

Vervolgberichten in het gekoppelde gesprek worden rechtstreeks naar de ACP- sessie gerouteerd en ACP-uitvoer wordt teruggeleverd aan hetzelfde kanaal/dezelfde thread/hetzelfde onderwerp.

Wat OpenClaw naar de harness verzendt:

• Normale gebonden vervolgberichten worden als prompttekst verzonden, plus bijlagen, maar alleen wanneer de harness/backend die ondersteunt.
• /acp-beheeropdrachten en lokale Gateway-opdrachten worden vóór ACP-dispatch onderschept.
• Tijdens runtime gegenereerde voltooiingsgebeurtenissen worden per doel gematerialiseerd. OpenClaw-agenten krijgen de interne runtime-contextenvelop van OpenClaw; externe ACP-harnesses krijgen een gewone prompt met het resultaat van het kind en de instructie. De onbewerkte <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>>-envelop mag nooit naar externe harnesses worden verzonden of als ACP-gebruikerstranscripttekst worden opgeslagen.
• ACP-transcriptvermeldingen gebruiken de voor de gebruiker zichtbare triggertekst 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 agentrun worden gestart, zijn achtergrondkinderen, vergelijkbaar met subagenten:

• De ouder vraagt om werk met sessions_spawn({ runtime: "acp", mode: "run" }).
• Het kind wordt uitgevoerd in een eigen ACP-harnesssessie.
• Kindbeurten worden uitgevoerd in dezelfde achtergrondbaan als die voor het starten van native subagenten, zodat een trage ACP-harness 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 die naar een externe harness wordt verzonden, zodat harnesses geen runtime-contextmarkeringen zien die alleen voor OpenClaw bestemd zijn.
• De ouder herschrijft het resultaat van het kind in een normale assistentstem wanneer een gebruikersgericht antwoord nuttig is.

Behandel dit pad niet als een peer-to-peerchat tussen ouder en kind. Het kind heeft al een voltooiingskanaal terug naar de ouder.

sessions_send kan na het starten een andere sessie als doel kiezen. Voor normale peersessies gebruikt OpenClaw een agent-naar-agentvervolgpad (A2A) nadat het bericht is geïnjecteerd:

• Wacht op het antwoord van de doelsessie.
• Laat de aanvrager en het doel eventueel een begrensd aantal vervolgbeurten uitwisselen.
• Vraag het doel om een aankondigingsbericht te produceren.
• Bezorg die aankondiging in het zichtbare kanaal of de zichtbare thread.

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

OpenClaw slaat het A2A-vervolg alleen over wanneer de aanvrager de ouder is van zijn eigen eenmalige ACP-kind dat door de ouder wordt beheerd. In dat geval kan A2A boven op taakvoltooiing de ouder wekken met het resultaat van het kind, het antwoord van de ouder terugsturen naar het kind en een echolus tussen ouder en kind veroorzaken. Het resultaat van sessions_send meldt voor dat beheerde kindgeval delivery.status="skipped", 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": "Ga verder waar we gebleven waren - los de resterende testfouten op",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Veelvoorkomende gebruiksscenario's:

• Draag een Codex-sessie over van je laptop naar je telefoon: vertel je agent dat deze verder moet gaan waar je gebleven was.
• Zet een codeersessie die je interactief in de CLI hebt gestart nu zonder gebruikersinterface voort via je agent.
• Hervat werk dat door een herstart van de Gateway of een time-out wegens inactiviteit is onderbroken.

Opmerkingen:

• resumeSessionId is alleen van toepassing wanneer runtime: "acp"; de standaardruntime voor subagenten negeert dit veld dat alleen voor ACP bestemd is.
• streamTo is alleen van toepassing wanneer runtime: "acp"; de standaardruntime voor subagenten negeert dit veld dat alleen voor ACP bestemd is.
• resumeSessionId is een hostlokale hervattings-id voor ACP/harnesses, geen OpenClaw-kanaalsessiesleutel; OpenClaw controleert vóór dispatch nog steeds het ACP-startbeleid en het beleid van de doelagent, terwijl de ACP-backend of harness verantwoordelijk is voor 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 maakt, dus mode: "session" vereist nog steeds thread: true.
• De doelagent moet session/load ondersteunen (Codex en Claude Code doen dat).
• 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 Gateway-implementatie een live end-to-endcontrole uit in plaats van op unittests te vertrouwen:

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 om sessions_spawn aan te roepen met runtime: "acp", agentId: "codex", mode: "run" en 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.

Houd de gate op mode: "run" en sla streamTo: "parent" over: threadgebonden mode: "session"- en streamrelaypaden zijn afzonderlijke, uitgebreidere integratiecontroles.