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

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

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

Быстрая отладка

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

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

Он выводит:

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

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

Изоляция контролируется через agents.defaults.sandbox.mode:

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

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

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

  • docker.binds пробивает файловую систему песочницы: всё, что вы монтируете, видно внутри контейнера с режимом, который вы установили (:ro или :rw).
  • По умолчанию используется чтение-запись, если вы опускаете режим; предпочитайте :ro для исходников/секретов.
  • scope: "shared" игнорирует привязки для отдельных агентов (применяются только глобальные привязки).
  • Привязка /var/run/docker.sock фактически передаёт управление хостом в песочницу; делайте это только намеренно.
  • Доступ к рабочей области (workspaceAccess: "ro"/"rw") независим от режимов привязки.

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

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

  • Профиль инструмента: 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 только изменяет настройки сессии по умолчанию для авторизованных отправителей; он не предоставляет доступ к инструментам. Ключи инструментов провайдера принимают либо provider (например, google-antigravity), либо provider/model (например, openai/gpt-5.2).

Группы инструментов (сокращения)

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

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"]
      }
    }
  }
}

Доступные группы:

  • group:runtime: exec, bash, process
  • group:fs: read, write, edit, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory: memory_search, memory_get
  • group:ui: browser, canvas
  • group:automation: cron, gateway
  • group:messaging: message
  • group:nodes: nodes
  • group:openclaw: все встроенные инструменты OpenClaw (исключая плагины провайдеров)

Повышенные права: только exec "запуск на хосте"

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

  • Если вы в песочнице, /elevated on (или exec с elevated: true) выполняется на хосте (могут всё ещё применяться одобрения).
  • Используйте /elevated full для пропуска одобрений exec для сессии.
  • Если вы уже работаете напрямую, повышенные права фактически не имеют эффекта (всё равно контролируются).
  • Повышенные права не ограничены навыком и не переопределяют allow/deny инструментов.
  • /exec отдельный от повышенных прав. Он только настраивает настройки exec по умолчанию для сессии для авторизованных отправителей.

Шлюзы:

  • Включение: tools.elevated.enabled (и опционально agents.list[].tools.elevated.enabled)
  • Белые списки отправителей: tools.elevated.allowFrom.<provider> (и опционально agents.list[].tools.elevated.allowFrom.<provider>)

Смотрите Elevated Mode.

Общие исправления "sandbox jail"

"Инструмент 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 для отдельного агента)

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

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

← Назад к документации