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

Песочница

В этом документе описано, как запускать 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, если требуется полноценное пользовательское пространство Linux (например, для инструментов, требующих Linux-бинарников).
  • На Linux/Windows:
    • Используйте Docker или Podman.

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

# Enable sandboxing with command flag
qwen -s -p "analyze the code structure"
 
# Or enable sandboxing for your shell session (recommended for CI / scripts)
export QWEN_SANDBOX=true   # true auto-picks a provider (see notes below)
qwen -p "run the test suite"
 
# Configure in 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=<provider>
  3. Файл настроек: tools.sandbox в вашем settings.json (например, {"tools": {"sandbox": true}}).
Important

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

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

  • Флаг CLI: --sandbox-image <image>
  • Переменная окружения: QWEN_SANDBOX_IMAGE=<image>
  • Файл настроек: tools.sandboxImage в вашем settings.json (например, {"tools": {"sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1"}})

Порядок приоритета (от высшего к низшему):

  1. --sandbox-image
  2. QWEN_SANDBOX_IMAGE
  3. tools.sandboxImage
  4. Встроенный образ по умолчанию из пакета CLI (например, ghcr.io/qwenlm/qwen-code:<version>)

settings.env.QWEN_SANDBOX_IMAGE также работает как механизм общей инъекции переменных окружения, но tools.sandboxImage является предпочтительным параметром для постоянного хранения.

Профили macOS Seatbelt

Встроенные профили (задаются через переменную окружения 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"

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

Если вы хотите ограничить исходящий сетевой доступ только разрешёнными адресами (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   # Force host UID/GID
export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping

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

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

“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.

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

# Check environment
qwen -s -p "run shell command: env | grep SANDBOX"
 
# List mounts
qwen -s -p "run shell command: mount | grep workspace"

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

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

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

  • Configuration: Полные параметры конфигурации.
  • Commands: Доступные команды.
  • Troubleshooting: Общее устранение неполадок.
Last updated on
Кэширование токеновi18n