Песочница

В этом документе объясняется, как запустить 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) и при необходимости загружает его.

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

Выбор метода

На 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.

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

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

Переменная окружения: GEMINI_SANDBOX=true|false|docker|podman|sandbox-exec
Флаг команды / аргумент: -s, --sandbox, или --sandbox=<провайдер>
Файл настроек: 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>).

Профили безопасности 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"

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

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

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

Это особенно полезно при использовании профилей Seatbelt с суффиксом *-proxied.

Рабочий пример прокси-скрипта со списком разрешенных адресов можно найти здесь: Пример прокси-скрипта.

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

Песочница автоматически управляет правами пользователей в Linux. Переопределите эти права с помощью:


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

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

Если вам нужны дополнительные инструменты внутри контейнера (например, git, python, rg), создайте собственный Dockerfile:

Путь: .qwen/sandbox.Dockerfile
Затем запустите с помощью: BUILD_SANDBOX=1 qwen -s ...

Это создаст образ, специфичный для проекта, на основе стандартного образа песочницы.

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

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

“Operation not permitted”

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

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

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

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

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

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


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"

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

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

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

Конфигурация: Полный список параметров конфигурации.
Команды: Доступные команды.
Устранение неполадок: Общие рекомендации по устранению проблем.