--- read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change. status: active summary: 'Почему инструмент заблокирован: среда выполнения песочницы, политика разрешения и запрета инструментов и ограничения на выполнение команд с повышенными привилегиями' title: Песочница, политика инструментов и повышенные привилегии x-i18n: generated_at: "2026-07-13T18:13:16Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 2fce3dab337e89fc2b196f59e763a169d76206ce2695744e00252c158b161260 source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md workflow: 16 --- OpenClaw имеет три связанных, но разных механизма управления: 1. **Песочница** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) определяет, **где запускаются инструменты** (в песочнице или на хосте). 2. **Политика инструментов** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) определяет, **какие инструменты доступны и разрешены**. 3. **Повышенный режим** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) — это **аварийный выход только для exec**, позволяющий выполнять команды вне песочницы, когда сеанс изолирован (`gateway` по умолчанию или `node`, когда целью exec настроен `node`). ## Быстрая диагностика Используйте инспектор, чтобы узнать, что OpenClaw делает _на самом деле_: ```bash openclaw sandbox explain openclaw sandbox explain --session agent:main:main openclaw sandbox explain --agent work openclaw sandbox explain --json ``` Он выводит: - фактический режим и область песочницы, а также доступ к рабочему пространству - находится ли текущий сеанс в песочнице (основной или неосновной) - фактические разрешения и запреты инструментов песочницы (и их источник: агент, глобальная конфигурация или значение по умолчанию) - ограничения повышенного режима и пути к ключам для исправления ## Песочница: где запускаются инструменты Работа песочницы управляется параметром `agents.defaults.sandbox.mode`: - `"off"`: всё запускается на хосте. - `"non-main"`: только неосновные сеансы изолируются в песочнице (частая неожиданность для групп и каналов). - `"all"`: всё запускается в песочнице. `agents.defaults.sandbox.workspaceAccess` определяет, что доступно песочнице: `"none"`, `"ro"` или `"rw"`. Полную матрицу (область, подключения рабочего пространства, образы) см. в разделе [Песочница](/ru/gateway/sandboxing). ### Подключения bind (быстрая проверка безопасности) - `docker.binds` _пробивает_ файловую систему песочницы: всё подключённое становится доступно внутри контейнера в заданном режиме (`:ro` или `:rw`). - Если режим не указан, по умолчанию используется чтение и запись; для исходного кода и секретов предпочитайте `:ro`. - `scope: "shared"` игнорирует подключения отдельных агентов (применяются только глобальные подключения). - OpenClaw дважды проверяет источники подключений: сначала нормализованный исходный путь, затем путь после разрешения через наиболее глубокого существующего предка. Выход через родительский символьный путь не позволяет обойти проверки запрещённых путей или разрешённых корневых каталогов. - Несуществующие конечные пути также проверяются безопасным образом. Если `/workspace/alias-out/new-file` через родительскую символьную ссылку разрешается в запрещённый путь или за пределы настроенных разрешённых корневых каталогов, подключение отклоняется. - Подключение `/var/run/docker.sock` фактически передаёт песочнице управление хостом; делайте это только намеренно. - Доступ к рабочему пространству (`workspaceAccess`) не зависит от режимов подключений. ## Политика инструментов: какие инструменты существуют и могут вызываться Важны два уровня: - **Профиль инструментов**: `tools.profile` и `agents.list[].tools.profile` (базовый список разрешений) - **Профиль инструментов провайдера**: `tools.byProvider[provider].profile` и `agents.list[].tools.byProvider[provider].profile` - **Глобальная политика инструментов и политика отдельных агентов**: `tools.allow`/`tools.deny` и `agents.list[].tools.allow`/`agents.list[].tools.deny` - **Политика инструментов провайдера**: `tools.byProvider[provider].allow/deny` и `agents.list[].tools.byProvider[provider].allow/deny` - **Политика инструментов песочницы** (применяется только в песочнице): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` и `agents.list[].tools.sandbox.tools.*` Основные правила: - `deny` всегда имеет приоритет. - Если `allow` не пуст, всё остальное считается заблокированным. - Политика инструментов — окончательное ограничение: `/exec` не может разрешить запрещённый инструмент `exec`. - Политика инструментов фильтрует их доступность по имени; она не проверяет побочные эффекты внутри `exec`. Если `exec` разрешён, запрет `write`, `edit` или `apply_patch` не переводит команды оболочки в режим только для чтения. - `/exec` изменяет только значения сеанса по умолчанию для авторизованных отправителей; доступа к инструментам он не предоставляет. - Ключи инструментов провайдера принимают либо `provider` (например, `google-antigravity`), либо `provider/model` (например, `openai/gpt-5.4`). - Журналы Gateway содержат записи аудита `agents/tool-policy`, когда один из этапов политики инструментов удаляет инструменты или политика инструментов песочницы блокирует вызов. Используйте `openclaw logs`, чтобы увидеть метку правила, ключ конфигурации и имена затронутых инструментов. ### Группы инструментов (сокращения) Политики инструментов (глобальные, агентские и относящиеся к песочнице) поддерживают записи `group:*`, которые разворачиваются в несколько инструментов: ```json5 { tools: { sandbox: { tools: { allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"], }, }, }, } ``` Доступные группы: | Группа | Инструменты | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution` (`bash` принимается как псевдоним для `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | | `group:web` | `web_search`, `x_search`, `web_fetch` | | `group:ui` | `browser`, `canvas` | | `group:automation` | `heartbeat_respond`, `cron`, `gateway` | | `group:messaging` | `message` | | `group:nodes` | `nodes`, `computer` | | `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop` | | `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` | | `group:openclaw` | большинство встроенных инструментов OpenClaw (кроме примитивов файловой системы и среды выполнения `read`/`write`/`edit`/`apply_patch`/`exec`/`process`, `canvas` и плагинов провайдеров) | | `group:plugins` | все загруженные инструменты, принадлежащие плагинам, включая настроенные серверы MCP, предоставляемые через `bundle-mcp` | Для агентов, работающих только в режиме чтения, запретите `group:runtime`, а также инструменты, изменяющие файловую систему, если ограничение только для чтения не обеспечивается политикой файловой системы песочницы или отдельной границей хоста. Для серверов MCP в песочнице политика инструментов песочницы служит вторым разрешающим барьером. Если `mcp.servers` настроен, но при работе в песочнице отображаются только встроенные инструменты, добавьте `bundle-mcp`, `group:plugins` либо имя или шаблон инструмента MCP с префиксом сервера, например `outlook__send_mail` или `outlook__*`, в `tools.sandbox.tools.alsoAllow`, затем перезапустите или перезагрузите Gateway и снова получите список инструментов. Шаблоны серверов используют безопасный для провайдера префикс сервера MCP: символы, не относящиеся к `[A-Za-z0-9_-]`, заменяются на `-`; к именам, которые не начинаются с буквы, добавляется префикс `mcp-`; длинные или повторяющиеся префиксы могут сокращаться или получать суффикс. `openclaw doctor` сейчас проверяет эту структуру для серверов под управлением OpenClaw в `mcp.servers`. Серверы MCP, загруженные из манифестов встроенных плагинов или Claude `.mcp.json`, используют тот же барьер песочницы, но эта диагностика пока не перечисляет такие источники; если их инструменты исчезают в сеансах песочницы, используйте те же записи списка разрешений. ## Повышенный режим: «запуск на хосте» только для exec Повышенный режим **не** предоставляет дополнительные инструменты; он влияет только на `exec`. - Если вы находитесь в песочнице, `/elevated on` (или `exec` с `elevated: true`) выполняется вне песочницы (при этом подтверждение всё ещё может требоваться). - Используйте `/elevated full`, чтобы пропустить подтверждения exec для сеанса. - Если выполнение уже происходит напрямую, повышенный режим фактически ничего не меняет (ограничения всё равно применяются). - Повышенный режим **не** ограничен областью Skills и **не** переопределяет разрешения и запреты инструментов. - Повышенный режим не предоставляет произвольных переопределений между хостами из `host=auto`; он следует обычным правилам выбора цели exec и сохраняет `node` только тогда, когда настроенной целью или целью сеанса уже является `node`. - `/exec` не относится к повышенному режиму. Он лишь изменяет значения exec по умолчанию для сеанса у авторизованных отправителей. Ограничения: - Включение: `tools.elevated.enabled` (и при необходимости `agents.list[].tools.elevated.enabled`) - Списки разрешённых отправителей: `tools.elevated.allowFrom.` (и при необходимости `agents.list[].tools.elevated.allowFrom.`) См. раздел [Повышенный режим](/ru/tools/elevated). ## Типичные способы выхода из «тюрьмы песочницы» ### «Инструмент X заблокирован политикой инструментов песочницы» Ключи для исправления (выберите один вариант): - Отключить песочницу: `agents.defaults.sandbox.mode=off` (или `agents.list[].sandbox.mode=off` для отдельного агента) - Разрешить инструмент внутри песочницы: - удалите его из `tools.sandbox.tools.deny` (или `agents.list[].tools.sandbox.tools.deny` для отдельного агента) - либо добавьте его в `tools.sandbox.tools.allow` (или в список разрешений отдельного агента) - Проверьте запись `agents/tool-policy` в `openclaw logs`. В ней указан режим песочницы и правило разрешения или запрета, заблокировавшее инструмент. ### «Я думал, это основной сеанс. Почему он находится в песочнице?» В режиме `"non-main"` ключи групп и каналов _не_ являются основными. Используйте ключ основного сеанса (показанный командой `sandbox explain`) или переключитесь в режим `"off"`. ## См. также - [Песочница](/ru/gateway/sandboxing) — полный справочник по песочнице (режимы, области, бэкенды, образы) - [Песочница и инструменты для нескольких агентов](/ru/tools/multi-agent-sandbox-tools) — переопределения для отдельных агентов и порядок приоритетов - [Повышенный режим](/ru/tools/elevated)