Agenci ACP
Sesje Agent Client Protocol (ACP) pozwalają OpenClaw uruchamiać zewnętrzne harnessy programistyczne (na przykład Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI i inne obsługiwane harnessy ACPX) przez plugin backendu ACP. Jeśli poprosisz OpenClaw prostym 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 sub-agent). Każde uruchomienie sesji ACP jest śledzone jako zadanie w tle. Jeśli chcesz, aby Codex lub Claude Code łączyły się bezpośrednio jako zewnętrzny klient MCP z istniejącymi rozmowami na kanałach OpenClaw, użyjopenclaw mcp serve zamiast ACP.
Której strony potrzebuję?
W pobliżu są trzy 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ę Gateway OpenClaw jako serwer ACP dla edytora lub klienta | openclaw acp | Tryb mostu. IDE/klient rozmawia z OpenClaw przez ACP po stdio/WebSocket |
| Użyć lokalnego CLI AI jako tekstowego modelu zapasowego | Backendy CLI | 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 dostarczają bundled plugin runtime
acpxdomyślnie włączony. - Bundled plugin
acpxpreferuje własną, przypiętą lokalnie binarkęacpx. - Przy starcie OpenClaw sonduje tę binarkę i sam się naprawia, jeśli to konieczne.
- Zacznij od
/acp doctor, jeśli chcesz szybko sprawdzić gotowość.
- Adapter docelowego harnessu może zostać pobrany na żądanie przez
npxprzy pierwszym użyciu tego harnessu. - Uwierzytelnianie dostawcy nadal musi istnieć na hoście dla tego harnessu.
- Jeśli host nie ma dostępu do npm/sieci, pobieranie adaptera przy pierwszym uruchomieniu może się nie powieść, dopóki cache nie zostanie rozgrzany albo adapter nie zostanie zainstalowany inną drogą.
/acp spawn codex: OpenClaw powinien być gotowy do bootstrapowaniaacpx, ale adapter ACP Codex może nadal wymagać pobrania przy pierwszym uruchomieniu./acp spawn claude: podobna sytuacja dla adaptera Claude ACP, plus uwierzytelnienie po stronie Claude na tym hoście.
Szybki przepływ operatora
Użyj tego, jeśli chcesz praktycznego runbooka/acp:
- Uruchom sesję:
/acp spawn codex --bind here/acp spawn codex --mode persistent --thread auto
- Pracuj w powiązanej rozmowie lub wątku (albo jawnie kieruj do tego klucza sesji).
- Sprawdź stan runtime:
/acp status
- W razie potrzeby dostrój opcje runtime:
/acp model <provider/model>/acp permissions <profile>/acp timeout <seconds>
- Szturchnij 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ę + 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 skupienie.”
- „Uruchom to jako jednorazową sesję Claude Code ACP i podsumuj wynik.”
- „Powiąż ten czat iMessage z Codex i utrzymuj kolejne wiadomości w tym samym workspace.”
- „Użyj Gemini CLI do tego zadania w wątku, a potem utrzymuj dalsze wiadomości w tym samym wątku.”
- Wybrać
runtime: "acp". - Rozwiązać żądany cel harnessu (
agentId, na przykładcodex). - Jeśli żądane jest powiązanie z bieżącą rozmową i aktywny kanał to obsługuje, powiązać sesję ACP z tą rozmową.
- W przeciwnym razie, jeśli żądane jest powiązanie z wątkiem i bieżący kanał to obsługuje, powiązać sesję ACP z wątkiem.
- Kierować dalsze powiązane wiadomości do tej samej sesji ACP aż do rozogniskowania / zamknięcia / wygaśnięcia.
ACP kontra sub-agenci
Używaj ACP, gdy chcesz zewnętrznego runtime harnessu. Używaj sub-agentów, gdy chcesz delegowanych przebiegów natywnych dla OpenClaw.| Obszar | Sesja ACP | Przebieg sub-agent |
|---|---|---|
| Runtime | Plugin backendu ACP (np. acpx) | Natywny runtime sub-agent 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
Dla Claude Code przez ACP stos wygląda następująco:- Control plane sesji ACP OpenClaw
- Bundled plugin runtime
acpx - Adapter Claude ACP
- Runtime / mechanika sesji po stronie Claude
- Claude przez ACP to nie to samo co bezpośredni runtime zapasowy
claude-cli/.... - Claude przez ACP to sesja harnessu z kontrolkami ACP, wznawianiem sesji, śledzeniem zadań w tle i opcjonalnym powiązaniem z rozmową/wątkiem.
claude-cli/...to tekstowy lokalny backend CLI. Zobacz Backendy CLI.
- chcesz
/acp spawn, sesje możliwe do powiązania, kontrolki runtime albo trwałą pracę harnessu: użyj ACP - chcesz prostego lokalnego fallbacku tekstowego przez surowe CLI: użyj backendów CLI
Sesje powiązane
Powiązania z bieżącą rozmową
Użyj/acp spawn <harness> --bind here, gdy chcesz, aby bieżąca rozmowa stała się trwałym workspace 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.
- Dalsze wiadomości w tej rozmowie są kierowane do tej samej sesji ACP.
/newi/resetresetują tę samą powiązaną sesję ACP in-place./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 heremoże nadal utworzyć nową sesję ACP, jeśli uruchamiasz świeżą pracę. Powiązanie dołącza tę sesję do bieżącej rozmowy.--bind heresamo z siebie nie tworzy podrzędnego wątku Discord ani tematu Telegram.- Runtime ACP może nadal mieć własny katalog roboczy (
cwd) albo workspace zarządzany przez backend na dysku. Ten workspace runtime jest oddzielny od powierzchni czatu i nie oznacza nowego wątku wiadomości. - Jeśli uruchamiasz do innego agenta ACP i nie podasz
--cwd, OpenClaw domyślnie dziedziczy workspace docelowego agenta, a nie workspace osoby wywołującej. - Jeśli ta odziedziczona ścieżka workspace nie istnieje (
ENOENT/ENOTDIR), OpenClaw wraca do domyślnegocwdbackendu zamiast po cichu użyć niewłaściwego drzewa. - Jeśli odziedziczony workspace istnieje, ale nie można uzyskać do niego dostępu (na przykład
EACCES), uruchomienie zwraca rzeczywisty błąd dostępu zamiast pomijaćcwd.
- powierzchnia czatu: miejsce, gdzie ludzie dalej rozmawiają (
kanał Discord,temat Telegram,czat iMessage) - sesja ACP: trwały stan runtime Codex/Claude/Gemini, do którego OpenClaw kieruje ruch
- podrzędny wątek/temat: opcjonalna dodatkowa powierzchnia wiadomości tworzona tylko przez
--thread ... - workspace runtime: lokalizacja systemu plików, w której działa harness (
cwd, checkout repo, workspace backendu)
/acp spawn codex --bind here: zachowaj ten czat, uruchom lub podłą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 powiązać tam 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 reklamują obsługę powiązań ACP z bieżącą rozmową, mogą używać
--bind hereprzez współdzieloną ścieżkę powiązania rozmowy. - Kanały z własną semantyką wątków/tematów mogą nadal dostarczać specyficzną dla kanału kanonikalizację za tą samą współdzieloną warstwą.
--bind herezawsze oznacza „powiąż bieżącą rozmowę in-place”.- 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 in-place.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ć wiązane z wątkami:- OpenClaw wiąże wątek z docelową sesją ACP.
- Dalsze wiadomości w tym wątku są kierowane do powiązanej sesji ACP.
- Wyjście ACP jest dostarczane z powrotem do tego samego wątku.
- Rozogniskowanie / zamknięcie / archiwizacja / timeout bezczynności lub wygaśnięcie 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 specyficzna dla adaptera kanału
- 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ść wiązania sesji/wątków.
- Obecnie wbudowana obsługa:
- Wątki/kanały Discord
- Tematy Telegram (forum topics w grupach/supergrupach i tematy DM)
- Kanały pluginów mogą dodawać obsługę przez ten sam interfejs wiązania.
Ustawienia specyficzne dla kanału
Dla workflowów nieefemerycznych skonfiguruj trwałe powiązania ACP w najwyższego poziomu wpisachbindings[].
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:*>"Preferujchat_id:*albochat_identifier:*dla stabilnych powiązań grupowych. - Czat DM/grupowy iMessage:
match.channel="imessage"+match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"Preferujchat_id:*dla stabilnych powiązań grupowych.
- Kanał lub wątek Discord:
bindings[].agentIdto identyfikator właściciela agenta OpenClaw.- Opcjonalne nadpisania ACP znajdują się pod
bindings[].acp:mode(persistentalbooneshot)labelcwdbackend
Domyślne ustawienia runtime per agent
Użyjagents.list[].runtime, aby raz zdefiniować domyślne ustawienia ACP per agent:
agents.list[].runtime.type="acp"agents.list[].runtime.acp.agent(identyfikator harnessu, na przykładcodexalboclaude)agents.list[].runtime.acp.backendagents.list[].runtime.acp.modeagents.list[].runtime.acp.cwd
bindings[].acp.*agents.list[].runtime.acp.*- globalne wartości domyślne ACP (na przykład
acp.backend)
- OpenClaw upewnia się, że skonfigurowana sesja ACP istnieje 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 in-place. - Tymczasowe powiązania runtime (na przykład tworzone przez przepływy fokusowania wątku) nadal obowiązują, gdy są obecne.
- Dla uruchomień ACP między agentami bez jawnego
cwdOpenClaw dziedziczy workspace docelowego agenta z konfiguracji agenta. - Brakujące odziedziczone ścieżki workspace wracają do domyślnego
cwdbackendu; niebrakujące 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 albo wywołania narzędzia.
runtimedomyślnie ma wartośćsubagent, więc ustawruntime: "acp"jawnie dla sesji ACP.- Jeśli pominięto
agentId, OpenClaw używaacp.defaultAgent, gdy 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 harnessu ACP. Wraca doacp.defaultAgent, jeśli ustawiono.thread(opcjonalne, domyślniefalse): żądanie przepływu powiązania z wątkiem tam, gdzie jest obsługiwane.mode(opcjonalne):run(jednorazowe) albosession(trwałe).- domyślnie
run - jeśli
thread: true, a mode pominięto, OpenClaw może domyślnie użyć zachowania trwałego zależnie od ścieżki runtime mode: "session"wymagathread: true
- domyślnie
cwd(opcjonalne): żądany katalog roboczy runtime (walidowany przez politykę backendu/runtime). Jeśli pominięto, uruchomienie ACP dziedziczy workspace docelowego agenta, gdy jest skonfigurowane; brakujące odziedziczone ścieżki wracają do wartości domyślnych backendu, a rzeczywiste błędy dostępu są zwracane.label(opcjonalne): etykieta widoczna dla operatora, używana w tekście sesji/baneru.resumeSessionId(opcjonalne): wznowienie istniejącej sesji ACP zamiast tworzenia nowej. Agent odtwarza historię rozmowy przezsession/load. Wymagaruntime: "acp".streamTo(opcjonalne):"parent"przesyła podsumowania postępu początkowego przebiegu ACP z powrotem do sesji żądającej jako zdarzenia systemowe.- Gdy dostępne, akceptowane odpowiedzi zawierają
streamLogPathwskazujące plik JSONL o zakresie sesji (<sessionId>.acp-stream.jsonl), który można śledzić dla pełnej historii przekazywania.
- Gdy dostępne, akceptowane odpowiedzi zawierają
Wznawianie istniejącej sesji
UżyjresumeSessionId, aby kontynuować wcześniejszą sesję ACP zamiast zaczynać od zera. 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 — powiedz agentowi, żeby podjął pracę tam, gdzie skończyłeś
- Kontynuowanie sesji programistycznej rozpoczętej interaktywnie w CLI, teraz w trybie headless przez agenta
- Podjęcie pracy przerwanej przez restart gateway albo timeout bezczynności
resumeSessionIdwymagaruntime: "acp"— zwraca błąd, jeśli zostanie użyte z runtime sub-agent.resumeSessionIdprzywraca historię rozmowy upstream ACP;threadimodenadal działają normalnie dla 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 nie znaleziono identyfikatora sesji, uruchomienie kończy się czytelnym błędem — bez cichego fallbacku do nowej sesji.
Smoke test operatora
Użyj tego po wdrożeniu gateway, gdy chcesz szybko sprawdzić na żywo, że uruchamianie ACP rzeczywiście 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ę mostu 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 raportuje:
accepted=yes- rzeczywiste
childSessionKey - brak błędu walidatora
- Posprzątaj tymczasową sesję mostu ACPX.
- Zachowaj ten smoke test przy
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 sesji osoby żądającej i jest osobnym testem integracyjnym. - Traktuj testy
mode: "session"powiązane z wątkiem jako drugi, bogatszy przebieg integracyjny z prawdziwego wątku Discord albo tematu Telegram.
Zgodność z sandboxem
Sesje ACP obecnie działają w runtime hosta, a nie wewnątrz sandboxa OpenClaw. Obecne ograniczenia:- Jeśli sesja żądająca jest sandboxowana, uruchomienia ACP są 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, aby w razie potrzeby jawnie sterować z poziomu operatora z czatu.
--mode persistent|oneshot--bind here|off--thread auto|here|off--cwd <absolute-path>--label <name>
Rozwiązywanie celu sesji
Większość akcji/acp akceptuje opcjonalny cel sesji (session-key, session-id albo session-label).
Kolejność rozwiązywania:
- Jawny argument celu (albo
--sessiondla/acp steer)- najpierw próba jako key
- potem jako session id w kształcie UUID
- potem jako label
- Bieżące powiązanie z wątkiem (jeśli ta rozmowa / ten wątek są powiązane z sesją ACP)
- Fallback do bieżącej sesji żądającej
Unable to resolve session target: ...).
Tryby powiązań przy uruchamianiu
/acp spawn obsługuje --bind here|off.
| Tryb | Zachowanie |
|---|---|
here | Powiąż bieżącą aktywną rozmowę in-place; zakończ błędem, jeśli nie ma aktywnej. |
off | Nie twórz powiązania z bieżącą rozmową. |
--bind hereto najprostsza ścieżka operatora dla „niech ten kanał albo czat będzie oparty na Codex”.--bind herenie tworzy podrzędnego wątku.--bind herejest dostępne tylko na kanałach udostępniających obsługę powiązań 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 startuje bez powiązania. |
- Na powierzchniach bez obsługi powiązań z wątkiem domyślne zachowanie jest w praktyce
off. - Uruchamianie powiązane z wątkiem wymaga obsługi przez politykę kanału:
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true - Telegram:
channels.telegram.threadBindings.spawnAcpSessions=true
- Discord:
- Użyj
--bind here, gdy 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 oraz, gdy są dostępne, identyfikatory sesji na poziomie runtime i backendu.
Niektóre kontrolki zależą od możliwości backendu. Jeśli backend nie obsługuje danej kontrolki, OpenClaw zwraca czytelny błąd unsupported-control.
Książka kucharska poleceń ACP
| Polecenie | Co robi | Przykład |
|---|---|---|
/acp spawn | Tworzy sesję ACP; opcjonalne powiązanie z bieżącą rozmową lub wątkiem. | /acp spawn codex --bind here --cwd /repo |
/acp cancel | Anuluje turę in-flight dla docelowej sesji. | /acp cancel agent:codex:acp:<uuid> |
/acp steer | Wysyła instrukcję steer do działającej sesji. | /acp steer --session support inbox prioritize failing tests |
/acp close | Zamyka sesję i odwiązuje 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 timeout 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 ze store. | /acp sessions |
/acp doctor | Zdrowie backendu, możliwości, konkretne poprawki. | /acp doctor |
/acp install | Wypisuje deterministyczne kroki instalacji i włączenia. | /acp install |
/acp sessions odczytuje store dla bieżącej powiązanej sesji albo sesji żądającej. Polecenia, które akceptują tokeny session-key, session-id albo session-label, rozwiązują cele przez wykrywanie sesji gateway, w tym własne katalogi session.store per agent.
Mapowanie opcji runtime
/acp ma polecenia wygodne i ogólny setter.
Równoważne operacje:
/acp model <id>mapuje na klucz konfiguracji runtimemodel./acp permissions <profile>mapuje na klucz konfiguracji runtimeapproval_policy./acp timeout <seconds>mapuje na klucz konfiguracji runtimetimeout./acp cwd <path>bezpośrednio aktualizuje nadpisanie cwd runtime./acp set <key> <value>to ścieżka ogólna.- Szczególny przypadek:
key=cwdużywa ścieżki nadpisania cwd.
- Szczególny przypadek:
/acp reset-optionsczyści wszystkie nadpisania runtime dla docelowej sesji.
Obsługa harnessów acpx (obecnie)
Obecne wbudowane aliasy harnessów acpx:claudecodexcopilotcursor(Cursor CLI:cursor-agent acp)droidgeminiiflowkilocodekimikiroopenclawopencodepiqwen
agentId, chyba że Twoja 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 też kierować do dowolnych adapterów przez --agent <command>, ale ta surowa furtka jest funkcją CLI acpx (a nie normalną ścieżką agentId w OpenClaw).
Wymagana konfiguracja
Bazowa konfiguracja ACP core:- Discord:
channels.discord.threadBindings.spawnAcpSessions=true
Konfiguracja pluginu dla backendu acpx
Świeże instalacje dostarczają bundled plugin runtimeacpx domyślnie włączony, 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 developerski, użyj jawnej ścieżki pluginu:
Konfiguracja polecenia i wersji acpx
Domyślnie bundled plugin backendu acpx (acpx) używa przypiętej lokalnej binarki pluginu:
- Polecenie domyślnie wskazuje plugin-local
node_modules/.bin/acpxwewnątrz pakietu pluginu ACPX. - Oczekiwana wersja domyślnie odpowiada przypięciu rozszerzenia.
- Startup rejestruje backend ACP natychmiast jako not-ready.
- Zadanie ensure w tle weryfikuje
acpx --version. - Jeśli lokalna binarka pluginu brakuje albo wersja się nie zgadza, uruchamia:
npm install --omit=dev --no-save acpx@<pinned>i ponownie weryfikuje.
commandakceptuje ścieżkę bezwzględną, względną albo nazwę polecenia (acpx).- Ścieżki względne są rozwiązywane względem katalogu workspace OpenClaw.
expectedVersion: "any"wyłącza ścisłe dopasowanie wersji.- Gdy
commandwskazuje własną binarkę / ścieżkę, automatyczna instalacja lokalna pluginu jest wyłączona. - Startup OpenClaw pozostaje nieblokujący, gdy działa kontrola zdrowia backendu.
Automatyczna instalacja zależności
Gdy instalujesz OpenClaw globalnie przeznpm install -g openclaw, zależności runtime acpx
(binarki specyficzne dla platformy) są instalowane automatycznie
przez hook postinstall. Jeśli instalacja automatyczna się nie powiedzie, gateway nadal uruchamia się
normalnie i raportuje brakującą zależność przez openclaw acp doctor.
Most MCP dla narzędzi pluginów
Domyślnie sesje ACPX nie udostępniają zarejestrowanych w pluginach narzędzi OpenClaw do harnessu 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.
- Utrzymuje tę funkcję jako jawną i domyślnie wyłączoną.
- To rozszerza powierzchnię narzędzi harnessu 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 kodu w samym OpenClaw.
- Przed włączeniem sprawdź zainstalowane pluginy.
mcpServers nadal działają jak wcześniej. Wbudowany most plugin-tools to
dodatkowa wygoda typu opt-in, a nie zamiennik ogólnej konfiguracji serwera MCP.
Konfiguracja uprawnień
Sesje ACP działają nieinteraktywnie — nie ma TTY do zatwierdzania albo odrzucania promptów uprawnień zapisu plików i wykonania shella. Plugin acpx udostępnia dwa klucze konfiguracyjne kontrolujące sposób obsługi uprawnień: Te uprawnienia harnessu ACPX są oddzielone od zatwierdzeń exec OpenClaw i od flag obejścia dostawcy w backendach CLI, takich jak Claude CLI--permission-mode bypassPermissions. ACPX approve-all to przełącznik awaryjny na poziomie harnessu dla sesji ACP.
permissionMode
Steruje tym, które operacje agent harnessu może wykonywać bez promptu.
| Wartość | Zachowanie |
|---|---|
approve-all | Automatycznie zatwierdza wszystkie zapisy plików i polecenia shell. |
approve-reads | Automatycznie zatwierdza tylko odczyty; zapis i exec wymagają promptów. |
deny-all | Odrzuca wszystkie prompty uprawnień. |
nonInteractivePermissions
Steruje tym, co się dzieje, gdy prompt uprawnień miałby zostać pokazany, ale nie ma dostępnego interaktywnego TTY (co zawsze ma miejsce dla sesji ACP).
| Wartość | Zachowanie |
|---|---|
fail | Przerywa sesję z AcpRuntimeError. (domyślnie) |
deny | Po cichu odrzuca uprawnienie i kontynuuje (łagodne pogorszenie działania). |
Konfiguracja
Ustaw przez konfigurację pluginu:Ważne: OpenClaw obecnie domyślnie używapermissionMode=approve-readsinonInteractivePermissions=fail. W nieinteraktywnych sesjach ACP każdy zapis albo exec wywołujący prompt uprawnień może zakończyć się błędemAcpRuntimeError: Permission prompt unavailable in non-interactive mode. Jeśli chcesz ograniczyć uprawnienia, ustawnonInteractivePermissionsnadeny, aby sesje degradowały się łagodnie zamiast się wywracać.
Rozwiązywanie problemów
| Objaw | Prawdopodobna przyczyna | Poprawka |
|---|---|---|
ACP runtime backend is not configured | Brakuje 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ątku jest wyłączony. | Ustaw acp.dispatch.enabled=true. |
ACP agent "<id>" is not allowed by policy | Agent nie znajduje się na allowliście. | Użyj dozwolonego agentId albo zaktualizuj acp.allowedAgents. |
Unable to resolve session target: ... | Nieprawidłowy token key/id/label. | Uruchom /acp sessions, skopiuj dokładny key/label i spróbuj ponownie. |
--bind here requires running /acp spawn inside an active ... conversation | --bind here użyto bez aktywnej rozmowy możliwej do powiązania. | 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ązań ACP z bieżącą rozmową. | Użyj /acp spawn ... --thread ..., jeśli jest obsługiwane, skonfiguruj najwyższego poziomu bindings[] albo przejdź do obsługiwanego kanału. |
--thread here requires running /acp spawn inside an active ... thread | --thread here użyto 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. | Przepnij 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ązań z wątkiem. | 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 sandboxowanych sesji albo uruchom 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 sandboxingu albo ACP z sandbox="inherit" z sesji niesandboxowanej. |
| Missing ACP metadata for bound session | Przestarzałe/usunięte metadane sesji ACP. | Utwórz ponownie przez /acp spawn, a następnie ponownie powiąż / ustaw fokus na 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 Konfigurację uprawnień. |
| ACP session fails early with little output | 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. |
| ACP session stalls indefinitely after completing work | Proces harnessu zakończył się, ale sesja ACP nie zgłosiła zakończenia. | Monitoruj przez ps aux | grep acpx; ręcznie zabij zaległe procesy. |