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

Он выводит:

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

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

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

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

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

Bind-монтирования (быстрая проверка безопасности)

docker.binds пробивает файловую систему песочницы: все, что вы монтируете, видно внутри контейнера с заданным режимом (:ro или :rw).
По умолчанию используется чтение-запись, если режим опущен; предпочитайте :ro для исходного кода/секретов.
scope: "shared" игнорирует bind-монтирования для отдельных агентов (применяются только глобальные bind-монтирования).
OpenClaw проверяет источники bind-монтирования дважды: сначала нормализованный исходный путь, затем еще раз после разрешения через самый глубокий существующий предок. Выходы через родительские symlink не обходят проверки заблокированных путей или разрешенных корней.
Несуществующие конечные пути все равно проверяются безопасно. Если /workspace/alias-out/new-file разрешается через родительский symlink в заблокированный путь или за пределы настроенных разрешенных корней, bind-монтирование отклоняется.
Монтирование /var/run/docker.sock фактически передает песочнице управление хостом; делайте это только намеренно.
Доступ к рабочей области (workspaceAccess: "ro"/"rw") не зависит от режимов bind-монтирования.

Политика инструментов: какие инструменты существуют/могут вызываться

Важны два слоя:

Профиль инструментов: 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 не делает команды shell доступными только для чтения.
/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:runtime, а также инструменты, изменяющие файловую систему, если политика файловой системы песочницы или отдельная граница хоста не обеспечивает ограничение только для чтения.
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
group:agents: agents_list, update_plan
group:media: image, image_generate, music_generate, video_generate, tts
group:openclaw: все встроенные инструменты OpenClaw (исключая плагины провайдеров)
group:plugins: все загруженные инструменты, принадлежащие Plugin, включая настроенные MCP-серверы, предоставленные через bundle-mcp

Для 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-серверы, загруженные из манифестов bundled Plugin или Claude .mcp.json, используют тот же шлюз песочницы, но эта диагностика пока не перечисляет такие источники; используйте те же записи списка разрешений, если их инструменты исчезают в ходах в песочнице.

Повышенный режим: «запустить на хосте» только для exec

Повышенный режим не предоставляет дополнительные инструменты; он влияет только на exec.

Если вы в песочнице, /elevated on (или exec с elevated: true) запускается вне песочницы (одобрения все еще могут применяться).
Используйте /elevated full, чтобы пропустить одобрения exec для сеанса.
Если вы уже запускаетесь напрямую, повышенный режим фактически ничего не меняет (но все равно проверяется шлюзами).
Повышенный режим не ограничен Skills и не переопределяет allow/deny инструментов.
Повышенный режим не предоставляет произвольных межхостовых переопределений из 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 (или в поагентный allow)
Проверьте openclaw logs на запись agents/tool-policy. В ней фиксируется режим песочницы и то, какое правило allow или deny заблокировало инструмент.

«Я думал, что это main, почему он в песочнице?»

В режиме "non-main" ключи групп/каналов не являются main. Используйте ключ main-сеанса (показан в sandbox explain) или переключите режим на "off".

Связанные материалы

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

Was this useful?