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

Песочница

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

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

Перед использованием песочницы необходимо установить и настроить Qwen Code:

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

Чтобы проверить установку:

qwen --version

Обзор изоляции в песочнице

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

Преимущества изоляции в песочнице:

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

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

Методы изоляции в песочнице

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

1. Seatbelt для macOS (только для 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 QWEN_SANDBOX=true   # значение true автоматически выбирает поставщика (см. примечания ниже)
qwen -p "запустить набор тестов"
 
# Настройка в файле settings.json
{
  "tools": {
    "sandbox": true
  }
}
Tip

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

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

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

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

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

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

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

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

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

Профили 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-<profile_name>.sb в вашем проекте.
  2. Установите переменную окружения SEATBELT_PROFILE=<profile_name>.

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

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

Пример (Podman):

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

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

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

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

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

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

  • Установите переменную окружения QWEN_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

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

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

«Операция запрещена»

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

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

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

Java недоступна в Docker-песочнице

Официальный Docker-образ Qwen Code намеренно минимален — это обеспечивает небольшой размер образа, повышенную безопасность и быструю загрузку. Разным пользователям требуются разные среды выполнения (Java, Python, Node.js и т. д.), поэтому включение всех сред в один образ непрактично. Следовательно, Java не включена по умолчанию в Docker-песочницу.

Если ваш рабочий процесс требует Java, вы можете расширить базовый образ, создав в своём проекте файл .qwen/sandbox.Dockerfile:

FROM ghcr.io/qwenlm/qwen-code:latest
 
RUN apt-get update && \
    apt-get install -y openjdk-17-jre && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

Затем пересоберите образ песочницы:

QWEN_SANDBOX=docker BUILD_SANDBOX=1 qwen -s

Дополнительные сведения о настройке песочницы см. в разделе Настройка среды песочницы.

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

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

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

DEBUG=1 qwen -s -p "команда отладки"

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

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

 
# Проверка окружения
qwen -s -p "выполнить команду оболочки: env | grep SANDBOX"
 
# Список точек монтирования
qwen -s -p "выполнить команду оболочки: mount | grep workspace"

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

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

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

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