Инструмент выполнения команд

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

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

Параметры

Примечания:

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

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

Выполнение на хосте без одобрения используется по умолчанию для Gateway и узла (security=full, ask=off) — это определяется значениями политики хоста по умолчанию, а не host=auto. Если требуется одобрение или поведение на основе списка разрешений, ужесточите как tools.exec.*, так и файл одобрений хоста; см. Одобрения выполнения. Чтобы принудительно направлять выполнение через Gateway или узел независимо от состояния песочницы, задайте tools.exec.host или используйте /exec host=....

Пример:

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

Режимы

tools.exec.mode — нормализованный параметр политики. При его задании выводятся значения security/ask; его нельзя использовать вместе с явно заданными tools.exec.security/tools.exec.ask.

ask/ask=always по-прежнему каждый раз запрашивает одобрение человека независимо от режима.

Одобрение автоматической проверки действует однократно. На Gateway OpenClaw передаёт системе проверки разрешённый путь к исполняемому файлу и привязывает выполнение к этому же пути. Команды, которые невозможно свести к одному контролируемому плану выполнения, — например, heredoc-конструкции, подстановки оболочки или неподдерживаемое экранирование оболочек-обёрток, — переходят к одобрению человеком, даже если модель в противном случае разрешила бы их.

Одобрения команд сервера приложений Codex, которые ещё не определены явной политикой среды выполнения или встроенной политикой, направляются человеку. OpenClaw не запускает для этих запросов настроенную систему проверки выполнения, поскольку Codex не предоставляет контролируемый разрешённый исполняемый файл, позволяющий привязать решение проверки к команде, которую выполняет Codex.

Встроенное вычисление (strictInlineEval)

Когда tools.exec.strictInlineEval имеет значение true, встроенные формы вычисления интерпретатора требуют проверки или явного одобрения: python -c, node -e, ruby -e, perl -e, php -r, lua -e, osascript -e и аналогичные формы в других поддерживаемых интерпретаторах и средствах передачи команд (awk, find -exec, make, sed, xargs и других). В режиме mode=auto обычный путь одобрения выполнения может позволить встроенной автоматической системе проверки разрешить явно низкорисковую одноразовую команду; прямые вызовы system.run на хосте узла по-прежнему требуют явного одобрения, поскольку они не могут передать команду в маршрут одобрения человеком. Если система проверки запрашивает одобрение, запрос направляется человеку. allow-always по-прежнему может сохранять безопасные вызовы интерпретаторов и скриптов, но формы встроенного вычисления не превращаются в постоянные правила разрешения.

Обработка PATH

• host=gateway: объединяет PATH вашей оболочки входа с окружением выполнения. Переопределения env.PATH отклоняются при выполнении на хосте. Сам демон по-прежнему работает с минимальным 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 (оболочку входа) внутри контейнера, поэтому /etc/profile может сбросить PATH. OpenClaw добавляет env.PATH в начало после загрузки профиля через внутреннюю переменную окружения (без интерполяции оболочки); tools.exec.pathPrepend применяется и здесь.
• host=node: узлу передаются только указанные вами незаблокированные переопределения окружения. Переопределения env.PATH отклоняются при выполнении на хосте и игнорируются хостами узлов. Если на узле нужны дополнительные записи PATH, настройте окружение службы хоста узла (systemd/launchd) или установите инструменты в стандартные расположения.

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

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

В Control UI страница Устройства содержит небольшую панель «Привязка узла выполнения» для тех же настроек.

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

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

Пример:

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

/exec учитывается только для авторизованных отправителей (списки разрешений каналов/сопряжение вместе с commands.useAccessGroups). Он обновляет только состояние сеанса и не записывает конфигурацию. Авторизованные отправители внешних каналов могут задавать эти значения сеанса по умолчанию. Внутренним клиентам Gateway и веб-чата требуется operator.admin, чтобы сохранять их.

Чтобы полностью отключить выполнение, запретите его в политике инструментов (tools.deny: ["exec"] или для отдельного агента). Одобрения хоста по-прежнему применяются, если явно не заданы security=full и ask=off.

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

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

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

В каналах с нативными карточками/кнопками подтверждения агент должен в первую очередь полагаться на этот нативный интерфейс и включать команду для ручного подтверждения /approve только в том случае, если результат инструмента явно указывает, что подтверждения в чате недоступны или ручное подтверждение — единственный вариант.

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

При ручном применении списка разрешений сопоставляются шаблоны полного пути к исполняемому файлу и шаблоны только имени команды. Имена без пути соответствуют только командам, запускаемым через PATH, поэтому rg может соответствовать /opt/homebrew/bin/rg, когда команда имеет вид rg, но не ./rg или /tmp/rg.

Когда security=allowlist, команды оболочки разрешаются автоматически, только если каждый сегмент конвейера входит в список разрешений или является безопасным исполняемым файлом. Цепочки (;, &&, ||) и перенаправления отклоняются в режиме списка разрешений, если не каждый сегмент верхнего уровня удовлетворяет списку разрешений (включая безопасные исполняемые файлы). Перенаправления по-прежнему не поддерживаются. Постоянное доверие allow-always не позволяет обойти это правило: для цепочки команд по-прежнему требуется соответствие каждого сегмента верхнего уровня.

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

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

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

Не рассматривайте safeBins как универсальный список разрешений и не добавляйте двоичные файлы интерпретаторов/сред выполнения (например, python3, node, ruby, bash). Если они необходимы, используйте явные записи списка разрешений и оставьте запросы подтверждения включёнными.

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

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

Примеры

Интерактивный режим:

{ "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 paste):

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

apply_patch

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

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

Примечания:

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

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

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