Zatwierdzenia wykonywania poleceń

Zatwierdzenia exec są zabezpieczeniem aplikacji towarzyszącej / hosta węzła, które pozwala agentowi w piaskownicy uruchamiać polecenia na prawdziwym hoście (gateway lub node). To blokada bezpieczeństwa: polecenia są dozwolone tylko wtedy, gdy polityka + lista dozwolonych + (opcjonalne) zatwierdzenie użytkownika są zgodne. Zatwierdzenia exec nakładają się na politykę narzędzi i bramkowanie podwyższone (chyba że podwyższenie jest ustawione na full, co pomija zatwierdzenia).

Omówienie trybów deny, allowlist, ask, auto, full, mapowania Codex Guardian oraz uprawnień uprzęży ACPX w ujęciu od trybu znajdziesz w Tryby uprawnień.

Sprawdzanie efektywnej polityki

Gdy zakres lokalny żąda host=node, exec-policy show zgłasza ten zakres w czasie działania jako zarządzany przez węzeł, zamiast udawać, że lokalny plik zatwierdzeń jest źródłem prawdy.

Jeśli interfejs aplikacji towarzyszącej jest niedostępny, każde żądanie, które normalnie wywołałoby monit, jest rozstrzygane przez awaryjny tryb ask (domyślnie: deny).

Gdzie to ma zastosowanie

Zatwierdzenia exec są egzekwowane lokalnie na hoście wykonawczym:

• Host Gateway → proces openclaw na maszynie Gateway.
• Host węzła → uruchamiacz węzła (aplikacja towarzysząca macOS lub bezgłowy host węzła).

Model zaufania

• Wywołujący uwierzytelnieni przez Gateway są zaufanymi operatorami tego Gateway.
• Sparowane węzły rozszerzają tę możliwość zaufanego operatora na host węzła.
• Zatwierdzenia exec zmniejszają ryzyko przypadkowego wykonania, ale nie są granicą uwierzytelniania per użytkownik ani polityką tylko do odczytu systemu plików.
• Po zatwierdzeniu polecenie może modyfikować pliki zgodnie z wybranymi uprawnieniami hosta lub systemu plików piaskownicy.
• Zatwierdzone uruchomienia na hoście węzła wiążą kanoniczny kontekst wykonania: kanoniczny cwd, dokładne argv, wiązanie env, gdy jest obecne, oraz przypiętą ścieżkę pliku wykonywalnego, gdy ma zastosowanie.
• W przypadku skryptów powłoki oraz bezpośrednich wywołań plików interpretera/środowiska uruchomieniowego OpenClaw próbuje też powiązać jeden konkretny lokalny operand plikowy. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem, uruchomienie zostanie odrzucone zamiast wykonywania treści, która uległa zmianie.
• Wiązanie plików jest celowo najlepszym możliwym przybliżeniem, nie kompletnym modelem semantycznym każdej ścieżki ładowania interpretera/środowiska uruchomieniowego. Jeśli tryb zatwierdzania nie może zidentyfikować dokładnie jednego konkretnego lokalnego pliku do powiązania, odmawia wystawienia uruchomienia opartego na zatwierdzeniu, zamiast udawać pełne pokrycie.

Podział macOS

• Usługa hosta węzła przekazuje system.run do aplikacji macOS przez lokalne IPC.
• Aplikacja macOS egzekwuje zatwierdzenia i wykonuje polecenie w kontekście interfejsu użytkownika.

Ustawienia i przechowywanie

Zatwierdzenia znajdują się w lokalnym pliku JSON na hoście wykonawczym. Gdy OPENCLAW_STATE_DIR jest ustawione, plik podąża za tym katalogiem stanu; w przeciwnym razie używa domyślnego katalogu stanu OpenClaw:

$OPENCLAW_STATE_DIR/exec-approvals.json# otherwise~/.openclaw/exec-approvals.json

Domyślne gniazdo zatwierdzeń używa tego samego katalogu głównego: $OPENCLAW_STATE_DIR/exec-approvals.sock albo ~/.openclaw/exec-approvals.sock, gdy zmienna nie jest ustawiona.

Przykładowy schemat:

{  "version": 1,  "socket": {    "path": "~/.openclaw/exec-approvals.sock",    "token": "base64url-token"  },  "defaults": {    "security": "deny",    "ask": "on-miss",    "askFallback": "deny",    "autoAllowSkills": false  },  "agents": {    "main": {      "security": "allowlist",      "ask": "on-miss",      "askFallback": "deny",      "autoAllowSkills": true,      "allowlist": [        {          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",          "pattern": "~/Projects/**/bin/rg",          "source": "allow-always",          "commandText": "rg -n TODO",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

Pokrętła polityki

tools.exec.mode

tools.exec.mode to preferowana znormalizowana powierzchnia polityki dla exec hosta. Wartości to:

• deny - blokuje exec hosta.
• allowlist - uruchamia tylko polecenia z listy dozwolonych bez pytania.
• ask - używa polityki listy dozwolonych i pyta przy chybieniach.
• auto - używa polityki listy dozwolonych, uruchamia deterministyczne dopasowania bezpośrednio i wysyła chybienia zatwierdzeń przez natywnego automatycznego recenzenta OpenClaw przed powrotem do ścieżki zatwierdzenia przez człowieka.
• full - uruchamia exec hosta bez monitów o zatwierdzenie.

Starsze tools.exec.security / tools.exec.ask pozostają obsługiwane i nadal wygrywają, gdy są ustawione w węższym zakresie sesji lub agenta.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Przykłady, które wychwytuje tryb ścisły:

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

W trybie ścisłym te polecenia nadal wymagają wyraźnego zatwierdzenia, a allow-always nie utrwala dla nich automatycznie nowych wpisów listy dozwolonych.

tools.exec.commandHighlighting

To ustawienie nie zmienia security, ask, dopasowywania listy dozwolonych, zachowania ścisłego inline-eval, przekazywania zatwierdzeń ani wykonywania poleceń. Można je ustawić globalnie w tools.exec.commandHighlighting lub dla agenta w agents.list[].tools.exec.commandHighlighting.

Tryb YOLO (bez zatwierdzeń)

Jeśli chcesz, aby exec hosta działał bez monitów o zatwierdzenie, musisz otworzyć obie warstwy polityki - żądaną politykę exec w konfiguracji OpenClaw (tools.exec.*) oraz lokalną dla hosta politykę zatwierdzeń w pliku zatwierdzeń hosta wykonawczego.

OpenClaw domyślnie ustawia pominięte askFallback na deny. Ustaw hostowe askFallback jawnie na full, gdy monit zatwierdzenia bez interfejsu użytkownika ma awaryjnie zezwalać.

Dostawcy wspierani przez CLI, którzy udostępniają własny nieinteraktywny tryb uprawnień, mogą stosować tę politykę. Claude CLI dodaje --permission-mode bypassPermissions, gdy efektywna polityka exec OpenClaw to YOLO. W przypadku sesji live Claude zarządzanych przez OpenClaw efektywna polityka exec OpenClaw jest nadrzędna wobec natywnego trybu uprawnień Claude: YOLO normalizuje uruchomienia live do --permission-mode bypassPermissions, a restrykcyjna efektywna polityka exec normalizuje uruchomienia live do --permission-mode default, nawet jeśli surowe argumenty backendu Claude określają inny tryb.

Jeśli chcesz bardziej konserwatywnej konfiguracji, zaostrz politykę exec OpenClaw z powrotem do allowlist / on-miss albo deny.

Trwała konfiguracja hosta Gateway „nigdy nie pytaj”

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

openclaw approvals set --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Lokalny skrót

openclaw exec-policy preset yolo

Ten lokalny skrót aktualizuje oba elementy:

• Lokalne tools.exec.host/security/ask.
• Domyślne wartości lokalnego pliku zatwierdzeń, w tym askFallback: "full".

Jest on celowo tylko lokalny. Aby zdalnie zmienić zatwierdzenia hosta Gateway lub hosta węzła, użyj openclaw approvals set --gateway albo openclaw approvals set --node <id|name|ip>.

Host węzła

Dla hosta węzła zastosuj zamiast tego ten sam plik zatwierdzeń na tym węźle:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Skrót tylko dla sesji

• /exec security=full ask=off zmienia tylko bieżącą sesję.
• /elevated full to awaryjny skrót, który pomija zatwierdzenia exec tylko wtedy, gdy zarówno żądana polityka, jak i plik zatwierdzeń hosta rozpoznają się jako security: "full" i ask: "off". Surowszy plik hosta, taki jak ask: "always", nadal wyświetla monit.

Jeśli plik zatwierdzeń hosta pozostaje surowszy niż konfiguracja, surowsza polityka hosta nadal wygrywa.

Lista dozwolonych (na agenta)

Listy dozwolonych są na agenta. Jeśli istnieje wielu agentów, przełącz w aplikacji macOS, którego agenta edytujesz. Wzorce są dopasowaniami glob.

Wzorce mogą być globami rozpoznanych ścieżek binarnych albo gołymi globami nazw poleceń. Gołe nazwy pasują tylko do poleceń wywoływanych przez PATH, więc rg może pasować do /opt/homebrew/bin/rg, gdy poleceniem jest rg, ale nie do ./rg ani /tmp/rg. Użyj globu ścieżki, gdy chcesz zaufać jednej konkretnej lokalizacji pliku binarnego.

Starsze wpisy agents.default są migrowane do agents.main podczas ładowania. Łańcuchy powłoki, takie jak echo ok && pwd, nadal wymagają, aby każdy segment najwyższego poziomu spełniał reguły listy dozwolonych.

Przykłady:

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Ograniczanie argumentów za pomocą argPattern

Dodaj argPattern, gdy wpis listy dozwolonych ma pasować do pliku binarnego i konkretnego kształtu argumentów. OpenClaw ocenia wyrażenie regularne względem przeanalizowanych argumentów polecenia, z wyłączeniem tokenu wykonywalnego (argv[0]). W przypadku wpisów pisanych ręcznie argumenty są łączone pojedynczą spacją, więc zakotwicz wzorzec, gdy potrzebujesz dokładnego dopasowania.

{  "version": 1,  "agents": {    "main": {      "allowlist": [        {          "pattern": "python3",          "argPattern": "^safe\\.py$"        }      ]    }  }}

Ten wpis zezwala na python3 safe.py; python3 other.py nie trafia w listę dozwolonych. Jeśli istnieje też wpis tylko ze ścieżką dla tego samego pliku binarnego, niedopasowane argumenty mogą nadal wrócić do tego wpisu tylko ze ścieżką. Pomiń wpis tylko ze ścieżką, gdy celem jest ograniczenie pliku binarnego do zadeklarowanych argumentów.

Wpisy zapisane przez przepływy zatwierdzania mogą używać wewnętrznego formatu separatora do dokładnego dopasowywania argv. Preferuj UI albo przepływ zatwierdzania, aby ponownie wygenerować te wpisy, zamiast ręcznie edytować zakodowaną wartość. Jeśli OpenClaw nie może przeanalizować argv dla segmentu polecenia, wpisy z argPattern nie pasują.

Każdy wpis listy dozwolonych obsługuje:

Automatyczne zezwalanie na CLI Skills

Gdy Automatyczne zezwalanie na CLI Skills jest włączone, pliki wykonywalne wskazywane przez znane Skills są traktowane jako dozwolone na Node (Node macOS albo bezgłowy host Node). Używa to skills.bins przez Gateway RPC, aby pobrać listę binariów Skills. Wyłącz to, jeśli chcesz mieć ściśle ręczne listy dozwolonych.

Bezpieczne binaria i przekazywanie zatwierdzeń

Informacje o bezpiecznych binariach (szybka ścieżka tylko przez stdin), szczegółach wiązania interpreterów oraz o tym, jak przekazywać monity zatwierdzeń do Slack/Discord/Telegram (albo uruchamiać je jako natywnych klientów zatwierdzeń), znajdziesz w Zatwierdzenia exec - zaawansowane.

Edytowanie w Control UI

Użyj karty Control UI → Node → Zatwierdzenia exec, aby edytować wartości domyślne, nadpisania na agenta i listy dozwolonych. Wybierz zakres (Domyślne albo agent), dostosuj politykę, dodaj/usuń wzorce listy dozwolonych, a potem wybierz Zapisz. UI pokazuje metadane ostatniego użycia dla każdego wzorca, aby można było utrzymać listę w porządku.

Selektor celu wybiera Gateway (zatwierdzenia lokalne) albo Node. Node muszą ogłaszać system.execApprovals.get/set (aplikacja macOS albo bezgłowy host Node). Jeśli Node jeszcze nie ogłasza zatwierdzeń exec, edytuj bezpośrednio jego lokalny plik zatwierdzeń.

CLI: openclaw approvals obsługuje edytowanie Gateway albo Node - zobacz CLI zatwierdzeń.

Przepływ zatwierdzania

Gdy wymagany jest monit, Gateway rozgłasza exec.approval.requested do klientów operatora. Control UI i aplikacja macOS rozwiązują go przez exec.approval.resolve, a następnie Gateway przekazuje zatwierdzone żądanie do hosta Node.

Dla host=node żądania zatwierdzenia zawierają kanoniczny payload systemRunPlan. Gateway używa tego planu jako autorytatywnego kontekstu command/cwd/session podczas przekazywania zatwierdzonych żądań system.run.

Ma to znaczenie dla opóźnień zatwierdzeń asynchronicznych:

• Ścieżka exec Node przygotowuje z góry jeden kanoniczny plan.
• Rekord zatwierdzenia przechowuje ten plan i jego metadane wiązania.
• Po zatwierdzeniu końcowe przekazane wywołanie system.run ponownie używa zapisanego planu, zamiast ufać późniejszym edycjom wywołującego.
• Jeśli wywołujący zmieni command, rawCommand, cwd, agentId albo sessionKey po utworzeniu żądania zatwierdzenia, Gateway odrzuca przekazane uruchomienie jako niezgodność zatwierdzenia.

Zdarzenia systemowe

Cykl życia exec jest pokazywany jako komunikaty systemowe:

• Exec running (tylko jeśli polecenie przekroczy próg powiadomienia o działaniu).
• Exec finished.

Są one publikowane w sesji agenta po zgłoszeniu zdarzenia przez Node. Odmówione zatwierdzenia exec są terminalne dla samego polecenia hosta: polecenie nie zostaje uruchomione. W przypadku asynchronicznych zatwierdzeń głównego agenta z sesją źródłową OpenClaw publikuje odmowę z powrotem do tej sesji jako wewnętrzną kontynuację, aby agent mógł przestać czekać na polecenie asynchroniczne i uniknąć naprawy brakującego wyniku. Jeśli nie ma sesji albo sesji nie można wznowić, OpenClaw nadal może zgłosić zwięzłą odmowę operatorowi albo bezpośredniej trasie czatu. Odmowy dla sesji subagentów nie są publikowane z powrotem do subagenta. Zatwierdzenia exec hostowane przez Gateway emitują te same zdarzenia cyklu życia, gdy polecenie się kończy (i opcjonalnie, gdy działa dłużej niż próg). Exec ograniczone zatwierdzeniem ponownie używają id zatwierdzenia jako runId w tych komunikatach, aby ułatwić korelację.

Zachowanie przy odmowie zatwierdzenia

Gdy asynchroniczne zatwierdzenie exec zostanie odmówione, OpenClaw traktuje polecenie hosta jako terminalne i zamknięte odmową. W sesjach głównego agenta odmowa jest dostarczana jako wewnętrzna kontynuacja sesji, która mówi agentowi, że polecenie asynchroniczne nie zostało uruchomione. Zachowuje to ciągłość transkryptu bez ujawniania nieaktualnego wyjścia polecenia. Jeśli dostarczenie do sesji jest niedostępne, OpenClaw wraca do zwięzłej odmowy dla operatora albo bezpośredniego czatu, gdy istnieje bezpieczna trasa.

Implikacje

• full jest potężne; preferuj listy dozwolonych, gdy to możliwe.
• ask utrzymuje cię w obiegu, a jednocześnie pozwala na szybkie zatwierdzenia.
• Listy dozwolonych na agenta zapobiegają przeciekaniu zatwierdzeń jednego agenta do innych.
• Zatwierdzenia dotyczą tylko żądań exec hosta od autoryzowanych nadawców. Nieautoryzowani nadawcy nie mogą wywołać /exec.
• /exec security=full to wygoda na poziomie sesji dla autoryzowanych operatorów i z założenia pomija zatwierdzenia. Aby twardo zablokować exec hosta, ustaw zabezpieczenia zatwierdzeń na deny albo odmów narzędzia exec przez politykę narzędzi.

Powiązane