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

​
Параметры

​
command
string
обязательно
Команда оболочки для выполнения.
​
workdir
string
по умолчанию:"cwd"
Рабочий каталог для команды.
​
env
object
Переопределения окружения в виде ключ/значение, объединяемые поверх унаследованного окружения.
​
yieldMs
number
по умолчанию:"10000"
Автоматически перевести команду в фон после этой задержки (мс).
​
background
boolean
по умолчанию:"false"
Сразу перевести команду в фон вместо ожидания yieldMs.
​
timeout
number
по умолчанию:"tools.exec.timeoutSec"
Переопределить настроенный тайм-аут exec для этого вызова. Устанавливайте timeout: 0 только когда команда должна выполняться без тайм-аута процесса exec.
​
pty
boolean
по умолчанию:"false"
Запускать в псевдотерминале, когда он доступен. Используйте для CLI, требующих TTY, кодирующих агентов и терминальных UI.
​
host
'auto' | 'sandbox' | 'gateway' | 'node'
по умолчанию:"auto"
Где выполнять. auto разрешается в sandbox, когда активна среда выполнения песочницы, и в gateway в остальных случаях.
​
security
'deny' | 'allowlist' | 'full'
Игнорируется для обычных вызовов инструментов. Безопасность gateway / node управляется tools.exec.security и файлом одобрений хоста; повышенный режим может принудительно установить security=full только когда оператор явно предоставляет повышенный доступ.
​
ask
'off' | 'on-miss' | 'always'
Базовый режим запроса берется из tools.exec.ask и одобрений хоста. Для вызовов модели, пришедших из канала, ask для отдельного вызова игнорируется, когда эффективный запрос хоста равен off; иначе он может только усилиться до более строгого режима. Доверенные внутренние/API вызывающие стороны, которые создают инструменты exec с явным значением ask, не меняются.
​
node
string
ID/имя Node, когда host=node.
​
elevated
boolean
по умолчанию:"false"
Запросить повышенный режим — выйти из песочницы на настроенный путь хоста. security=full принудительно устанавливается только когда elevated разрешается в full.
Примечания:
  • 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.list
openclaw 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 записывал/удалял файлы за пределами каталога рабочей области.

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