容器与 macOS 沙箱

Docker、Podman 与 macOS Seatbelt 在沙箱环境中运行整个 CLI。Linux 工具级隔离另见工具执行沙箱，二者不要混用。

启用与参数

qwen --sandbox=true -p "Analyze the project structure."

启用优先级是 QWEN_SANDBOX 环境变量 → --sandbox / -s → tools.sandbox。值支持 true、false、docker、podman、sandbox-exec；macOS 自动选择通常优先 Seatbelt，Linux/Windows 自动选择要求 Docker 或 Podman 已安装。

--sandbox 与 -s 接受可选值。因此 qwen --sandbox "query" 会把 query 当作后端名而报错；使用 --sandbox=true "query" 或 --sandbox -p "query"。提示内需要字面选项文本时用 -p。-- 后的词不会成为默认命令的 prompt，管理子命令也不接受会话沙箱参数。

容器镜像

默认使用 CLI 包指定的发布镜像，必要时拉取；工作区和 ~/.qwen 挂载进容器，以保留认证与设置。

镜像选择优先级为 --sandbox-image → QWEN_SANDBOX_IMAGE → tools.sandboxImage → 包内默认。settings.env 注入对应变量也有效，但长期配置优先用 tools.sandboxImage。自定义镜像需自行维护并更新其中 Qwen Code，以获得新的更新交接机制。

自定义工具与 BUILD_SANDBOX 的源码安装限制见自定义容器。

Seatbelt profile

通过 SEATBELT_PROFILE 选择：

自定义 profile 文件放在项目 .qwen/sandbox-macos-<profile_name>.sb，再设置 SEATBELT_PROFILE 为该名称。Seatbelt 使用主机程序，程序所在路径仍可能受 profile 限制。

容器标志与网络

SANDBOX_FLAGS 可给 Docker/Podman 追加标志。官方 Podman 示例 --security-opt label=disable 会关闭挂载的 SELinux labeling，应只在明确需要此兼容性调整时采用。

整进程沙箱可通过 QWEN_SANDBOX_PROXY_COMMAND 启动本地代理，要求监听 :::8877；适用于 proxied Seatbelt profile 等场景。这不是 Linux executionSandbox 的可用网络策略。

Linux 默认启用 UID/GID 映射；SANDBOX_SET_UID_GID=true 强制主机 UID/GID，false 禁用。挂载文件所有权异常时先检查这一设置。

常见故障

Operation not permitted 时核对被访问路径、挂载和 profile；缺命令时检查容器中是否安装，官方最小镜像默认不含 Java。网络失败时同时检查 profile 和代理，不能仅凭主机能联网就断言容器可用。

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

项目普通 .env 中 DEBUG 被默认排除；可使用专门的 .qwen/.env 或显式进程环境。GUI 应用可能不能在沙箱中正常运行。