Agenci ACP
Sesje Agent Client Protocol (ACP) pozwalają OpenClaw uruchamiać zewnętrzne coding harnesses (na przykład Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI i inne obsługiwane harnesses ACPX) przez plugin backendu ACP. Jeśli poprosisz OpenClaw zwykłym językiem, aby „uruchomił to w Codex” albo „uruchomił Claude Code w wątku”, OpenClaw powinien skierować to żądanie do runtime ACP (a nie do natywnego runtime podagentów). Każde uruchomienie sesji ACP jest śledzone jako zadanie w tle. Jeśli chcesz, aby Codex lub Claude Code połączyły się bezpośrednio jako zewnętrzny klient MCP z istniejącymi rozmowami kanałowymi OpenClaw, użyjopenclaw mcp serve zamiast ACP.
Którą stronę chcę?
Są tu trzy powiązane powierzchnie, które łatwo pomylić:| Chcesz… | Użyj tego | Uwagi |
|---|---|---|
| Uruchamiać Codex, Claude Code, Gemini CLI lub inny zewnętrzny harness przez OpenClaw | Ta strona: agenci ACP | Sesje powiązane z czatem, /acp spawn, sessions_spawn({ runtime: "acp" }), zadania w tle, kontrolki runtime |
| Udostępnić sesję OpenClaw Gateway jako serwer ACP dla edytora lub klienta | openclaw acp | Tryb mostka. IDE/klient mówi ACP do OpenClaw przez stdio/WebSocket |
| Użyć lokalnego AI CLI ponownie jako tekstowego modelu zapasowego | CLI Backends | To nie jest ACP. Brak narzędzi OpenClaw, brak kontrolek ACP, brak runtime harness |
Czy to działa od razu po instalacji?
Zwykle tak.- Świeże instalacje są teraz dostarczane z włączonym domyślnie dołączonym pluginem runtime
acpx. - Dołączony plugin
acpxpreferuje własny, przypięty binarny plikacpx. - Przy uruchomieniu OpenClaw sonduje ten plik binarny i w razie potrzeby sam go naprawia.
- Zacznij od
/acp doctor, jeśli chcesz przeprowadzić szybki test gotowości.
- Adapter docelowego harness może zostać pobrany na żądanie przez
npxprzy pierwszym użyciu tego harness. - Uwierzytelnienie dostawcy nadal musi istnieć na hoście dla tego harness.
- Jeśli host nie ma dostępu do npm/sieci, pobrania adapterów przy pierwszym uruchomieniu mogą się nie powieść, dopóki pamięci podręczne nie zostaną rozgrzane albo adapter nie zostanie zainstalowany w inny sposób.
/acp spawn codex: OpenClaw powinien być gotowy do bootstrapowaniaacpx, ale adapter ACP Codex może nadal wymagać pobrania przy pierwszym uruchomieniu./acp spawn claude: podobnie w przypadku adaptera ACP Claude oraz uwierzytelnienia po stronie Claude na tym hoście.
Szybki przepływ operatora
Użyj tego, gdy chcesz praktycznego poradnika do/acp:
- Uruchom sesję:
/acp spawn codex --bind here/acp spawn codex --mode persistent --thread auto
- Pracuj w powiązanej rozmowie lub wątku (albo wskaż jawnie ten klucz sesji).
- Sprawdź stan runtime:
/acp status
- Dostosuj opcje runtime w razie potrzeby:
/acp model <provider/model>/acp permissions <profile>/acp timeout <seconds>
- Skieruj aktywną sesję bez zastępowania kontekstu:
/acp steer tighten logging and continue
- Zatrzymaj pracę:
/acp cancel(zatrzymaj bieżącą turę), albo/acp close(zamknij sesję i usuń powiązania)
Szybki start dla ludzi
Przykłady naturalnych próśb:- „Powiąż ten kanał Discord z Codex.”
- „Uruchom trwałą sesję Codex w wątku tutaj i utrzymuj jej fokus.”
- „Uruchom to jako jednorazową sesję Claude Code ACP i podsumuj wynik.”
- „Powiąż ten czat iMessage z Codex i zachowaj kolejne wiadomości w tym samym obszarze roboczym.”
- „Użyj Gemini CLI do tego zadania w wątku, a potem zachowaj kolejne wiadomości w tym samym wątku.”
- Wybrać
runtime: "acp". - Rozpoznać żądany cel harness (
agentId, na przykładcodex). - Jeśli zażądano powiązania z bieżącą rozmową i aktywny kanał to obsługuje, powiązać sesję ACP z tą rozmową.
- W przeciwnym razie, jeśli zażądano powiązania z wątkiem i bieżący kanał to obsługuje, powiązać sesję ACP z wątkiem.
- Kierować kolejne wiadomości w powiązaniu do tej samej sesji ACP, dopóki nie zostanie odfokusowana/zamknięta/wygaśnie.
ACP a podagenci
Używaj ACP, gdy chcesz zewnętrznego runtime harness. Używaj podagentów, gdy chcesz delegowanych uruchomień natywnych dla OpenClaw.| Obszar | Sesja ACP | Uruchomienie podagenta |
|---|---|---|
| Runtime | Plugin backendu ACP (na przykład acpx) | Natywny runtime podagentów OpenClaw |
| Klucz sesji | agent:<agentId>:acp:<uuid> | agent:<agentId>:subagent:<uuid> |
| Główne polecenia | /acp ... | /subagents ... |
| Narzędzie uruchamiania | sessions_spawn z runtime:"acp" | sessions_spawn (domyślny runtime) |
Jak ACP uruchamia Claude Code
W przypadku Claude Code przez ACP stos wygląda następująco:- Płaszczyzna sterowania sesjami ACP OpenClaw
- dołączony plugin runtime
acpx - adapter Claude ACP
- mechanizm runtime/sesji po stronie Claude
- ACP Claude to sesja harness z kontrolkami ACP, wznawianiem sesji, śledzeniem zadań w tle i opcjonalnym powiązaniem z rozmową/wątkiem.
- CLI backends to oddzielne tekstowe lokalne runtime zapasowe. Zobacz CLI Backends.
- chcesz
/acp spawn, sesje możliwe do powiązania, kontrolki runtime albo trwałą pracę harness: użyj ACP - chcesz prosty lokalny fallback tekstowy przez surowe CLI: użyj CLI backends
Powiązane sesje
Powiązania z bieżącą rozmową
Użyj/acp spawn <harness> --bind here, gdy chcesz, aby bieżąca rozmowa stała się trwałym obszarem roboczym ACP bez tworzenia podrzędnego wątku.
Zachowanie:
- OpenClaw nadal zarządza transportem kanału, auth, bezpieczeństwem i dostarczaniem.
- Bieżąca rozmowa jest przypinana do uruchomionego klucza sesji ACP.
- Kolejne wiadomości w tej rozmowie są kierowane do tej samej sesji ACP.
/newi/resetresetują tę samą powiązaną sesję ACP na miejscu./acp closezamyka sesję i usuwa powiązanie bieżącej rozmowy.
--bind herezachowuje tę samą powierzchnię czatu. Na Discord bieżący kanał pozostaje bieżącym kanałem.--bind herenadal może utworzyć nową sesję ACP, jeśli uruchamiasz nową pracę.--bind heresam z siebie nie tworzy podrzędnego wątku Discord ani tematu Telegram.- Runtime ACP nadal może mieć własny katalog roboczy (
cwd) albo obszar roboczy zarządzany przez backend na dysku. Ten obszar roboczy runtime jest oddzielny od powierzchni czatu i nie oznacza nowego wątku wiadomości. - Jeśli uruchamiasz do innego agenta ACP i nie podajesz
--cwd, OpenClaw domyślnie dziedziczy obszar roboczy docelowego agenta, a nie żądającego. - Jeśli ta odziedziczona ścieżka obszaru roboczego nie istnieje (
ENOENT/ENOTDIR), OpenClaw wraca do domyślnegocwdbackendu zamiast po cichu ponownie użyć niewłaściwego drzewa. - Jeśli odziedziczony obszar roboczy istnieje, ale nie można uzyskać do niego dostępu (na przykład
EACCES), uruchomienie zwraca rzeczywisty błąd dostępu zamiast porzucaćcwd.
- powierzchnia czatu: gdzie ludzie nadal rozmawiają (
kanał Discord,temat Telegram,czat iMessage) - sesja ACP: trwały stan runtime Codex/Claude/Gemini, do którego OpenClaw kieruje wiadomości
- podrzędny wątek/temat: opcjonalna dodatkowa powierzchnia wiadomości tworzona tylko przez
--thread ... - obszar roboczy runtime: lokalizacja w systemie plików, w której działa harness (
cwd, checkout repozytorium, obszar roboczy backendu)
/acp spawn codex --bind here: zachowaj ten czat, uruchom lub dołącz sesję Codex ACP i kieruj do niej przyszłe wiadomości stąd/acp spawn codex --thread auto: OpenClaw może utworzyć podrzędny wątek/temat i tam powiązać sesję ACP/acp spawn codex --bind here --cwd /workspace/repo: to samo powiązanie czatu co wyżej, ale Codex działa w/workspace/repo
- Kanały czatu/wiadomości, które ogłaszają obsługę powiązania z bieżącą rozmową, mogą używać
--bind hereprzez współdzieloną ścieżkę powiązań rozmów. - Kanały z niestandardową semantyką wątków/tematów nadal mogą zapewniać kanoniczność specyficzną dla kanału za tym samym współdzielonym interfejsem.
--bind herezawsze oznacza „powiąż bieżącą rozmowę na miejscu”.- Ogólne powiązania z bieżącą rozmową używają współdzielonego magazynu powiązań OpenClaw i przetrwają zwykłe restarty gateway.
--bind herei--thread ...wzajemnie się wykluczają w/acp spawn.- Na Discord
--bind herewiąże bieżący kanał lub wątek na miejscu.spawnAcpSessionsjest wymagane tylko wtedy, gdy OpenClaw musi utworzyć podrzędny wątek dla--thread auto|here. - Jeśli aktywny kanał nie udostępnia powiązań ACP z bieżącą rozmową, OpenClaw zwraca jasny komunikat o braku obsługi.
resumei pytania o „nową sesję” dotyczą sesji ACP, a nie kanału. Możesz ponownie użyć albo zastąpić stan runtime bez zmiany bieżącej powierzchni czatu.
Sesje powiązane z wątkiem
Gdy powiązania wątków są włączone dla adaptera kanału, sesje ACP mogą być powiązane z wątkami:- OpenClaw wiąże wątek z docelową sesją ACP.
- Kolejne wiadomości w tym wątku są kierowane do powiązanej sesji ACP.
- Wynik ACP jest dostarczany z powrotem do tego samego wątku.
- Odfokusowanie/zamknięcie/archiwizacja/wygaśnięcie limitu bezczynności lub maksymalnego wieku usuwa powiązanie.
acp.enabled=trueacp.dispatch.enabledjest domyślnie włączone (ustawfalse, aby wstrzymać dispatch ACP)- Włączona flaga uruchamiania wątków ACP adaptera kanału (zależna od adaptera)
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true - Telegram:
channels.telegram.threadBindings.spawnAcpSessions=true
- Discord:
Kanały obsługujące wątki
- 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 forum w grupach/supergrupach i tematy DM)
- Kanały pluginów mogą dodać obsługę przez ten sam interfejs powiązań.
Ustawienia specyficzne dla kanału
W przypadku nieefemerycznych przepływów pracy skonfiguruj trwałe powiązania ACP w wpisach najwyższego poziomubindings[].
Model powiązań
bindings[].type="acp"oznacza trwałe powiązanie rozmowy ACP.bindings[].matchidentyfikuje docelową rozmowę:- kanał lub wątek Discord:
match.channel="discord"+match.peer.id="<channelOrThreadId>" - temat forum Telegram:
match.channel="telegram"+match.peer.id="<chatId>:topic:<topicId>" - czat DM/grupowy BlueBubbles:
match.channel="bluebubbles"+match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"Dla stabilnych powiązań grup preferujchat_id:*lubchat_identifier:*. - czat DM/grupowy iMessage:
match.channel="imessage"+match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"Dla stabilnych powiązań grup preferujchat_id:*.
- kanał lub wątek Discord:
bindings[].agentIdto identyfikator właścicielskiego agenta OpenClaw.- Opcjonalne nadpisania ACP znajdują się w
bindings[].acp:mode(persistentluboneshot)labelcwdbackend
Domyślne ustawienia runtime na agenta
Użyjagents.list[].runtime, aby zdefiniować domyślne ustawienia ACP raz dla każdego agenta:
agents.list[].runtime.type="acp"agents.list[].runtime.acp.agent(identyfikator harness, na przykładcodexlubclaude)agents.list[].runtime.acp.backendagents.list[].runtime.acp.modeagents.list[].runtime.acp.cwd
bindings[].acp.*agents.list[].runtime.acp.*- globalne ustawienia domyślne ACP (na przykład
acp.backend)
- OpenClaw zapewnia istnienie skonfigurowanej sesji ACP przed użyciem.
- Wiadomości w tym kanale lub temacie są kierowane do skonfigurowanej sesji ACP.
- W powiązanych rozmowach
/newi/resetresetują ten sam klucz sesji ACP na miejscu. - Tymczasowe powiązania runtime (na przykład utworzone przez przepływy fokusu wątków) nadal mają zastosowanie tam, gdzie istnieją.
- Przy uruchamianiu ACP między agentami bez jawnego
cwdOpenClaw dziedziczy obszar roboczy docelowego agenta z konfiguracji agenta. - Brakujące odziedziczone ścieżki obszaru roboczego wracają do domyślnego
cwdbackendu; rzeczywiste błędy dostępu są zwracane jako błędy uruchomienia.
Uruchamianie sesji ACP (interfejsy)
Z sessions_spawn
Użyj runtime: "acp", aby uruchomić sesję ACP z tury agenta lub wywołania narzędzia.
runtimedomyślnie ma wartośćsubagent, więc ustawruntime: "acp"jawnie dla sesji ACP.- Jeśli pominięto
agentId, OpenClaw użyjeacp.defaultAgent, jeśli jest skonfigurowane. mode: "session"wymagathread: true, aby zachować trwałą powiązaną rozmowę.
task(wymagane): początkowy prompt wysyłany do sesji ACP.runtime(wymagane dla ACP): musi mieć wartość"acp".agentId(opcjonalne): identyfikator docelowego harness ACP. Wraca doacp.defaultAgent, jeśli jest ustawiony.thread(opcjonalne, domyślniefalse): żądanie przepływu powiązania z wątkiem, gdy jest obsługiwane.mode(opcjonalne):run(jednorazowe) albosession(trwałe).- domyślnie jest
run - jeśli
thread: trueimodepominięto, OpenClaw może domyślnie przejść do zachowania trwałego zależnie od ścieżki runtime mode: "session"wymagathread: true
- domyślnie jest
cwd(opcjonalne): żądany katalog roboczy runtime (walidowany przez politykę backendu/runtime). Jeśli pominięty, uruchomienie ACP dziedziczy obszar roboczy docelowego agenta, gdy jest skonfigurowany; brakujące odziedziczone ścieżki wracają do domyślnych backendu, a rzeczywiste błędy dostępu są zwracane.label(opcjonalne): etykieta widoczna dla operatora używana w tekście sesji/banera.resumeSessionId(opcjonalne): wznowienie istniejącej sesji ACP zamiast tworzenia nowej. Agent odtwarza historię rozmowy przezsession/load. Wymagaruntime: "acp".streamTo(opcjonalne):"parent"strumieniuje podsumowania postępu początkowego uruchomienia ACP z powrotem do sesji żądającej jako zdarzenia systemowe.- Gdy dostępne, zaakceptowane odpowiedzi zawierają
streamLogPath, wskazujące na plik JSONL logu o zakresie sesji (<sessionId>.acp-stream.jsonl), który można śledzić, aby zobaczyć pełną historię przekazywania.
- Gdy dostępne, zaakceptowane odpowiedzi zawierają
Wznowienie istniejącej sesji
UżyjresumeSessionId, aby kontynuować poprzednią sesję ACP zamiast zaczynać od nowa. Agent odtwarza historię rozmowy przez session/load, więc wznawia pracę z pełnym kontekstem tego, co było wcześniej.
- Przekazanie sesji Codex z laptopa na telefon — poproś agenta, aby podjął pracę tam, gdzie skończyłeś
- Kontynuowanie sesji programistycznej rozpoczętej interaktywnie w CLI, teraz bezgłowo przez agenta
- Wznowienie pracy przerwanej przez restart gateway albo timeout bezczynności
resumeSessionIdwymagaruntime: "acp"— zwraca błąd, jeśli zostanie użyte z runtime podagenta.resumeSessionIdprzywraca historię rozmowy upstream ACP;threadimodenadal stosują się normalnie do nowej sesji OpenClaw, którą tworzysz, więcmode: "session"nadal wymagathread: true.- Docelowy agent musi obsługiwać
session/load(Codex i Claude Code to obsługują). - Jeśli identyfikator sesji nie zostanie znaleziony, uruchomienie kończy się jawnym błędem — bez cichego przejścia do nowej sesji.
Smoke test operatora
Użyj tego po wdrożeniu gateway, gdy chcesz szybko na żywo sprawdzić, czy uruchamianie ACP naprawdę działa end-to-end, a nie tylko przechodzi testy jednostkowe. Zalecana bramka:- Zweryfikuj wdrożoną wersję/commit gateway na hoście docelowym.
- Potwierdź, że wdrożone źródło zawiera akceptację linii ACP w
src/gateway/sessions-patch.ts(subagent:* or acp:* sessions). - Otwórz tymczasową sesję mostka ACPX do aktywnego agenta (na przykład
razor(main)najpclawhq). - Poproś tego agenta o wywołanie
sessions_spawnz:runtime: "acp"agentId: "codex"mode: "run"- task:
Reply with exactly LIVE-ACP-SPAWN-OK
- Zweryfikuj, że agent zgłasza:
accepted=yes- rzeczywisty
childSessionKey - brak błędu walidatora
- Posprzątaj tymczasową sesję mostka ACPX.
- Trzymaj ten smoke test w
mode: "run", chyba że celowo testujesz trwałe sesje ACP powiązane z wątkiem. - Nie wymagaj
streamTo: "parent"dla podstawowej bramki. Ta ścieżka zależy od możliwości żądającego/sesji i jest osobnym testem integracyjnym. - Traktuj testowanie
mode: "session"powiązanego z wątkiem jako drugi, bogatszy przebieg integracyjny z rzeczywistego wątku Discord albo tematu Telegram.
Zgodność z sandbox
Sesje ACP obecnie działają w runtime hosta, a nie wewnątrz sandbox OpenClaw. Obecne ograniczenia:- Jeśli sesja żądająca jest sandboxowana, uruchamianie ACP jest blokowane zarówno dla
sessions_spawn({ runtime: "acp" }), jak i/acp spawn.- Błąd:
Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
- Błąd:
sessions_spawnzruntime: "acp"nie obsługujesandbox: "require".- Błąd:
sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".
- Błąd:
runtime: "subagent", gdy potrzebujesz wykonania wymuszanego przez sandbox.
Z polecenia /acp
Użyj /acp spawn, gdy potrzebujesz jawnej kontroli operatora z czatu.
--mode persistent|oneshot--bind here|off--thread auto|here|off--cwd <absolute-path>--label <name>
Rozpoznawanie celu sesji
Większość akcji/acp akceptuje opcjonalny cel sesji (session-key, session-id albo session-label).
Kolejność rozpoznawania:
- Jawny argument celu (albo
--sessiondla/acp steer)- próbuje najpierw klucza
- potem identyfikatora sesji w formacie UUID
- potem etykiety
- Bieżące powiązanie wątku (jeśli ta rozmowa/wątek jest powiązana z sesją ACP)
- Powrót do bieżącej sesji żądającej
Unable to resolve session target: ...).
Tryby powiązania przy uruchamianiu
/acp spawn obsługuje --bind here|off.
| Tryb | Zachowanie |
|---|---|
here | Powiąż bieżącą aktywną rozmowę na miejscu; zakończ błędem, jeśli żadna nie jest aktywna. |
off | Nie twórz powiązania z bieżącą rozmową. |
--bind hereto najprostsza ścieżka operatora dla „niech ten kanał lub czat będzie obsługiwany przez Codex”.--bind herenie tworzy podrzędnego wątku.--bind herejest dostępne tylko w kanałach, które udostępniają obsługę powiązania z bieżącą rozmową.--bindi--threadnie mogą być łączone w tym samym wywołaniu/acp spawn.
Tryby wątków przy uruchamianiu
/acp spawn obsługuje --thread auto|here|off.
| Tryb | Zachowanie |
|---|---|
auto | W aktywnym wątku: powiąż ten wątek. Poza wątkiem: utwórz/powiąż podrzędny wątek, jeśli jest obsługiwany. |
here | Wymagaj bieżącego aktywnego wątku; zakończ błędem, jeśli nie jesteś w wątku. |
off | Brak powiązania. Sesja uruchamia się bez powiązania. |
- Na powierzchniach bez obsługi powiązań wątków domyślne zachowanie jest w praktyce równe
off. - Uruchamianie powiązane z wątkiem wymaga obsługi polityki kanału:
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true - Telegram:
channels.telegram.threadBindings.spawnAcpSessions=true
- Discord:
- Użyj
--bind here, jeśli chcesz przypiąć bieżącą rozmowę bez tworzenia podrzędnego wątku.
Kontrolki ACP
Dostępna rodzina poleceń:/acp spawn/acp cancel/acp steer/acp close/acp status/acp set-mode/acp set/acp cwd/acp permissions/acp timeout/acp model/acp reset-options/acp sessions/acp doctor/acp install
/acp status pokazuje efektywne opcje runtime i, gdy są dostępne, identyfikatory sesji zarówno na poziomie runtime, jak i backendu.
Niektóre kontrolki zależą od możliwości backendu. Jeśli backend nie obsługuje danej kontrolki, OpenClaw zwraca jasny błąd nieobsługiwanej kontrolki.
Książka kucharska poleceń ACP
| Polecenie | Co robi | Przykład |
|---|---|---|
/acp spawn | Tworzy sesję ACP; opcjonalnie powiązanie z bieżącą rozmową albo z wątkiem. | /acp spawn codex --bind here --cwd /repo |
/acp cancel | Anuluje turę będącą w toku dla docelowej sesji. | /acp cancel agent:codex:acp:<uuid> |
/acp steer | Wysyła instrukcję sterującą do uruchomionej sesji. | /acp steer --session support inbox prioritize failing tests |
/acp close | Zamyka sesję i odpina cele wątków. | /acp close |
/acp status | Pokazuje backend, tryb, stan, opcje runtime, możliwości. | /acp status |
/acp set-mode | Ustawia tryb runtime dla docelowej sesji. | /acp set-mode plan |
/acp set | Ogólny zapis opcji konfiguracji runtime. | /acp set model openai/gpt-5.4 |
/acp cwd | Ustawia nadpisanie katalogu roboczego runtime. | /acp cwd /Users/user/Projects/repo |
/acp permissions | Ustawia profil polityki zatwierdzeń. | /acp permissions strict |
/acp timeout | Ustawia limit czasu runtime (sekundy). | /acp timeout 120 |
/acp model | Ustawia nadpisanie modelu runtime. | /acp model anthropic/claude-opus-4-6 |
/acp reset-options | Usuwa nadpisania opcji runtime sesji. | /acp reset-options |
/acp sessions | Wyświetla ostatnie sesje ACP z magazynu. | /acp sessions |
/acp doctor | Stan backendu, możliwości, możliwe działania naprawcze. | /acp doctor |
/acp install | Wyświetla deterministyczne kroki instalacji i włączenia. | /acp install |
/acp sessions odczytuje magazyn dla bieżącej powiązanej sesji albo sesji żądającej. Polecenia, które akceptują tokeny session-key, session-id albo session-label, rozpoznają cele przez wykrywanie sesji gateway, w tym niestandardowe katalogi session.store dla poszczególnych agentów.
Mapowanie opcji runtime
/acp ma wygodne polecenia i generyczny setter.
Równoważne operacje:
/acp model <id>mapuje do klucza konfiguracji runtimemodel./acp permissions <profile>mapuje do klucza konfiguracji runtimeapproval_policy./acp timeout <seconds>mapuje do klucza konfiguracji runtimetimeout./acp cwd <path>bezpośrednio aktualizuje nadpisaniecwdruntime./acp set <key> <value>to ścieżka ogólna.- Przypadek specjalny:
key=cwdużywa ścieżki nadpisaniacwd.
- Przypadek specjalny:
/acp reset-optionsczyści wszystkie nadpisania runtime dla docelowej sesji.
Obsługa harness acpx (obecnie)
Bieżące wbudowane aliasy harness acpx:claudecodexcopilotcursor(Cursor CLI:cursor-agent acp)droidgeminiiflowkilocodekimikiroopenclawopencodepiqwen
agentId, chyba że konfiguracja acpx definiuje własne aliasy agentów.
Jeśli lokalna instalacja Cursor nadal udostępnia ACP jako agent acp, nadpisz polecenie agenta cursor w swojej konfiguracji acpx zamiast zmieniać wbudowaną wartość domyślną.
Bezpośrednie użycie CLI acpx może również kierować żądania do dowolnych adapterów przez --agent <command>, ale ta surowa furtka jest funkcją CLI acpx (a nie zwykłą ścieżką agentId w OpenClaw).
Wymagana konfiguracja
Bazowa konfiguracja ACP:- Discord:
channels.discord.threadBindings.spawnAcpSessions=true
Konfiguracja pluginu dla backendu acpx
Świeże instalacje są dostarczane z włączonym domyślnie dołączonym pluginem runtimeacpx, więc ACP zwykle działa bez ręcznego kroku instalacji pluginu.
Zacznij od:
acpx, zablokowałeś go przez plugins.allow / plugins.deny albo chcesz
przełączyć się na lokalny checkout deweloperski, użyj jawnej ścieżki pluginu:
Konfiguracja polecenia i wersji acpx
Domyślnie dołączony plugin backendu acpx (acpx) używa lokalnego dla pluginu przypiętego pliku binarnego:
- Polecenie domyślnie wskazuje lokalny dla pluginu
node_modules/.bin/acpxwewnątrz pakietu pluginu ACPX. - Oczekiwana wersja domyślnie jest zgodna z przypięciem rozszerzenia.
- Przy uruchomieniu ACP backend jest rejestrowany od razu jako niegotowy.
- Zadanie ensure w tle weryfikuje
acpx --version. - Jeśli lokalny dla pluginu plik binarny jest nieobecny albo ma niezgodną wersję, uruchamiane jest:
npm install --omit=dev --no-save acpx@<pinned>i następuje ponowna weryfikacja.
commandakceptuje ścieżkę bezwzględną, ścieżkę względną albo nazwę polecenia (acpx).- Ścieżki względne są rozwiązywane względem katalogu obszaru roboczego OpenClaw.
expectedVersion: "any"wyłącza ścisłe dopasowanie wersji.- Gdy
commandwskazuje niestandardowy plik binarny/ścieżkę, automatyczna instalacja lokalna dla pluginu jest wyłączona. - Uruchamianie OpenClaw pozostaje nieblokujące podczas działania sprawdzania stanu backendu w tle.
Automatyczna instalacja zależności
Gdy instalujesz OpenClaw globalnie przeznpm install -g openclaw, zależności runtime acpx
(binaria zależne od platformy) są instalowane automatycznie
przez hook postinstall. Jeśli automatyczna instalacja się nie powiedzie, gateway nadal uruchamia się
normalnie i zgłasza brakującą zależność przez openclaw acp doctor.
Most MCP dla narzędzi pluginów
Domyślnie sesje ACPX nie udostępniają narzędzi rejestrowanych przez pluginy OpenClaw harness ACP. Jeśli chcesz, aby agenci ACP, tacy jak Codex albo Claude Code, mogli wywoływać zainstalowane narzędzia pluginów OpenClaw, takie jak memory recall/store, włącz dedykowany most:- Wstrzykuje wbudowany serwer MCP o nazwie
openclaw-plugin-toolsdo bootstrapu sesji ACPX. - Udostępnia narzędzia pluginów już zarejestrowane przez zainstalowane i włączone pluginy OpenClaw.
- Zachowuje tę funkcję jako jawną i domyślnie wyłączoną.
- To rozszerza powierzchnię narzędzi harness ACP.
- Agenci ACP otrzymują dostęp tylko do narzędzi pluginów już aktywnych w gateway.
- Traktuj to jako tę samą granicę zaufania, co pozwolenie tym pluginom na wykonywanie działań w samym OpenClaw.
- Przejrzyj zainstalowane pluginy przed włączeniem tej funkcji.
mcpServers nadal działają jak wcześniej. Wbudowany most narzędzi pluginów jest
dodatkową wygodną funkcją opt-in, a nie zamiennikiem ogólnej konfiguracji serwera MCP.
Konfiguracja limitu czasu runtime
Dołączony pluginacpx domyślnie ustawia 120-sekundowy
limit czasu dla osadzonych tur runtime. Daje to wolniejszym harnesses, takim jak Gemini CLI, dość czasu na ukończenie
uruchamiania i inicjalizacji ACP. Nadpisz tę wartość, jeśli host wymaga innego
limitu runtime:
Konfiguracja uprawnień
Sesje ACP działają nieinteraktywnie — nie ma TTY do zatwierdzania ani odrzucania promptów uprawnień zapisu plików i wykonywania poleceń powłoki. Plugin acpx udostępnia dwa klucze konfiguracyjne kontrolujące sposób obsługi uprawnień: Te uprawnienia harness ACPX są oddzielne od zatwierdzeń exec OpenClaw i oddzielne od flag obejścia dostawcy backendu CLI, takich jak Claude CLI--permission-mode bypassPermissions. ACPX approve-all jest przełącznikiem awaryjnym na poziomie harness dla sesji ACP.
permissionMode
Kontroluje, jakie operacje agent harness może wykonywać bez promptu.
| Wartość | Zachowanie |
|---|---|
approve-all | Automatycznie zatwierdza wszystkie zapisy plików i polecenia powłoki. |
approve-reads | Automatycznie zatwierdza tylko odczyty; zapis i exec wymagają promptów. |
deny-all | Odrzuca wszystkie prompty uprawnień. |
nonInteractivePermissions
Kontroluje, co dzieje się, gdy prompt uprawnień normalnie zostałby pokazany, ale nie ma dostępnego interaktywnego TTY (co zawsze ma miejsce w sesjach ACP).
| Wartość | Zachowanie |
|---|---|
fail | Przerywa sesję z AcpRuntimeError. (domyślne) |
deny | Cicho odrzuca uprawnienie i kontynuuje (łagodna degradacja). |
Konfiguracja
Ustaw przez konfigurację pluginu:Ważne: OpenClaw obecnie domyślnie używapermissionMode=approve-readsinonInteractivePermissions=fail. W nieinteraktywnych sesjach ACP każdy zapis lub exec, który wywoła prompt uprawnień, może zakończyć się błędemAcpRuntimeError: Permission prompt unavailable in non-interactive mode. Jeśli musisz ograniczyć uprawnienia, ustawnonInteractivePermissionsnadeny, aby sesje ulegały łagodnej degradacji zamiast się wykrzaczać.
Rozwiązywanie problemów
| Objaw | Prawdopodobna przyczyna | Poprawka |
|---|---|---|
ACP runtime backend is not configured | Brak pluginu backendu albo jest wyłączony. | Zainstaluj i włącz plugin backendu, a następnie uruchom /acp doctor. |
ACP is disabled by policy (acp.enabled=false) | ACP jest globalnie wyłączone. | Ustaw acp.enabled=true. |
ACP dispatch is disabled by policy (acp.dispatch.enabled=false) | Dispatch z normalnych wiadomości w wątku jest wyłączony. | Ustaw acp.dispatch.enabled=true. |
ACP agent "<id>" is not allowed by policy | Agent nie znajduje się na liście dozwolonych. | Użyj dozwolonego agentId albo zaktualizuj acp.allowedAgents. |
Unable to resolve session target: ... | Nieprawidłowy token klucza/id/etykiety. | Uruchom /acp sessions, skopiuj dokładny klucz/etykietę i spróbuj ponownie. |
--bind here requires running /acp spawn inside an active ... conversation | --bind here zostało użyte bez aktywnej rozmowy, którą można powiązać. | Przejdź do docelowego czatu/kanału i spróbuj ponownie albo użyj uruchomienia bez powiązania. |
Conversation bindings are unavailable for <channel>. | Adapter nie ma możliwości powiązania ACP z bieżącą rozmową. | Użyj /acp spawn ... --thread ..., jeśli jest obsługiwane, skonfiguruj wpisy najwyższego poziomu bindings[] albo przejdź do obsługiwanego kanału. |
--thread here requires running /acp spawn inside an active ... thread | --thread here zostało użyte poza kontekstem wątku. | Przejdź do docelowego wątku albo użyj --thread auto/off. |
Only <user-id> can rebind this channel/conversation/thread. | Inny użytkownik jest właścicielem aktywnego celu powiązania. | Powiąż ponownie jako właściciel albo użyj innej rozmowy lub wątku. |
Thread bindings are unavailable for <channel>. | Adapter nie ma możliwości powiązania wątków. | Użyj --thread off albo przejdź do obsługiwanego adaptera/kanału. |
Sandboxed sessions cannot spawn ACP sessions ... | Runtime ACP działa po stronie hosta; sesja żądająca jest sandboxowana. | Użyj runtime="subagent" z sesji sandboxowanych albo uruchamiaj ACP z sesji niesandboxowanej. |
sessions_spawn sandbox="require" is unsupported for runtime="acp" ... | Zażądano sandbox="require" dla runtime ACP. | Użyj runtime="subagent" dla wymaganego sandboxowania albo użyj ACP z sandbox="inherit" z niesandboxowanej sesji. |
| Brak metadanych ACP dla powiązanej sesji | Nieaktualne/usunięte metadane sesji ACP. | Odtwórz je przez /acp spawn, a następnie ponownie powiąż/ustaw fokus wątku. |
AcpRuntimeError: Permission prompt unavailable in non-interactive mode | permissionMode blokuje zapis/exec w nieinteraktywnej sesji ACP. | Ustaw plugins.entries.acpx.config.permissionMode na approve-all i uruchom ponownie gateway. Zobacz Konfiguracja uprawnień. |
| Sesja ACP kończy się niepowodzeniem wcześnie i daje mało danych wyjściowych | Prompty uprawnień są blokowane przez permissionMode/nonInteractivePermissions. | Sprawdź logi gateway pod kątem AcpRuntimeError. Dla pełnych uprawnień ustaw permissionMode=approve-all; dla łagodnej degradacji ustaw nonInteractivePermissions=deny. |
| Sesja ACP zawiesza się bez końca po ukończeniu pracy | Proces harness zakończył się, ale sesja ACP nie zgłosiła ukończenia. | Monitoruj przez ps aux | grep acpx; ręcznie zabij nieaktualne procesy. |