​

Narzędzie Exec

​

Parametry

• command (wymagane)
• workdir (domyślnie cwd)
• env (nadpisania klucz/wartość)
• yieldMs (domyślnie 10000): automatyczne przejście w tło po opóźnieniu
• background (bool): natychmiastowe uruchomienie w tle
• timeout (sekundy, domyślnie 1800): zakończenie po upływie czasu
• pty (bool): uruchamia w pseudoterminalu, gdy jest dostępny (CLI tylko dla TTY, agenci kodujący, terminalowe interfejsy UI)
• host (auto | sandbox | gateway | node): gdzie wykonać
• security (deny | allowlist | full): tryb wymuszania dla gateway/node
• ask (off | on-miss | always): prompty zatwierdzeń dla gateway/node
• node (string): identyfikator/nazwa node dla host=node
• elevated (bool): żądanie trybu podwyższonego (wyjście z sandboxa na skonfigurowaną ścieżkę hosta); security=full jest wymuszane tylko wtedy, gdy elevated zostanie rozwiązane do full

• host domyślnie ma wartość auto: sandbox, gdy dla sesji aktywne jest środowisko sandbox, w przeciwnym razie gateway.
• auto to domyślna strategia routingu, a nie wildcard. Wywołanie per-call host=node jest dozwolone z auto; per-call host=gateway jest dozwolone tylko wtedy, gdy nie jest aktywne żadne środowisko sandbox.
• Bez dodatkowej konfiguracji host=auto nadal „po prostu działa”: brak sandboxa oznacza rozstrzygnięcie do gateway; aktywny sandbox oznacza pozostanie w sandboxie.
• elevated wychodzi z sandboxa na skonfigurowaną ścieżkę hosta: domyślnie gateway albo node, gdy tools.exec.host=node (lub domyślnie sesji ustawiono host=node). Jest dostępne tylko wtedy, gdy dla bieżącej sesji/dostawcy włączono dostęp podwyższony.
• Zatwierdzenia gateway/node są kontrolowane przez ~/.openclaw/exec-approvals.json.
• node wymaga sparowanego node (aplikacja towarzysząca lub bezgłowy host 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.
• Na hostach innych niż Windows exec używa SHELL, jeśli jest ustawione; jeśli SHELL to fish, preferuje bash (lub sh) z PATH, aby uniknąć skryptów niezgodnych z fish, a dopiero potem wraca do SHELL, jeśli żaden z nich nie istnieje.
• Na hostach Windows exec preferuje wykrywanie PowerShell 7 (pwsh) (Program Files, ProgramW6432, a potem PATH), a następnie wraca do Windows PowerShell 5.1.
• Wykonanie na hoście (gateway/node) odrzuca env.PATH oraz nadpisania loadera (LD_*/DYLD_*), aby zapobiec przejęciu binariów lub wstrzyknięciu kodu.
• OpenClaw ustawia OPENCLAW_SHELL=exec w środowisku uruchamianego polecenia (w tym PTY i wykonania w sandboxie), aby reguły powłoki/profilu mogły wykrywać kontekst narzędzia exec.
• Ważne: sandboxing jest domyślnie wyłączony. Jeśli sandboxing jest wyłączony, niejawne host=auto rozstrzyga się do gateway. Jawne host=sandbox nadal bezpiecznie kończy się odmową zamiast po cichu uruchamiać się na hoście gateway. Włącz sandboxing albo użyj host=gateway z zatwierdzeniami.
• Kontrole wstępne skryptów (dla typowych błędów składni powłoki Python/Node) sprawdzają tylko pliki wewnątrz skutecznej granicy workdir. Jeśli ścieżka skryptu rozstrzyga się poza workdir, kontrola wstępna jest pomijana dla tego pliku.
• Dla długotrwałej pracy, która zaczyna się teraz, uruchom ją raz i polegaj na automatycznym wybudzeniu po zakończeniu, gdy jest ono włączone i polecenie generuje dane wyjściowe lub kończy się błędem. Używaj process do logów, statusu, wejścia lub interwencji; nie emuluj harmonogramowania za pomocą pętli sleep, timeout ani powtarzanego odpytywania.
• Dla pracy, która ma zostać wykonana później lub według harmonogramu, używaj cron zamiast wzorców sleep/delay z exec.

​

Config

• tools.exec.notifyOnExit (domyślnie: true): gdy ma wartość true, sesje exec uruchomione w tle dodają zdarzenie systemowe do kolejki i żądają heartbeat po zakończeniu.
• tools.exec.approvalRunningNoticeMs (domyślnie: 10000): emituje pojedyncze powiadomienie „running”, gdy exec wymagający zatwierdzenia działa dłużej niż ten czas (0 wyłącza).
• tools.exec.host (domyślnie: auto; rozstrzyga się do sandbox, gdy środowisko sandbox jest aktywne, w przeciwnym razie do gateway)
• tools.exec.security (domyślnie: deny dla sandbox, full dla gateway + node, gdy nie ustawiono)
• tools.exec.ask (domyślnie: off)
• Wykonanie hosta bez zatwierdzeń jest domyślne dla gateway + node. Jeśli chcesz zachowania z zatwierdzeniami/allowlist, 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 do gateway lub node, ustaw tools.exec.host albo użyj /exec host=....
• tools.exec.node (domyślnie: nieustawione)
• tools.exec.strictInlineEval (domyślnie: false): gdy ma wartość true, formy eval inline interpretera, takie jak python -c, node -e, ruby -e, perl -e, php -r, lua -e i osascript -e, zawsze wymagają jawnego zatwierdzenia. allow-always nadal może utrwalać zaufanie dla nieszkodliwych wywołań interpretera/skryptu, ale formy inline-eval nadal pytają za każdym razem.
• tools.exec.pathPrepend: lista katalogów dodawanych na początek PATH dla uruchomień exec (tylko gateway + sandbox).
• tools.exec.safeBins: bezpieczne binaria tylko dla stdin, które mogą działać bez jawnych wpisów allowlist. Szczegóły zachowania: Safe bins.
• tools.exec.safeBinTrustedDirs: dodatkowe jawne katalogi zaufane dla sprawdzania ścieżek safeBins. Wpisy PATH nigdy nie są automatycznie uznawane za zaufane. Wbudowane domyślne wartości to /bin i /usr/bin.
• tools.exec.safeBinProfiles: opcjonalna niestandardowa polityka argv dla każdego safe bin (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 wykonania 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łoka logowania) wewnątrz kontenera, więc /etc/profile może resetować PATH. OpenClaw dodaje env.PATH na początek po wczytaniu profilu przez wewnętrzną zmienną środowiskową (bez interpolacji powłoki); tools.exec.pathPrepend działa tutaj również.
• host=node: do node wysyłane są tylko nieblokowane nadpisania env, które przekażesz. Nadpisania env.PATH są odrzucane dla wykonania 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)

​

Allowlist + safe bins

• tools.exec.safeBins: małe filtry strumieni tylko dla stdin.
• tools.exec.safeBinTrustedDirs: jawne dodatkowe zaufane katalogi dla ścieżek wykonywalnych safe-bin.
• tools.exec.safeBinProfiles: jawna polityka argv dla niestandardowych safe-bin.
• allowlist: 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.4"] },
    },
  },
}

• Dostępne tylko dla modeli OpenAI/OpenAI Codex.
• Polityka narzędzi nadal ma zastosowanie; allow: ["write"] domyślnie zezwala także na apply_patch.
• Konfiguracja znajduje się w tools.exec.applyPatch.
• tools.exec.applyPatch.enabled domyślnie ma wartość true; ustaw false, aby wyłączyć narzędzie dla modeli OpenAI.
• tools.exec.applyPatch.workspaceOnly domyślnie ma wartość true (ograniczenie do workspace). Ustaw false tylko wtedy, gdy celowo chcesz, aby apply_patch zapisywało/usunęło pliki poza katalogiem workspace.

​

Powiązane

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