Narzędzie Exec

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Parametry

• host domyślnie ma wartość auto: piaskownica, gdy środowisko wykonawcze piaskownicy jest aktywne dla sesji, w przeciwnym razie Gateway.
• host akceptuje tylko auto, sandbox, gateway lub node. Nie jest selektorem nazwy hosta; wartości podobne do nazw hostów są odrzucane przed uruchomieniem polecenia.
• auto to domyślna strategia routingu, a nie symbol wieloznaczny. host=node dla pojedynczego wywołania jest dozwolone z auto; host=gateway dla pojedynczego wywołania jest dozwolone tylko wtedy, gdy żadne środowisko wykonawcze piaskownicy nie jest aktywne.
• Bez dodatkowej konfiguracji host=auto nadal „po prostu działa”: brak piaskownicy oznacza rozwiązanie do gateway; aktywna piaskownica oznacza pozostanie w piaskownicy.
• elevated wychodzi z piaskownicy na skonfigurowaną ścieżkę hosta: domyślnie gateway albo node, gdy tools.exec.host=node (lub domyślna wartość sesji to host=node). Jest dostępne tylko wtedy, gdy podwyższony dostęp jest włączony dla bieżącej sesji/dostawcy.
• Zatwierdzenia gateway/node są kontrolowane przez ~/.openclaw/exec-approvals.json.
• node wymaga sparowanego Node (aplikacji towarzyszącej lub bezgłowego hosta Node).
• Jeśli dostępnych jest wiele Node, ustaw exec.node lub tools.exec.node, aby wybrać jeden.
• exec host=node to jedyna ścieżka wykonywania powłoki dla Node; starszy wrapper nodes.run został usunięty.
• timeout dotyczy wykonywania na pierwszym planie, w tle, yieldMs, Gateway, piaskownicy i Node system.run. Jeśli zostanie pominięte, OpenClaw używa tools.exec.timeoutSec; jawne timeout: 0 wyłącza limit czasu procesu exec dla tego wywołania.
• Na hostach innych niż Windows exec używa SHELL, gdy jest ustawione; jeśli SHELL to fish, preferuje bash (lub sh) z PATH, aby uniknąć skryptów niezgodnych z fish, a następnie wraca do SHELL, jeśli żadne z nich nie istnieje.
• Na hostach Windows exec preferuje wykrywanie PowerShell 7 (pwsh) (Program Files, ProgramW6432, następnie PATH), a potem wraca do Windows PowerShell 5.1.
• Wykonywanie na hoście (gateway/node) odrzuca env.PATH i nadpisania loadera (LD_*/DYLD_*), aby zapobiec przejęciu binariów lub wstrzykniętemu kodowi.
• OpenClaw ustawia OPENCLAW_SHELL=exec w środowisku uruchamianego polecenia (w tym wykonywania PTY i piaskownicy), aby reguły powłoki/profilu mogły wykryć kontekst narzędzia exec.
• openclaw channels login jest blokowane w exec, ponieważ jest interaktywnym przepływem uwierzytelniania kanału; uruchom je w terminalu na hoście Gateway albo użyj natywnego dla kanału narzędzia logowania z czatu, jeśli istnieje.
• Ważne: piaskownica jest domyślnie wyłączona. Jeśli piaskownica jest wyłączona, niejawne host=auto rozwiązuje się do gateway. Jawne host=sandbox nadal kończy się zamkniętym błędem, zamiast po cichu uruchamiać się na hoście Gateway. Włącz piaskownicę albo użyj host=gateway z zatwierdzeniami.
• Wstępne kontrole skryptów (dla typowych błędów składni powłoki Python/Node) sprawdzają tylko pliki wewnątrz efektywnej granicy workdir. Jeśli ścieżka skryptu rozwiązuje się poza workdir, kontrola wstępna jest pomijana dla tego pliku.
• W przypadku długotrwałej pracy, która zaczyna się teraz, uruchom ją raz i polegaj na automatycznym wznowieniu po zakończeniu, gdy jest włączone i polecenie emituje wyjście lub kończy się niepowodzeniem. Używaj process do logów, statusu, wejścia lub interwencji; nie emuluj harmonogramowania pętlami sleep, pętlami timeout ani wielokrotnym odpytywaniem.
• W przypadku pracy, która ma wydarzyć się później lub zgodnie z harmonogramem, użyj cron zamiast wzorców sleep/delay w exec.

​

Konfiguracja

• tools.exec.notifyOnExit (domyślnie: true): gdy ma wartość true, przeniesione do tła sesje exec dodają zdarzenie systemowe do kolejki i żądają Heartbeat przy wyjściu.
• tools.exec.approvalRunningNoticeMs (domyślnie: 10000): wyemituj pojedyncze powiadomienie „uruchomione”, gdy exec chronione zatwierdzeniem działa dłużej niż ta wartość (0 wyłącza).
• tools.exec.timeoutSec (domyślnie: 1800): domyślny limit czasu exec dla pojedynczego polecenia w sekundach. timeout dla pojedynczego wywołania go nadpisuje; timeout: 0 dla pojedynczego wywołania wyłącza limit czasu procesu exec.
• tools.exec.host (domyślnie: auto; rozwiązuje się do sandbox, gdy środowisko wykonawcze piaskownicy jest aktywne, w przeciwnym razie do gateway)
• tools.exec.security (domyślnie: deny dla piaskownicy, full dla Gateway + Node, gdy nieustawione)
• tools.exec.ask (domyślnie: off)
• Host exec bez zatwierdzeń jest domyślny dla Gateway + Node. Jeśli chcesz zachowanie z zatwierdzeniami/listą dozwolonych, zaostrz zarówno tools.exec.*, jak i hostowe ~/.openclaw/exec-approvals.json; zobacz Zatwierdzenia exec.
• YOLO wynika z domyślnych zasad hosta (security=full, ask=off), a nie z host=auto. Jeśli chcesz wymusić routing Gateway lub Node, ustaw tools.exec.host albo użyj /exec host=....
• W trybie security=full plus ask=off host exec bezpośrednio przestrzega skonfigurowanych zasad; nie ma dodatkowego heurystycznego prefiltra zaciemniania poleceń ani warstwy odrzucania wstępnej kontroli skryptów.
• tools.exec.node (domyślnie: nieustawione)
• tools.exec.strictInlineEval (domyślnie: false): gdy ma wartość true, formularze inline eval interpreterów, takie jak python -c, node -e, ruby -e, perl -e, php -r, lua -e i osascript -e, zawsze wymagają jawnego zatwierdzenia. allow-always może nadal utrwalać nieszkodliwe wywołania interpreterów/skryptów, ale formularze inline-eval nadal pytają za każdym razem.
• tools.exec.commandHighlighting (domyślnie: false): gdy ma wartość true, monity o zatwierdzenie mogą podświetlać wyprowadzone przez parser zakresy poleceń w tekście polecenia. Ustaw na true globalnie lub dla pojedynczego agenta, aby włączyć podświetlanie tekstu polecenia bez zmieniania zasad zatwierdzania exec.
• tools.exec.pathPrepend: lista katalogów do dodania na początku PATH dla uruchomień exec (tylko Gateway + piaskownica).
• tools.exec.safeBins: bezpieczne binaria tylko dla stdin, które mogą działać bez jawnych wpisów na liście dozwolonych. Szczegóły zachowania znajdziesz w Bezpieczne binaria.
• tools.exec.safeBinTrustedDirs: dodatkowe jawne katalogi zaufane dla kontroli ścieżek safeBins. Wpisy PATH nigdy nie są automatycznie zaufane. Wbudowane wartości domyślne to /bin i /usr/bin.
• tools.exec.safeBinProfiles: opcjonalne niestandardowe zasady argv dla każdego bezpiecznego binarium (minPositional, maxPositional, allowedValueFlags, deniedFlags).

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​

Obsługa PATH

• host=gateway: scala PATH twojej powłoki logowania ze środowiskiem exec. Nadpisania env.PATH są odrzucane dla wykonywania na hoście. Sam daemon nadal działa z minimalnym PATH:
  • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
  • Linux: /usr/local/bin, /usr/bin, /bin
• host=sandbox: uruchamia sh -lc (powłokę logowania) wewnątrz kontenera, więc /etc/profile może zresetować PATH. OpenClaw dodaje env.PATH na początku po wczytaniu profilu przez wewnętrzną zmienną środowiskową (bez interpolacji powłoki); tools.exec.pathPrepend też ma tu zastosowanie.
• host=node: tylko nieblokowane nadpisania środowiska, które przekażesz, są wysyłane do Node. Nadpisania env.PATH są odrzucane dla wykonywania na hoście i ignorowane przez hosty Node. Jeśli potrzebujesz dodatkowych wpisów PATH na Node, skonfiguruj środowisko usługi hosta Node (systemd/launchd) albo zainstaluj narzędzia w standardowych lokalizacjach.

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

​

Nadpisania sesji (/exec)

/exec host=auto security=allowlist ask=on-miss node=mac-1

​

Model autoryzacji

​

Zatwierdzenia exec (aplikacja towarzysząca / host Node)

​

Lista dozwolonych + bezpieczne binaria

• tools.exec.safeBins: małe filtry strumieniowe działające tylko na stdin.
• tools.exec.safeBinTrustedDirs: jawne dodatkowe zaufane katalogi dla ścieżek wykonywalnych safe-bin.
• tools.exec.safeBinProfiles: jawna polityka argv dla niestandardowych safe bins.
• lista dozwolonych: jawne zaufanie dla ścieżek wykonywalnych.

​

Przykłady

{ "tool": "exec", "command": "ls -la" }

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​

apply_patch

{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
    },
  },
}

• Dostępne tylko dla modeli OpenAI/OpenAI Codex.
• Polityka narzędzi nadal obowiązuje; allow: ["write"] niejawnie zezwala na apply_patch.
• deny: ["write"] nie blokuje apply_patch; zablokuj apply_patch jawnie albo użyj deny: ["group:fs"], gdy zapisy poprawek również mają być blokowane.
• Konfiguracja znajduje się pod tools.exec.applyPatch.
• tools.exec.applyPatch.enabled domyślnie ma wartość true; ustaw ją na false, aby wyłączyć narzędzie dla modeli OpenAI.
• tools.exec.applyPatch.workspaceOnly domyślnie ma wartość true (ograniczone do obszaru roboczego). Ustaw ją na false tylko wtedy, gdy celowo chcesz, aby apply_patch zapisywało/usuwało poza katalogiem obszaru roboczego.

​

Powiązane

• Zatwierdzenia exec — bramki zatwierdzania dla poleceń powłoki
• Sandboxing — uruchamianie poleceń w środowiskach sandboxowych
• Proces w tle — długotrwałe narzędzie exec i process
• Bezpieczeństwo — polityka narzędzi i podwyższony dostęp