ACP-agenten

• Als plugins.allow is ingesteld, is dit een beperkende Plugin-inventaris en moet deze acpx bevatten; anders wordt de geïnstalleerde ACP-backend bewust geblokkeerd en meldt /acp doctor de ontbrekende allowlist-vermelding.
• De Codex ACP-adapter wordt met de acpx-Plugin voorbereid en waar mogelijk lokaal gestart.
• Andere doel-harness-adapters kunnen nog steeds op aanvraag met npx worden opgehaald wanneer je ze voor het eerst gebruikt.
• Vendor-authenticatie moet nog steeds op de host aanwezig zijn voor die harness.
• Als de host geen npm- of netwerktoegang heeft, mislukken adapterophalingen bij de eerste run totdat caches vooraf zijn opgewarmd of de adapter op een andere manier is geïnstalleerd.

ACP start een echt extern harness-proces. OpenClaw beheert routering, achtergrondtaakstatus, aflevering, bindingen en beleid; de harness beheert de provider-login, modelcatalogus, bestandssysteemgedrag en native tools.

Controleer voordat je OpenClaw de schuld geeft:

• /acp doctor meldt een ingeschakelde, gezonde backend.
• De doel-id is toegestaan door acp.allowedAgents wanneer die allowlist is ingesteld.
• De harness-opdracht kan starten op de Gateway-host.
• Provider-authenticatie is aanwezig voor die harness (claude, codex, gemini, opencode, droid, enz.).
• Het geselecteerde model bestaat voor die harness - model-id's zijn niet overdraagbaar tussen harnesses.
• De aangevraagde cwd bestaat en is toegankelijk, of laat cwd weg en laat de backend de standaardwaarde gebruiken.
• De machtigingsmodus past bij het werk. Niet-interactieve sessies kunnen niet op native machtigingsprompts klikken, dus schrijf-/exec-intensieve coding-runs hebben meestal een ACPX-machtigingsprofiel nodig dat headless kan doorgaan.

• Spawn maakt of hervat een ACP-runtime-sessie, registreert ACP-metadata in de OpenClaw-sessieopslag en kan een achtergrondtaak maken wanneer de run eigendom is van de parent.
• ACP-sessies die eigendom zijn van de parent worden behandeld als achtergrondwerk, zelfs wanneer de runtime-sessie persistent is; voltooiing en levering over oppervlakken heen verlopen via de taaknotifier van de parent in plaats van zich te gedragen als een normale gebruikersgerichte chatsessie.
• Taakonderhoud sluit terminale of verweesde eenmalige ACP-sessies die eigendom zijn van de parent. Persistente ACP-sessies blijven behouden zolang er een actieve gespreksbinding blijft bestaan; verlopen persistente sessies zonder actieve binding worden gesloten zodat ze niet stilzwijgend kunnen worden hervat nadat de eigenaars-taak klaar is of het taakrecord is verdwenen.
• Gekoppelde vervolgberichten gaan rechtstreeks naar de ACP-sessie totdat de binding wordt gesloten, ontfocust, gereset of verlopen is.
• Gateway-opdrachten blijven lokaal. /acp ..., /status en /unfocus worden nooit als normale prompttekst naar een gekoppelde ACP-harness verzonden.
• cancel breekt de actieve beurt af wanneer de backend annulering ondersteunt; het verwijdert de binding of sessiemetadata niet.
• close beëindigt de ACP-sessie vanuit het perspectief van OpenClaw en verwijdert de binding. Een harness kan nog steeds zijn eigen upstreamgeschiedenis bewaren als deze hervatten ondersteunt.
• Inactieve runtime-workers komen in aanmerking voor opschoning na acp.runtime.ttlMinutes; opgeslagen sessiemetadata blijft beschikbaar voor /acp sessions.

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

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

Native Codex-gespreksbinding is het standaardpad voor chatbesturing. OpenClaw dynamische 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 een native hook-relay per beurt, zodat Plugin-hooks 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 modelpass kunnen aanvragen voordat Codex het antwoord afrondt. De relay blijft bewust conservatief: deze muteert geen Codex-native toolargumenten en herschrijft geen Codex-threadrecords. Gebruik expliciete ACP alleen wanneer je het ACP-runtime-/sessiemodel wilt. De ondersteuningsgrens voor ingebedde Codex-ondersteuning is gedocumenteerd in het Codex harness v1-ondersteuningscontract.

• openai-codex/* - PI Codex OAuth-/abonnementsroute.
• openai/* plus agentRuntime.id: "codex" - native ingesloten runtime van de Codex-appserver.
• /codex ... - native gespreksbesturing voor Codex.
• /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", lost de harness agentId op, bindt waar ondersteund aan het huidige gesprek of de huidige thread, en routeert vervolgstappen naar die sessie tot sluiting/verval. Codex volgt dit pad alleen wanneer ACP/acpx expliciet is of de native Codex Plugin niet beschikbaar is voor de gevraagde bewerking.

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

• --bind here en --thread ... sluiten elkaar uit.
• --bind here werkt alleen op kanalen die binding aan het huidige gesprek adverteren; anders retourneert OpenClaw een duidelijke melding dat dit niet wordt ondersteund. Bindingen blijven behouden na Gateway-herstarts.
• Op Discord begrenst spawnSessions het maken van child-threads voor --thread auto|here - niet --bind here.
• Als je naar een andere ACP-agent spawnt zonder --cwd, erft OpenClaw standaard de werkruimte van de doelagent. Ontbrekende geërfde paden (ENOENT/ENOTDIR) vallen terug op de backendstandaard; andere toegangsfouten (bijv. EACCES) verschijnen als spawnfouten.
• Gateway-beheercommando's blijven lokaal in gebonden gesprekken - /acp ...-commando's worden door OpenClaw afgehandeld, zelfs wanneer normale vervolgtekst naar de gebonden ACP-sessie routeert; /status en /unfocus blijven ook lokaal wanneer commandoafhandeling voor dat oppervlak is ingeschakeld.

Wanneer threadbindingen zijn ingeschakeld voor een kanaaladapter:

• OpenClaw bindt een thread aan een doel-ACP-sessie.
• Vervolgberichten in die thread routeren naar de gebonden ACP-sessie.
• ACP-uitvoer wordt teruggeleverd aan dezelfde thread.
• Unfocus/sluiten/archiveren/idle-timeout of max-age-verval verwijdert de binding.
• /acp close, /acp cancel, /acp status, /status en /unfocus zijn Gateway-commando's, geen prompts voor de ACP-harness.

Vereiste featureflags voor thread-gebonden ACP:

• acp.enabled=true
• acp.dispatch.enabled staat standaard aan (stel false in om automatische ACP-threaddispatch te pauzeren; expliciete sessions_spawn({ runtime: "acp" })-aanroepen blijven werken).
• Spawns van thread-sessies via kanaaladapters ingeschakeld (standaard: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Ondersteuning voor threadbinding is adapterspecifiek. Als de actieve kanaal- adapter geen threadbindingen ondersteunt, retourneert OpenClaw een duidelijke melding dat dit niet wordt ondersteund/niet beschikbaar is.

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

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

• /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/thread/onderwerp.

Wat OpenClaw naar de harness verzendt:

• Normale gebonden vervolgberichten worden verzonden als prompttekst, plus bijlagen alleen wanneer de harness/backend die ondersteunt.
• /acp-beheeropdrachten en lokale Gateway-opdrachten worden onderschept vóór ACP-dispatch.
• Door runtime gegenereerde voltooiingsgebeurtenissen worden per doel gematerialiseerd. OpenClaw-agenten krijgen OpenClaw's interne runtime-contextenvelop; externe ACP-harnesses krijgen een gewone prompt met het childresultaat en de instructie. De ruwe <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>>-envelop mag nooit naar externe harnesses worden verzonden of als ACP-gebruikerstranscripttekst worden opgeslagen.
• ACP-transcriptvermeldingen gebruiken 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 gespawnd zijn achtergrond- children, vergelijkbaar met subagenten:

• De parent vraagt om werk met sessions_spawn({ runtime: "acp", mode: "run" }).
• De child draait in zijn eigen ACP-harnesssessie.
• Childturns draaien op dezelfde achtergrondlane die wordt gebruikt door native subagentspawns, zodat een trage ACP-harness ongerelateerd hoofdsessiewerk niet blokkeert.
• Voltooiing rapporteert terug via het aankondigingspad voor taakvoltooiing. OpenClaw zet interne voltooiingsmetadata om naar een gewone ACP-prompt voordat die naar een externe harness wordt verzonden, zodat harnesses geen runtimecontextmarkeringen zien die alleen voor OpenClaw zijn.
• De parent herschrijft het childresultaat in normale assistentstem wanneer een gebruikergericht antwoord nuttig is.

Behandel dit pad niet als een peer-to-peerchat tussen parent en child. De child heeft al een voltooiingskanaal terug naar de parent.

sessions_send kan na spawn een andere sessie targeten. Voor normale peersessies gebruikt OpenClaw een agent-naar-agent (A2A)-vervolgpad nadat het bericht is geïnjecteerd:

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

Dat A2A-pad is een fallback voor peer sends waarbij de afzender een zichtbaar vervolg nodig heeft. Het blijft ingeschakeld wanneer een ongerelateerde sessie een ACP-doel kan zien en berichten kan sturen, bijvoorbeeld onder brede tools.sessions.visibility-instellingen.

OpenClaw slaat het A2A-vervolg alleen over wanneer de aanvrager de parent is van zijn eigen parent-eigendom eenmalige ACP-child. In dat geval kan A2A bovenop taakvoltooiing draaien de parent wekken met het childresultaat, het antwoord van de parent terugsturen naar de child, en een parent/child-echo-loop maken. Het sessions_send-resultaat rapporteert delivery.status="skipped" voor dat geval met een eigendom-child omdat het voltooiingspad al verantwoordelijk is voor het resultaat.

Gebruik resumeSessionId om een vorige ACP-sessie voort te zetten in plaats van opnieuw te beginnen. De agent speelt zijn gespreksgeschiedenis opnieuw af via session/load, zodat hij 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 - zeg je agent dat hij verder moet gaan waar je was gebleven.
• Zet een codesessie voort die je interactief in de CLI bent begonnen, nu headless via je agent.
• Pak werk weer op dat werd onderbroken door een Gateway-herstart of idle-time-out.

Opmerkingen:

• resumeSessionId is alleen van toepassing wanneer runtime: "acp"; de standaard subagentruntime negeert dit veld dat alleen voor ACP is.
• streamTo is alleen van toepassing wanneer runtime: "acp"; de standaard subagentruntime negeert dit veld dat alleen voor ACP is.
• resumeSessionId is een hostlokale ACP/harness-hervat-id, geen OpenClaw-kanaalsessiesleutel; OpenClaw controleert nog steeds ACP-spawnbeleid en doelagentbeleid vóór dispatch, terwijl de ACP-backend of harness eigenaar is van autorisatie voor het laden van die upstream-id.
• resumeSessionId herstelt de upstream ACP-gespreksgeschiedenis; thread en mode blijven 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, faalt de spawn met een duidelijke fout - geen stille fallback naar een nieuwe sessie.

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

1. Verifieer de gedeployde gatewayversie en commit op de doelhost.
2. Open een tijdelijke ACPX-bridgesessie naar een live agent.
3. Vraag die agent sessions_spawn aan te roepen met runtime: "acp", agentId: "codex", mode: "run", en taak Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verifieer accepted=yes, een echte childSessionKey, en geen validatorfout.
5. Ruim de tijdelijke bridgesessie op.

Houd de gate op mode: "run" en sla streamTo: "parent" over - threadgebonden mode: "session" en stream-relaypaden zijn afzonderlijke rijkere integratiepasses.