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=<провайдер>
  3. Файл настроек: tools.sandbox в вашем settings.json (например, {"tools": {"sandbox": true}}).
Important

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

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

  • Флаг CLI: --sandbox-image <образ>
  • Переменная окружения: QWEN_SANDBOX_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:<версия>)

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

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

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

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

Пример (Podman):

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

```bash
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

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

Частые проблемы

«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

Подробнее о настройке изолированного окружения см. Настройка изолированного окружения.

Сетевые проблемы

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

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

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

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

Просмотр изолированного окружения

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

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

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

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

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