Agenci ACP

• Jeśli ustawiono plugins.allow, jest to restrykcyjny wykaz Pluginów i musi zawierać acpx; w przeciwnym razie zainstalowane zaplecze ACP zostanie celowo zablokowane (/acp doctor zgłosi brakujący wpis na liście dozwolonych).
• Adapter Codex ACP jest dostarczany z Pluginem acpx i w miarę możliwości uruchamia się lokalnie.
• Codex ACP działa z odizolowanym CODEX_HOME. OpenClaw kopiuje z konfiguracji Codex hosta zaufane wpisy zaufania projektów oraz bezpieczną konfigurację routingu modeli/dostawców (model, model_provider, model_reasoning_effort, sandbox_mode i bezpieczne pola model_providers.<name>); uwierzytelnianie, powiadomienia i haki pozostają wyłącznie w konfiguracji hosta.
• Adaptery innych docelowych środowisk mogą być pobierane na żądanie za pomocą npx przy pierwszym użyciu.
• Uwierzytelnianie u dostawcy musi już być skonfigurowane na hoście dla danego środowiska.
• Jeśli host nie ma dostępu do npm ani sieci, pobieranie adapterów przy pierwszym uruchomieniu nie powiedzie się, dopóki pamięci podręczne nie zostaną wcześniej wypełnione lub adapter nie zostanie zainstalowany w inny sposób.

ACP uruchamia rzeczywisty proces zewnętrznego środowiska. OpenClaw odpowiada za routing, stan zadań w tle, dostarczanie, powiązania i zasady; środowisko odpowiada za logowanie u dostawcy, katalog modeli, działanie systemu plików i natywne narzędzia.

Zanim obwinisz OpenClaw, sprawdź:

• /acp doctor zgłasza włączone i sprawne zaplecze.
• Identyfikator docelowy jest dozwolony przez acp.allowedAgents, jeśli ta lista dozwolonych jest ustawiona.
• Polecenie środowiska może zostać uruchomione na hoście Gateway.
• Uwierzytelnianie dostawcy jest dostępne dla tego środowiska (claude, codex, gemini, opencode, droid itd.).
• Wybrany model istnieje w tym środowisku — identyfikatorów modeli nie można przenosić między środowiskami.
• Żądany katalog cwd istnieje i jest dostępny; możesz też pominąć cwd, aby zaplecze użyło wartości domyślnej.
• Tryb uprawnień odpowiada wykonywanej pracy. Sesje nieinteraktywne nie mogą klikać natywnych monitów o uprawnienia, dlatego uruchomienia programistyczne intensywnie zapisujące dane lub wykonujące polecenia zwykle wymagają profilu uprawnień ACPX, który może działać bez interfejsu.

• Uruchomienie tworzy lub wznawia sesję środowiska wykonawczego ACP, zapisuje metadane ACP w magazynie sesji OpenClaw i może utworzyć zadanie w tle, gdy uruchomienie należy do procesu nadrzędnego.
• Sesje ACP należące do procesu nadrzędnego są traktowane jako praca w tle nawet wtedy, gdy sesja środowiska wykonawczego jest trwała; zakończenie i dostarczanie między powierzchniami odbywają się przez mechanizm powiadomień zadania nadrzędnego, zamiast zachowywać się jak zwykła sesja czatu widoczna dla użytkownika.
• Utrzymanie zadań zamyka zakończone lub osierocone jednorazowe sesje ACP należące do procesu nadrzędnego. Trwałe sesje ACP są zachowywane, dopóki istnieje aktywne powiązanie z konwersacją; 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 lub usunięciu jego rekordu.
• Kolejne wiadomości w ramach powiązania trafiają bezpośrednio do sesji ACP, dopóki powiązanie nie zostanie zamknięte, pozbawione fokusu, zresetowane lub nie wygaśnie.
• Polecenia Gateway pozostają lokalne. /acp ..., /status i /unfocus nigdy nie są wysyłane jako zwykły tekst monitu do powiązanego środowiska ACP.
• cancel przerywa aktywną turę, jeśli zaplecze obsługuje anulowanie; nie usuwa powiązania ani metadanych sesji.
• close kończy sesję ACP z punktu widzenia OpenClaw i usuwa powiązanie. Środowisko może nadal zachowywać własną historię po stronie nadrzędnej, jeśli obsługuje wznawianie.
• Plugin acpx po wykonaniu close czyści drzewa procesów opakowujących i adapterów należących do OpenClaw oraz usuwa nieaktualne osierocone procesy ACPX należące do OpenClaw podczas uruchamiania Gateway.
• Bezczynne procesy robocze środowiska wykonawczego mogą zostać usunięte po czasie określonym przez acp.runtime.ttlMinutes; zapisane metadane sesji pozostają dostępne dla /acp sessions.

Wyzwalacze w języku naturalnym, które powinny być kierowane do natywnego Pluginu Codex, gdy jest on włączony:

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

Natywne powiązanie konwersacji Codex jest domyślną ścieżką sterowania czatem. Dynamiczne narzędzia OpenClaw nadal są wykonywane przez OpenClaw, natomiast narzędzia natywne dla Codex, takie jak powłoka/apply-patch, są wykonywane wewnątrz Codex. Dla zdarzeń narzędzi natywnych dla Codex OpenClaw wprowadza w każdej turze natywny przekaźnik hooków, dzięki któremu hooki pluginów mogą blokować before_tool_call, obserwować after_tool_call i kierować zdarzenia Codex PermissionRequest przez mechanizm zatwierdzeń OpenClaw. Hooki Codex Stop są przekazywane do before_agent_finalize OpenClaw, gdzie pluginy mogą zażądać jeszcze jednego przebiegu modelu, zanim Codex sfinalizuje odpowiedź. Przekaźnik celowo pozostaje zachowawczy: 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 korzystać z modelu środowiska wykonawczego/sesji ACP. Granice obsługi osadzonego Codex opisano w kontrakcie obsługi mechanizmu Codex v1.

• starsze odwołania do modeli Codex - starsza ścieżka modelu Codex OAuth/subskrypcji naprawiana przez doctor.
• openai/* - osadzone natywne środowisko wykonawcze serwera aplikacji Codex dla tur agenta OpenAI.
• /codex ... - natywne sterowanie konwersacją Codex.
• /acp ... lub runtime: "acp" - jawne sterowanie ACP/acpx.

Wyzwalacze, które powinny kierować do środowiska wykonawczego 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 prowadź dalsze interakcje w tym samym wątku”.
• „Uruchom Codex przez ACP w wątku działającym w tle”.

OpenClaw wybiera runtime: "acp", rozpoznaje agentId mechanizmu, wiąże go z bieżącą konwersacją lub wątkiem, jeśli jest to obsługiwane, i kieruje dalsze interakcje do tej sesji aż do jej zamknięcia/wygaśnięcia. Codex korzysta z tej ścieżki tylko wtedy, gdy ACP/acpx wskazano jawnie lub natywny plugin Codex jest niedostępny dla żądanej operacji.

W przypadku sessions_spawn opcja runtime: "acp" jest udostępniana tylko wtedy, gdy ACP jest włączone, zgłaszający nie działa w piaskownicy i załadowano backend środowiska wykonawczego ACP. acp.dispatch.enabled=false wstrzymuje automatyczne kierowanie wątków ACP, ale nie ukrywa ani nie blokuje jawnych wywołań sessions_spawn({ runtime: "acp" }). Opcja ta wskazuje identyfikatory mechanizmów ACP, takie jak codex, claude, droid, gemini lub opencode. Nie przekazuj zwykłego identyfikatora agenta z konfiguracji OpenClaw, pochodzącego z agents_list, chyba że ten wpis został jawnie skonfigurowany za pomocą agents.list[].runtime.type="acp"; w przeciwnym razie użyj domyślnego środowiska wykonawczego podagenta. Gdy agent OpenClaw jest skonfigurowany z runtime.type="acp", OpenClaw używa runtime.acp.agent jako bazowego identyfikatora mechanizmu.

• --bind here i --thread ... wzajemnie się wykluczają.
• --bind here działa tylko w kanałach, które deklarują obsługę powiązania z bieżącą konwersacją; w przeciwnym razie OpenClaw zwraca jasny komunikat o braku obsługi. Powiązania zachowują się po ponownym uruchomieniu Gateway.
• W Discord opcja spawnSessions kontroluje tworzenie wątków podrzędnych dla --thread auto|here — nie dla --bind here.
• Jeśli uruchomisz sesję dla innego agenta ACP bez --cwd, OpenClaw domyślnie dziedziczy obszar roboczy agenta docelowego. Brakujące odziedziczone ścieżki (ENOENT/ENOTDIR) powodują użycie domyślnej wartości backendu; inne błędy dostępu (np. EACCES) są zgłaszane jako błędy uruchamiania.
• Polecenia zarządzania Gateway pozostają lokalne w powiązanych konwersacjach — polecenia /acp ... są obsługiwane przez OpenClaw nawet wtedy, gdy zwykły tekst dalszej interakcji jest kierowany do powiązanej sesji ACP; /status i /unfocus również pozostają lokalne, 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.
• Kolejne wiadomości w tym wątku są kierowane do powiązanej sesji ACP.
• Dane wyjściowe ACP są dostarczane z powrotem do tego samego wątku.
• Usunięcie fokusu/zamknięcie/archiwizacja/przekroczenie limitu bezczynności lub maksymalnego wieku usuwa powiązanie.
• /acp close, /acp cancel, /acp status, /status i /unfocus są poleceniami Gateway, a nie monitami dla mechanizmu ACP.

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

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

Obsługa powiązań wątków zależy od 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 udostępniający możliwość wiązania sesji/wątków.
• Obecna wbudowana obsługa: wątki/kanały Discord, tematy Telegram (tematy forum w grupach/supergrupach i tematy wiadomości bezpośrednich).
• Kanały pluginów mogą dodać obsługę przez ten sam interfejs powiązań.

Sesje interaktywne służą 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 wpisy bindings[].type="acp" kierują pasujące konwersacje do tej samej sesji ACP.

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

Co OpenClaw wysyła do środowiska:

• Zwykłe powiązane wiadomości uzupełniające są wysyłane jako tekst promptu wraz z załącznikami, ale tylko wtedy, gdy środowisko/backend je obsługuje.
• Polecenia zarządzające /acp oraz lokalne polecenia Gateway są przechwytywane przed przekazaniem do ACP.
• Zdarzenia ukończenia generowane przez środowisko uruchomieniowe są materializowane osobno dla każdego celu. Agenci OpenClaw otrzymują wewnętrzną kopertę kontekstu środowiska uruchomieniowego OpenClaw; zewnętrzne środowiska ACP otrzymują zwykły prompt z wynikiem procesu podrzędnego i instrukcją. Surowa koperta <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> nigdy nie powinna być wysyłana do zewnętrznych środowisk ani utrwalana jako tekst wypowiedzi użytkownika w transkrypcji ACP.
• Wpisy transkrypcji ACP używają tekstu wyzwalającego widocznego dla użytkownika albo zwykłego promptu ukończenia. Wewnętrzne metadane zdarzeń pozostają w OpenClaw w postaci ustrukturyzowanej, gdy jest to możliwe, i nie są traktowane jako treść czatu utworzona przez użytkownika.

Jednorazowe sesje ACP uruchamiane przez innego agenta są procesami podrzędnymi działającymi w tle, podobnie jak podagenci:

• Sesja nadrzędna zleca pracę za pomocą sessions_spawn({ runtime: "acp", mode: "run" }).
• Proces podrzędny działa we własnej sesji środowiska ACP.
• Tury procesu podrzędnego działają na tej samej ścieżce zadań w tle, której używają natywne uruchomienia podagentów, dzięki czemu powolne środowisko ACP nie blokuje niezwiązanej pracy sesji głównej.
• Ukończenie jest zgłaszane przez ścieżkę powiadamiania o ukończeniu zadania. OpenClaw przekształca wewnętrzne metadane ukończenia w zwykły prompt ACP przed wysłaniem go do zewnętrznego środowiska, dzięki czemu środowiska nie widzą znaczników kontekstu środowiska uruchomieniowego właściwych wyłącznie dla OpenClaw.
• Sesja nadrzędna przepisuje wynik procesu podrzędnego zwykłym głosem asystenta, gdy przydatna jest odpowiedź przeznaczona dla użytkownika.

Nie traktuj tej ścieżki jako czatu równorzędnego między sesją nadrzędną a procesem podrzędnym. Proces podrzędny ma już kanał zgłaszania ukończenia do sesji nadrzędnej.

Po uruchomieniu sessions_send może wskazywać inną sesję. W przypadku zwykłych sesji równorzędnych OpenClaw po wstrzyknięciu wiadomości używa ścieżki kolejnej wiadomości agent-agent (A2A):

• Poczekaj na odpowiedź sesji docelowej.
• Opcjonalnie pozwól sesji zgłaszającej żądanie i sesji docelowej wymienić ograniczoną liczbę kolejnych tur.
• Poproś sesję docelową o utworzenie komunikatu ogłoszenia.
• Dostarcz to ogłoszenie do widocznego kanału lub wątku.

Ta ścieżka A2A jest rozwiązaniem rezerwowym dla wysyłania między równorzędnymi sesjami, gdy nadawca potrzebuje widocznej odpowiedzi uzupełniającej. 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 odpowiedź uzupełniającą A2A tylko wtedy, gdy żądający jest rodzicem własnego, jednorazowego elementu podrzędnego ACP należącego do rodzica. W takim przypadku uruchomienie A2A po ukończeniu zadania może wznowić rodzica z wynikiem elementu podrzędnego, przekazać odpowiedź rodzica z powrotem do elementu podrzędnego i utworzyć pętlę echa rodzic/element podrzędny. Wynik sessions_send zgłasza delivery.status="skipped" dla tego przypadku własnego elementu podrzędnego, ponieważ za wynik odpowiada już ścieżka ukończenia.

Użyj resumeSessionId, aby kontynuować poprzednią sesję ACP zamiast rozpoczynać nową. Agent odtwarza historię konwersacji za pomocą session/load, dzięki czemu podejmuje pracę z pełnym kontekstem wcześniejszych działań.

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

Typowe zastosowania:

• Przekazanie sesji Codex z laptopa na telefon — poleć agentowi kontynuować od miejsca, w którym przerwano.
• Kontynuowanie sesji programistycznej rozpoczętej interaktywnie w CLI, teraz bez interfejsu za pośrednictwem agenta.
• Wznowienie pracy przerwanej przez ponowne uruchomienie Gateway lub limit czasu bezczynności.

Uwagi:

• resumeSessionId ma zastosowanie tylko przy runtime: "acp"; domyślne środowisko uruchomieniowe podagenta ignoruje to pole przeznaczone wyłącznie dla ACP.
• streamTo ma zastosowanie tylko przy runtime: "acp"; domyślne środowisko uruchomieniowe podagenta ignoruje to pole przeznaczone wyłącznie dla ACP.
• resumeSessionId jest lokalnym dla hosta identyfikatorem wznowienia ACP/harness, a nie kluczem sesji kanału OpenClaw; przed przekazaniem OpenClaw nadal sprawdza zasady uruchamiania ACP i zasady agenta docelowego, natomiast backend ACP lub harness odpowiada za autoryzację wczytania tego nadrzędnego identyfikatora.
• resumeSessionId przywraca nadrzędną historię konwersacji ACP; thread i mode nadal działają normalnie dla tworzonej nowej sesji OpenClaw, dlatego mode: "session" wciąż wymaga thread: true.
• Agent docelowy musi obsługiwać session/load (Codex i Claude Code 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 przeprowadź rzeczywisty test kompleksowy zamiast polegać na testach jednostkowych:

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

Ogranicz ten test do mode: "run" i pomiń streamTo: "parent" — powiązany z wątkiem tryb mode: "session" oraz ścieżki przekazywania strumienia stanowią oddzielne, bardziej rozbudowane testy integracyjne.