Skip to Content
Руководство пользователяФункцииПесочница

Песочница

Этот документ объясняет, как запустить Qwen Code внутри песочницы, чтобы уменьшить риски при выполнении инструментами команд оболочки или изменении файлов.

Предварительные требования

Прежде чем использовать изоляцию в песочнице, вам нужно установить и настроить Qwen Code:

npm install -g @qwen-code/qwen-code

Для проверки установки

qwen --version

Обзор песочницы

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

Преимущества песочницы включают:

  • Безопасность: предотвращение случайного повреждения системы или потери данных.
  • Изоляция: ограничение доступа к файловой системе директорией проекта.
  • Согласованность: обеспечение воспроизводимости сред на разных системах.
  • Безопасность: снижение рисков при работе с ненадежным кодом или экспериментальными командами.
Note

Примечание по именованию: Некоторые переменные окружения, связанные с песочницей, все еще используют префикс GEMINI_* для обратной совместимости.

Методы песочницы

Ваш идеальный метод песочницы может отличаться в зависимости от вашей платформы и предпочитаемого решения контейнеризации.

1. macOS Seatbelt (только для macOS)

Легкая встроенная песочница с использованием sandbox-exec.

Профиль по умолчанию: permissive-open — ограничивает запись за пределами каталога проекта, но разрешает большинство других операций и исходящий сетевой доступ.

Наилучшее применение: Быстрая работа без использования Docker, надежные ограничения на запись файлов.

2. На основе контейнеров (Docker/Podman)

Кроссплатформенная песочница с полной изоляцией процессов.

По умолчанию Qwen Code использует опубликованный образ песочницы (настроенный в пакете CLI) и будет загружать его при необходимости.

Песочница контейнера монтирует ваше рабочее пространство и каталог ~/.qwen внутрь контейнера, чтобы аутентификация и настройки сохранялись между запусками.

Наилучшее применение: Сильная изоляция на любой ОС, согласованность инструментов внутри известного образа.

Выбор метода

  • В macOS:
    • Используйте Seatbelt, когда вам нужен легковесный песочник (рекомендуется для большинства пользователей).
    • Используйте Docker/Podman, когда вам нужна полная пользовательская среда Linux (например, инструменты, требующие двоичных файлов Linux).
  • В Linux/Windows:
    • Используйте Docker или Podman.

Быстрый старт

 
# Включить песочницу с помощью флага команды
qwen -s -p "анализировать структуру кода"
 
# Или включить песочницу для вашей сессии оболочки (рекомендуется для CI / скриптов)
export GEMINI_SANDBOX=true   # true автоматически выбирает поставщика (см. примечания ниже)
qwen -p "запустить тестовый набор"
 
# Настроить в settings.json
{
  "tools": {
    "sandbox": true
  }
}
Tip

Примечания по выбору поставщика:

  • В macOS, GEMINI_SANDBOX=true обычно выбирает sandbox-exec (Seatbelt), если он доступен.
  • В Linux/Windows, GEMINI_SANDBOX=true требует установки docker или podman.
  • Чтобы принудительно выбрать поставщика, установите GEMINI_SANDBOX=docker|podman|sandbox-exec.

Конфигурация

Включение песочницы (в порядке приоритета)

  1. Переменная окружения: GEMINI_SANDBOX=true|false|docker|podman|sandbox-exec
  2. Флаг команды / аргумент: -s, --sandbox или --sandbox=<provider>
  3. Файл настроек: tools.sandbox в вашем settings.json (например, {"tools": {"sandbox": true}}).
Important

Если переменная GEMINI_SANDBOX установлена, она переопределяет флаг CLI и settings.json.

Настройка образа песочницы (Docker/Podman)

  • Флаг CLI: --sandbox-image <image>
  • Переменная окружения: GEMINI_SANDBOX_IMAGE=<image>

Если вы не укажете ни один из них, Qwen Code использует образ по умолчанию, настроенный в пакете CLI (например, ghcr.io/qwenlm/qwen-code:<version>).

Профили Seatbelt в macOS

Встроенные профили (устанавливаются через переменную окружения SEATBELT_PROFILE):

  • permissive-open (по умолчанию): Ограничения на запись, сеть разрешена
  • permissive-closed: Ограничения на запись, сеть запрещена
  • permissive-proxied: Ограничения на запись, сеть через прокси
  • restrictive-open: Строгие ограничения, сеть разрешена
  • restrictive-closed: Максимальные ограничения
  • restrictive-proxied: Строгие ограничения, сеть через прокси
Tip

Начните с permissive-open, затем перейдите к restrictive-closed, если ваш рабочий процесс по-прежнему работает.

Пользовательские профили Seatbelt (macOS)

Чтобы использовать пользовательский профиль Seatbelt:

  1. Создайте файл с именем .qwen/sandbox-macos-<имя_профиля>.sb в вашем проекте.
  2. Установите SEATBELT_PROFILE=<имя_профиля>.

Пользовательские флаги песочницы

Для контейнерной изоляции вы можете внедрять пользовательские флаги в команду docker или podman, используя переменную окружения SANDBOX_FLAGS. Это полезно для расширенных конфигураций, например, для отключения функций безопасности в определенных сценариях использования.

Пример (Podman):

Чтобы отключить пометку SELinux для монтируемых томов, можно установить следующее:

export SANDBOX_FLAGS="--security-opt label=disable"

Можно указать несколько флагов в виде строки, разделенной пробелами:

export SANDBOX_FLAGS="--flag1 --flag2=value"

Проксирование сети (все методы песочницы)

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

  • Установите GEMINI_SANDBOX_PROXY_COMMAND=<команда>
  • Команда должна запускать прокси-сервер, который прослушивает порт :::8877

Это особенно полезно с профилями Seatbelt *-proxied.

Для рабочего примера прокси-сервера в стиле белого списка см.: Пример скрипта прокси.

Обработка UID/GID в Linux

В Linux Qwen Code по умолчанию включает сопоставление UID/GID, чтобы песочница работала под вашим пользователем (и повторно использовала смонтированный ~/.qwen). Переопределите с помощью:

export SANDBOX_SET_UID_GID=true   # Принудительно использовать UID/GID хоста
export SANDBOX_SET_UID_GID=false  # Отключить сопоставление UID/GID

Устранение неполадок

Распространенные проблемы

“Operation not permitted”

  • Операция требует доступа за пределами песочницы.
  • В macOS Seatbelt: попробуйте использовать более разрешающий SEATBELT_PROFILE.
  • В Docker/Podman: убедитесь, что рабочая область смонтирована и ваша команда не требует доступа за пределы каталога проекта.

Отсутствующие команды

  • Песочница контейнера: добавьте их через .qwen/sandbox.Dockerfile или .qwen/sandbox.bashrc.
  • Seatbelt: используются бинарные файлы хоста, но песочница может ограничивать доступ к некоторым путям.

Проблемы с сетью

  • Проверьте, разрешает ли профиль песочницы работу в сети.
  • Убедитесь в правильности настройки прокси.

Режим отладки

DEBUG=1 qwen -s -p "debug command"

Примечание: Если у вас есть DEBUG=true в файле .env проекта, это не повлияет на CLI из-за автоматического исключения. Используйте файлы .qwen/.env для настроек отладки Qwen Code.

Проверка песочницы

 
# Проверить окружение
qwen -s -p "run shell command: env | grep SANDBOX"
 
# Список монтирований
qwen -s -p "run shell command: mount | grep workspace"

Примечания по безопасности

  • Песочница снижает, но не устраняет все риски.
  • Используйте наиболее ограниченный профиль, который позволяет выполнять вашу работу.
  • Накладные расходы контейнера минимальны после первого скачивания/сборки.
  • Графические приложения могут не работать в песочнице.

Связанная документация

Last updated on
Кэширование токеновi18n