Инструмент Exec

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

Параметры

  • command (обязательно)
  • workdir (по умолчанию cwd)
  • env (переопределения ключ/значение)
  • yieldMs (по умолчанию 10000): автоматический переход в фон после задержки
  • background (bool): немедленный переход в фон
  • timeout (секунды, по умолчанию 1800): завершить при истечении
  • pty (bool): запустить в псевдотерминале, когда доступно (CLI только для TTY, агенты кодирования, терминальные UI)
  • host (sandbox | gateway | node): где выполнять
  • security (deny | allowlist | full): режим принуждения для gateway/node
  • ask (off | on-miss | always): запросы на одобрение для gateway/node
  • node (строка): id/имя узла для host=node
  • elevated (bool): запросить повышенный режим (хост шлюза); security=full принудительно только когда elevated разрешается в full

Примечания:

  • host по умолчанию sandbox.
  • elevated игнорируется, когда изоляция отключена (exec уже работает на хосте).
  • Одобрения gateway/node контролируются ~/.openclaw/exec-approvals.json.
  • node требует сопряжённого узла (сопутствующее приложение или безголовый хост узла).
  • Если доступно несколько узлов, установите exec.node или tools.exec.node для выбора одного.
  • На хостах не Windows exec использует SHELL, если установлен; если SHELL это fish, он предпочитает bash (или sh) из PATH для избежания несовместимых с fish скриптов, затем возвращается к SHELL, если ни один не существует.
  • Важно: изоляция отключена по умолчанию. Если изоляция отключена, host=sandbox запускается непосредственно на хосте шлюза (без контейнера) и не требует одобрений. Для требования одобрений запускайте с host=gateway и настройте одобрения exec (или включите изоляцию).

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

  • tools.exec.notifyOnExit (по умолчанию: true): когда true, фоновые сессии exec ставят в очередь системное событие и запрашивают heartbeat при выходе.
  • tools.exec.approvalRunningNoticeMs (по умолчанию: 10000): выдать одно уведомление "запущено", когда exec с одобрением выполняется дольше этого (0 отключает).
  • tools.exec.host (по умолчанию: sandbox)
  • tools.exec.security (по умолчанию: deny для sandbox, allowlist для gateway + node, когда не установлено)
  • tools.exec.ask (по умолчанию: on-miss)
  • tools.exec.node (по умолчанию: не установлено)
  • tools.exec.pathPrepend: список каталогов для добавления в начало PATH для запусков exec.
  • tools.exec.safeBins: безопасные двоичные файлы только для stdin, которые могут запускаться без явных записей в белом списке.

Пример:

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

Обработка PATH

  • host=gateway: объединяет ваш PATH логин-оболочки в окружение exec (если вызов exec уже не устанавливает env.PATH). Сам демон всё ещё работает с минимальным PATH:
    • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
    • Linux: /usr/local/bin, /usr/bin, /bin
  • host=sandbox: запускает sh -lc (логин-оболочку) внутри контейнера, поэтому /etc/profile может сбросить PATH. OpenClaw добавляет env.PATH в начало после загрузки профиля через внутреннюю переменную окружения (без интерполяции оболочки); tools.exec.pathPrepend также применяется здесь.
  • host=node: только переопределения env, которые вы передаёте, отправляются на узел. tools.exec.pathPrepend применяется только если вызов exec уже устанавливает env.PATH. Безголовые хосты узлов принимают PATH только когда он добавляется в начало PATH хоста узла (без замены). Узлы macOS полностью отбрасывают переопределения PATH.

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

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

Control UI: вкладка Узлы включает небольшую панель "Привязка узла exec" для тех же настроек.

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

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

Пример:

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

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

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

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

Изолированные агенты могут требовать одобрения для каждого запроса перед тем, как exec запустится на шлюзе или хосте узла. См. Одобрения Exec для политики, белого списка и потока UI.

Когда требуются одобрения, инструмент exec немедленно возвращает status: "approval-pending" и id одобрения. После одобрения (или отказа / тайм-аута), Gateway выдаёт системные события (Exec finished / Exec denied). Если команда всё ещё выполняется после tools.exec.approvalRunningNoticeMs, выдаётся одно уведомление Exec running.

Белый список + безопасные двоичные файлы

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

Примеры

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

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

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

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

apply_patch (экспериментально)

apply_patch — это подинструмент exec для структурированного редактирования нескольких файлов. Включите его явно:

\{
  tools: \{
    exec: \{
      applyPatch: \{ enabled: true, allowModels: ["gpt-5.2"] \}
    \}
  \}
\}

Примечания:

  • Доступно только для моделей OpenAI/OpenAI Codex.
  • Политика инструментов всё ещё применяется; allow: ["exec"] неявно разрешает apply_patch.
  • Конфигурация находится под tools.exec.applyPatch.
← Назад к документации