Agenci ACP

• Jeśli ustawiono plugins.allow, jest to restrykcyjny wykaz pluginów i musi zawierać acpx; w przeciwnym razie zainstalowany backend ACP jest celowo blokowany, a /acp doctor zgłasza brakujący wpis na liście dozwolonych.
• Adapter Codex ACP jest przygotowywany wraz z pluginem acpx i uruchamiany lokalnie, gdy to możliwe.
• Codex ACP działa z izolowanym CODEX_HOME; OpenClaw kopiuje z konfiguracji Codex hosta zaufane wpisy projektów oraz bezpieczną konfigurację routingu modeli/dostawców, natomiast auth, powiadomienia i hooki pozostają w konfiguracji hosta.
• Inne adaptery docelowych harnessów nadal mogą być pobierane na żądanie przez npx przy pierwszym użyciu.
• Auth dostawcy nadal musi istnieć na hoście dla tego harnessu.
• Jeśli host nie ma npm ani dostępu do sieci, pobieranie adaptera przy pierwszym uruchomieniu kończy się niepowodzeniem, dopóki cache nie zostaną wstępnie rozgrzane albo adapter nie zostanie zainstalowany w inny sposób.

ACP uruchamia prawdziwy zewnętrzny proces harnessu. OpenClaw odpowiada za routing, stan zadań w tle, dostarczanie, powiązania i politykę; harness odpowiada za logowanie do dostawcy, katalog modeli, zachowanie systemu plików i narzędzia natywne.

Zanim obwinisz OpenClaw, sprawdź:

• /acp doctor zgłasza włączony, sprawny backend.
• Identyfikator celu jest dozwolony przez acp.allowedAgents, gdy ta lista dozwolonych jest ustawiona.
• Polecenie harnessu może uruchomić się na hoście Gateway.
• Auth dostawcy jest obecne dla tego harnessu (claude, codex, gemini, opencode, droid itd.).
• Wybrany model istnieje dla tego harnessu - identyfikatory modeli nie są przenośne między harnessami.
• Żądane cwd istnieje i jest dostępne albo pomiń cwd i pozwól backendowi użyć wartości domyślnej.
• Tryb uprawnień pasuje do pracy. Sesje nieinteraktywne nie mogą klikać natywnych monitów o uprawnienia, więc uruchomienia programistyczne intensywnie używające zapisu/wykonywania zwykle wymagają profilu uprawnień ACPX, który może działać bez nadzoru.

• Uruchomienie tworzy lub wznawia sesję środowiska uruchomieniowego ACP, zapisuje metadane ACP w magazynie sesji OpenClaw i może utworzyć zadanie w tle, gdy uruchomienie należy do rodzica.
• Sesje ACP należące do rodzica są traktowane jako praca w tle, nawet gdy sesja środowiska uruchomieniowego jest trwała; ukończenie i dostarczanie między powierzchniami przechodzą przez notifier zadania rodzica zamiast działać jak normalna sesja czatu widoczna dla użytkownika.
• Utrzymanie zadań zamyka końcowe lub osierocone jednorazowe sesje ACP należące do rodzica. Trwałe sesje ACP są zachowywane, dopóki istnieje aktywne powiązanie konwersacji; nieaktualne trwałe sesje bez aktywnego powiązania są zamykane, aby nie mogły zostać po cichu wznowione po zakończeniu zadania właściciela albo usunięciu jego rekordu zadania.
• Powiązane wiadomości uzupełniające trafiają bezpośrednio do sesji ACP, dopóki powiązanie nie zostanie zamknięte, odfokusowane, zresetowane albo nie wygaśnie.
• Polecenia Gateway pozostają lokalne. /acp ..., /status i /unfocus nigdy nie są wysyłane jako normalny tekst promptu do powiązanego harnessu ACP.
• cancel przerywa aktywną turę, gdy backend obsługuje anulowanie; nie usuwa powiązania ani metadanych sesji.
• close kończy sesję ACP z punktu widzenia OpenClaw i usuwa powiązanie. Harness nadal może zachować własną historię upstream, jeśli obsługuje wznawianie.
• Plugin acpx czyści drzewa procesów wrapperów i adapterów należące do OpenClaw po close oraz zbiera nieaktualne osierocone procesy ACPX należące do OpenClaw podczas uruchamiania Gateway.
• Bezczynni workerzy środowiska uruchomieniowego kwalifikują się do czyszczenia po acp.runtime.ttlMinutes; zapisane metadane sesji pozostają dostępne dla /acp sessions.

Wyzwalacze w języku naturalnym, które powinny kierować do natywnego pluginu Codex, gdy jest włączony:

• „Powiąż ten kanał Discord z Codex.”
• „Dołącz ten czat do wątku Codex <id>.”
• „Pokaż wątki Codex, a potem powiąż ten.”

Natywne powiązanie konwersacji Codex jest domyślną ścieżką sterowania czatem. Dynamiczne narzędzia OpenClaw nadal wykonują się przez OpenClaw, natomiast narzędzia natywne dla Codex, takie jak shell/apply-patch, wykonują się wewnątrz Codex. Dla zdarzeń narzędzi natywnych dla Codex OpenClaw wstrzykuje natywny przekaźnik hooków dla każdej tury, aby hooki pluginów mogły blokować before_tool_call, obserwować after_tool_call oraz kierować zdarzenia Codex PermissionRequest przez zatwierdzenia OpenClaw. Hooki Codex Stop są przekazywane do OpenClaw before_agent_finalize, gdzie pluginy mogą poprosić o jeszcze jedno przejście modelu, zanim Codex sfinalizuje odpowiedź. Przekaźnik pozostaje celowo konserwatywny: nie modyfikuje argumentów narzędzi natywnych dla Codex ani nie przepisuje rekordów wątków Codex. Używaj jawnego ACP tylko wtedy, gdy chcesz model środowiska uruchomieniowego/sesji ACP. Granica wbudowanego wsparcia Codex jest udokumentowana w kontrakcie wsparcia Codex harness v1.

• starsze referencje modeli Codex - starsza trasa modelu OAuth/subskrypcji Codex naprawiana przez doctor.
• openai/* - natywne wbudowane środowisko uruchomieniowe app-server Codex dla tur agentów OpenAI.
• /codex ... - natywne sterowanie konwersacją Codex.
• /acp ... lub runtime: "acp" - jawne sterowanie ACP/acpx.

Wyzwalacze, które powinny kierować do środowiska uruchomieniowego ACP:

• "Uruchom to jako jednorazową sesję Claude Code ACP i podsumuj wynik."
• "Użyj Gemini CLI do tego zadania w wątku, a następnie utrzymuj dalsze odpowiedzi w tym samym wątku."
• "Uruchom Codex przez ACP w wątku w tle."

OpenClaw wybiera runtime: "acp", rozwiązuje agentId harnessa, wiąże z bieżącą konwersacją lub wątkiem, gdy jest to obsługiwane, i kieruje dalsze odpowiedzi do tej sesji aż do zamknięcia/wygaśnięcia. Codex używa tej ścieżki tylko wtedy, gdy ACP/acpx jest jawne albo natywny plugin Codex jest niedostępny dla żądanej operacji.

Dla sessions_spawn, runtime: "acp" jest ogłaszane tylko wtedy, gdy ACP jest włączone, żądający nie działa w piaskownicy, a backend środowiska uruchomieniowego ACP jest załadowany. acp.dispatch.enabled=false wstrzymuje automatyczne wysyłanie wątków ACP, ale nie ukrywa ani nie blokuje jawnych wywołań sessions_spawn({ runtime: "acp" }). Celuje w identyfikatory harnessów ACP, takie jak codex, claude, droid, gemini lub opencode. Nie przekazuj zwykłego identyfikatora agenta konfiguracji OpenClaw z agents_list, chyba że ten wpis jest jawnie skonfigurowany z agents.list[].runtime.type="acp"; w przeciwnym razie użyj domyślnego środowiska uruchomieniowego podagenta. Gdy agent OpenClaw jest skonfigurowany z runtime.type="acp", OpenClaw używa runtime.acp.agent jako bazowego identyfikatora harnessa.

• --bind here i --thread ... wzajemnie się wykluczają.
• --bind here działa tylko na kanałach, które ogłaszają powiązanie bieżącej konwersacji; w przeciwnym razie OpenClaw zwraca jasny komunikat o braku obsługi. Powiązania utrzymują się po restartach Gateway.
• W Discord spawnSessions bramkuje tworzenie wątków potomnych dla --thread auto|here - nie dla --bind here.
• Jeśli uruchamiasz innego agenta ACP bez --cwd, OpenClaw domyślnie dziedziczy przestrzeń roboczą agenta docelowego. Brakujące dziedziczone ścieżki (ENOENT/ENOTDIR) wracają do domyślnego backendu; inne błędy dostępu (np. EACCES) pojawiają się jako błędy uruchomienia.
• Polecenia zarządzania Gateway pozostają lokalne w powiązanych konwersacjach - polecenia /acp ... są obsługiwane przez OpenClaw nawet wtedy, gdy zwykły tekst dalszych odpowiedzi trafia do powiązanej sesji ACP; /status i /unfocus również pozostają lokalne zawsze, gdy obsługa poleceń jest włączona dla tej powierzchni.

Gdy powiązania wątków są włączone dla adaptera kanału:

• OpenClaw wiąże wątek z docelową sesją ACP.
• Dalsze wiadomości w tym wątku trafiają do powiązanej sesji ACP.
• Dane wyjściowe ACP są dostarczane z powrotem do tego samego wątku.
• Cofnięcie fokusu/zamknięcie/archiwizacja/limit bezczynności lub wygaśnięcie maksymalnego wieku usuwa powiązanie.
• /acp close, /acp cancel, /acp status, /status i /unfocus to polecenia Gateway, a nie prompty do harnessa ACP.

Wymagane flagi funkcji dla ACP powiązanego z wątkiem:

• acp.enabled=true
• acp.dispatch.enabled jest domyślnie włączone (ustaw false, aby wstrzymać automatyczne wysyłanie wątków ACP; jawne wywołania sessions_spawn({ runtime: "acp" }) nadal działają).
• Uruchamianie sesji wątków adaptera kanału włączone (domyślnie: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Obsługa powiązań wątków jest specyficzna dla adaptera. Jeśli aktywny adapter kanału nie obsługuje powiązań wątków, OpenClaw zwraca jasny komunikat o braku obsługi/niedostępności.

• Dowolny adapter kanału, który udostępnia możliwość powiązania sesji/wątku.
• Bieżąca wbudowana obsługa: wątki/kanały Discord, tematy Telegram (tematy forów w grupach/supergrupach i tematy DM).
• Kanały pluginów mogą dodać obsługę przez ten sam interfejs powiązań.

Sesje interaktywne są przeznaczone do kontynuowania rozmowy na widocznej powierzchni czatu:

• /acp spawn ... --bind here wiąże bieżącą konwersację z sesją ACP.
• /acp spawn ... --thread ... wiąże wątek/temat kanału z sesją ACP.
• Trwałe skonfigurowane bindings[].type="acp" kierują dopasowane konwersacje do tej samej sesji ACP.

Kolejne wiadomości w powiązanej konwersacji są kierowane bezpośrednio do sesji ACP, a wyjście ACP jest dostarczane z powrotem do tego samego kanału/wątku/tematu.

Co OpenClaw wysyła do harnessu:

• Zwykłe powiązane kontynuacje są wysyłane jako tekst promptu, plus załączniki tylko wtedy, gdy harness/backend je obsługuje.
• Polecenia zarządzające /acp i lokalne polecenia Gateway są przechwytywane przed wysłaniem do ACP.
• Zdarzenia ukończenia wygenerowane przez środowisko uruchomieniowe są materializowane dla każdego celu. Agenci OpenClaw otrzymują wewnętrzną kopertę kontekstu środowiska uruchomieniowego OpenClaw; zewnętrzne harnessy ACP otrzymują zwykły prompt z wynikiem dziecka i instrukcją. Surowa koperta <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> nigdy nie powinna być wysyłana do zewnętrznych harnessów ani utrwalana jako tekst transkryptu użytkownika ACP.
• Wpisy transkryptu ACP używają tekstu wyzwalacza widocznego dla użytkownika albo zwykłego promptu ukończenia. Wewnętrzne metadane zdarzeń pozostają ustrukturyzowane w OpenClaw tam, gdzie to możliwe, i nie są traktowane jako treść czatu autorstwa użytkownika.

Jednorazowe sesje ACP uruchomione przez inne uruchomienie agenta są dziećmi działającymi w tle, podobnie jak subagenci:

• Rodzic prosi o pracę przez sessions_spawn({ runtime: "acp", mode: "run" }).
• Dziecko działa we własnej sesji harnessu ACP.
• Tury dziecka działają na tej samej ścieżce tła, której używają natywne uruchomienia subagentów, więc powolny harness ACP nie blokuje niepowiązanej pracy głównej sesji.
• Raporty ukończenia wracają przez ścieżkę ogłaszania ukończenia zadania. OpenClaw konwertuje wewnętrzne metadane ukończenia na zwykły prompt ACP przed wysłaniem go do zewnętrznego harnessu, więc harnessy nie widzą znaczników kontekstu środowiska uruchomieniowego właściwych tylko dla OpenClaw.
• Rodzic przepisuje wynik dziecka normalnym głosem asystenta, gdy przydatna jest odpowiedź widoczna dla użytkownika.

Nie traktuj tej ścieżki jako czatu peer-to-peer między rodzicem a dzieckiem. Dziecko ma już kanał ukończenia z powrotem do rodzica.

sessions_send może kierować do innej sesji po uruchomieniu. Dla zwykłych sesji równorzędnych OpenClaw używa ścieżki kontynuacji agent-do-agenta (A2A) po wstrzyknięciu wiadomości:

• Poczekaj na odpowiedź sesji docelowej.
• Opcjonalnie pozwól żądającemu i celowi wymienić ograniczoną liczbę tur kontynuacji.
• Poproś cel o utworzenie wiadomości ogłoszenia.
• Dostarcz to ogłoszenie do widocznego kanału lub wątku.

Ta ścieżka A2A jest mechanizmem awaryjnym dla wysyłek równorzędnych, w których nadawca potrzebuje widocznej kontynuacji. Pozostaje włączona, gdy niepowiązana sesja może zobaczyć cel ACP i wysłać do niego wiadomość, na przykład przy szerokich ustawieniach tools.sessions.visibility.

OpenClaw pomija dalszą obsługę A2A tylko wtedy, gdy żądający jest rodzicem własnego, należącego do rodzica, jednorazowego dziecka ACP. W takim przypadku uruchomienie A2A na zakończeniu zadania może wybudzić rodzica z wynikiem dziecka, przekazać odpowiedź rodzica z powrotem do dziecka i utworzyć pętlę echa rodzic/dziecko. Wynik sessions_send zgłasza delivery.status="skipped" dla tego przypadku należącego dziecka, ponieważ ścieżka zakończenia już odpowiada za wynik.

Użyj resumeSessionId, aby kontynuować poprzednią sesję ACP zamiast zaczynać od nowa. Agent odtwarza historię konwersacji przez session/load, więc wznawia pracę z pełnym kontekstem tego, co było wcześniej.

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

Typowe przypadki użycia:

• Przekaż sesję Codex z laptopa na telefon - powiedz agentowi, aby kontynuował od miejsca, w którym skończono.
• Kontynuuj sesję programowania rozpoczętą interaktywnie w CLI, teraz bezobsługowo przez swojego agenta.
• Wznów pracę przerwaną przez restart Gateway lub limit bezczynności.

Uwagi:

• resumeSessionId ma zastosowanie tylko, gdy runtime: "acp"; domyślne środowisko uruchomieniowe podagenta ignoruje to pole wyłącznie dla ACP.
• streamTo ma zastosowanie tylko, gdy runtime: "acp"; domyślne środowisko uruchomieniowe podagenta ignoruje to pole wyłącznie dla ACP.
• resumeSessionId to lokalny dla hosta identyfikator wznowienia ACP/harness, a nie klucz sesji kanału OpenClaw; OpenClaw nadal sprawdza zasady uruchamiania ACP i zasady agenta docelowego przed wysłaniem, natomiast backend ACP lub harness odpowiada za autoryzację ładowania tego nadrzędnego identyfikatora.
• resumeSessionId przywraca nadrzędną historię konwersacji ACP; thread i mode nadal normalnie stosują się do nowej sesji OpenClaw, którą tworzysz, więc mode: "session" nadal wymaga thread: true.
• Agent docelowy musi obsługiwać session/load (Codex i Claude Code to obsługują).
• Jeśli identyfikator sesji nie zostanie znaleziony, uruchomienie kończy się czytelnym błędem - bez cichego przejścia do nowej sesji.

Po wdrożeniu Gateway uruchom rzeczywiste sprawdzenie end-to-end zamiast polegać na testach jednostkowych:

1. Zweryfikuj wdrożoną wersję Gateway i commit na hoście docelowym.
2. Otwórz tymczasową sesję mostka ACPX do rzeczywistego agenta.
3. Poproś tego agenta o wywołanie sessions_spawn z runtime: "acp", agentId: "codex", mode: "run" oraz zadaniem Reply with exactly LIVE-ACP-SPAWN-OK.
4. Zweryfikuj accepted=yes, rzeczywisty childSessionKey i brak błędu walidatora.
5. Wyczyść tymczasową sesję mostka.

Pozostaw bramkę na mode: "run" i pomiń streamTo: "parent" - powiązany z wątkiem mode: "session" oraz ścieżki przekazywania strumienia to osobne, bogatsze przebiegi integracyjne.