沙盒与排障

Linux 工具执行沙盒（bwrap/Landlock）、macOS Seatbelt 与 Docker/Podman 沙盒、启用优先级，以及认证错误、退出码和调试的排障指南。

沙盒

沙盒把可能危险的操作（如 shell 命令或文件修改）与你的主机系统隔离，在 CLI 和你的环境之间提供安全屏障：安全（防止意外的系统损坏或数据丢失）、隔离（把文件系统访问限制在项目目录）、一致（确保跨不同系统的可复现环境）、稳妥（处理不受信任的代码或实验性命令时降低风险）。

Linux 工具执行沙盒

在 Linux 上，安装 bwrap（Bubblewrap）获得最强的受支持边界，然后在你的用户设置（~/.qwen/settings.json）里启用工具执行沙盒：

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

filesystem 和 network 是必需的；backend 默认 auto，先尝试 bwrap；bwrap 不可用且 network 为 open 时，auto 可以在内核支持的情况下使用捆绑的 Landlock 助手。CLI、模型传输、认证和会话存储留在主机上；shell、终端 !、提示 shell 插值、Monitor、Read/Write/Edit 以及受支持的嵌套进程内 Agent/Code Mode 在沙盒里执行。Landlock 报告 partial 强制程度：它限制路径名的读、写和目录变更，但不创建 PID 或网络命名空间，目前无法限制每一种元数据操作；它的可写设备面也更窄（授予对 /dev/null 的写入，但不像 bwrap 那样创建私有的 /dev 和 /proc 挂载）。工作区设置不能启用、禁用或修改这个策略，即使在受信任的项目里也不行；有效优先级是 System 高于 User 高于 SystemDefaults，选择一个完整的策略对象。这个初始公开模式支持普通的无头 CLI 和两种终端 UI；ACP、qwen serve 和 web 终端明确拒绝它。运行任务前检查并验证活动的边界：

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

报告会点名工具边界、请求的/有效的后端、强制程度、适用时的 Landlock ABI、工作区、文件系统和命令的网络策略；--verify 检查工作区写入等。从整个 CLI 的 bwrap 迁移：替换 --sandbox bwrap，并移除 tools.sandbox: "bwrap"、QWEN_SANDBOX=bwrap、QWEN_SANDBOX_NET 和 QWEN_SANDBOX_PROXY_COMMAND，然后如上配置 tools.executionSandbox。下面的 Docker、Podman 和 macOS Seatbelt 方法仍然在它们现有的环境里运行整个 CLI。

沙盒方法

macOS Seatbelt（仅 macOS）：用 sandbox-exec 的轻量内置沙盒。默认配置 permissive-open：限制项目目录之外的写入，但允许大多数其他操作和出站网络访问。适合快速、无需 Docker、对文件写入有强护栏。
基于容器（Docker/Podman）：带完整进程隔离的跨平台沙盒。默认 Qwen Code 使用发布的沙盒镜像（在 CLI 包里配置），按需拉取；容器沙盒把你的工作区和 ~/.qwen 目录挂载进容器，使认证和设置跨运行保持。适合在任何操作系统上提供强隔离、在已知镜像里获得一致的工具。

选择方法：在 macOS 上，想要轻量沙盒时用 Seatbelt（推荐给大多数用户），需要完整的 Linux 用户空间（如需要 Linux 二进制文件的工具）时用 Docker/Podman；在 Linux/Windows 上用 Docker 或 Podman。启用沙盒（按优先级顺序）：环境变量 QWEN_SANDBOX=true|false|docker|podman|sandbox-exec；命令标志 -s、--sandbox 或 --sandbox=<provider>；设置文件里的 tools.sandbox（如 {"tools": {"sandbox": true}}）。注意：设置了 QWEN_SANDBOX 时，它覆盖 CLI 标志和 settings.json。沙盒镜像（Docker/Podman）、macOS Seatbelt 配置、自定义沙盒标志、网络代理、UID/GID 处理和调试模式见官方沙盒文档。

排障

认证或登录错误

Qwen OAuth free tier was discontinued on 2026-04-15：原因是 Qwen OAuth 自 2026 年 4 月 15 日起不再可用；解决：运行 qwen → /auth 切换到其他认证方式（阿里云百炼的 API Key，或 Coding Plan）。
UNABLE_TO_GET_ISSUER_CERT_LOCALLY、UNABLE_TO_VERIFY_LEAF_SIGNATURE 或 unable to get local issuer certificate：你可能在拦截并检查 SSL/TLS 流量的企业网络防火墙后面，这通常需要让 Node.js 信任自定义根 CA 证书；解决：把 NODE_EXTRA_CA_CERTS 环境变量设为你企业根 CA 证书文件的绝对路径，如 export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt。
针对自签名端点的 Connection error. (cause: fetch failed)：你把 Qwen Code 指向了自托管服务器（例如 https:// 后面的本地模型），其 TLS 证书是自签名的，被 Node.js 拒绝；解决：优先用 NODE_EXTRA_CA_CERTS 信任该证书；在受信任的实验室/私有网络里不实际时，用 --insecure 标志跳过验证（如 qwen --insecure --openaiBaseUrl https://192.168.1.10:8080 ...），警告：禁用验证会失去对中间人攻击的保护，只对你完全信任的端点使用。
Device authorization flow failed: fetch failed：Node.js 无法到达 Qwen OAuth 端点（通常是代理或 SSL/TLS 信任问题）；解决：如果你仍在用 Qwen OAuth，通过 /auth 切到 API Key 或 Coding Plan；在代理后面时，用 qwen --proxy <url>（或 settings.json 里的 proxy 设置）设置代理；你的网络使用企业 TLS 检查 CA 时，如上设置 NODE_EXTRA_CA_CERTS。
认证失败后无法显示 UI：选择认证类型后认证失败的话，security.auth.selectedType 设置可能被持久化在 settings.json 里，重启时 CLI 可能卡在尝试用失败的方式认证；解决：清除 settings.json（~/.qwen/settings.json 或项目的 ./.qwen/settings.json）里的 security.auth.selectedType 字段并重启 CLI，让它再次提示认证。

退出码

Qwen Code 用特定退出码指示终止原因，对脚本和自动化尤其有用：41（FatalAuthenticationError，认证过程出错）、42（FatalInputError，给 CLI 的输入无效或缺失，仅非交互模式）、44（FatalSandboxError，沙盒环境出错，如 Docker、Podman 或 Seatbelt）、52（FatalConfigError，settings.json 无效或有错误）、53（FatalTurnLimitedError，达到会话的最大对话轮数，仅非交互模式）。

调试技巧

CLI 调试：对 CLI 命令使用 --verbose 标志（如可用）获得更详细的输出；检查 CLI 日志，通常在用户特定的配置或缓存目录里。
工具问题：特定工具失败时，尝试隔离问题，运行该工具所做的最简单版本的命令或操作；对 run_shell_command，先确认命令在你的 shell 里能直接工作；对文件系统工具，验证路径正确并检查权限。
IDE Companion 连不上、附件上传在反向代理后返回 HTTP 413 等问题，以及常见的错误信息，见官方的排障页；也可以在 GitHub 上搜索类似的已有 issue 或新建 issue。