Код и файлы: exec, файловые операции, apply_patch

27.04.2026 · 5 мин чтения · admin

Агент работает с кодом и файлами через четыре инструмента: exec (shell-команды), read/write/edit (файловые операции), apply_patch (многофайловые патчи) и code_execution (удалённый Python). Каждый решает свою задачу — от запуска скриптов до анализа данных.

Exec — запуск команд

exec запускает shell-команды в workspace. Поддерживает foreground и background выполнение через process.

Основные параметры

Параметр	По умолчанию	Описание
`command`	—	Shell-команда (обязательно)
`workdir`	cwd	Рабочая директория
`timeout`	1800	Таймаут в секундах
`yieldMs`	10000	Авто-background после N мс
`background`	false	Фоновый запуск сразу
`pty`	false	Псевдо-терминал (для TTY-only CLI)
`host`	auto	Где запускать: `auto`, `sandbox`, `gateway`, `node`
`security`	deny/full	Режим безопасности
`ask`	off	Поведение approval-промпта

Foreground vs Background

Foreground — команда выполняется, агент ждёт результат:

{ "tool": "exec", "command": "ls -la" }

Background — команда запускается в фоне, агент продолжает работу:

{ "tool": "exec", "command": "npm run build", "yieldMs": 1000 }

После background-запуска используйте process для управления:

poll — проверить статус
log — получить вывод
send-keys — отправить клавиши (как в tmux)
submit — отправить Enter
paste — вставить текст
kill — остановить

Где запускать (host)

Значение	Поведение
`auto`	Sandbox если активен, иначе gateway
`sandbox`	В контейнере-песочнице
`gateway`	На хосте Gateway
`node`	На подключённом устройстве

PTY (псевдо-терминал)

Параметр pty: true нужен для:

Интерактивных CLI (vim, htop, ssh)
TUI-приложений
Coding-агентов, которые ожидают TTY
Программ с цветным выводом

Без PTY команды, требующие терминал, могут зависнуть или выдать ошибку.

PATH и окружение

host=gateway — использует login-shell PATH
host=sandbox — запускает sh -lc внутри контейнера
host=node — env overrides ограничены, env.PATH отклоняется
env.PATH и loader overrides (LD_*, DYLD_*) блокируются для host execution

Для добавления путей в PATH:

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

File I/O — чтение, запись, редактирование

Три инструмента для работы с файлами:

Инструмент	Что делает
`read`	Читает файл (текст или изображение)
`write`	Создаёт или перезаписывает файл
`edit`	Точечная замена текста в файле

read

read(path="/path/to/file", offset=1, limit=100)

Поддерживает текстовые файлы и изображения (jpg, png, gif, webp)
Текстовые файлы обрезаются до 2000 строк или 50KB
offset и limit для чтения больших файлов частями

write

write(path="/path/to/file", content="содержимое")

Создаёт файл (и директории автоматически)
Перезаписывает существующий файл

edit

edit(path="/path/to/file", edits=[{"oldText": "старый", "newText": "новый"}])

Точечная замена уникального текста
Каждый oldText должен быть уникальным в файле
Нельзя делать перекрывающиеся замены

Когда использовать write vs edit

write — для полной перезаписи файла. Когда вы переписываете файл целиком или создаёте новый.

edit — для точечных правок. Когда нужно изменить конкретную строку или абзац, не трогая остальное.

Правило: read → edit для маленьких правок. write для больших изменений.

apply_patch — многофайловые патчи

apply_patch применяет структурированный патч для изменения нескольких файлов за раз. Идеально для multi-file или multi-hunk правок, где edit будет хрупким.

Формат патча

*** Begin Patch
*** Add File: path/to/new.txt
+line 1
+line 2
*** Update File: src/app.ts
@@
-old line
+new line
*** Delete File: obsolete.txt
*** End Patch

Возможности

Add File — создать новый файл
Update File — изменить существующий
Delete File — удалить файл
Move to: — переименовать файл (внутри Update File)
End of File — вставка в конец файла

Ограничения

По умолчанию только для OpenAI/OpenAI Codex моделей
workspaceOnly: true — патчи только внутри workspace
Пути поддерживают относительные (от workspace) и абсолютные

{
  "tools": {
    "exec": {
      "applyPatch": {
        "enabled": true,
        "workspaceOnly": true
      }
    }
  }
}

code_execution — удалённый Python

code_execution запускает песочничный Python на xAI Responses API. Это не локальное выполнение — код выполняется на серверах xAI.

Когда использовать

Вычисления и статистика
Обработка данных из web_search или x_search
Построение графиков
Быстрый анализ табличных данных

Когда НЕ использовать

Нужен доступ к локальным файлам
Нужен shell или репозиторий
Нужны подключённые устройства

Настройка

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "codeExecution": {
            "enabled": true,
            "model": "grok-4-1-fast",
            "maxTurns": 2,
            "timeoutSeconds": 30
          }
        }
      }
    }
  }
}

Пример использования

Используй code_execution чтобы рассчитать 7-дневную скользящую среднюю для этих чисел: ...

Exec approvals — контроль выполнения

Exec approvals — это guardrail для запуска команд на реальном хосте. Команды разрешены только когда policy + allowlist + (опционально) approval совпадают.

Режимы безопасности (security)

Режим	Поведение
`deny`	Блокировать все host exec
`allowlist`	Только разрешённые команды
`full`	Разрешить всё (YOLO)

Режимы одобрения (ask)

Режим	Поведение
`off`	Никогда не спрашивать
`on-miss`	Спрашивать когда нет в allowlist
`always`	Спрашивать всегда

Safe bins

safeBins — список stdin-only бинарников, которые работают в allowlist-режиме без явного allowlist:

По умолчанию: cut, uniq, head, tail, tr, wc

⚠️ Не добавляйте в safeBins интерпретаторы (python3, node, ruby, bash) — они могут выполнять произвольный код.

YOLO-режим

Для запуска без approval-промптов:

openclaw exec-policy preset yolo

Это установит security=full, ask=off в обоих слоях: конфигурации и host-approvals.

Когда YOLO безопасен

YOLO-режим подходит для:

Личного сервера с одним пользователем
CI/CD окружения
Разработческих машин

YOLO не безопасен для:

Публичных серверов
Машин с несколькими пользователями
Продакшен-окружений

Практические примеры

Запуск тестов:

exec(command="npm test", timeout=300)

Редактирование конфига:

read(path="config.json") → edit(path="config.json", edits=[...])

Многофайловый рефакторинг:

apply_patch(input="*** Begin Patch\n*** Update File: src/app.ts\n@@\n-old\n+new\n*** End Patch")

Анализ данных:

web_search("AI benchmarks 2026") → code_execution("сравни процентные изменения")

Частые ошибки

Команда зависла. Используйте timeout или yieldMs для автоматического background.
PTY не работает. Убедитесь что pty: true для интерактивных команд.
edit не находит текст. Проверьте уникальность oldText — он должен встречаться ровно один раз.
apply_patch не доступен. Работает только для OpenAI моделей. Используйте edit/write для других.

Что дальше

Автоматизация — cron, hooks, taskflow
Безопасность и доступ — sandboxing, tool policy
Инструменты: обзор — три уровня: tools, skills, plugins