# 容器与 macOS 沙箱

> 选择 Docker、Podman 或 Seatbelt，核对参数解析、镜像和网络代理。

- 网址：https://funcoding.ai/agents/qwen-code/configuration/container-sandbox/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Qwen Code 官方文档：Sandbox](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/sandbox.md)

---
Docker、Podman 与 macOS Seatbelt 在沙箱环境中运行整个 CLI。Linux 工具级隔离另见[工具执行沙箱](https://funcoding.ai/agents/qwen-code/configuration/linux-sandbox/)，二者不要混用。

## 启用与参数

```bash
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 的源码安装限制见[自定义容器](https://funcoding.ai/agents/qwen-code/configuration/custom-sandbox/)。

## Seatbelt profile

通过 SEATBELT_PROFILE 选择：

| Profile | 行为 |
| --- | --- |
| permissive-open | 默认，限制写入，允许网络 |
| permissive-closed | 限制写入，关闭网络 |
| permissive-proxied | 限制写入，通过代理联网 |
| restrictive-open | 更严格限制，允许网络 |
| restrictive-closed | 更严格限制，关闭网络 |
| restrictive-proxied | 更严格限制，通过代理联网 |

自定义 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 和代理，不能仅凭主机能联网就断言容器可用。

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

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