Agenci ACP

• Jeśli ustawiono plugins.allow, jest to restrykcyjny spis pluginów i musi zawierać acpx; w przeciwnym razie zainstalowany backend ACP jest celowo blokowany, a /acp doctor zgłasza brakujący wpis listy dozwolonych.
• Adapter Codex ACP jest dostarczany z Plugin acpx i uruchamiany lokalnie, gdy to możliwe.
• Inne adaptery docelowych środowisk mogą nadal być pobierane na żądanie przez npx przy pierwszym użyciu.
• Uwierzytelnianie dostawcy nadal musi istnieć na hoście dla tego środowiska.
• Jeśli host nie ma dostępu do npm ani sieci, pierwsze pobrania adaptera zakończą się niepowodzeniem, dopóki pamięci podręczne nie zostaną wstępnie przygotowane albo 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 politykę; środowisko odpowiada za logowanie do dostawcy, katalog modeli, zachowanie systemu plików oraz natywne narzędzia.

Zanim obwinisz OpenClaw, sprawdź:

• /acp doctor zgłasza włączony i zdrowy backend.
• Identyfikator docelowy jest dozwolony przez acp.allowedAgents, gdy ta lista dozwolonych jest ustawiona.
• Polecenie środowiska może zostać uruchomione na hoście Gateway.
• Uwierzytelnianie dostawcy jest obecne dla tego środowiska (claude, codex, gemini, opencode, droid itd.).
• Wybrany model istnieje dla tego środowiska - identyfikatory modeli nie są przenośne między środowiskami.
• Żądany cwd istnieje i jest dostępny, albo pomiń cwd i pozwól backendowi użyć wartości domyślnej.
• Tryb uprawnień pasuje do pracy. Sesje nieinteraktywne nie mogą klikać natywnych próśb o uprawnienia, więc przebiegi kodowania intensywnie korzystające z 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 przebieg należy do rodzica.
• Sesje ACP należące do rodzica są traktowane jako praca w tle nawet wtedy, gdy sesja środowiska uruchomieniowego jest trwała; ukończenie i dostarczanie między powierzchniami przechodzą przez powiadamiacz zadania rodzica, zamiast działać jak zwykła 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, gdy pozostaje aktywne powiązanie rozmowy; nieaktualne trwałe sesje bez aktywnego powiązania są zamykane, aby nie mogły zostać cicho wznowione po zakończeniu zadania właściciela lub zniknię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 zwykły tekst promptu do powiązanego środowiska ACP.
• cancel przerywa aktywną turę, gdy backend obsługuje anulowanie; nie usuwa powiązania ani metadanych sesji.
• close kończy sesję ACP z perspektywy OpenClaw i usuwa powiązanie. Środowisko może nadal zachować własną historię upstream, jeśli obsługuje wznawianie.
• Bezczynni pracownicy ś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 być kierowane do natywnego Plugin Codex, gdy jest włączony:

• "Bind this Discord channel to Codex."
• "Attach this chat to Codex thread <id>."
• "Show Codex threads, then bind this one."

Natywne powiązanie rozmowy Codex jest domyślną ścieżką sterowania czatem. Dynamiczne narzędzia OpenClaw nadal wykonują się przez OpenClaw, podczas gdy natywne narzędzia Codex, takie jak shell/apply-patch, wykonują się wewnątrz Codex. Dla zdarzeń natywnych narzędzi Codex OpenClaw wstrzykuje natywny przekaźnik hooków na turę, aby hooki pluginów mogły blokować before_tool_call, obserwować after_tool_call i kierować zdarzenia Codex PermissionRequest przez zatwierdzenia OpenClaw. Hooki Codex Stop są przekazywane do OpenClaw before_agent_finalize, gdzie pluginy mogą zażądać jeszcze jednego przebiegu modelu, zanim Codex sfinalizuje odpowiedź. Przekaźnik pozostaje celowo konserwatywny: nie modyfikuje argumentów natywnych narzędzi Codex ani nie przepisuje rekordów wątków Codex. Użyj jawnego ACP tylko wtedy, gdy chcesz modelu środowiska uruchomieniowego/sesji ACP. Granica obsługi wbudowanego Codex jest udokumentowana w kontrakcie obsługi środowiska Codex v1.

• openai-codex/* - ścieżka PI Codex OAuth/subskrypcji.
• openai/* plus agentRuntime.id: "codex" - natywne środowisko uruchomieniowe Codex osadzone w serwerze aplikacji.
• /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 utrzymaj dalsze odpowiedzi w tym samym wątku."
• "Uruchom Codex przez ACP w wątku w tle."

OpenClaw wybiera runtime: "acp", rozwiązuje uprząż agentId, wiąże z bieżącą konwersacją lub wątkiem, gdy jest to obsługiwane, i kieruje dalsze odpowiedzi do tej sesji do czasu zamknięcia/wygaśnięcia. Codex podąża tą ścieżką 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 jest 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 uprzęży 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 uprzęży.

• --bind here i --thread ... wzajemnie się wykluczają.
• --bind here działa tylko na kanałach, które ogłaszają wiązanie bieżącej konwersacji; w przeciwnym razie OpenClaw zwraca czytelny komunikat o braku obsługi. Powiązania utrzymują się po restartach Gateway.
• W Discord, spawnSessions bramkuje tworzenie wątków podrzędnych dla --thread auto|here - nie dla --bind here.
• Jeśli uruchomisz innego agenta ACP bez --cwd, OpenClaw domyślnie dziedziczy obszar roboczy agenta docelowego. Brakujące odziedziczone ścieżki (ENOENT/ENOTDIR) wracają do domyślnej wartości backendu; inne błędy dostępu (np. EACCES) są zgłaszane 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, 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 trafiają do powiązanej sesji ACP.
• Wyjście ACP jest dostarczane z powrotem do tego samego wątku.
• Usunięcie fokusu/zamknięcie/archiwizacja/limit bezczynności albo wygaśnięcie maksymalnego wieku usuwa powiązanie.
• /acp close, /acp cancel, /acp status, /status i /unfocus są poleceniami Gateway, a nie promptami dla uprzęży 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ą).
• Włączone uruchamianie sesji wątków adaptera kanału (domyślnie: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

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

• Dowolny adapter kanału, który udostępnia zdolność wiązania sesji/wątku.
• Obecna wbudowana obsługa: wątki/kanały Discord, tematy Telegram (tematy forum w grupach/supergrupach i tematy DM).
• Kanały pluginów mogą dodać obsługę przez ten sam interfejs wiązania.

Sesje interaktywne mają kontynuować rozmowę 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ą pasujące konwersacje do tej samej sesji ACP.

Kolejne wiadomości w powiązanej konwersacji trafiają 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 oraz 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 runtime są materializowane dla każdego celu. Agenty OpenClaw otrzymują wewnętrzną kopertę kontekstu runtime OpenClaw; zewnętrzne harnessy ACP otrzymują zwykły prompt z wynikiem podrzędnym 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ą widocznego dla użytkownika tekstu wyzwalacza 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 spawnowane przez inne uruchomienie agenta są dziećmi w tle, podobnie jak sub-agenci:

• 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 tym samym pasie w tle, którego używają natywne spawny sub-agentów, więc wolny harness ACP nie blokuje niepowiązanej pracy sesji głównej.
• Ukończenie raportuje z powrotem 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ą markerów kontekstu runtime dostępnych tylko w 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 po spawnie kierować do innej sesji. Dla zwykłych sesji równorzędnych OpenClaw używa ścieżki kontynuacji agent-to-agent (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 ścieżką zapasową dla wysyłek peer, w których nadawca potrzebuje widocznej kontynuacji. Pozostaje włączona, gdy niepowiązana sesja może zobaczyć i wysłać wiadomość do celu ACP, na przykład przy szerokich ustawieniach tools.sessions.visibility.

OpenClaw pomija kontynuację A2A tylko wtedy, gdy żądający jest rodzicem własnego, należącego do rodzica jednorazowego dziecka ACP. W takim przypadku uruchomienie A2A na ścieżce ukończenia zadania może wybudzić rodzica wynikiem dziecka, przekazać odpowiedź rodzica z powrotem do dziecka i utworzyć pętlę echa rodzic/dziecko. Wynik sessions_send raportuje delivery.status="skipped" dla tego przypadku własnego dziecka, ponieważ ścieżka ukoń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 podejmuje 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 podjął pracę od miejsca, w którym skończyłeś.
• Kontynuuj sesję kodowania rozpoczętą interaktywnie w CLI, teraz bezinterfejsowo przez swojego agenta.
• Podejmij pracę przerwaną przez restart gatewaya lub limit czasu bezczynności.

Uwagi:

• resumeSessionId ma zastosowanie tylko wtedy, gdy runtime: "acp"; domyślny runtime sub-agenta ignoruje to pole dostępne tylko dla ACP.
• streamTo ma zastosowanie tylko wtedy, gdy runtime: "acp"; domyślny runtime sub-agenta ignoruje to pole dostępne tylko dla ACP.
• resumeSessionId to lokalny dla hosta identyfikator wznowienia ACP/harnessu, a nie klucz sesji kanału OpenClaw; OpenClaw nadal sprawdza zasady spawnu ACP i zasady agenta docelowego przed wysłaniem, natomiast backend ACP lub harness odpowiada za autoryzację ładowania tego identyfikatora upstream.
• resumeSessionId przywraca historię konwersacji upstream 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 obsługują).
• Jeśli identyfikator sesji nie zostanie znaleziony, spawn kończy się jasnym błędem - bez cichego powrotu do nowej sesji.

Po wdrożeniu gatewaya uruchom żywy test end-to-end zamiast ufać testom jednostkowym:

1. Zweryfikuj wersję i commit wdrożonego gatewaya na hoście docelowym.
2. Otwórz tymczasową sesję mostu ACPX do żywego agenta.
3. Poproś tego agenta, aby wywołał sessions_spawn z runtime: "acp", agentId: "codex", mode: "run" oraz zadaniem Reply with exactly LIVE-ACP-SPAWN-OK.
4. Zweryfikuj accepted=yes, rzeczywiste childSessionKey i brak błędu walidatora.
5. Posprzątaj tymczasową sesję mostu.

Utrzymaj bramkę na mode: "run" i pomiń streamTo: "parent" - powiązane z wątkiem mode: "session" oraz ścieżki przekazywania strumienia są osobnymi, bogatszymi przebiegami integracyjnymi.