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

Sandbox

В этом документе объясняется, как запускать Qwen Code в изолированной среде (sandbox), чтобы снизить риски при выполнении 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.

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

# Включение изоляции с помощью флага команды
qwen -s -p "проанализировать структуру кода"
 
# Или включение изоляции для вашей shell-сессии (рекомендуется для 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=<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, если ваш workflow всё ещё работает.

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

Java недоступна в Docker-изоляции

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

Если ваш workflow требует 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 "отладочная команда"

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

Проверка изолированной среды

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

Заметки по безопасности

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

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

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