配置沙盒策略

一次智能体运行是否被沙盒包裹，是在服务器启动时决定的（--sandbox）。 设置 → 服务器 → 诊断与隐私 下的 启用沙盒 开关和后端选择器，都是存储在你设备上的偏好设置。沙箱卡片的主机探测报告的，只是服务器主机能够包裹什么。

有两个控件能触达一次运行，本指南两个都会讲：设置 → 工作区 → 智能体权限 中的操作规则——它们决定智能体可以推送、打开或访问什么——以及服务器自己的 --sandbox 标志。

什么在约束一次智能体运行

有六样东西在约束智能体。第一样是操作系统沙盒，也是唯一有条件的一样—— 另外五样在每台主机上都成立。

边界	它的作用
操作系统沙盒	macOS 上是 Seatbelt，Linux 和 WSL2 上是 bubblewrap。包裹 Claude Code CLI、ACP 适配器和运行器的 `bash` 工具。在 Windows 上、以及在缺少 `bwrap` 和 `socat` 的 Linux 上缺席
它自己的工作树	每段对话都会得到一个写时复制检出。原始检出会作为拒绝写入路径并入这次运行，真正强制执行它的是沙盒
代理签发的凭据	凭据代理为每次运行签发一份环境，并在拆除时撤销它。其中的 GitHub 令牌可以读取但不能推送：推送会经由 Control Center，它会先询问推送规则
操作护栏	每个会改变状态的工具都会声明自己的效果类别，护栏会在调用运行前解析它们。没有连接任何批准者时，`prompt` 会被拒绝
环境净化	ACP 和运行器的 `bash` 工具会得到一个过滤后的环境。经由 `NoSandboxAdapter` 的 Claude Code 会继承宿主机环境
模式的工具面	只读模式会直接移除会改动工作树的工具，并钉住该模式自己的输出动词，使它仍然能够交付

有三件事比它们看上去更弱：

只有 内置运行器 会强制执行工具闸门、完成契约和结构性模式规则。 Claude Code 适配器不会。尤其是 Claude Code 以 --dangerously-skip-permissions 启动，因为非交互式的 claude -p 否则会永远阻塞在它自己的提示上——所以 Claude 自己的 read、write 和 edit 调用既不会被 Control Center 看到，也不会被它门控， bash 命令也只由一个读取命令行的钩子检查。沙盒开启的地方，它就是这些调用周围的边界。
运行器的进程内文件工具（read、write、edit、apply patch、search、 find、search_files）运行在服务器进程内部，因此没有任何沙盒配置档约束它们。只有 bash 工具会走受沙盒包裹的命令运行器。这些工具的边界是它们自身的路径限制加上操作护栏。
在没有后端的主机上，第一行完全不适用。ACP 和运行器的 bash 工具会回退到环境净化加上命令策略；Claude Code 则经由 NoSandboxAdapter 继承宿主机环境。服务器会在启动日志里说明这一点。在下面检查你自己的情况。

决定智能体可以推送什么

git push、GitHub、工单和网络都没有按智能体的开关。每一项都是一条操作规则：

规则	内置默认值	涵盖内容
推送到远程仓库	先询问	每一次推送到 GitHub 的 `git push`，无论使用哪个适配器
打开 pull request	先询问	`gh pr create` 以及 pull request 工具
发布评审或合并	先询问	`gh pr merge`、`gh pr review`、`gh pr comment`、`gh pr close`
写入外部跟踪器	先询问	经由 Control Center 工具和 `gh issue` 的工单写入
访问网络	允许	沙盒是否有网络，以及运行器的网页工具

打开 设置 → 工作区 → 智能体权限
选择范围——工作区、智能体或空间——然后在该规则所在的行上选择允许、先询问或拒绝

限定分支的推送规则，例如拒绝推送到 main 的规则，同样生效：参见护栏。

检查点：让智能体推送一个分支。设为先询问时，你会收到一条写明仓库和 ref 的审批请求；设为拒绝时，git 会打印 ! [remote rejected] <ref> (Control Center policy: …)。

每条规则如何作用于运行：

推送靠运行手里持有什么来强制执行。它的 GitHub 令牌是一个只读的 GitHub App 安装令牌，能读取内容并处理 pull request。它的 git 配置把每一次 GitHub 推送发往 cc_server 上的一个回环网关，网关先询问规则，然后才用一个智能体永远看不到的写入令牌转发推送。网关只转发到工作树自己的仓库，或与工作区关联的 GitHub 仓库。这对每个适配器都成立。
来自 shell 的 pull request 和 issue 会通过命令行被识别：在运行器的 bash 工具中，以及经由钩子在 Claude Code 的 Bash 工具中。隐藏命令的智能体（脚本、 eval、直接调用 API）能绕过这项检查，但绕不过推送网关。
工单密钥从不放入沙盒。智能体通过 Control Center 的 MCP 工具写工单，这些工具会询问规则。
网络在运行开始时解析一次。拒绝会关闭沙盒的网络；允许和先询问 会让它保持开启，而在先询问下，运行器的 web_fetch 和 web_search 工具仍会在每次调用时询问。只要网络开启，GitHub 就始终在出站允许列表中。

检查你的智能体运行是否被沙盒包裹

有两件事决定它，而且两件都在服务器上：主机是否提供后端，以及 --sandbox 是否开启。按这个顺序检查它们。

打开 设置 → 服务器 → 诊断与隐私
查看沙箱卡片。主机一项指的是运行 cc_server 的那台机器，而不是你正在看的这台机器。后端字段会列出 原生沙盒 （macOS 上的 Seatbelt，Linux 和 WSL2 上的 bubblewrap）或 无隔离。 生效中 一项是本设备的偏好，而不是服务器实际使用的包裹。
查看服务器的启动日志。它只会打印下面三行中的一行：
- agent sandbox ON 加上后端说明——运行会被包裹
- no OS-native agent sandbox on this host 加上可用的安装提示——运行不会被包裹
- agent sandbox DISABLED by --sandbox off——一次刻意的退出

GET /healthz 不会报告沙盒状态，因此启动日志才是检查手段。

要有意关闭沙盒——存在这个开关，正是因为有些主机上的配置档会出问题—— 请用 --sandbox off 启动服务器，或者设置 CC_SERVER_SANDBOX=off。默认值是 on，而 on 的含义是“主机有后端就用一个”，绝不是“必须有一个”。

有两种情况永远不会得到原生沙盒的包裹。在 Windows 上，原生探测始终报告不可用，也没有东西可安装——智能体派发会使用 none。microvm 后端是另一回事（交互式终端和隔离舱），并按它自己的运行时进行探测门控。在 Linux 和 WSL2 上，bwrap 和 socat 都必须位于 PATH 中；缺少它们时，探测会报告不可用，并指出缺失的软件包。

在安装了 bubblewrap 的 Linux/WSL2 上，对于智能体之后创建的文件，标准策略的密钥文件 glob 无法强制执行。这样的原生运行现在会失败，而不是静默忽略这些规则。因此，启动探测通过并不能保证 Linux 上的派发一定能启动。 --sandbox off 是一次刻意的无约束退出，而不是替代性的安全边界。

了解模式已经禁止了什么

模式按空间存储，并作为 模式预设 层输入护栏解析器。四种模式中有三种是只读的，而只读模式会直接拒绝十一种效果类别：

模式	工作树	被预设拒绝的
Agent（`chat`）	可写	无——适用内置默认值
Plan	只读	删除文件、写入工作树之外、创建提交、推送到远程仓库、创建 PR、发布或合并、写入外部跟踪器、安装软件包、运行进程、更改工作区结构、启动或操控隔离舱
Review	只读	同样这十一种。不能由用户选择——输入框只提供 Agent、Plan 和 Orchestrate
Orchestrate	只读	同样这十一种

网络访问和密钥访问被只读模式刻意地_不_拒绝：研究正是只读模式的全部意义。

在操作运行前要求批准

批准是一项护栏决定，而不是沙盒设置。

打开 设置 → 工作区 → 智能体权限
在工作区、智能体或空间作用域下，把该操作类别设为 先询问

一个 先询问 决定会打断这次运行并向你询问。在没有连接任何批准者时，它会失效即拒绝，该操作会被拒绝。完整的解析顺序见配置护栏。

故障排查

智能体无法推送，而我从未拒绝过它

看看 git 打印了什么。Control Center policy: … 表示某条规则拒绝了这次推送，或者一个先询问没有得到回应。… is not linked to this workspace 表示推送目标既不是工作树自己的仓库，也没有与工作区关联。 Control Center has no GitHub credential that can push … 表示该仓库没有安装 GitHub App，也没有能推送的回退凭据：在该仓库上安装这个 App，或连接 GitHub。

“沙箱”卡片报告没有原生沙盒

那么该主机上的智能体运行就不会被 Seatbelt 或 bubblewrap 包裹，剩下那些边界就是你全部的依靠。在 Linux 和 WSL2 上，安装两个缺失的工具—— sudo apt-get install bubblewrap socat——并重启服务器；启动日志随后应当显示沙盒已开启。在 Windows 上，没有原生后端可安装，因此请改为收紧护栏：参见配置护栏。

智能体触及了工作树之外的文件

是哪个工具触及了它，决定了这是否在意料之中。

运行器的进程内文件工具（read、write、edit、apply patch、search、find、 search_files）运行在服务器进程中，因此没有任何沙盒配置档适用于它们—— 它们的边界是自身路径限制加上护栏。在存在后端的地方，bash 命令或 Claude Code CLI 会被包裹，而无论哪种模式，你已注册的检出在那层包裹里都是拒绝写入的，包括它们经符号链接解析后的写法（在 macOS 上，经由 /tmp 或 /var/folders 抵达的路径会解析到 /private 之下，现在两种写法都会被拒绝）。在没有后端的主机上，这些都不适用。无论哪种情况，护栏都能直接拒绝 写入工作树之外。