Инструмент Exec

Выполняйте команды оболочки в рабочей области. exec — изменяющая поверхность оболочки: команды могут создавать, редактировать или удалять файлы везде, где это разрешает выбранный хост или файловая система песочницы. Отключение файловых инструментов OpenClaw, таких как write, edit или apply_patch, не делает exec доступным только для чтения.

Поддерживает выполнение на переднем плане и в фоне через process. Если process запрещен, exec выполняется синхронно и игнорирует yieldMs/background. Фоновые сеансы ограничены областью агента; process видит только сеансы того же агента.

Параметры

Примечания:

• host по умолчанию равен auto: песочница, когда для сеанса активна среда выполнения песочницы, иначе gateway.
• host принимает только auto, sandbox, gateway или node. Это не селектор имени хоста; значения, похожие на имена хостов, отклоняются до запуска команды.
• auto — стратегия маршрутизации по умолчанию, а не подстановочный шаблон. host=node для отдельного вызова разрешен из auto; host=gateway для отдельного вызова разрешен только когда среда выполнения песочницы не активна.
• tools.exec.mode — нормализованный переключатель политики. Значения: deny, allowlist, ask, auto и full. auto напрямую запускает детерминированные совпадения allowlist/safe-bin и направляет каждый оставшийся случай одобрения exec через нативного авторецензента OpenClaw перед запросом человека. ask / ask=always по-прежнему каждый раз спрашивает человека.
• Без дополнительной конфигурации host=auto все равно «просто работает»: если песочницы нет, он разрешается в gateway; если песочница активна, он остается в песочнице.
• elevated выходит из песочницы на настроенный путь хоста: gateway по умолчанию или node, когда tools.exec.host=node (или значение сеанса по умолчанию — host=node). Доступно только когда повышенный доступ включен для текущего сеанса/провайдера.
• Одобрения gateway/node управляются файлом одобрений хоста.
• node требует сопряженный Node (сопутствующее приложение или headless-хост Node).
• Если доступно несколько Node, задайте exec.node или tools.exec.node, чтобы выбрать один.
• exec host=node — единственный путь выполнения команд оболочки для Node; устаревшая обертка nodes.run удалена.
• timeout применяется к выполнению на переднем плане, в фоне, yieldMs, gateway, песочнице и system.run на Node. Если опущен, OpenClaw использует tools.exec.timeoutSec; явный timeout: 0 отключает тайм-аут процесса exec для этого вызова.
• На не-Windows хостах exec использует SHELL, если он задан; если SHELL — fish, он предпочитает bash (или sh) из PATH, чтобы избежать скриптов, несовместимых с fish, затем откатывается к SHELL, если ни один не найден.
• На Windows хостах exec предпочитает обнаружение PowerShell 7 (pwsh) (Program Files, ProgramW6432, затем PATH), затем откатывается к Windows PowerShell 5.1.
• На не-Windows gateway-хостах команды exec bash и zsh используют стартовый снимок. OpenClaw захватывает пригодные для source псевдонимы/функции и небольшой безопасный набор окружения из стартовых файлов оболочки в $OPENCLAW_STATE_DIR/cache/shell-snapshots/, затем выполняет source этого снимка перед каждой командой exec. Переменные, похожие на секреты, исключаются; exec в песочнице и Node не используют этот снимок. Задайте OPENCLAW_EXEC_SHELL_SNAPSHOT=0 в окружении процесса Gateway, чтобы отключить этот путь снимков.
• Выполнение на хосте (gateway/node) отклоняет env.PATH и переопределения загрузчика (LD_*/DYLD_*), чтобы предотвратить подмену бинарных файлов или внедренный код.
• OpenClaw задает OPENCLAW_SHELL=exec в окружении порожденной команды (включая выполнение в PTY и песочнице), чтобы правила оболочки/профиля могли определить контекст инструмента exec.
• Для запусков из каналов OpenClaw также предоставляет узкую JSON-полезную нагрузку с идентичностью отправителя/чата в OPENCLAW_CHANNEL_CONTEXT, когда канал предоставил эти ID.
• openclaw channels login заблокирован из exec, потому что это интерактивный поток авторизации канала; запускайте его в терминале на gateway-хосте или используйте нативный для канала инструмент входа из чата, когда он существует.
• Важно: песочница по умолчанию отключена. Если песочница отключена, неявный host=auto разрешается в gateway. Явный host=sandbox все равно закрыто завершается ошибкой вместо тихого запуска на gateway-хосте. Включите песочницу или используйте host=gateway с одобрениями.
• Предварительные проверки скриптов (для распространенных ошибок синтаксиса оболочки Python/Node) проверяют только файлы внутри эффективной границы workdir. Если путь скрипта разрешается за пределами workdir, предварительная проверка для этого файла пропускается.
• Для длительной работы, которая начинается сейчас, запустите ее один раз и полагайтесь на автоматическое пробуждение по завершению, когда оно включено и команда выводит данные или завершается ошибкой. Используйте process для логов, статуса, ввода или вмешательства; не имитируйте планирование циклами sleep, циклами тайм-аутов или повторным опросом.
• Для работы, которая должна произойти позже или по расписанию, используйте cron вместо шаблонов sleep/delay в exec.

Конфигурация

• tools.exec.notifyOnExit (по умолчанию: true): когда true, фоновые сеансы exec ставят системное событие в очередь и запрашивают Heartbeat при выходе.
• tools.exec.approvalRunningNoticeMs (по умолчанию: 10000): выдать одно уведомление «выполняется», когда exec, ограниченный одобрением, работает дольше этого времени (0 отключает).
• tools.exec.timeoutSec (по умолчанию: 1800): тайм-аут exec по умолчанию для каждой команды в секундах. timeout для отдельного вызова переопределяет его; timeout: 0 для отдельного вызова отключает тайм-аут процесса exec.
• tools.exec.host (по умолчанию: auto; разрешается в sandbox, когда среда выполнения песочницы активна, иначе в gateway)
• tools.exec.security (по умолчанию: deny для песочницы, full для gateway + node, когда не задано)
• tools.exec.ask (по умолчанию: off)
• Выполнение exec на хосте без одобрений является настройкой по умолчанию для gateway + node. Если нужно поведение с одобрениями/allowlist, ужесточите и tools.exec.*, и файл одобрений хоста; см. Одобрения exec.
• YOLO берется из значений политики хоста по умолчанию (security=full, ask=off), а не из host=auto. Если нужно принудительно маршрутизировать в gateway или node, задайте tools.exec.host или используйте /exec host=....
• В режиме security=full плюс ask=off host exec напрямую следует настроенной политике; дополнительного эвристического префильтра обфускации команд или слоя отклонения предварительной проверки скриптов нет.
• tools.exec.node (по умолчанию: не задано)
• tools.exec.strictInlineEval (по умолчанию: false): когда true, формы inline eval интерпретаторов, такие как python -c, node -e, ruby -e, perl -e, php -r, lua -e и osascript -e, требуют рецензента или явного одобрения. В mode=auto обычный путь одобрения exec может позволить нативному авторецензенту разрешить явно низкорисковую разовую команду; прямые вызовы system.run на node-хосте все равно требуют явного одобрения, потому что они не могут передать команду в маршрут человеческого одобрения. Если рецензент запрашивает, запрос отправляется человеку. allow-always все еще может сохранять безвредные вызовы интерпретаторов/скриптов, но формы inline-eval не становятся долговременными правилами разрешения.
• tools.exec.commandHighlighting (по умолчанию: false): когда true, запросы одобрения могут подсвечивать полученные парсером фрагменты команд в тексте команды. Задайте true глобально или для отдельного агента, чтобы включить подсветку текста команд без изменения политики одобрения exec.
• tools.exec.pathPrepend: список каталогов для добавления в начало PATH при запусках exec (только gateway + песочница).
• tools.exec.safeBins: безопасные бинарные файлы только со stdin, которые могут запускаться без явных записей allowlist. Подробнее о поведении см. Безопасные бинарные файлы.
• tools.exec.safeBinTrustedDirs: дополнительные явные каталоги, доверенные для проверок путей safeBins. Записи PATH никогда не считаются доверенными автоматически. Встроенные значения по умолчанию: /bin и /usr/bin.
• tools.exec.safeBinProfiles: необязательная пользовательская политика argv для каждого безопасного бинарного файла (minPositional, maxPositional, allowedValueFlags, deniedFlags).

Пример:

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

Обработка PATH

• host=gateway: объединяет PATH вашей login-shell в окружение exec. Переопределения env.PATH отклоняются для выполнения на хосте. Сам daemon по-прежнему запускается с минимальным PATH:
  • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
  • Linux: /usr/local/bin, /usr/bin, /bin
    • Чтобы предотвратить переопределение приоритетных путей пользовательской конфигурацией оболочки (например, ~/.zshenv или /etc/zshenv) во время запуска, записи tools.exec.pathPrepend безопасно добавляются в начало финального PATH внутри команды оболочки прямо перед выполнением.
• host=sandbox: запускает sh -lc (login shell) внутри контейнера, поэтому /etc/profile может сбросить PATH. OpenClaw добавляет env.PATH после source профиля через внутреннюю переменную окружения (без интерполяции оболочки); tools.exec.pathPrepend применяется и здесь.
• host=node: на Node отправляются только переданные вами незаблокированные переопределения окружения. Переопределения env.PATH отклоняются для выполнения на хосте и игнорируются node-хостами. Если нужны дополнительные записи PATH на Node, настройте окружение службы node-хоста (systemd/launchd) или установите инструменты в стандартные расположения.

Привязка Node для отдельного агента (используйте индекс агента в списке в конфигурации):

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

Control UI: вкладка Nodes содержит небольшую панель «Привязка exec-Node» для тех же настроек.

Переопределения сеанса (/exec)

Используйте /exec, чтобы задать значения по умолчанию для отдельного сеанса для host, security, ask и node. Отправьте /exec без аргументов, чтобы показать текущие значения.

Пример:

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

Модель авторизации

/exec учитывается только для авторизованных отправителей (списки разрешений/сопряжение каналов плюс commands.useAccessGroups). Он обновляет только состояние сеанса и не записывает конфигурацию. Авторизованные отправители внешних каналов могут задавать эти значения сеанса по умолчанию. Внутренним клиентам Gateway/webchat нужен operator.admin, чтобы сохранять их. Чтобы жестко отключить exec, запретите его через политику инструментов (tools.deny: ["exec"] или для отдельного агента). Одобрения хоста по-прежнему применяются, если вы явно не зададите security=full и ask=off.

Одобрения exec (сопутствующее приложение / хост Node)

Агенты в песочнице могут требовать одобрение для каждого запроса перед запуском exec на Gateway или хосте Node. См. Одобрения exec для политики, списка разрешений и UI-потока.

Когда требуются одобрения, инструмент exec сразу возвращает status: "approval-pending" и идентификатор одобрения. После одобрения (или отказа / истечения времени ожидания) Gateway отправляет системные события хода и завершения команды только для одобренных запусков (Exec running / Exec finished). Отклоненные или просроченные одобрения являются конечными и не пробуждают сеанс агента системным событием об отказе. В каналах с нативными карточками/кнопками одобрения агент должен сначала полагаться на этот нативный UI и включать ручную команду /approve только когда результат инструмента явно сообщает, что одобрения в чате недоступны или ручное одобрение является единственным путем.

Список разрешений + безопасные исполняемые файлы

Ручное применение списка разрешений сопоставляет glob-шаблоны разрешенных путей исполняемых файлов и glob-шаблоны простых имен команд. Простые имена совпадают только с командами, вызванными через PATH, поэтому rg может соответствовать /opt/homebrew/bin/rg, когда команда — rg, но не ./rg или /tmp/rg. Когда security=allowlist, shell-команды автоматически разрешаются только если каждый сегмент конвейера есть в списке разрешений или является безопасным исполняемым файлом. Связывание команд (;, &&, ||) и перенаправления отклоняются в режиме списка разрешений, если каждый сегмент верхнего уровня не удовлетворяет списку разрешений (включая безопасные исполняемые файлы). Перенаправления остаются неподдерживаемыми. Долговременное доверие allow-always не обходит это правило: связанная команда по-прежнему требует, чтобы каждый сегмент верхнего уровня совпадал.

autoAllowSkills — это отдельный удобный путь в одобрениях exec. Это не то же самое, что ручные записи списка разрешенных путей. Для строгого явного доверия оставляйте autoAllowSkills отключенным.

Используйте два элемента управления для разных задач:

• tools.exec.safeBins: небольшие потоковые фильтры только для stdin.
• tools.exec.safeBinTrustedDirs: явные дополнительные доверенные каталоги для путей безопасных исполняемых файлов.
• tools.exec.safeBinProfiles: явная политика argv для пользовательских безопасных исполняемых файлов.
• список разрешений: явное доверие к путям исполняемых файлов.

Не рассматривайте safeBins как универсальный список разрешений и не добавляйте исполняемые файлы интерпретаторов/рантаймов (например, python3, node, ruby, bash). Если они нужны, используйте явные записи списка разрешений и оставляйте запросы одобрения включенными. openclaw security audit предупреждает, когда записи safeBins для интерпретаторов/рантаймов не имеют явных профилей, а openclaw doctor --fix может создать каркас отсутствующих пользовательских записей safeBinProfiles. openclaw security audit и openclaw doctor также предупреждают, когда вы явно добавляете исполняемые файлы с широким поведением, такие как jq, обратно в safeBins. Если вы явно разрешаете интерпретаторы, включите tools.exec.strictInlineEval, чтобы формы встроенной оценки кода по-прежнему требовали проверки рецензентом или явного одобрения.

Полные сведения о политике и примеры см. в Одобрения exec и Безопасные исполняемые файлы и список разрешений.

Примеры

Передний план:

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

Фоновый режим + опрос:

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

Опрос предназначен для статуса по запросу, а не для циклов ожидания. Если автоматическое пробуждение по завершению включено, команда может разбудить сеанс, когда выводит данные или завершается с ошибкой.

Отправка клавиш (в стиле tmux):

{"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"]}

Отправка (только CR):

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

Вставка (по умолчанию bracketed):

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

apply_patch

apply_patch — это подинструмент exec для структурированных многофайловых правок. Он включен по умолчанию для моделей OpenAI и OpenAI Codex. Используйте конфигурацию только когда хотите отключить его или ограничить конкретными моделями:

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

Примечания:

• Доступно только для моделей OpenAI/OpenAI Codex.
• Политика инструментов по-прежнему применяется; allow: ["write"] неявно разрешает apply_patch.
• deny: ["write"] не запрещает apply_patch; запретите apply_patch явно или используйте deny: ["group:fs"], когда записи патчей также должны блокироваться.
• Конфигурация находится в tools.exec.applyPatch.
• tools.exec.applyPatch.enabled по умолчанию равно true; задайте false, чтобы отключить инструмент для моделей OpenAI.
• tools.exec.applyPatch.workspaceOnly по умолчанию равно true (только внутри рабочей области). Задавайте false только если намеренно хотите, чтобы apply_patch записывал/удалял файлы за пределами каталога рабочей области.

Связанные разделы

• Одобрения exec — шлюзы одобрения для shell-команд
• Песочница — запуск команд в изолированных окружениях
• Фоновый процесс — длительно выполняющиеся exec и инструмент process
• Безопасность — политика инструментов и повышенный доступ