Agenci ACP — konfiguracja

Omówienie, podręcznik operacyjny i pojęcia znajdują się w sekcji agenci ACP.

Ta strona opisuje konfigurację środowiska acpx, konfigurację pluginu dla mostków MCP oraz konfigurację uprawnień.

Tej strony należy używać tylko podczas konfigurowania ścieżki ACP/acpx. Informacje o natywnej konfiguracji środowiska uruchomieniowego app-server Codex znajdują się w sekcji Środowisko Codex. Informacje o kluczach API OpenAI lub konfiguracji dostawcy modeli Codex OAuth znajdują się w sekcji OpenAI.

Codex udostępnia dwie ścieżki OpenClaw:

Należy preferować ścieżkę natywną, chyba że jawnie wymagane jest zachowanie ACP/acpx.

Obsługa środowiska acpx (obecnie)

Wbudowane aliasy środowiska acpx (z przypiętej zależności acpx):

factory-droid i factorydroid również wskazują na wbudowany adapter droid.

Gdy OpenClaw używa backendu acpx, należy preferować te wartości dla agentId, chyba że konfiguracja acpx definiuje niestandardowe aliasy agentów. Jeśli lokalna instalacja Cursor nadal udostępnia ACP jako agent acp, należy zastąpić polecenie agenta cursor w konfiguracji acpx zamiast zmieniać wbudowaną wartość domyślną.

Bezpośrednie użycie CLI acpx może również wskazywać dowolne adaptery za pomocą --agent <command>, ale ten surowy mechanizm obejścia jest funkcją CLI acpx (a nie standardową ścieżką OpenClaw agentId).

Sterowanie modelem zależy od możliwości adaptera. Odwołania do modeli Codex ACP są normalizowane przez OpenClaw przed uruchomieniem. Inne środowiska wymagają obsługi ACP models oraz session/set_model; jeśli środowisko nie udostępnia ani tej funkcji ACP, ani własnej flagi modelu używanej podczas uruchamiania, OpenClaw/acpx nie może wymusić wyboru modelu.

Wymagana konfiguracja

Podstawowa konfiguracja ACP w rdzeniu:

{  acp: {    enabled: true,    // Opcjonalne. Wartość domyślna to true; ustaw false, aby wstrzymać wysyłanie ACP przy zachowaniu kontrolek /acp.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // Wartości domyślne to coalesceIdleMs: 350, maxChunkChars: 1800; pokazano je tutaj jawnie.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

Konfiguracja powiązań wątków zależy od adaptera kanału. Przykład dla Discord:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // Wartość domyślna to już true; pokazano ją tutaj jawnie.        spawnSessions: true,      },    },  },}

Jeśli uruchamianie ACP powiązane z wątkiem nie działa, należy najpierw sprawdzić flagę funkcji adaptera:

• Discord: channels.discord.threadBindings.spawnSessions=true

Powiązania z bieżącą konwersacją nie wymagają utworzenia wątku podrzędnego. Wymagają aktywnego kontekstu konwersacji oraz adaptera kanału udostępniającego powiązania konwersacji ACP.

Zobacz Dokumentację konfiguracji.

Konfiguracja pluginu dla backendu acpx

Instalacje z pakietu używają oficjalnego pluginu środowiska uruchomieniowego @openclaw/acpx dla ACP. Należy go zainstalować i włączyć przed użyciem sesji środowiska ACP:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Kopie robocze kodu źródłowego mogą również używać lokalnego pluginu obszaru roboczego po wykonaniu pnpm install.

Należy rozpocząć od:

/acp doctor

Jeśli wyłączono acpx, odmówiono dostępu za pomocą plugins.allow / plugins.deny lub wymagany jest powrót do pluginu z pakietu, należy użyć jawnej ścieżki pakietu:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Instalacja lokalnego obszaru roboczego podczas programowania:

openclaw plugins install ./path/to/local/acpx-plugin

Następnie należy sprawdzić stan backendu:

/acp doctor

Sonda uruchomienia środowiska acpx

Plugin acpx osadza środowisko uruchomieniowe ACP bezpośrednio (bez oddzielnego pliku binarnego acpx ani wersji do skonfigurowania). Domyślnie rejestruje osadzony backend podczas uruchamiania Gateway i oczekuje na sondę uruchomieniową przed sygnałem gateway ready. Wartości OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 lub OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 należy ustawiać tylko dla skryptów lub środowisk, które celowo utrzymują sondę uruchomieniową jako wyłączoną. Aby jawnie uruchomić sondę na żądanie, należy wykonać /acp doctor.

Polecenie pojedynczego agenta ACP można zastąpić argumentami strukturalnymi, gdy ścieżka lub wartość flagi powinna pozostać jednym tokenem argv:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command to plik wykonywalny lub istniejący ciąg polecenia dla danego agenta ACP.
• agents.<id>.args jest opcjonalne. Każdy element tablicy jest ujmowany w cudzysłowy powłoki, zanim OpenClaw przekaże go przez bieżący rejestr ciągów poleceń acpx.

Zobacz Pluginy.

Automatyczne pobieranie adaptera

acpx automatycznie pobiera adaptery ACP (na przykład mostki ACP Claude i Codex) za pomocą npx przy pierwszym użyciu. Nie trzeba ręcznie instalować pakietów adapterów, a sam OpenClaw nie wymaga oddzielnego kroku poinstalacyjnego. Jeśli pobieranie lub uruchamianie adaptera zakończy się niepowodzeniem, /acp doctor zgłosi błąd.

Mostek MCP narzędzi pluginów

Domyślnie sesje ACPX nie udostępniają środowisku ACP narzędzi zarejestrowanych przez pluginy OpenClaw.

Aby agenci ACP, tacy jak Codex lub Claude Code, mogli wywoływać narzędzia zainstalowanych pluginów OpenClaw, takie jak odczyt i zapis pamięci, należy włączyć dedykowany mostek:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

Działanie:

• Wstrzykuje wbudowany serwer MCP o nazwie openclaw-plugin-tools do inicjalizacji sesji ACPX.
• Udostępnia narzędzia pluginów już zarejestrowane przez zainstalowane i włączone pluginy OpenClaw.
• Przekazuje aktywną tożsamość sesji ACP do fabryk narzędzi pluginów, dzięki czemu narzędzia o zakresie agenta pozostają w przestrzeni nazw tego agenta.
• Zapewnia jawne włączanie funkcji, która jest domyślnie wyłączona.

Uwagi dotyczące bezpieczeństwa i zaufania:

• Rozszerza to zakres narzędzi środowiska ACP.
• Agenci ACP uzyskują dostęp tylko do narzędzi pluginów już aktywnych w gateway.
• Należy traktować to jako tę samą granicę zaufania co zezwolenie tym pluginom na wykonywanie kodu w samym OpenClaw.
• Przed włączeniem należy przejrzeć zainstalowane pluginy.

Niestandardowe mcpServers nadal działają tak jak wcześniej. Wbudowany mostek narzędzi pluginów jest dodatkowym, opcjonalnym udogodnieniem, a nie zamiennikiem ogólnej konfiguracji serwera MCP.

Mostek MCP narzędzi OpenClaw

Domyślnie sesje ACPX nie udostępniają również wbudowanych narzędzi OpenClaw przez MCP. Gdy agent ACP potrzebuje wybranych wbudowanych narzędzi, takich jak cron, należy włączyć oddzielny mostek narzędzi rdzenia:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

Działanie:

• Wstrzykuje wbudowany serwer MCP o nazwie openclaw-tools do inicjalizacji sesji ACPX.
• Udostępnia wybrane wbudowane narzędzia OpenClaw. Początkowa wersja serwera udostępnia cron.
• Zapewnia jawne udostępnianie narzędzi rdzenia, które jest domyślnie wyłączone.

Konfiguracja limitu czasu operacji środowiska uruchomieniowego

Plugin acpx domyślnie przyznaje 120 sekund na uruchomienie osadzonego środowiska uruchomieniowego i operacje sterujące. Dzięki temu wolniejsze środowiska, takie jak Gemini CLI, mają wystarczająco dużo czasu na ukończenie uruchamiania i inicjalizacji ACP. Jeśli host wymaga innego limitu operacji, należy go zastąpić:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

Przebiegi środowiska uruchomieniowego korzystają z limitów czasu agentów/przebiegów OpenClaw, w tym /acp timeout. sessions_spawn nie przyjmuje indywidualnych nadpisań limitu czasu dla poszczególnych wywołań; ścieżką operatora jest agents.defaults.subagents.runTimeoutSeconds. Po zmianie timeoutSeconds należy ponownie uruchomić gateway.

Konfiguracja agenta sondy stanu

Gdy /acp doctor lub sonda uruchomieniowa sprawdza backend, dołączony plugin acpx sonduje jednego agenta środowiska. Jeśli ustawiono acp.allowedAgents, domyślnie wybierany jest pierwszy dozwolony agent; w przeciwnym razie wartością domyślną jest codex. Jeśli wdrożenie wymaga innego agenta ACP do kontroli stanu, należy jawnie ustawić agenta sondy:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Po zmianie tej wartości należy ponownie uruchomić gateway.

Konfiguracja uprawnień

Sesje ACP działają nieinteraktywnie — nie ma TTY umożliwiającego zatwierdzanie lub odrzucanie monitów o uprawnienia do zapisu plików i wykonywania poleceń powłoki. Plugin acpx udostępnia dwa klucze konfiguracji sterujące obsługą uprawnień:

Te uprawnienia mechanizmu ACPX są niezależne od zatwierdzeń wykonywania w OpenClaw oraz od flag dostawców backendów CLI omijających zabezpieczenia, takich jak Claude CLI --permission-mode bypassPermissions. ACPX approve-all to awaryjny przełącznik na poziomie mechanizmu dla sesji ACP.

Szersze porównanie tools.exec.mode w OpenClaw, zatwierdzeń Codex Guardian oraz uprawnień mechanizmu ACPX zawiera sekcja Tryby uprawnień.

permissionMode

Określa, które operacje agent mechanizmu może wykonywać bez wyświetlania monitu.

nonInteractivePermissions

Określa, co się dzieje, gdy powinien zostać wyświetlony monit o uprawnienia, ale interaktywny TTY nie jest dostępny (co zawsze ma miejsce w przypadku sesji ACP).

Konfiguracja

Ustaw za pomocą konfiguracji Pluginu:

openclaw config set plugins.entries.acpx.config.permissionMode approve-allopenclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Po zmianie tych wartości uruchom ponownie Gateway.

Powiązane

• Agenci ACP — przegląd, podręcznik operatora, pojęcia
• Podagenci
• Routing wieloagentowy