OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Piaskownica a zasady narzędzi a tryb podwyższonych uprawnień

Status: active

OpenClaw ma trzy powiązane, ale różne mechanizmy sterowania:

  1. Piaskownica (agents.defaults.sandbox.* / agents.list[].sandbox.*) określa, gdzie uruchamiane są narzędzia (backend piaskownicy lub host).
  2. Zasady narzędzi (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) określają, które narzędzia są dostępne/dozwolone.
  3. Tryb podwyższonych uprawnień (tools.elevated.*, agents.list[].tools.elevated.*) to wyjście awaryjne wyłącznie dla exec, umożliwiające uruchamianie poza piaskownicą, gdy sesja działa w piaskownicy (domyślnie gateway lub node, gdy cel wykonywania skonfigurowano jako node).

Szybkie debugowanie

Użyj inspektora, aby sprawdzić, co OpenClaw faktycznie robi:

bash
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Wyświetla on:

  • efektywny tryb i zakres piaskownicy oraz dostęp do obszaru roboczego
  • informację, czy bieżąca sesja działa w piaskownicy (główna lub inna niż główna)
  • efektywne zezwolenia i blokady narzędzi w piaskownicy (oraz informację, czy pochodzą z ustawień agenta, globalnych czy domyślnych)
  • warunki trybu podwyższonych uprawnień i ścieżki kluczy wymagających poprawy

Piaskownica: gdzie uruchamiane są narzędzia

Działaniem piaskownicy steruje agents.defaults.sandbox.mode:

  • "off": wszystko działa na hoście.
  • "non-main": tylko sesje inne niż główna działają w piaskownicy (częste „zaskoczenie” w przypadku grup/kanałów).
  • "all": wszystko działa w piaskownicy.

agents.defaults.sandbox.workspaceAccess określa, co piaskownica może zobaczyć: "none", "ro" lub "rw".

Pełną macierz (zakres, montowania obszaru roboczego, obrazy) zawiera sekcja Piaskownica.

Montowania wiązane (szybka kontrola bezpieczeństwa)

  • docker.binds przebija system plików piaskownicy: wszystko, co zamontujesz, jest widoczne wewnątrz kontenera w ustawionym trybie (:ro lub :rw).
  • Jeśli pominiesz tryb, domyślnie obowiązuje odczyt i zapis; w przypadku kodu źródłowego/danych poufnych preferuj :ro.
  • scope: "shared" ignoruje montowania poszczególnych agentów (obowiązują tylko montowania globalne).
  • OpenClaw dwukrotnie sprawdza źródła montowań: najpierw znormalizowaną ścieżkę źródłową, a następnie ponownie po jej rozwiązaniu przez najgłębszy istniejący katalog nadrzędny. Ucieczki przez dowiązania symboliczne katalogów nadrzędnych nie omijają kontroli zablokowanych ścieżek ani dozwolonych katalogów głównych.
  • Nieistniejące ścieżki końcowe również są bezpiecznie sprawdzane. Jeśli /workspace/alias-out/new-file przez nadrzędne dowiązanie symboliczne wskazuje zablokowaną ścieżkę lub lokalizację poza skonfigurowanymi dozwolonymi katalogami głównymi, montowanie zostaje odrzucone.
  • Powiązanie /var/run/docker.sock faktycznie przekazuje piaskownicy kontrolę nad hostem; rób to wyłącznie świadomie.
  • Dostęp do obszaru roboczego (workspaceAccess) jest niezależny od trybów montowania.

Zasady narzędzi: które narzędzia istnieją i można wywoływać

Znaczenie mają następujące warstwy:

  • Profil narzędzi: tools.profile i agents.list[].tools.profile (bazowa lista dozwolonych narzędzi)
  • Profil narzędzi dostawcy: tools.byProvider[provider].profile i agents.list[].tools.byProvider[provider].profile
  • Globalne/indywidualne zasady narzędzi agenta: tools.allow/tools.deny i agents.list[].tools.allow/agents.list[].tools.deny
  • Zasady narzędzi dostawcy: tools.byProvider[provider].allow/deny i agents.list[].tools.byProvider[provider].allow/deny
  • Zasady narzędzi piaskownicy (obowiązują tylko podczas pracy w piaskownicy): tools.sandbox.tools.allow/tools.sandbox.tools.deny i agents.list[].tools.sandbox.tools.*

Praktyczne reguły:

  • deny zawsze ma pierwszeństwo.
  • Jeśli allow nie jest puste, wszystko inne jest traktowane jako zablokowane.
  • Zasady narzędzi są bezwzględną blokadą: /exec nie może zastąpić odmowy dostępu do narzędzia exec.
  • Zasady narzędzi filtrują ich dostępność według nazw; nie sprawdzają skutków ubocznych wewnątrz exec. Jeśli exec jest dozwolone, zablokowanie write, edit lub apply_patch nie powoduje, że polecenia powłoki stają się tylko do odczytu.
  • /exec zmienia wyłącznie domyślne ustawienia sesji dla autoryzowanych nadawców; nie przyznaje dostępu do narzędzi.
  • Klucze narzędzi dostawcy akceptują zarówno provider (np. google-antigravity), jak i provider/model (np. openai/gpt-5.4).
  • Gdy etap zasad narzędzi usuwa narzędzia lub zasady narzędzi piaskownicy blokują wywołanie, dzienniki Gateway zawierają wpisy audytowe agents/tool-policy. Użyj openclaw logs, aby zobaczyć etykietę reguły, klucz konfiguracji i nazwy narzędzi, których dotyczy wpis.

Grupy narzędzi (skróty)

Zasady narzędzi (globalne, agenta i piaskownicy) obsługują wpisy group:*, które są rozwijane do wielu narzędzi:

json5
{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

Dostępne grupy:

Grupa Narzędzia
group:runtime exec, process, code_execution (bash jest akceptowane jako alias exec)
group:fs read, write, edit, apply_patch
group:sessions sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
group:memory memory_search, memory_get
group:web web_search, x_search, web_fetch
group:ui browser, canvas
group:automation heartbeat_respond, cron, gateway
group:messaging message
group:nodes nodes, computer
group:agents agents_list, get_goal, create_goal, update_goal, update_plan, skill_workshop
group:media image, image_generate, music_generate, video_generate, tts
group:openclaw większość wbudowanych narzędzi OpenClaw (z wyłączeniem prymitywów systemu plików i środowiska wykonawczego read/write/edit/apply_patch/exec/process, narzędzia canvas i pluginów dostawców)
group:plugins wszystkie załadowane narzędzia należące do pluginów, w tym skonfigurowane serwery MCP udostępniane przez bundle-mcp

W przypadku agentów tylko do odczytu zablokuj group:runtime oraz narzędzia modyfikujące system plików, chyba że ograniczenie tylko do odczytu jest wymuszane przez zasady systemu plików piaskownicy lub oddzielną granicę hosta.

W przypadku serwerów MCP działających w piaskownicy zasady narzędzi piaskownicy stanowią drugą bramę zezwoleń. Jeśli skonfigurowano mcp.servers, ale tury działające w piaskownicy pokazują tylko narzędzia wbudowane, dodaj bundle-mcp, group:plugins albo nazwę lub wzorzec globalny narzędzia MCP z prefiksem serwera, na przykład outlook__send_mail lub outlook__*, do tools.sandbox.tools.alsoAllow, a następnie uruchom ponownie/przeładuj Gateway i ponownie przechwyć listę narzędzi. Wzorce globalne serwerów używają bezpiecznego dla dostawcy prefiksu serwera MCP: znaki inne niż [A-Za-z0-9_-] są zastępowane znakiem -, nazwy, które nie zaczynają się literą, otrzymują prefiks mcp-, a długie lub zduplikowane prefiksy mogą zostać skrócone lub otrzymać przyrostek.

openclaw doctor sprawdza obecnie tę strukturę w przypadku serwerów zarządzanych przez OpenClaw w mcp.servers. Serwery MCP ładowane z manifestów dołączonych pluginów lub pliku .mcp.json Claude używają tej samej bramy piaskownicy, ale ta diagnostyka nie wylicza jeszcze tych źródeł; jeśli ich narzędzia znikają w turach działających w piaskownicy, użyj tych samych wpisów listy dozwolonych.

Tryb podwyższonych uprawnień: „uruchamianie na hoście” tylko dla exec

Tryb podwyższonych uprawnień nie przyznaje dodatkowych narzędzi; wpływa wyłącznie na exec.

  • Jeśli działasz w piaskownicy, /elevated on (lub exec z elevated: true) uruchamia operację poza piaskownicą (zatwierdzenia mogą nadal być wymagane).
  • Użyj /elevated full, aby pominąć zatwierdzenia exec w tej sesji.
  • Jeśli operacje są już uruchamiane bezpośrednio, tryb podwyższonych uprawnień praktycznie niczego nie zmienia (nadal podlega ograniczeniom).
  • Tryb podwyższonych uprawnień nie jest ograniczony do Skills i nie zastępuje reguł zezwalania/blokowania narzędzi.
  • Tryb podwyższonych uprawnień nie przyznaje dowolnych uprawnień do przełączania hostów przy host=auto; przestrzega zwykłych reguł celu wykonywania i zachowuje node tylko wtedy, gdy skonfigurowanym lub sesyjnym celem jest już node.
  • /exec jest niezależne od trybu podwyższonych uprawnień. Dostosowuje wyłącznie sesyjne ustawienia domyślne exec dla autoryzowanych nadawców.

Warunki:

  • Włączenie: tools.elevated.enabled (oraz opcjonalnie agents.list[].tools.elevated.enabled)
  • Listy dozwolonych nadawców: tools.elevated.allowFrom.<provider> (oraz opcjonalnie agents.list[].tools.elevated.allowFrom.<provider>)

Zobacz Tryb podwyższonych uprawnień.

Typowe rozwiązania problemów z „uwięzieniem w piaskownicy”

„Narzędzie X zostało zablokowane przez zasady narzędzi piaskownicy”

Klucze do poprawy (wybierz jeden):

  • Wyłącz piaskownicę: agents.defaults.sandbox.mode=off (lub dla wybranego agenta agents.list[].sandbox.mode=off)
  • Zezwól na narzędzie w piaskownicy:
    • usuń je z tools.sandbox.tools.deny (lub dla wybranego agenta z agents.list[].tools.sandbox.tools.deny)
    • albo dodaj je do tools.sandbox.tools.allow (lub listy zezwoleń wybranego agenta)
  • Sprawdź wpis agents/tool-policy za pomocą openclaw logs. Rejestruje on tryb piaskownicy oraz informację, czy narzędzie zablokowała reguła zezwalająca, czy blokująca.

„To miała być sesja główna — dlaczego działa w piaskownicy?”

W trybie "non-main" klucze grup/kanałów nie są główne. Użyj klucza sesji głównej (pokazanego przez sandbox explain) lub zmień tryb na "off".

Powiązane materiały

Was this useful?
On this page

On this page