沙箱 - Qoder

沙箱（Sandbox）让 Qoder CLI 在受限的隔离环境中执行命令与工具，从而降低误操作或不受信任代码带来的风险。启用沙箱后，命令的文件系统访问、网络访问会被限制在设定的边界内，超出边界的操作会被拒绝。沙箱适合在处理不受信任的代码、执行有潜在风险的命令，或希望为自动化流程加一层防护时使用。本页介绍沙箱的启用方式、隔离能力与相关配置。

启用沙箱

有三种方式启用沙箱，优先级为：环境变量 > 命令行参数 > 配置文件。

命令行参数

-s, --sandbox 是布尔开关，仅用于开启沙箱，不接受后端名：

qodercli --sandbox

使用哪个后端由环境变量 QODER_SANDBOX 或配置文件决定；两者都未指定时按平台自动探测（见下文）。

环境变量

export QODER_SANDBOX=docker
qodercli

配置文件

在 settings.json 中设置（修改后需重启）：

{
  "tools": {
    "sandbox": "docker"
  }
}

或使用对象形式做更细的控制：

{
  "tools": {
    "sandbox": {
      "enabled": true,
      "command": "docker",
      "image": "custom/image:tag",
      "allowedPaths": ["/tmp"],
      "networkAccess": false
    }
  }
}

如果检测到已经处于沙箱内部（SANDBOX 环境变量已设置），Qoder CLI 不会再次嵌套启用沙箱。

支持的沙箱后端

sandbox 可以设为布尔值、配置对象，或以下具体的沙箱命令之一：

命令	平台	说明
`docker`	Linux / 通用	使用 Docker 容器隔离（需安装 Docker）。
`podman`	Linux	Docker 的替代方案。
`sandbox-exec`	macOS	macOS 原生沙箱，在 macOS 上会被自动检测。
`runsc`	Linux	gVisor 隔离，需配合 Docker，仅 Linux 支持，且不会被自动检测。
`lxc`	Linux	LXC 容器，需要预先创建并运行，不会被自动检测。
`windows-native`	Windows	Windows 原生沙箱。

自动检测

当把 sandbox 设为 true 而未指定具体命令时，Qoder CLI 会按平台自动选择：在 macOS 上优先使用 sandbox-exec；否则依次尝试 docker、podman。若开启了沙箱但找不到可用命令，会报错提示安装 Docker/Podman 或显式指定命令。runsc 和 lxc 不会被自动检测，必须显式指定。

隔离能力

文件系统隔离

默认只把工作区目录挂载为可读写。
通过 tools.sandboxAllowedPaths（或对象配置中的 allowedPaths）可以额外授予对指定绝对路径的访问权限。
敏感文件和版本控制目录会被隔离在沙箱访问之外。

网络隔离

由 tools.sandboxNetworkAccess（或对象配置中的 networkAccess）控制，默认 false（禁止访问网络）。
当禁止网络访问或配置了沙箱代理时，会为沙箱创建内部网络，限制其对外连接。
通过环境变量 QODER_SANDBOX_PROXY_COMMAND 可以为沙箱内部请求配置代理命令，代理相关环境变量会被转发进沙箱。

命令执行

命令执行受安全检查约束，基于已知安全 / 危险命令的判定。
敏感环境变量在传入沙箱前会被清理，避免密钥泄露到隔离环境中。

沙箱镜像

对于容器类后端（docker / podman），可以指定自定义镜像：

配置对象中的 image 字段。
环境变量 QODER_SANDBOX_IMAGE（或默认镜像变量 QODER_SANDBOX_IMAGE_DEFAULT）。

若未指定，使用内置的默认镜像。原生沙箱（sandbox-exec、lxc、windows-native）不需要镜像。

工具级沙箱

除了对整个 CLI 进程做沙箱隔离，还可以启用更细粒度的工具级沙箱：

{
  "security": {
    "toolSandboxing": true
  }
}

security.toolSandboxing（默认 false，需重启）会隔离单个工具的执行，而不是整个 CLI 进程，适合只想约束特定高风险操作的场景。

变量	说明
`QODER_SANDBOX`	指定沙箱命令或开关。
`QODER_SANDBOX_IMAGE`	自定义沙箱镜像。
`QODER_SANDBOX_IMAGE_DEFAULT`	默认沙箱镜像。
`QODER_SANDBOX_PROXY_COMMAND`	沙箱内部代理命令。
`SANDBOX`	由沙箱环境注入，用于检测是否已处于沙箱内以避免嵌套（通常无需手工设置）。

下一步

理解权限与放行机制：权限与目录信任。
网络与代理配置：网络、代理与 VPC。
配置文件与生效顺序：配置文件与生效顺序。

​启用沙箱

​命令行参数

​环境变量

​配置文件

​支持的沙箱后端

​自动检测

​隔离能力

​文件系统隔离

​网络隔离

​命令执行

​沙箱镜像

​工具级沙箱

​相关环境变量

​下一步