Zatwierdzenia wykonywania poleceń

Zatwierdzenia exec są zabezpieczeniem aplikacji towarzyszącej / hosta node, które pozwala agentowi w piaskownicy uruchamiać polecenia na rzeczywistym 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 działają ponad polityką narzędzi i bramkowaniem podwyższonych uprawnień (chyba że podwyższone uprawnienia są ustawione na full, co pomija zatwierdzenia).

# Sprawdzanie efektywnej polityki

Gdy zakres lokalny żąda host=node, exec-policy show zgłasza ten zakres w czasie wykonywania jako zarządzany przez node, 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 awaryjną wartość ask (domyślnie: deny).

# Gdzie ma zastosowanie

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

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

# Model zaufania

• Wywołujący uwierzytelnieni przez Gateway są zaufanymi operatorami tego Gateway.
• Sparowane node rozszerzają tę zdolność zaufanego operatora na host node.
• Zatwierdzenia exec ograniczają ryzyko przypadkowego wykonania, ale nie stanowią granicy uwierzytelniania dla każdego użytkownika.
• Zatwierdzone uruchomienia na hoście node wiążą kanoniczny kontekst wykonania: kanoniczny cwd, dokładny argv, wiązanie env, gdy jest obecne, oraz przypiętą ścieżkę wykonywalną, gdy ma zastosowanie.
• W przypadku skryptów powłoki i bezpośrednich wywołań plików interpretera/środowiska uruchomieniowego OpenClaw próbuje także powiązać jeden konkretny lokalny operand pliku. Jeśli ten powiązany plik zmieni się po zatwierdzeniu, ale przed wykonaniem, uruchomienie zostanie odrzucone zamiast wykonania zmienionej treści.
• Wiązanie plików jest celowo realizowane na zasadzie best-effort, nie jako kompletny model semantyczny każdej ścieżki ładowania interpretera/środowiska uruchomieniowego. Jeśli tryb zatwierdzeń nie może zidentyfikować dokładnie jednego konkretnego lokalnego pliku do powiązania, odmawia utworzenia uruchomienia opartego na zatwierdzeniu, zamiast udawać pełne pokrycie.

# Podział w macOS

• Usługa hosta node przekazuje system.run do aplikacji macOS przez lokalny IPC.
• Aplikacja macOS egzekwuje zatwierdzenia i wykonuje polecenie w kontekście UI.

# Ustawienia i przechowywanie

Zatwierdzenia znajdują się w lokalnym pliku JSON na hoście wykonania:

~/.openclaw/exec-approvals.json

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

# 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ą jawnego zatwierdzenia, a allow-always nie utrwala automatycznie dla nich nowych wpisów listy dozwolonych.

# Tryb YOLO (bez zatwierdzeń)

Jeśli chcesz, aby exec hosta działał bez monitów zatwierdzenia, musisz otworzyć obie warstwy polityki - żądaną politykę exec w konfiguracji OpenClaw (tools.exec.*) oraz lokalną dla hosta politykę zatwierdzeń w ~/.openclaw/exec-approvals.json.

YOLO jest domyślnym zachowaniem hosta, chyba że wyraźnie je zaostrzysz:

Dostawcy oparci na CLI, którzy udostępniają własny nieinteraktywny tryb uprawnień, mogą przestrzegać tej polityki. Claude CLI dodaje --permission-mode bypassPermissions, gdy żądana przez OpenClaw polityka exec to YOLO. Nadpisz to zachowanie backendu jawnymi argumentami Claude pod agents.defaults.cliBackends.claude-cli.args / resumeArgs - na przykład --permission-mode default, acceptEdits lub bypassPermissions.

Jeśli chcesz bardziej konserwatywnej konfiguracji, zaostrz dowolną warstwę z powrotem do allowlist / on-miss albo deny.

# Trwała konfiguracja hosta Gateway „nigdy nie pytaj”

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw 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 ~/.openclaw/exec-approvals.json.

Jest celowo wyłącznie lokalny. Aby zdalnie zmienić zatwierdzenia hosta Gateway lub hosta node, użyj openclaw approvals set --gateway albo openclaw approvals set --node <id|name|ip>.

# Host node

Dla hosta node zastosuj zamiast tego ten sam plik zatwierdzeń na tym node:

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 także pomija zatwierdzenia exec dla tej sesji.

Jeśli plik zatwierdzeń hosta pozostaje bardziej restrykcyjny niż konfiguracja, bardziej restrykcyjna polityka hosta nadal wygrywa.

# Lista dozwolonych (na agenta)

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

Wzorce mogą być globami rozwiązanych ścieżek binarnych albo globami samych nazw poleceń. Same nazwy pasują tylko do poleceń wywołanych przez PATH, więc rg może pasować do /opt/homebrew/bin/rg, gdy polecenie to rg, ale nie do ./rg ani /tmp/rg. Użyj globu ścieżki, gdy chcesz zaufać jednej konkretnej lokalizacji binarnej.

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 powinien pasować do pliku binarnego i konkretnego kształtu argumentów. OpenClaw ocenia wyrażenie regularne względem sparsowanych argumentów polecenia, z wyłączeniem tokenu wykonywalnego (argv[0]). W przypadku ręcznie tworzonych wpisów 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 jest chybieniem listy dozwolonych. Jeśli obecny jest także wpis tylko ze ścieżką dla tego samego pliku binarnego, niedopasowane argumenty nadal mogą 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 dopasowania argv. Preferuj UI lub przepływ zatwierdzania do ponownego wygenerowania tych wpisów zamiast ręcznej edycji zakodowanej wartości. Jeśli OpenClaw nie może sparsować 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 znajdujące się na liście dozwolonych na Node (Node macOS lub bezgłowy host Node). To używa skills.bins przez RPC Gateway do pobrania listy bin Skills. Wyłącz to, jeśli chcesz mieć ścisłe ręczne listy dozwolonych.

# Bezpieczne pliki binarne i przekazywanie zatwierdzeń

Informacje o bezpiecznych plikach binarnych (szybka ścieżka tylko przez stdin), szczegółach wiązania interpretera oraz przekazywaniu monitów zatwierdzania do Slack/Discord/Telegram (albo uruchamianiu ich jako natywnych klientów zatwierdzania) znajdziesz w Zatwierdzenia Exec - zaawansowane.

# Edycja w interfejsie sterowania

Użyj karty Interfejs sterowania → Node → Zatwierdzenia Exec, aby edytować wartości domyślne, nadpisania dla poszczególnych agentów oraz listy dozwolonych. Wybierz zakres (Domyślne lub agent), dostosuj zasady, dodaj/usuń wzorce listy dozwolonych, a następnie Zapisz. UI pokazuje metadane ostatniego użycia dla każdego wzorca, aby ułatwić utrzymanie listy w porządku.

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

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

# Przepływ zatwierdzania

Gdy wymagany jest monit, Gateway rozgłasza exec.approval.requested do klientów operatora. Interfejs sterowania 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 ładunek systemRunPlan. Gateway używa tego planu jako autorytatywnego kontekstu polecenia/cwd/sesji podczas przekazywania zatwierdzonych żądań system.run.

Ma to znaczenie dla opóźnienia zatwierdzania asynchronicznego:

• Ś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 zmianom wywołującego.
• Jeśli wywołujący zmieni command, rawCommand, cwd, agentId lub sessionKey po utworzeniu żądania zatwierdzenia, Gateway odrzuci przekazane uruchomienie jako niezgodność zatwierdzenia.

# Zdarzenia systemowe

Cykl życia Exec jest ujawniany jako komunikaty systemowe:

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

Są one publikowane w sesji agenta po zgłoszeniu zdarzenia przez Node. Zatwierdzenia Exec hostowane przez Gateway emitują te same zdarzenia cyklu życia, gdy polecenie się zakończy (oraz opcjonalnie, gdy działa dłużej niż próg). Polecenia exec objęte zatwierdzeniem ponownie używają identyfikatora zatwierdzenia jako runId w tych komunikatach, aby ułatwić korelację.

# Zachowanie po odmowie zatwierdzenia

Gdy asynchroniczne zatwierdzenie Exec zostanie odrzucone, OpenClaw uniemożliwia agentowi ponowne użycie wyjścia z wcześniejszego uruchomienia tego samego polecenia w sesji. Powód odmowy jest przekazywany z wyraźną wskazówką, że żadne wyjście polecenia nie jest dostępne, co powstrzymuje agenta przed twierdzeniem, że pojawiło się nowe wyjście, lub powtarzaniem odrzuconego polecenia z nieaktualnymi wynikami z poprzedniego udanego uruchomienia.

# Implikacje

• full daje duże możliwości; preferuj listy dozwolonych, gdy to możliwe.
• ask utrzymuje Cię w pętli, nadal pozwalając na szybkie zatwierdzenia.
• Listy dozwolonych dla poszczególnych agentów zapobiegają przenikaniu 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 celowo pomija zatwierdzenia. Aby twardo zablokować exec hosta, ustaw zabezpieczenia zatwierdzeń na deny albo odmów narzędzia exec przez zasady narzędzi.

# Powiązane