Инструмент Exec¶

Запуск команд оболочки в рабочем пространстве. Поддерживает выполнение на переднем и фоновом плане через 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 (string): id/имя узла для host=node
• elevated (bool): запрос повышенного режима (хост шлюза Gateway); security=full принудительно применяется только когда повышенный режим разрешается в full

Примечания:

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

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

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

Пример:

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

Обработка PATH¶

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

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

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

UI управления: вкладка Nodes включает небольшую панель «Exec node binding» с теми же настройками.

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

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

Пример:

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

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

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

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

Агенты в sandbox могут требовать подтверждение для каждого запроса перед тем, как exec будет выполнен на хосте шлюза Gateway или хосте узла. См. Подтверждения Exec — политика, allowlist и поток UI.

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

Allowlist + безопасные бинарники¶

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

Примеры¶

На переднем плане:

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