Перейти к основному содержанию

​
Инструмент 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 отклоняются для выполнения на хосте. Если вам нужны дополнительные записи PATH на узле, настройте окружение службы хоста узла (systemd/launchd) или установите инструменты в стандартные расположения.
Привязка узла к агенту (используйте индекс агента из конфига): 
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, если каждый сегмент верхнего уровня не удовлетворяет allowlist (включая safe bins). Перенаправления по-прежнему не поддерживаются.

​
Примеры

На переднем плане: 
{ "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.
  • tools.exec.applyPatch.workspaceOnly по умолчанию имеет значение true (в пределах workspace). Установите значение false только если вы намеренно хотите, чтобы apply_patch записывал/удалял файлы за пределами каталога workspace.