本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

沙盒模式

状态：生效 范围：当前状态 最近审阅：2026-08-23 负责人：ax-code 运行时

AX Code 包含内置的执行沙盒，可以限制 AI 代理在你的系统上做什么。默认情况下，AX Code 以 完全访问 启动且沙盒关闭，因此文件系统写入和网络访问不受限制。在处理不受信任的仓库或运行无人值守任务之前，请启用 workspace-write 或 read-only。

安全警告： full-access 不是安全边界。代理可以修改工作区之外的文件，写入 .git/ 和 .ax-code/，运行不受限制的 shell 命令，并访问网络。

快速开始

从 TUI 切换沙盒：

• 在提示中输入 /sandbox，或
• 按下 Ctrl+P 并搜索“沙盒”

状态栏显示当前状态：

• 沙盒开启（绿色）— 代理被限制在工作区内
• 沙盒关闭（红色）— 没有限制

该设置会跨会话保存在 ax-code.json 中。

有什么变化

配置

权威来源

本页总结面向用户的行为。行为变化时，请对照以下内容核验文档：

• packages/ax-code/src/isolation/index.ts：模式解析、受保护路径、网络检查、写入检查、bash 检查，以及 IsolationDeniedError。
• packages/ax-code/src/config/schema.ts：配置形状、默认值和说明。
• packages/ax-code/src/server/routes/isolation.ts：运行时切换行为与持久化。
• packages/ax-code/test/isolation/isolation.test.ts 与 packages/ax-code/test/tool/bash.test.ts：预期的强制执行行为。

根 README 中重复的说法保持简短，并链接回这里查看细节。

从 TUI 切换

使用 /sandbox 或命令面板（Ctrl+P → “打开/关闭沙盒”）。变更立即生效，并保存到项目的 ax-code.json。

CLI 标志

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

环境变量

AX_CODE_ISOLATION_MODE=workspace-write ax-code

配置文件

在 ax-code.json 中：

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

优先级

CLI 标志 > 环境变量 > 配置文件 > 默认值（full-access）

当 CLI 或环境覆盖处于活动状态时，TUI 会报告该有效模式。/sandbox 切换可以保存项目偏好，但更高优先级的覆盖会一直保持活动，直到它被移除（通常在重启时）。

隔离模式

受保护路径

在 workspace-write 模式下，这些路径始终受到写保护：

• .git/ — 防止意外破坏 git 状态
• .ax-code/ — 防止配置/插件被篡改

在配置中添加自定义受保护路径：

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

网络访问

网络在 workspace-write 和 read-only 模式下默认禁用。受影响的工具：

• webfetch — 已阻止
• websearch — 已阻止
• codesearch — 已阻止
• bash — 仅网络客户端（curl、wget、nc/ncat/netcat、telnet、ftp、tftp、scp、sftp、dig、nslookup、host）被阻止

限制： bash 中的网络阻止位于应用层，并覆盖上方那些专用网络客户端。它 不会 拦截也能离线工作的两用工具（git、npm/pnpm/yarn、pip、go，以及 python/node 这类语言解释器），因为它们的离线调用无法静态区分，阻止它们会破坏常见工作流。真正穷尽的网络隔离需要操作系统级控制，而这个沙盒并不提供。当碰到被拒绝的客户端时，代理会提示一次一次性升级。

要在保留写限制的同时允许网络：

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

隔离后端（应用与操作系统）

macOS： 通过 sandbox-exec 使用 Seatbelt 配置档（写入限制在工作区/工作树，当 network: false 时拒绝网络）。
Linux： 安装了 bubblewrap（bwrap）时使用它（网络禁用时为 --unshare-net，工作区以读写方式绑定挂载）。
Windows： 目前仅有应用层。

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

威胁模型见 安全说明 SECURITY.md。

仓库控制的权限与钩子

项目文件默认不受信任。ax-code.json、.ax-code/policy.json 中的权限规则，以及项目代理或模式定义，可以用 deny 收紧访问，但仓库控制的 allow/ask 授予会被忽略。项目命令不能启用 shell 展开。.ax-code/hooks.json、.ax-code/plugin/ 以及项目配置的插件不会被执行。

不受信任的项目配置也不能选择自定义 shell、可执行的 LSP 或格式化器、提供商包或 API 端点、提供商凭据环境变量、外部技能来源，或工作树之外的指令路径。安全的相对指令路径和不可执行的内置覆盖仍然可用。MCP 服务器使用单独的、带指纹的批准流程，见 MCP 集成。

审阅仓库控制的配置之后，用户可以在仓库之外为当前进程选择加入：

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

这个仅环境变量的开关防止某次检出把自己声明为受信任。

强制执行如何工作

沙盒强制执行 始终 在应用层，于每次工具调用时检查。当 backend 为 os 或 auto 且平台支持时，bash 还会被额外包进内核沙盒。

当工具违反隔离时，它会抛出 IsolationDeniedError，并附上清晰消息，说明被阻止的内容以及原因。