Безопасность и изоляция

Песочница 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)
  • эффективный список разрешенных/запрещенных инструментов в песочнице (и откуда он пришел: агент/глобальный/по умолчанию)
  • шлюзы повышенного режима и пути ключей для исправления

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

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

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

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

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

  • docker.binds пробивает файловую систему песочницы: всё, что вы смонтируете, будет видно внутри контейнера с указанным режимом (:ro или :rw).
  • По умолчанию используется режим чтения-записи, если режим не указан; предпочтительнее :ro для исходного кода/секретов.
  • scope: "shared" игнорирует 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 изменяет только настройки сессии по умолчанию для авторизованных отправителей; он не предоставляет доступ к инструментам. Ключи инструментов провайдера принимают либо 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 для сессии.
  • Если вы уже запускаетесь напрямую, повышенный режим фактически ничего не меняет (всё равно контролируется шлюзами).
  • Повышенный режим не ограничен навыком (skill-scoped) и не отменяет разрешение/запрет инструментов.
  • /exec отделен от повышенного режима. Он только настраивает значения по умолчанию для exec в сессии для авторизованных отправителей.

Шлюзы:

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

См. Повышенный режим (Elevated Mode).

Частые исправления «изоляции в песочнице»

«Инструмент 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. Используйте ключ основной сессии (показывается sandbox explain) или переключите режим на "off".

Изоляция (Sandboxing)Протокол шлюза (Gateway Protocol)