Agent 从 Demo 走向生产环境，最容易被低估的一环就是沙箱。很多人把注意力全放在 Prompt 编排、工具调用链和记忆系统上，等到真正要跑用户提交的代码、执行模型生成的脚本时，才发现"让代码安全地跑起来"这件事本身就是一整套工程。花椒这套方案我在实际项目里跟过一段时间，它要解决的核心问题很明确：Agent 生成的代码不可信、不可控、可能死循环、可能读敏感文件、可能把内存吃满，而生产环境又要求这些代码必须能跑、跑得可观测、跑完能追溯。这篇就把花椒在选型、持久化和执行协议这三块上的实践拆开讲，顺带把 Go SDK 接入时那些文档里不会写的坑一并说清楚。

1. 为什么 Agent 沙箱不能直接拿本地进程凑合

1.1 本地 exec 的三个致命问题

刚开始做 Agent 项目的人，十有八九会这么干：拿到模型生成的代码，直接exec.Command或者subprocess.run跑一下，把 stdout 抓回来喂给模型。Demo 阶段这么写没问题，因为你自己写的测试用例都是善意的。但一旦接入真实用户，问题立刻暴露。

第一个问题是资源无边界。用户让 Agent 写个"计算斐波那契数列"的脚本，模型可能生成一个递归版本，n 稍微大一点直接把内存打爆，或者一个while True把 CPU 占满。本地进程跑这种代码，你的服务进程跟着一起遭殃。

第二个问题是文件系统裸奔。模型生成的代码里如果出现open('/etc/passwd')或者遍历家目录，本地进程是有权限读的。这不是模型"坏"，而是它训练数据里就有这类代码，它只是照着模式生成。

第三个问题是状态污染。同一个进程里跑多次执行，全局变量、临时文件、环境变量会互相干扰。第一次执行留下的/tmp/xxx可能让第二次执行结果完全错乱，而这种 bug 极难复现。

1.2 沙箱要提供的四件事

一个能上生产的 Agent 沙箱，本质上要提供四件事：隔离（进程、文件系统、网络）、限额（CPU、内存、时间、磁盘）、可观测（执行日志、退出码、资源消耗）、可复现（同样的输入得到同样的环境）。这四件事缺一个，生产环境就会出问题。

花椒在选型阶段把市面上的方案过了一遍，大致分三类：基于容器（Docker、containerd）、基于微虚拟机（Firecracker、gVisor）、基于语言级隔离（WASM、V8 isolate）。每一类的隔离强度、启动开销、生态成熟度都不一样，选哪个取决于你的场景对"启动延迟"和"隔离强度"的权衡。

1.3 一个反直觉的结论

很多人以为隔离越强越好，直接上微虚拟机。但实际跑下来，如果你的 Agent 主要执行的是短小的数据处理脚本（几百毫秒到几秒），微虚拟机每次冷启动几十到上百毫秒的开销会显著拖慢整体响应。花椒最后的选择是容器为主、微虚拟机兜底：常规执行走容器池，高风险或需要强隔离的执行走微虚拟机。这个分层思路后面会详细讲。

2. 花椒的沙箱选型：容器、微虚拟机还是语言级隔离

2.1 三类方案的横向对比

选型不能拍脑袋，得把关键指标摆出来。花椒团队当时列了一张对比表，我把它整理成下面这样，方便你对照自己的场景：

看这张表你会发现，没有银弹。WASM 启动快、内存省，但你的 Agent 如果生成的是 Python 代码，编译到 WASM 这条路基本走不通（Pyodide 能跑但兼容性有限）。微虚拟机隔离最强，但运维成本和启动延迟都上去了。容器是折中点，生态兼容性最好，绝大多数语言都能跑。

2.2 花椒为什么最终选容器为主

花椒的核心场景是执行用户和模型生成的通用代码，语言分布很杂：Python 占大头，还有 Node、Go、Bash。这种情况下，语言级隔离直接出局，因为不可能要求所有代码都编译到统一格式。微虚拟机虽然隔离强，但每次执行都要拉起一个 VM，对于"用户点一下按钮等结果"的交互场景，延迟太明显。

容器的优势在于：镜像即环境。你可以为不同语言准备不同的基础镜像，Python 镜像里预装 numpy、pandas，Node 镜像里预装常用包，执行时直接指定镜像，环境一致性天然得到保证。而且容器的资源限额（cgroup）是内核级别的，CPU、内存、磁盘 IO 都能精确控制，这对"防止用户代码把机器打爆"至关重要。

提示：容器隔离的前提是不要用--privileged，也不要把宿主机的 Docker socket 挂进去。这两件事一旦做了，隔离形同虚设，用户代码可以直接逃逸到宿主机。

2.3 微虚拟机兜底的触发条件

花椒并没有完全放弃微虚拟机，而是把它作为高风险执行的兜底。什么算高风险？团队定了几个触发条件：代码里出现明显的系统调用（比如os.system、subprocess、ctypes）、执行时长超过阈值（比如 30 秒）、或者用户显式标记为"不受信任"。这些情况下，调度器会把执行路由到微虚拟机池。

这个分层设计的好处是：常规执行快，高风险执行稳。大部分用户提交的代码是普通的数据处理，走容器池，延迟低；少数可疑代码走微虚拟机，即使真有问题也逃不出 VM。这种"按风险分级"的思路，比一刀切上最强隔离要务实得多。

2.4 选型时容易忽略的隐性成本

选型时大家容易只看技术指标，忽略运维成本。容器方案看着简单，但你要维护镜像仓库、镜像预热、容器池的伸缩、镜像版本管理。微虚拟机方案更重，你得管 VM 模板、内核镜像、网络配置。花椒在这块踩过的坑是：镜像预热没做好，第一次执行某个语言时冷启动特别慢。

解决办法是维护一个"热镜像池"：常用的几个基础镜像常驻在节点上，执行时直接复用，不用每次拉取。同时用 LRU 策略淘汰长期不用的镜像。这个细节在选型文档里通常不会写，但它直接决定了你的 P99 延迟。

3. 持久化：执行状态、文件产物与记忆的分层存储

3.1 为什么沙箱需要持久化

沙箱默认是"用完即弃"的，执行完容器销毁，里面的一切都没了。但 Agent 场景下，很多东西需要留下来：执行日志（用于排查和审计）、文件产物（用户代码生成的文件，比如图表、CSV）、执行状态（长任务的中间状态，支持断点续跑）、会话记忆（Agent 跨轮次记住之前执行过什么）。

这四类数据的生命周期和访问模式完全不同，不能塞进同一个存储。花椒的做法是分层存储：热数据放内存或本地 SSD，温数据放对象存储，冷数据归档。下面逐层拆。

3.2 执行日志：结构化 + 可检索

执行日志最容易做砸。很多人直接把 stdout/stderr 原样存下来，结果查询时只能全文搜索，效率极低。花椒的做法是结构化日志：每条执行记录包含execution_id、session_id、language、exit_code、duration_ms、peak_memory_mb、stdout、stderr、artifacts等字段，存进支持索引的存储（比如带倒排索引的日志系统或关系库）。

这样做的价值在于：你可以按session_id拉出一次会话的所有执行，按exit_code != 0筛出所有失败执行，按duration_ms排序找出慢执行。这些查询在排查问题时是刚需。原样存文本的话，这些都得自己写解析逻辑，费时费力。

注意：stdout/stderr 要截断存储。用户代码可能打印几百万行日志，全存下来既浪费空间又拖慢查询。花椒的策略是每个流最多存前 64KB 和后 64KB，中间用省略标记，同时记录总行数。这样既保留了关键信息，又控制了存储成本。

3.3 文件产物：对象存储 + 签名 URL

用户代码生成的文件（图表、报告、数据集）不能留在容器里，容器一销毁就没了。花椒的做法是执行结束后，把容器内指定目录（比如/workspace/output）的文件同步到对象存储，然后在数据库里记录文件元信息（路径、大小、MIME 类型、对应的execution_id）。

访问这些文件时，不直接暴露对象存储的路径，而是生成带签名的临时 URL，设置过期时间（比如 15 分钟）。这样既保证了安全性（URL 泄露了也会过期），又减轻了后端服务的带宽压力（客户端直接从对象存储拉文件）。

这里有个细节：大文件要分片上传。用户代码可能生成几百 MB 的文件，一次性读进内存再上传会把沙箱节点的内存打爆。花椒用的是流式上传，边读边传，内存占用恒定。

3.4 执行状态：Redis 做中间态，数据库做终态

长任务（比如训练一个小模型、跑一个大数据处理）可能执行几分钟甚至更久。这期间如果沙箱节点挂了，任务就丢了。花椒的做法是执行状态双写：中间态写 Redis（快，支持 TTL 自动过期），终态写数据库（持久，支持复杂查询）。

具体来说，执行开始时在 Redis 写一条execution:{id}记录，状态为running，带上开始时间、节点 ID、容器 ID。执行过程中定期更新心跳。执行结束时，把最终状态（success/failed/timeout）写进数据库，同时删掉 Redis 记录。如果节点挂了，Redis 里的记录会因为心跳超时被标记为orphaned，调度器可以据此做清理或重试。

这个设计的关键是心跳机制。没有心跳，你无法区分"任务还在跑"和"节点已经挂了"。花椒的心跳间隔是 5 秒，超时阈值 30 秒，也就是连续 6 次没心跳才判定为孤儿。这个参数要根据你的执行时长分布调，短任务可以调小，长任务调大。

3.5 会话记忆：和沙箱解耦

Agent 的记忆体系（短期、长期、永久）不应该和沙箱绑在一起。沙箱只负责"执行"，记忆由独立的记忆服务管理。花椒的做法是：沙箱执行完后，把执行摘要（做了什么、结果是什么、生成了什么文件）回传给记忆服务，由记忆服务决定怎么存、存多久。

这样解耦的好处是：沙箱可以无状态化。沙箱节点不需要知道会话历史，只需要执行当前这一条代码。无状态意味着沙箱节点可以随意扩缩容、随意重启，不会丢数据。这是生产环境可运维性的基础。

4. 执行协议：从请求到结果的全链路设计

4.1 协议要解决的核心问题

执行协议是沙箱和调用方之间的契约。它要回答几个问题：请求怎么发、参数怎么传、执行怎么控、结果怎么回、异常怎么处理。花椒的协议设计围绕一个原则：同步接口，异步执行。调用方发起请求后，可以同步等结果（短任务），也可以拿一个execution_id去轮询（长任务）。

协议的消息格式用 JSON，字段设计如下：

{ "execution_id": "exec_20250101_abc123", "session_id": "sess_xyz789", "language": "python", "code": "print('hello')", "files": [ {"path": "input.csv", "url": "https://..."} ], "limits": { "timeout_ms": 30000, "memory_mb": 512, "cpu_cores": 1.0, "disk_mb": 1024 }, "env": {"KEY": "VALUE"}, "callback_url": "https://..." }

响应格式：

{ "execution_id": "exec_20250101_abc123", "status": "success", "exit_code": 0, "stdout": "hello\n", "stderr": "", "duration_ms": 123, "peak_memory_mb": 45, "artifacts": [ {"path": "output.png", "url": "https://...", "size": 12345} ] }

4.2 限额字段的设计逻辑

limits里的每个字段都有讲究。timeout_ms是硬超时，到点直接 kill 容器，防止死循环。memory_mb通过 cgroup 限制，超了触发 OOM kill。cpu_cores用小数表示，0.5 表示半个核，适合轻量任务。disk_mb限制可写层大小，防止用户代码写满磁盘。

这些限额不能设死，要允许调用方按任务类型调整。比如数据分析任务可能需要 2GB 内存，而简单的字符串处理 128MB 就够。花椒的做法是设默认值 + 允许覆盖，默认值偏保守（512MB 内存、30 秒超时），调用方按需调大。

提示：timeout_ms要留缓冲。如果你设 30 秒，实际 kill 可能发生在 30.5 秒，因为调度和信号传递有延迟。对时间敏感的场景，把业务超时设得比沙箱超时短一点，比如业务 25 秒，沙箱 30 秒，这样业务层能先感知到超时并做处理。

4.3 文件传递：输入用 URL，输出用对象存储

输入文件怎么传给沙箱？有两种方式：一是把文件内容直接塞进请求体（base64），二是传 URL 让沙箱自己去拉。花椒选的是URL 方式，因为大文件塞请求体会让请求体膨胀，而且 base64 编码有 33% 的体积开销。

沙箱收到 URL 后，在执行前把文件下载到容器的/workspace/input目录。下载也要设限额，防止用户传一个超大文件把沙箱磁盘写满。输出文件同理，执行完从/workspace/output同步到对象存储，返回签名 URL。

4.4 回调机制：长任务的通知方式

短任务同步返回结果就行，长任务得用回调。花椒的协议支持callback_url字段，执行完成后沙箱主动 POST 结果到这个地址。回调要处理几个问题：重试（回调失败要重试，指数退避）、幂等（同一个execution_id的回调可能重复，接收方要能去重）、签名（回调请求带签名，接收方验证来源）。

如果调用方不想用回调，也可以轮询。花椒提供GET /executions/{id}接口，返回当前状态。轮询的缺点是实时性差、浪费请求，优点是实现简单、不依赖回调地址可达。两种方式花椒都支持，调用方按场景选。

4.5 异常分类：让调用方知道发生了什么

执行失败的原因很多，协议要把它们区分开，否则调用方无法针对性处理。花椒把异常分成几类：

这个分类的价值在于：调用方可以根据类型做不同决策。compile_error和runtime_error是用户代码的问题，可以自动重试（让模型改代码）；timeout和oom是资源问题，要么调限额要么提示用户；internal_error是系统问题，直接重试。

5. Go SDK 接入实战：从初始化到错误处理

5.1 为什么花椒提供 Go SDK

花椒的后端服务是 Go 写的，所以 SDK 优先出 Go 版本。Go SDK 的价值在于：把协议细节封装掉，让调用方只关心业务。你不用自己拼 JSON、处理 HTTP 重试、解析错误码，SDK 都帮你做了。

SDK 的核心接口就几个：NewClient（初始化）、Execute（同步执行）、Submit（异步提交）、GetExecution（查询状态）、Cancel（取消执行）。下面逐个讲怎么用，以及踩过的坑。

5.2 初始化：连接池和超时配置

client := sandbox.NewClient(sandbox.Config{ Endpoint: "https://sandbox.internal:8443", APIKey: os.Getenv("SANDBOX_API_KEY"), Timeout: 60 * time.Second, MaxRetries: 3, HTTPClient: &http.Client{ Transport: &http.Transport{ MaxIdleConns: 100, MaxIdleConnsPerHost: 20, IdleConnTimeout: 90 * time.Second, }, }, })

这里有几个关键点。Timeout是整个请求的超时，包括连接、发送、等待响应。如果你的执行任务可能跑很久，这个值要设得比timeout_ms大，否则客户端先超时了，服务端还在跑。MaxRetries只对幂等操作生效，Execute这种可能产生副作用的操作要谨慎重试。

连接池配置容易被忽略。默认的http.Client每个 host 只保持 2 个空闲连接，高并发下会频繁建连。花椒的 SDK 默认把MaxIdleConnsPerHost设成 20，这个值要根据你的 QPS 调。QPS 高就调大，但别超过服务端的连接数限制。

5.3 同步执行：适合短任务

result, err := client.Execute(ctx, sandbox.ExecuteRequest{ Language: "python", Code: "print(sum(range(100)))", Limits: sandbox.Limits{ TimeoutMS: 10000, MemoryMB: 256, }, }) if err != nil { // 处理错误 } fmt.Println(result.Stdout) // 4950

同步执行适合几秒内能跑完的任务。SDK 内部会处理 HTTP 请求、解析响应、把错误码转成 Go error。注意ctx要传，这样调用方可以取消。如果ctx被取消，SDK 会中断请求，但服务端的执行不会自动停止，需要额外调Cancel。

注意：同步执行不要用在可能跑几十秒的任务上。HTTP 连接长时间挂着，容易触发各种中间件的超时（负载均衡、网关）。长任务用异步。

5.4 异步执行：长任务的正确姿势

execID, err := client.Submit(ctx, sandbox.ExecuteRequest{ Language: "python", Code: longRunningCode, Limits: sandbox.Limits{ TimeoutMS: 300000, // 5 分钟 MemoryMB: 2048, }, CallbackURL: "https://myapp.com/sandbox/callback", }) // 立即返回 execution_id，不等结果

Submit立即返回execution_id，执行在后台跑。结果通过回调或轮询获取。回调方式前面讲过，这里说轮询：

ticker := time.NewTicker(2 * time.Second) defer ticker.Stop() for range ticker.C { status, err := client.GetExecution(ctx, execID) if err != nil { // 处理查询错误 continue } if status.Status != "running" { // 执行结束，处理结果 break } }

轮询间隔别太短，2 秒是个合理值。太短会给服务端压力，太长实时性差。如果任务预期跑几分钟，间隔可以放到 5 秒。

5.5 错误处理：区分可重试和不可重试

SDK 返回的错误分两类：传输层错误（网络问题、超时）和业务层错误（执行失败）。传输层错误通常可重试，业务层错误要看类型。

result, err := client.Execute(ctx, req) if err != nil { var sbErr *sandbox.Error if errors.As(err, &sbErr) { switch sbErr.Type { case sandbox.ErrTimeout: // 提示用户或调大限额 case sandbox.ErrOOM: // 调大内存 case sandbox.ErrInternal: // 重试 } } else { // 传输层错误，可重试 } }

这个模式的关键是用errors.As而不是类型断言，因为 SDK 可能包装了错误。花椒的 SDK 定义了sandbox.Error类型，带Type字段，调用方据此分支处理。

5.6 并发控制：别把沙箱打爆

Go 的并发很容易写，但沙箱是有容量上限的。如果你无脑起 1000 个 goroutine 同时调Execute，沙箱节点会被打爆，大量请求超时。花椒 SDK 提供了信号量机制：

sem := make(chan struct{}, 50) // 最多 50 并发 for _, task := range tasks { sem <- struct{}{} go func(t Task) { defer func() { <-sem }() client.Execute(ctx, t.ToRequest()) }(task) }

50 这个值要根据沙箱集群的容量调。经验值是沙箱节点数 × 每节点并发数 × 0.8，留 20% 余量应对突发。每节点并发数取决于你的限额配置，内存限额 512MB 的话，一个 8GB 的节点大概能跑 10-15 个并发。

6. 生产环境踩过的坑与应对

6.1 容器逃逸：一个真实的教训

早期花椒用的是默认的 Docker 配置，结果有次安全测试发现，用户代码可以通过/proc读取到宿主机的部分信息。虽然没造成实际损失，但暴露了隔离不严的问题。修复方案是收紧容器的安全配置：

• 禁用--privileged，用--cap-drop=ALL丢掉所有 capability
• 用--read-only挂载根文件系统，只给/workspace和/tmp可写
• 用--security-opt=no-new-privileges防止提权
• 用 seccomp profile 限制系统调用

这些配置加上后，容器逃逸的难度大幅提升。但要注意，限制太严会导致某些正常代码跑不了。比如--read-only会让需要写临时文件的库报错。花椒的折中是给/tmp挂 tmpfs，可写但重启即失。

6.2 镜像膨胀：从 2GB 到 300MB

花椒最初的 Python 镜像装了全套数据科学库，2GB 多。问题是每次冷启动拉镜像要几十秒，严重影响体验。优化方案是分层镜像 + 按需加载：

• 基础镜像只装 Python 和标准库，300MB
• 常用库（numpy、pandas）做成独立层，按需挂载
• 冷门库不预装，用户代码里import失败时提示

这个优化把冷启动从几十秒降到几秒。代价是用户代码如果用了冷门库，需要先触发一次安装，第一次会慢。花椒的做法是预装 Top 50 常用库，覆盖 90% 的场景。

6.3 僵尸容器：清理机制不能少

沙箱节点上跑着跑着，会积累一堆"僵尸容器"——执行已经结束但容器没被清理。原因可能是调度器挂了、清理逻辑有 bug、或者容器卡在某个状态。这些容器占着资源不释放，时间长了节点就满了。

花椒的清理机制是双保险：一是执行结束后主动清理，二是定期扫描（比如每 5 分钟）找出运行超过timeout_ms × 2的容器，强制清理。扫描逻辑要能识别"正在执行"和"僵尸"的区别，靠的是 Redis 里的心跳记录。没有心跳且超过阈值的，判定为僵尸。

6.4 网络隔离：默认断网，按需放行

用户代码可能发起网络请求，这既是功能也是风险。功能上，用户可能想让代码拉个数据；风险上，代码可能扫描内网、发起攻击。花椒的默认策略是断网，容器启动时不给网络命名空间。如果用户需要网络，得显式申请，并且只能访问白名单域名。

白名单的实现靠出口代理：容器只能访问一个内部代理，代理根据白名单转发请求。这样既能控制访问范围，又能记录所有出站请求，便于审计。白名单的维护是个持续工作，花椒的做法是按域名后缀放行（比如*.github.com），而不是逐个 IP。

6.5 执行结果的不确定性：如何保证可复现

同样的代码，两次执行结果可能不一样，原因很多：随机数种子、时间戳、文件系统顺序、并发调度。Agent 场景下，结果不一致会让模型困惑，也会让用户觉得"不稳定"。

花椒的做法是固定环境：设置固定的时区、固定的随机数种子（通过环境变量注入）、固定的工作目录、固定的环境变量顺序。对于确实需要随机的场景（比如生成随机 ID），在协议里显式声明，让调用方知道这次执行是不确定的。

提示：Python 的hash()在不同进程间结果不同（因为 hash 随机化），如果用户代码依赖字典顺序，结果会不稳定。解决办法是设PYTHONHASHSEED=0，花椒的 Python 镜像默认设了这个。

7. 沙箱与 Agent 编排的衔接

7.1 沙箱在 Agent 循环中的位置

Agent 的典型循环是：思考 → 调用工具 → 观察结果 → 再思考。沙箱是"调用工具"里的一类，专门负责执行代码。它和普通工具调用的区别在于：执行时间长、结果体积大、可能失败。所以沙箱的调用要特殊处理。

花椒的编排层对沙箱调用做了几件事：超时控制（沙箱超时要比 Agent 整体超时短）、结果截断（stdout 太长要截断再喂给模型）、错误转换（把沙箱错误转成模型能理解的描述）。这些处理让模型能正确理解执行结果，而不是被一堆原始日志淹没。

7.2 多轮执行的上下文管理

Agent 经常需要多轮执行：第一轮写代码，第二轮根据报错改代码，第三轮再跑。这期间，工作目录要保留。如果每轮都是全新容器，上一轮生成的文件就没了，模型得重新生成。

花椒的做法是会话级工作目录：同一个session_id的执行共享一个持久化卷，挂载到/workspace。这样第一轮写的文件，第二轮还能看到。持久化卷有 TTL（比如 1 小时），过期自动清理，防止无限增长。

7.3 执行结果的摘要生成

沙箱返回的原始结果（stdout、stderr、文件列表）信息量很大，直接喂给模型会占用大量 token。花椒在编排层做了摘要生成：提取关键信息（退出码、错误类型、输出前 N 行、生成的文件名），压缩成简短描述再喂给模型。

摘要的粒度要把握好。太粗，模型不知道发生了什么；太细，浪费 token。花椒的经验是：成功执行给 stdout 前 20 行 + 文件列表，失败执行给完整 stderr + 退出码。这个策略在实践中效果不错。

7.4 沙箱调用的可观测性

生产环境必须能观测沙箱调用。花椒在编排层埋了几个关键指标：调用量（QPS）、成功率、P50/P95/P99 延迟、各错误类型占比、资源使用分布。这些指标接进监控系统，出问题能第一时间发现。

日志方面，每次沙箱调用都记一条结构化日志，包含session_id、execution_id、language、duration、status。排查问题时，按session_id能拉出整个会话的所有调用，按execution_id能拉到单次执行的详情。这种可追溯性是生产环境的底线。

8. 一些实操中的经验与取舍

8.1 限额设太松和太紧都不行

限额设太松，用户代码能把节点打爆；设太紧，正常代码跑不了。花椒的调参过程是这样的：先设一个保守值（256MB 内存、10 秒超时），观察一周的失败率，发现 OOM 和 timeout 占比高，然后逐步放宽到 512MB、30 秒，失败率降到可接受范围。

这个过程没有捷径，只能基于真实数据调。建议你上线初期把限额设得宽松点，收集数据后再收紧。反过来（先紧后松）会让用户频繁遇到失败，体验差。

8.2 冷启动优化值得投入

沙箱的冷启动延迟直接影响用户体验。花椒在这块投入不少：镜像预热、容器池、快照恢复。其中容器池效果最明显：预先启动一批空容器，执行时直接复用，省去启动开销。池子大小按 QPS 调，闲时缩、忙时扩。

容器池的难点是状态清理。复用的容器必须把上一次执行的状态清干净，否则会串数据。花椒的做法是每次执行前重置工作目录、清环境变量、重启进程。这个清理逻辑要严格测试，漏一个就会出诡异 bug。

8.3 别忽视小语种的支持

花椒最初只支持 Python 和 Node，后来用户要求支持 Go、Rust、Bash。每加一种语言，就要维护对应的镜像、处理该语言的错误格式、适配该语言的执行方式。工作量不小，但不支持的话用户会流失。

建议是按需支持：先支持主流语言，有明确需求再加。加的时候把语言相关的逻辑抽象成接口，新增语言只实现接口，不改核心逻辑。花椒的LanguageRunner接口就是这么设计的，加语言成本可控。

8.4 安全是持续过程，不是一次性配置

沙箱安全没有"配好了就完事"这一说。新的逃逸手法、新的内核漏洞、新的攻击方式层出不穷。花椒的做法是定期做安全测试：用已知的逃逸手法尝试突破，看能不能成功；关注容器运行时的安全公告，及时升级；对用户代码做静态扫描，识别可疑模式。

这块投入产出比很高。一次成功的逃逸可能导致整个集群沦陷，而定期测试的成本相对可控。建议至少每季度做一次安全演练。

8.5 文档和 SDK 示例要跟上

沙箱的接入体验很大程度取决于文档和 SDK。花椒的 SDK 提供了完整的示例代码，覆盖同步、异步、错误处理、并发控制等场景。文档里明确写了"什么场景用什么接口""常见错误怎么处理""限额怎么调"。

这些内容看着基础，但能大幅降低接入成本。我见过太多项目，SDK 功能齐全但文档稀烂，接入方得读源码才能用。花椒在这块做得不错，值得借鉴。

9. 从花椒实践里能带走的东西

花椒这套方案的核心思路可以总结成几条：分层隔离（容器为主、微虚拟机兜底）、分层存储（日志、产物、状态、记忆各归其位）、协议先行（同步异步双模式、异常分类清晰）、SDK 封装（把复杂度留在服务端）。这几条不是花椒独创，但组合起来确实解决了不少实际问题。

如果你正在做 Agent 沙箱，我的建议是：先跑通最小闭环，再逐步加固。别一上来就追求完美隔离，那样会陷入过度设计。先用容器跑起来，把协议定清楚，把持久化做对，然后再根据实际遇到的安全问题加固。沙箱这东西，跑起来比设计完美更重要，因为很多问题只有跑起来才会暴露。

最后分享一个我在实操中的体会：沙箱的复杂度不在沙箱本身，而在它和 Agent 编排、记忆系统、监控体系的衔接。单独看沙箱，无非是执行代码；但放到 Agent 的完整链路里，它要和上下文管理、错误恢复、成本控制打交道。设计的时候多想想"上游怎么调我""下游怎么用我的结果"，比闷头优化沙箱内部更有价值。