Claude Code 沙箱架构详解：Agent 安全的基础设施

为什么 Agent 需要沙箱？

AI Agent 的核心能力是执行代码、操作文件、访问网络。但这也意味着风险：

• Prompt Injection：恶意内容可能诱导 Agent 执行非预期操作
• 权限滥用：Agent 可能读取敏感文件（~/.ssh、~/.aws）
• 数据泄露：Agent 可能将敏感信息发送到外部服务器

传统方案是"权限弹窗"——每个操作都需要用户批准。但这导致两个问题：

1. 审批疲劳：频繁弹窗让用户麻木，最终无脑点"允许"
2. 效率低下：Agent 无法自主完成复杂任务

沙箱的核心思想：与其事后审批，不如事前划定边界。让 Agent 在安全边界内自由操作，越界才触发警告。

---

Claude Code 沙箱：双重隔离架构

Claude Code 的沙箱设计遵循一个核心原则：

"就算 Agent 被 Prompt Injection 攻陷，也要让它什么都干不了。"

为什么需要双重隔离？

单一隔离存在绕过路径：

flowchart LR
    subgraph "只有文件隔离"
        A1[Agent 读取 ~/.ssh] --> A2[通过网络发送给攻击者]
        A2 --> A3[密钥泄露 ❌]
    end

flowchart LR
    subgraph "只有网络隔离"
        B1[Agent 修改 .bashrc] --> B2[埋入后门代码]
        B2 --> B3[用户下次登录中招 ❌]
    end

必须同时实现文件系统隔离和网络隔离，才能形成有效防护。

架构概览

flowchart TB
    subgraph Sandbox["沙箱边界"]
        Agent["Claude Code Agent"]
        FS["文件系统访问"]
        Net["网络请求"]
    end

    subgraph Outside["沙箱外部"]
        Proxy["网络代理服务器"]
        System["系统文件"]
        External["外部服务"]
    end

    Agent --> FS
    Agent --> Net

    FS -->|"只允许 CWD"| CWD["当前工作目录 ✅"]
    FS -->|"禁止访问"| System

    Net -->|"Unix Socket"| Proxy
    Proxy -->|"域名白名单过滤"| External

    style Sandbox fill:#e1f5fe
    style Outside fill:#fff3e0

---

文件系统隔离

默认权限模型

操作	默认行为	可配置
写入	仅允许当前工作目录及子目录	可添加额外允许路径
读取	允许全部（除 deny list）	可配置禁止读取的路径

关键保护

• 系统文件：无法修改 /bin/、/etc/、.bashrc 等
• 敏感凭证：可配置禁止读取 ~/.ssh、~/.aws、~/.config/gcloud
• 子进程继承：所有由 Agent 启动的脚本、程序都继承相同限制

配置示例

{
  "sandbox": {
    "permissions": {
      "fs": {
        "write": {
          "allow": [".", "/tmp/agent-workspace"]
        },
        "read": {
          "deny": ["~/.ssh", "~/.aws", "~/.config"]
        }
      }
    }
  }
}

---

网络隔离

网络隔离的设计最为精妙——不是简单的防火墙规则，而是完全切断网络，只留受控出口。

架构设计

flowchart LR
    subgraph Sandbox["沙箱内部（无网络）"]
        Agent["Agent 进程"]
    end

    subgraph Bridge["受控通道"]
        Socket["Unix Socket"]
    end

    subgraph Outside["沙箱外部"]
        Proxy["Proxy Server"]
        Allowlist["域名白名单"]
        Log["审计日志"]
    end

    subgraph Internet["互联网"]
        API["api.anthropic.com ✅"]
        GitHub["github.com ✅"]
        Attacker["attacker.com ❌"]
    end

    Agent -->|"唯一出口"| Socket
    Socket --> Proxy
    Proxy --> Allowlist
    Proxy --> Log
    Allowlist -->|"允许"| API
    Allowlist -->|"允许"| GitHub
    Allowlist -->|"拒绝"| Attacker

    style Sandbox fill:#ffebee
    style Outside fill:#e8f5e9

工作原理

1. 网络 Namespace 移除：Linux 下使用 bubblewrap 移除网络命名空间，Agent 进程完全没有网络接口
2. Unix Socket 通信：唯一的"出口"是一个 Unix Domain Socket，连接到沙箱外部的 Proxy
3. Proxy 过滤：Proxy 负责：
   • 域名白名单验证
   • 流量审计日志
   • 新域名的用户确认

为什么这样设计？

即使 Agent 被完全攻陷，它也无法将数据发送到任意服务器——所有流量必须经过 Proxy，而 Proxy 只允许白名单域名。

---

OS 级强制执行

沙箱限制不是应用层实现，而是内核级强制：

平台	技术	原理
Linux	bubblewrap	使用 Linux namespaces 实现轻量级容器化
macOS	Seatbelt (sandbox-exec)	使用内核级沙箱 profile 限制系统调用

为什么选择 OS 原语？

1. 无法绕过：限制在内核层执行，用户态代码无法绑架
2. 子进程继承：Agent 启动的任何脚本、程序都自动继承限制
3. 性能优异：比 Docker 更轻量，无需启动容器

---

效果：权限弹窗减少 84%

Anthropic 内部测试数据：

启用沙箱后，权限弹窗减少了 84%。

这意味着：

• Agent 可以更自主地完成任务
• 用户不再被频繁打断
• 真正需要关注的操作（越界请求）更容易识别

---

如何启用沙箱

Claude Code 命令行

# 打开沙箱配置菜单
/sandbox

沙箱模式

模式	行为
Auto-Allow	Bash 命令自动在沙箱内运行，无需审批
Regular Permissions	所有命令走标准权限流程，但仍受沙箱限制

配置文件

完整配置示例（settings.json）：

{
  "sandbox": {
    "permissions": {
      "fs": {
        "write": { "allow": ["."] },
        "read": { "deny": ["~/.ssh", "~/.aws"] }
      },
      "network": {
        "allow": [
          "api.anthropic.com",
          "github.com",
          "registry.npmjs.org"
        ]
      }
    },
    "allowUnsandboxedCommands": true
  }
}

---

Agent SDK：生产环境部署选项

对于需要在服务端部署 Agent 的场景，Claude Agent SDK 提供了多层次的隔离方案：

隔离技术对比

flowchart TB
    subgraph Options["隔离方案（从轻到重）"]
        SR["Sandbox Runtime<br/>轻量级，OS 原语"]
        Docker["Docker + 安全配置<br/>容器化，共享内核"]
        gVisor["gVisor<br/>用户态系统调用拦截"]
        VM["Firecracker / VM<br/>硬件级隔离"]
    end

    SR --> |"隔离强度 ⬆️<br/>性能开销 ⬆️"| Docker
    Docker --> gVisor
    gVisor --> VM

方案	隔离强度	性能开销	复杂度	适用场景
Sandbox Runtime	Good	极低	低	开发环境、CI/CD
Docker	中等	低	中	通用生产环境
gVisor	优秀	中高	中	多租户、处理不可信内容
Firecracker/VM	优秀	高	高	最高安全要求

Docker 安全配置示例

docker run \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --read-only \
  --network none \
  --memory 2g \
  --cpus 2 \
  -v /path/to/code:/workspace:ro \
  -v /var/run/proxy.sock:/var/run/proxy.sock:ro \
  agent-image

关键配置说明：

选项	作用
--cap-drop ALL	移除所有 Linux capabilities
--network none	完全禁用网络，通过 Unix socket 通信
--read-only	文件系统只读
-v ...:/workspace:ro	代码目录只读挂载

---

开源 Sandbox Runtime

Anthropic 已将沙箱运行时开源：

npm install @anthropic-ai/sandbox-runtime

使用方式

# 在沙箱中运行命令
npx @anthropic-ai/sandbox-runtime <command>

仓库地址

github.com/anthropic-experimental/sandbox-runtime

这个 runtime 实现了：

• 跨平台支持（Linux bubblewrap / macOS Seatbelt）
• 文件系统隔离（allow/deny 配置）
• 网络隔离（内置 HTTP/SOCKS5 proxy）
• 违规追踪和监控

---

第三方沙箱生态

除了 Anthropic 官方方案，社区也提供了多种沙箱选择：

服务	特点	链接
E2B	云端沙箱，毫秒级启动	e2b.dev
Cloudflare Sandbox SDK	边缘计算沙箱	Cloudflare Docs
Koyeb Sandboxes	全托管隔离环境	Koyeb
Vercel Sandbox	Serverless 沙箱	Vercel
Docker 方案	本地 Docker 容器	GitHub

---

安全限制与注意事项

沙箱不是万能的，了解其限制很重要：

已知限制

限制	说明
流量不检查内容	Proxy 只验证域名，不检查请求内容
Domain Fronting	理论上可通过 CDN 域名转发绕过
Unix Socket 风险	如允许 Docker socket，可能获得宿主机权限
过宽的写权限	如果允许写 ~/.bashrc，仍可能被利用

最佳实践

1. 最小权限原则：只允许必需的目录和域名
2. 敏感文件禁读：明确 deny ~/.ssh、~/.aws 等
3. 审计日志：定期检查 Proxy 日志发现异常
4. 分层防御：沙箱 + IAM + 网络策略组合使用

---

兼容性说明

部分工具与沙箱不兼容：

工具	问题	解决方案
watchman	需要特殊文件系统权限	使用 jest --no-watchman
docker	需要宿主机访问	加入 excludedCommands
部分 CLI 工具	需要网络/文件系统访问	授予特定权限

---

总结

Claude Code 的沙箱架构体现了一个核心设计哲学：

防御性设计：假设 Agent 可能被攻陷，确保即使被攻陷也造不成破坏。

关键要点：

1. 双重隔离：文件系统 + 网络，缺一不可
2. OS 级强制：内核层执行，无法绕过
3. 受控出口：网络完全切断，只通过 Proxy 出去
4. 开源可用：@anthropic-ai/sandbox-runtime 可直接使用

2026 年，沙箱将成为 Agent 产品的标配基础设施，不是可选项。

---

参考资料

官方文档

• Claude Code Sandboxing 工程博客
• Claude Code 沙箱文档
• Agent SDK 安全部署指南

开源项目

• Sandbox Runtime
• bubblewrap

第三方服务

• E2B Sandbox
• Cloudflare Sandbox SDK

---

往期回顾

• Agent Skills 去哪找？这个站点收录了 5 万个
• Python 项目自动版本发布：从 Git Tag 到 PyPI
• Claude Skills 与 MCP：AI 能力扩展的两种哲学