Sandbox

В этом документе объясняется ограничение выполнения инструментов на Linux и существующие методы изоляции всего CLI.

Песочница выполнения инструментов на Linux

На Linux установите bwrap (Bubblewrap) в /usr/bin/bwrap (поддерживаемый системный путь) для наиболее строгой поддерживаемой границы, затем включите песочницу выполнения инструментов в ваших User настройках (~/.qwen/settings.json, или каталог, выбранный через QWEN_HOME) или администраторских System настройках:

{
  "tools": {
    "executionSandbox": {
      "backend": "auto",
      "filesystem": "workspace-write",
      "network": "closed"
    }
  }
}

filesystem и network обязательны. backend по умолчанию равен auto, который сначала пробует bwrap. Когда bwrap недоступен и network равен open, auto может использовать встроенный хелпер Landlock на ядрах с Landlock ABI 3 или новее. Установите backend в bwrap или landlock, чтобы требовать конкретную реализацию. Landlock не может применять network: closed или скрывать явные маскированные пути. Любое из этих требований отклоняет Landlock до запуска любой команды; автоматический фолбэк никогда не отбрасывает оставшуюся маску путей. Используйте read-only для запрета записи в рабочее пространство или workspace-write для разрешения записи внутри текущего канонического рабочего пространства. Каждая команда также получает собственное приватное временное пространство. Обычные настройки includeDirectories не предоставляют доступ на запись. Держите рабочее пространство отдельно от установки Qwen, каталогов пользовательской конфигурации и состояния выполнения.

CLI, транспорт модели, аутентификация и хранилище сессий остаются на хосте. Shell, терминальный !, интерполяция prompt shell, Monitor, Read/Write/Edit и поддерживаемые вложенные внутрипроцессные вызовы Agent/Code Mode используют ту же политику выполнения. С bwrap network: closed блокирует обычные соединения хоста/внешних IP из команд, тогда как open разделяет сеть хоста. Чтение остаётся широким: этот режим не скрывает секреты хоста и не обещает изолировать pathname Unix-сокеты и сервисы хоста. Approval и YOLO не расширяют политику файловой системы или сети. Стандартные потоки — это явные возможности, предоставленные вызывающей стороной: уже подключённый сокет, TTY или символьное устройство остаётся доступным даже при network: closed. Закрытая сеть не отзывает эти существующие дескрипторы; не предоставляйте подключение к сервису хоста как stdin, когда этот доступ нежелателен. stdin из файла хоста и именованного FIFO требует встроенного хелпера ввода Linux x64/arm64 и копируется через приватный потоковый Unix-сокет с закрытой половиной записи; смещения обычного файла продвигаются только на байты, потреблённые из этого сокета, а неактивный писатель FIFO не задерживает завершение команды. Читайте fd 0 напрямую: этот ввод является сокетом, а не FIFO, и его повторное открытие через /dev/stdin или /proc/self/fd/0 не поддерживается. SIGINT/SIGTERM отменяют команду, но всё ещё дренируют принятые байты stdout/stderr; закрытый вывод останавливает этот поток с кодом 141, пока другой допустимый вывод дренируется.

Landlock сообщает о partial применении, потому что он ограничивает pathname чтения, запись и мутации каталогов, но не создаёт пространства имён PID или сети и в настоящее время не может ограничить каждую операцию с метаданными, включая chmod, chown, расширенные атрибуты и временные метки. Команда Landlock может видеть процессы хоста и использует сеть хоста. Отсоединённые потомки сохраняют ограничения файловой системы Landlock, но не получают границу времени жизни пространства имён PID bwrap. Открытые файловые дескрипторы сохраняют свой существующий доступ. Qwen Code потоково передаёт stdin из файла хоста и именованного FIFO через приватный сокет только для чтения вместо передачи этих дескрипторов полезной нагрузке; сокеты, символьные устройства и анонимные каналы могут быть общими. Выходные стандартные потоки остаются явными назначениями вызывающей стороны. Дескриптор статуса выполнения закрывается при exec полезной нагрузки.

Landlock также имеет более узкую поверхность записываемых устройств: он предоставляет запись в /dev/null, но не создаёт приватные монтирования /dev и /proc bwrap. Открытие /dev/full или /dev/tty для записи и создание файлов в /dev/shm отклоняются, поэтому программы, требующие этих операций, могут завершиться с ошибкой. Используйте приватный временный каталог, доступный через TMPDIR, TMP и TEMP, для временных файлов. Уже открытые стандартные потоки, предоставленные вызывающей стороной, сохраняют свой существующий доступ. Зонд политики Landlock при запуске требует /usr/bin/true; хост, в котором он отсутствует, проваливает зонд, даже если его ядро поддерживает Landlock.

Настройки рабочего пространства не могут включать, отключать или изменять эту политику, даже в доверенном проекте. Эффективный приоритет: System выше User выше SystemDefaults, выбирая полный объект политики. Значения должны быть литералами; подстановки окружения, неизвестные поля и неполные объекты отклоняются. --bare и --safe-mode сохраняют ограничение оператора. Изменения требуют нового выполнения. Повреждённый или нечитаемый файл настроек SystemDefaults, User или System теперь блокирует запуск (код выхода конфигурации 52) вместо тихого сброса неизвестной политики в пустые настройки. Ошибка называет файл и действие по исправлению. Исправьте его JSON-объект или восстановите доступ на чтение, затем перезапустите. Копия User .corrupted является только справочной; исходный файл оператора никогда не очищается. Восстановление только для рабочего пространства остаётся доступным без ограничения оператора. Повреждённые связанные настройки рабочего пространства (включая связанный каталог .qwen или жёстко связанный файл) требуют ручного исправления; автоматическое восстановление отказывается до изменения оригинала или предыдущей копии повреждения. Допустимый связанный JSON остаётся читаемым.

Этот начальный публичный режим поддерживает обычный headless CLI и оба терминальных UI. ACP, qwen serve и веб-терминалы явно отклоняют его. MCP/LSP, исполняемые хуки/расширения, управление worktree/ареной, внешние агенты, спекулятивное выполнение, файловые контрольные точки, автоматическое обслуживание навыков/памяти и неперенесённые инструменты процесса или мутации отключены или отклонены. Обычные внутрипроцессные агенты того же рабочего пространства не могут добавлять хуки, серверы MCP, внешние исполнители или изоляцию worktree. Пользовательские команды статуса, внешние рендереры Markdown/изображений, обнаружение и подключение IDE, восстановление файлов и превью Git diff хоста отключены. Перемотка только для разговора остаётся доступной.

Явная диагностика оператора, такая как /doctor, открытие или редактирование файлов и папок через /memory и изменение настроек через /skills, остаётся доверенными действиями хоста. Эти команды управления не доступны как команды, вызываемые моделью. Выбор навыка заполняет поле ввода; отправка /skill-name в настоящее время сообщает об ошибке неподдерживаемого режима до подготовки аргументов или обновления записей использования. Выполнение команд навыков и модельный инструмент Skill остаются недоступными, пока их подготавливающие записи не будут ограничены. Автоматическое обслуживание памяти и навыков остаётся отключённым в этом выполнении, даже если вы измените их сохранённые настройки.

Проверьте и подтвердите активную границу перед запуском задачи:

qwen sandbox
qwen sandbox --verify
qwen sandbox -- sh -c 'printf "confined command\n"'
qwen -y -p "Update the project and run its tests"

Связанные Git worktree получают доступ на запись только к допущенному рабочему пространству. Метаданные общего каталога Git и worktree вне этого рабочего пространства остаются только для чтения; этот режим неявно не авторизует изменение метаданных репозитория другого checkout. Операции, требующие этих записей, могут быть отклонены.

Отчёт называет границу инструмента, запрошенный/эффективный бэкенд, уровень применения, Landlock ABI, если применимо, рабочее пространство, файловую систему и политику сети команд. --verify проверяет запись в рабочее пространство, отклонение против файла, заведомо записываемого на хосте, ожидаемое приватное или общее пространство имён PID и выбранное сетевое пространство имён. Пройденный зонд бэкенда устанавливает допуск, а не аутентифицированную жизнеспособность полной сессии при всех унаследованных настройках окружения. Запустите обычную задачу после этого, чтобы протестировать её необходимые инструменты и сервисы. Если проверка не может создать свою временную фикстуру на стороне хоста, проверьте TMPDIR и разрешения каталога; это отдельно от отказа границы. Ошибки настройки бэкенда возникают до выполнения полезной нагрузки и никогда не перезапускают команду на хосте. Подкоманда одной команды пересылает буквальные аргументы и перенаправленный stdin, сохраняя stdout и stderr побайтно; используйте терминальный ! для интерактивных команд PTY.

Миграция с whole-CLI bwrap

Замените --sandbox bwrap и удалите tools.sandbox: "bwrap", QWEN_SANDBOX=bwrap, QWEN_SANDBOX_NET и QWEN_SANDBOX_PROXY_COMMAND, затем настройте tools.executionSandbox как указано выше. Перезапустите из shell вне старой песочницы; унаследованный SANDBOX=bwrap отклоняется. proxied не является поддерживаемой политикой сети. Не комбинируйте этот режим с Docker, Podman, Seatbelt или унаследованным маркером whole-CLI песочницы. Старые настройки bwrap дают явную ошибку миграции.

Методы Docker, Podman и macOS Seatbelt ниже по-прежнему запускают весь CLI в их существующем окружении.

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

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

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

Чтобы проверить установку:

qwen --version

Обзор изолированной среды

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

Преимущества изолированной среды:

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

Методы изоляции

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

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
  }
}

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

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

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

--sandbox и -s принимают необязательное значение: true, false, docker, podman или sandbox-exec. Для автоматического выбора с prompt используйте qwen --sandbox=true "query" или qwen --sandbox -p "query". В отличие от старого парсера только с булевыми значениями, qwen --sandbox "query" теперь обрабатывает query как значение бэкенда и отклоняет неизвестный бэкенд. Опции перед -- используют ту же грамматику даже после позиционных слов; используйте -p "..." для буквального текста опции внутри prompt. -- останавливает разбор опций, но его завершающие токены не пересылаются как prompt команды по умолчанию. Флаги песочницы сессии не принимаются для подкоманд управления, чьи алиасы -s сохраняют своё собственное значение.

Настройка образа изоляции (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 является предпочтительной постоянной настройкой.

Пользовательские образы обслуживаются пользователем. Пересобирайте их с актуальной установкой Qwen Code, чтобы получать безопасные обновления; старые образы могут по-прежнему использовать свой оригинальный встроенный механизм обновления.

Профили macOS Seatbelt

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

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

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

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

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