Sandbox

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

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

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


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

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


qwen --version

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

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

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

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

Note

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

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

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

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

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

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

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

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

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

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

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

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

Выбор метода

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

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


# Включение песочницы через флаг команды
qwen -s -p "analyze the code structure"
 
# Или включение песочницы для текущей shell-сессии (рекомендуется для CI / скриптов)
export QWEN_SANDBOX=true   # true автоматически выбирает провайдера (см. примечания ниже)
qwen -p "run the test suite"
 
# Настройка в 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.

Настройка

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

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

Important

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

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

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

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

Профили macOS Seatbelt

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

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

Tip

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

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

Для использования пользовательского профиля Seatbelt:

Создайте в проекте файл с именем .qwen/sandbox-macos-<profile_name>.sb.
Задайте SEATBELT_PROFILE=<profile_name>.

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

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

Пример (Podman):

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


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

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


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

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

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

Задайте QWEN_SANDBOX_PROXY_COMMAND=<command>
Команда должна запускать прокси-сервер, слушающий порт :::8877

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

Рабочий пример прокси с allowlist-логикой см.: Example Proxy Script.

Обработка 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: используются бинарники хоста, но песочница может ограничивать доступ к некоторым путям.

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

Подробнее о настройке песочницы см. Customizing the sandbox environment.

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

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

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


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

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

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


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

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

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

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

Configuration: Полные параметры конфигурации.
Commands: Доступные команды.
Troubleshooting: Общее устранение неполадок.