Инструменты выполнения команд и одобрения

Что вы сможете сделать

Настроить инструмент exec для выполнения в трёх режимах (sandbox/gateway/node)
Понять и настроить механизмы безопасности одобрений (deny/allowlist/full)
Управлять списком разрешений (Allowlist) и безопасными bins
Одобрять запросы exec через UI или каналы чата
Устранять распространённые проблемы и ошибки безопасности инструмента exec

Ваша текущая дилемма

Инструмент exec позволяет ИИ-помощникам выполнять команды Shell, что является мощным, но и опасным：

Удастся ли ИИ удалить важные файлы в моей системе?
Как ограничить ИИ выполнением только безопасных команд?
В чём различия между разными режимами выполнения?
Как работает процесс одобрения?
Как должна быть настроена список разрешений?

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

Когда вам нужно, чтобы ИИ выполнял системные операции (управление файлами, компиляция кода)
Когда вы хотите, чтобы ИИ вызывал пользовательские скрипты или инструменты
Когда вам нужен точный контроль над правами выполнения ИИ
Когда вам нужно безопасно разрешить определённые команды

🎒 Подготовка перед началом

Предварительные требования

Это руководство предполагает, что вы завершили Запуск Gateway и демон Gateway работает.

Убедитесь, что установлено Node ≥22
Демон Gateway работает
Базовое понимание команд Shell и файловой системы Linux/Unix

Основные концепции

Три уровня безопасности инструмента exec

Инструмент exec использует трёхуровневый механизм безопасности для контроля прав выполнения ИИ, от грубого к точному：

Политика инструментов (Tool Policy)：контролирует, разрешён ли инструмент exec в tools.policy
Хост выполнения (Host)：команды выполняются в трёх средах sandbox/gateway/node
Механизм одобрений (Approvals)：в режимах gateway/node могут применяться дополнительные ограничения через allowlist и подсказки одобрения

Зачем нужна многоуровневая защита?

Одноуровневая защита легко обходится или неправильно настраивается. Многоуровневая защита гарантирует, что при сбое одного уровня другие уровни обеспечат защиту.

Сравнение трёх режимов выполнения

Режим выполнения	Место выполнения	Уровень безопасности	Типичные сценарии	Требуется одобрение
sandbox	Внутри контейнеров (например, Docker)	Высокий	Изолированная среда, тесты	Нет
gateway	Машина, где работает демон Gateway	Средний	Локальная разработка, интеграция	Да (allowlist + одобрение)
node	Пары устройства (macOS/iOS/Android)	Средний	Локальные операции устройства	Да (allowlist + одобрение)

Ключевые различия：

Режим sandbox по умолчанию не требует одобрения (но может быть ограничен Sandbox)
Режимы gateway и node по умолчанию требуют одобрения (если не настроены как full)

Следуйте инструкциям

Шаг 1: Понять параметры инструмента exec

Почему Понимание параметров инструмента exec является основой настройки безопасности.

Инструмент exec поддерживает следующие параметры：

json

{
  "tool": "exec",
  "command": "ls -la",
  "workdir": "/path/to/dir",
  "env": { "NODE_ENV": "production" },
  "yieldMs": 10000,
  "background": false,
  "timeout": 1800,
  "pty": false,
  "host": "sandbox",
  "security": "allowlist",
  "ask": "on-miss",
  "node": "mac-1"
}

Описание параметров：

Параметр	Тип	Значение по умолчанию	Описание
`command`	string	Обязательно	Выполняемая команда Shell
`workdir`	string	Текущий рабочий каталог	Каталог выполнения
`env`	object	Наследовать среду	Переопределение переменных среды
`yieldMs`	number	10000	Автоматически переходить в фон после таймаута (миллисекунды)
`background`	boolean	false	Немедленно выполнить в фоне
`timeout`	number	1800	Таймаут выполнения (секунды)
`pty`	boolean	false	Выполнять в псевдотерминале (поддержка TTY)
`host`	string	sandbox	Хост выполнения：`sandbox` \| `gateway` \| `node`
`security`	string	deny/allowlist	Политика безопасности：`deny` \| `allowlist` \| `full`
`ask`	string	on-miss	Политика одобрения：`off` \| `on-miss` \| `always`
`node`	string	-	ID или имя целевого узла в режиме node

Что вы должны увидеть：Список параметров ясно объясняет методы управления для каждого режима выполнения.

Шаг 2: Настроить режим выполнения по умолчанию

Почему Установка глобальных значений по умолчанию через файлы конфигурации позволяет избежать указания параметров при каждом вызове exec.

Отредактируйте ~/.clawdbot/clawdbot.json：

json

{
  "tools": {
    "exec": {
      "host": "sandbox",
      "security": "allowlist",
      "ask": "on-miss",
      "node": "mac-1",
      "notifyOnExit": true,
      "approvalRunningNoticeMs": 10000,
      "pathPrepend": ["~/bin", "/opt/homebrew/bin"],
      "safeBins": ["jq", "grep", "cut"]
    }
  }
}

Описание элементов конфигурации：

Элемент конфигурации	Тип	Значение по умолчанию	Описание
`host`	string	sandbox	Хост выполнения по умолчанию
`security`	string	deny (sandbox) / allowlist (gateway, node)	Политика безопасности по умолчанию
`ask`	string	on-miss	Политика одобрения по умолчанию
`node`	string	-	Узел по умолчанию в режиме node
`notifyOnExit`	boolean	true	Отправлять системное событие при завершении фоновых задач
`approvalRunningNoticeMs`	number	10000	Отправлять уведомление "выполняется" после таймаута (0 для отключения)
`pathPrepend`	string[]	-	Список каталогов для добавления в PATH
`safeBins`	string[]	[Список по умолчанию]	Список безопасных bins (только операции stdin)

Что вы должны увидеть：После сохранения конфигурации инструмент exec использует эти значения по умолчанию.

Шаг 3: Использовать переопределение сеанса `/exec`

Почему Переопределение сеанса позволяет временно настроить параметры выполнения без редактирования файла конфигурации.

Отправьте в чате：

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

Просмотреть текущие значения переопределения：

/exec

Что вы должны увидеть：Конфигурация параметров exec текущего сеанса.

Шаг 4: Настроить Allowlist (Список разрешений)

Почему allowlist является центральным механизмом безопасности в режимах gateway/node, позволяющим выполнять только определённые команды.

Редактировать allowlist

Редактировать через UI：

Откройте UI управления
Перейдите на вкладку Nodes
Найдите карточку Exec approvals
Выберите цель (Gateway или Node)
Выберите Агент (например, main)
Нажмите Add pattern, чтобы добавить шаблон команды
Нажмите Save, чтобы сохранить

Редактировать через CLI：

bash

clawdbot approvals

Редактировать через файл JSON：

Отредактируйте ~/.clawdbot/exec-approvals.json：

json

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/*",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/bin/rg"
        },
        {
          "id": "C1D9D1C4-3D3E-5F9B-0B4D-6B5C4D3E2F1G",
          "pattern": "/opt/homebrew/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg test",
          "lastResolvedPath": "/opt/homebrew/bin/rg"
        }
      ]
    }
  }
}

Описание режима Allowlist：

allowlist использует совпадение шаблонов glob (без учёта регистра)：

Шаблон	Совпадение	Описание
`~/Projects/*/bin/`	`/Users/user/Projects/any/bin/rg`	Совпадает со всеми подкаталогами
`~/.local/bin/*`	`/Users/user/.local/bin/jq`	Совпадает с локальным bin
`/opt/homebrew/bin/rg`	`/opt/homebrew/bin/rg`	Абсолютное совпадение пути

Важные правила

Совпадает только с разрешённым двоичным путём, не поддерживает совпадение базового имени (например, rg)
Цепочки Shell (&&, ||, ;) требуют, чтобы каждый сегмент удовлетворял allowlist
Перенаправления (>, <) не поддерживаются в режиме allowlist

Что вы должны увидеть：После настройки allowlist могут выполняться только совпадающие команды.

Шаг 5: Понять безопасные bins (Safe Bins)

Почему safe bins — это набор безопасных двоичных файлов, поддерживающих только операции stdin, которые могут выполняться в режиме allowlist без явного allowlist.

Безопасные bins по умолчанию：

jq, grep, cut, sort, uniq, head, tail, tr, wc

Характеристики безопасности безопасных bins：

Отклоняет аргументы файла позиции
Отклоняет флаги типа пути
Может работать только с переданным потоком (stdin)

Настроить пользовательские безопасные bins：

json

{
  "tools": {
    "exec": {
      "safeBins": ["jq", "grep", "my-safe-tool"]
    }
  }
}

Что вы должны увидеть：Команды безопасных bins могут выполняться напрямую в режиме allowlist.

Шаг 6: Одобрять запросы exec через каналы чата

Почему Когда UI недоступен, вы можете одобрять запросы exec через любой канал чата (WhatsApp, Telegram, Slack и т.д.).

Включить пересылку одобрений

Отредактируйте ~/.clawdbot/clawdbot.json：

json

{
  "approvals": {
    "exec": {
      "enabled": true,
      "mode": "session",
      "agentFilter": ["main"],
      "sessionFilter": ["discord"],
      "targets": [
        { "channel": "slack", "to": "U12345678" },
        { "channel": "telegram", "to": "123456789" }
      ]
    }
  }
}

Описание элементов конфигурации：

Элемент конфигурации	Описание
`enabled`	Включать ли пересылку одобрений exec
`mode`	`"session"` \| `"targets"` \| `"both"` - режим целей одобрения
`agentFilter`	Обрабатывать только запросы одобрения определённых агентов
`sessionFilter`	Фильтр сеанса (подстрока или regex)
`targets`	Список целевых каналов (`channel` + `to`)

Одобрить запросы

Когда инструменту exec требуется одобрение, вы получите сообщение со следующей информацией：

Exec approval request (id: abc-123)
Command: ls -la
CWD: /home/user
Agent: main
Resolved: /usr/bin/ls
Host: gateway
Security: allowlist

Опции одобрения：

/approve abc-123 allow-once     # Разрешить один раз
/approve abc-123 allow-always    # Всегда разрешать (добавить в allowlist)
/approve abc-123 deny           # Отклонить

Что вы должны увидеть：После одобрения команда выполняется или отклоняется.

Контрольная точка ✅

[ ] Вы понимаете различия между тремя режимами выполнения (sandbox/gateway/node)
[ ] Вы настроили глобальные параметры exec по умолчанию
[ ] Вы можете использовать переопределение сеанса команды /exec
[ ] Вы настроили allowlist (минимум один шаблон)
[ ] Вы понимаете характеристики безопасности безопасных bins
[ ] Вы можете одобрять запросы exec через каналы чата

Распространённые проблемы

Распространённые ошибки

Ошибка	Причина	Решение
`Command not allowed by exec policy`	`security=deny` или allowlist не совпадает	Проверьте `tools.exec.security` и конфигурацию allowlist
`Approval timeout`	UI недоступен, `askFallback=deny`	Установите `askFallback=allowlist` или включите UI
`Pattern does not resolve to binary`	Использование базового имени в режиме allowlist	Используйте полный путь (например, `/opt/homebrew/bin/rg`)
`Unsupported shell token`	Использование `>` или `&&` в режиме allowlist	Разделите команды или используйте `security=full`
`Node not found`	Узел не связан в режиме node	Сначала завершите связывание узлов

Цепочки и перенаправления Shell

Предупреждение

В режиме security=allowlist следующие функции Shell не поддерживаются：

Трубы：| (но || поддерживается)
Перенаправления：>, <, >>
Подстановка команд：$(), ` `
Фон：&, ;

Решения：

Используйте security=full (с осторожностью)
Разделите на несколько вызовов exec
Напишите сценарии-обёртки и добавьте путь сценария в allowlist

Переменные среды PATH

Разные режимы выполнения обрабатывают PATH по-разному：

Режим выполнения	Обработка PATH	Описание
`sandbox`	Наследует shell login, может быть сброшен `/etc/profile`	`pathPrepend` применяется после профиля
`gateway`	Сливает login shell PATH в среду exec	Демон сохраняет минимальный PATH, но exec наследует пользовательский PATH
`node`	Использует только переданные переопределения переменных среды	Узлы macOS отбрасывают переопределения `PATH`, headless-узлы поддерживают prepend

Что вы должны увидеть：Правильная настройка PATH влияет на поиск команд.

Резюме

Инструмент exec позволяет ИИ-помощникам безопасно выполнять команды Shell через трёхуровневый механизм защиты (политика инструментов, хост выполнения, одобрения)：

Режимы выполнения：sandbox (изоляция контейнера), gateway (локальное выполнение), node (операции устройства)
Политики безопасности：deny (полный запрет), allowlist (белый список), full (полное разрешение)
Механизм одобрений：off (без подсказки), on-miss (подсказка при несовпадении), always (всегда подсказывать)
Allowlist：совпадение шаблонов glob разрешённого двоичного пути
Безопасные bins：двоичные файлы, которые выполняют только операции stdin, освобождены от одобрения в режиме allowlist

Следующий урок

В следующем уроке мы изучим Инструменты веб-поиска и извлечения
Вы узнаете：
Как использовать инструмент web_search для веб-поиска
Как использовать инструмент web_fetch для извлечения содержимого веб-страниц
Как настроить провайдеры поисковых систем (Brave, Perplexity)
Как обрабатывать результаты поиска и ошибки веб-извлечения

Приложение: Справочник исходного кода

Нажмите, чтобы раскрыть местоположения исходного кода

Последнее обновление：2026-01-27

Функциональность	Путь файла	Номер строки
Определение инструмента exec	`src/agents/bash-tools.exec.ts`	1-500+
Логика одобрения exec	`src/infra/exec-approvals.ts`	1-1268
Анализ команд Shell	`src/infra/exec-approvals.ts`	500-1100
Совпадение Allowlist	`src/infra/exec-approvals.ts`	507-521
Проверка Safe bins	`src/infra/exec-approvals.ts`	836-873
Сокетная коммуникация одобрений	`src/infra/exec-approvals.ts`	1210-1267
Выполнение процессов	`src/process/exec.ts`	1-125
Schema конфигурации инструментов	`src/config/zod-schema.core.ts`	-

Ключевые типы：

ExecHost: "sandbox" \| "gateway" \| "node" - Тип хоста выполнения
ExecSecurity: "deny" \| "allowlist" \| "full" - Политика безопасности
ExecAsk: "off" \| "on-miss" \| "always" - Политика одобрения
ExecAllowlistEntry: Тип записи allowlist (содержит pattern, lastUsedAt и т.д.)

Ключевые константы：

DEFAULT_SECURITY = "deny" - Политика безопасности по умолчанию
DEFAULT_ASK = "on-miss" - Политика одобрения по умолчанию
DEFAULT_SAFE_BINS = ["jq", "grep", "cut", "sort", "uniq", "head", "tail", "tr", "wc"] - Безопасные bins по умолчанию

Ключевые функции：

resolveExecApprovals(): Разрешает конфигурацию exec-approvals.json
evaluateShellAllowlist(): Оценивает, удовлетворяет ли команда Shell allowlist
matchAllowlist(): Проверяет, совпадает ли путь команды с шаблоном allowlist
isSafeBinUsage(): Проверяет, является ли команда использованием безопасного bin
requestExecApprovalViaSocket(): Запрашивает одобрение через Unix-сокет

Начало работы с нуля

Интеграция с популярными мессенджерами

Разблокируйте сверхспособности AI

Что делать при возникновении проблем

Инструменты выполнения команд и одобрения

Что вы сможете сделать

Ваша текущая дилемма

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

🎒 Подготовка перед началом

Основные концепции

Три уровня безопасности инструмента exec

Сравнение трёх режимов выполнения

Следуйте инструкциям

Шаг 1: Понять параметры инструмента exec

Шаг 2: Настроить режим выполнения по умолчанию

Шаг 3: Использовать переопределение сеанса `/exec`

Шаг 4: Настроить Allowlist (Список разрешений)

Редактировать allowlist

Шаг 5: Понять безопасные bins (Safe Bins)

Шаг 6: Одобрять запросы exec через каналы чата

Включить пересылку одобрений

Одобрить запросы

Контрольная точка ✅

Распространённые проблемы

Распространённые ошибки

Цепочки и перенаправления Shell

Переменные среды PATH

Резюме

Следующий урок

Приложение: Справочник исходного кода

Инструменты выполнения команд и одобрения ​

Что вы сможете сделать ​

Ваша текущая дилемма ​

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

🎒 Подготовка перед началом ​

Основные концепции ​

Три уровня безопасности инструмента exec ​

Сравнение трёх режимов выполнения ​

Следуйте инструкциям ​

Шаг 1: Понять параметры инструмента exec ​

Шаг 2: Настроить режим выполнения по умолчанию ​

Шаг 3: Использовать переопределение сеанса /exec ​

Шаг 4: Настроить Allowlist (Список разрешений) ​

Редактировать allowlist ​

Шаг 5: Понять безопасные bins (Safe Bins) ​

Шаг 6: Одобрять запросы exec через каналы чата ​

Включить пересылку одобрений ​

Одобрить запросы ​

Контрольная точка ✅ ​

Распространённые проблемы ​

Распространённые ошибки ​

Цепочки и перенаправления Shell ​

Переменные среды PATH ​

Резюме ​

Следующий урок ​

Приложение: Справочник исходного кода ​

Инструменты выполнения команд и одобрения

Что вы сможете сделать

Ваша текущая дилемма

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

🎒 Подготовка перед началом

Основные концепции

Три уровня безопасности инструмента exec

Сравнение трёх режимов выполнения

Следуйте инструкциям

Шаг 1: Понять параметры инструмента exec

Шаг 2: Настроить режим выполнения по умолчанию

Шаг 3: Использовать переопределение сеанса `/exec`

Шаг 4: Настроить Allowlist (Список разрешений)

Редактировать allowlist

Шаг 5: Понять безопасные bins (Safe Bins)

Шаг 6: Одобрять запросы exec через каналы чата

Включить пересылку одобрений

Одобрить запросы

Контрольная точка ✅

Распространённые проблемы

Распространённые ошибки

Цепочки и перенаправления Shell

Переменные среды PATH

Резюме

Следующий урок

Приложение: Справочник исходного кода