Sandboxing в Qwen Code
Этот документ содержит руководство по использованию sandboxing в Qwen Code, включая необходимые условия, быстрый старт и настройку.
Необходимые условия
Перед использованием sandboxing необходимо установить и настроить Qwen Code:
npm install -g @qwen-code/qwen-code
Чтобы проверить установку:
qwen --version
Обзор sandboxing
Sandboxing изолирует потенциально опасные операции (например, shell-команды или изменения файлов) от вашей хост-системы, обеспечивая уровень безопасности между AI-операциями и вашим окружением.
Преимущества sandboxing:
- Безопасность: Предотвращает случайное повреждение системы или потерю данных.
- Изоляция: Ограничивает доступ к файловой системе только директорией проекта.
- Консистентность: Обеспечивает воспроизводимость окружений на разных системах.
- Безопасная работа: Снижает риски при работе с непроверенным кодом или экспериментальными командами.
Методы песочницы
Ваш идеальный метод песочницы может отличаться в зависимости от вашей платформы и предпочтительного решения для контейнеризации.
1. macOS Seatbelt (только macOS)
Легковесная встроенная песочница с использованием sandbox-exec
.
Профиль по умолчанию: permissive-open
— ограничивает запись вне директории проекта, но разрешает большинство других операций.
2. На основе контейнеров (Docker/Podman)
Кроссплатформенная песочница с полной изоляцией процессов.
Примечание: Требуется локальная сборка образа песочницы или использование опубликованного образа из реестра вашей организации.
Быстрый старт
# Включить песочницу с помощью флага команды
qwen -s -p "analyze the code structure"
# Использовать переменную окружения
export GEMINI_SANDBOX=true
qwen -p "run the test suite"
# Настроить в settings.json
{
"sandbox": "docker"
}
Конфигурация
Включение sandboxing (в порядке приоритета)
- Флаг команды:
-s
или--sandbox
- Переменная окружения:
GEMINI_SANDBOX=true|docker|podman|sandbox-exec
- Файл настроек:
"sandbox": true
вsettings.json
macOS Seatbelt профили
Встроенные профили (устанавливаются через переменную окружения SEATBELT_PROFILE
):
permissive-open
(по умолчанию): Ограничения на запись, сеть разрешенаpermissive-closed
: Ограничения на запись, сеть запрещенаpermissive-proxied
: Ограничения на запись, сеть через proxyrestrictive-open
: Строгие ограничения, сеть разрешенаrestrictive-closed
: Максимальные ограничения
Пользовательские флаги Sandbox
Для песочницы на основе контейнеров вы можете внедрить собственные флаги в команду docker
или podman
, используя переменную окружения SANDBOX_FLAGS
. Это полезно для расширенных конфигураций, например, для отключения функций безопасности в определенных сценариях использования.
Пример (Podman):
Чтобы отключить маркировку SELinux для монтирования томов, вы можете установить следующее:
export SANDBOX_FLAGS="--security-opt label=disable"
Несколько флагов можно указать в виде строки, разделенной пробелами:
export SANDBOX_FLAGS="--flag1 --flag2=value"
Обработка UID/GID в Linux
Песочница автоматически обрабатывает права пользователей в Linux. Переопределите эти права с помощью:
export SANDBOX_SET_UID_GID=true # Принудительно использовать UID/GID хоста
export SANDBOX_SET_UID_GID=false # Отключить сопоставление UID/GID
Устранение неполадок
Распространенные проблемы
“Operation not permitted”
- Операция требует доступа за пределы песочницы.
- Попробуйте использовать более разрешающий профиль или добавьте точки монтирования.
Отсутствующие команды
- Добавьте в собственный Dockerfile.
- Установите через
sandbox.bashrc
.
Проблемы с сетью
- Проверьте, что профиль песочницы разрешает сетевой доступ.
- Убедитесь, что настройки proxy корректны.
Режим отладки
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"
Замечания по безопасности
- Песочница снижает, но не устраняет все риски.
- Используйте максимально ограничительный профиль, который позволяет выполнять вашу работу.
- Накладные расходы контейнера минимальны после первой сборки.
- GUI-приложения могут не работать в песочнице.
Связанная документация
- Конфигурация: Полные опции конфигурации.
- Команды: Доступные команды.
- Устранение неполадок: Общие вопросы по устранению неполадок.