Gateway

Песочница, политика инструментов и повышенные привилегии

Status: active

OpenClaw имеет три связанных, но разных механизма управления:

Песочница (agents.defaults.sandbox.* / agents.list[].sandbox.*) определяет, где запускаются инструменты (в песочнице или на хосте).
Политика инструментов (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) определяет, какие инструменты доступны и разрешены.
Повышенный режим (tools.elevated.*, agents.list[].tools.elevated.*) — это аварийный выход только для exec, позволяющий выполнять команды вне песочницы, когда сеанс изолирован (gateway по умолчанию или node, когда целью exec настроен node).

Быстрая диагностика

Используйте инспектор, чтобы узнать, что OpenClaw делает на самом деле:

bash

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Он выводит:

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

Песочница: где запускаются инструменты

Работа песочницы управляется параметром agents.defaults.sandbox.mode:

"off": всё запускается на хосте.
"non-main": только неосновные сеансы изолируются в песочнице (частая неожиданность для групп и каналов).
"all": всё запускается в песочнице.

agents.defaults.sandbox.workspaceAccess определяет, что доступно песочнице: "none", "ro" или "rw".

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

Подключения 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.<provider> (и при необходимости agents.list[].tools.elevated.allowFrom.<provider>)

См. раздел Повышенный режим.

Типичные способы выхода из «тюрьмы песочницы»

«Инструмент 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".

См. также

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

Was this useful?