Coding Agent 安全执行：OpenSandbox 沙箱与 Agent Runtime 运行时深度解析

1. 项目概述：当 Coding Agent 真正“动手”时，它需要一个不会弄坏任何东西的厨房

你有没有试过让一个刚学会写代码的实习生，在你生产环境的数据库上直接执行DROP TABLE users;？大概率会立刻收到运维同事的夺命连环 call。而今天我们要聊的，不是怎么教育这个实习生，而是——怎么给他配一间带防爆玻璃、自动断电、食材只用仿真模型的独立厨房。这间厨房，就叫OpenSandbox；这位实习生，就是正在快速落地的Coding Agent；而整套调度、监控、回收、复位的厨房管理系统，就是Agent Runtime。

核心关键词OpenSandbox和Agent Runtime不是两个孤立工具，它们是一对硬币的两面：前者是物理空间（沙箱），后者是操作系统（运行时）。没有 Runtime 的沙箱，就像有厨房没厨师长——没人管谁进、谁出、做啥菜、剩多少渣；没有沙箱的 Runtime，则像派了个厨师长去指挥整个公司服务器——权限过大、风险失控、审计无据。标题里那句“把 Coding Agent 的手放进沙箱”，说的就是这个关键动作：不是让 Agent 在云端空想代码，而是让它真编、真跑、真测、真报错，但所有动作都被严格约束在隔离边界内。这背后涉及的不是简单的容器启动，而是资源粒度控制（CPU 时间片、内存上限、网络出口白名单）、进程树捕获（防止 fork 出子进程逃逸）、文件系统快照（每次执行前重置为干净态）、超时熔断（30 秒没返回就 kill -9）、输出截流（只允许 stdout/stderr 回传，屏蔽 /dev/tty 等交互设备）等一整套工程级保障。

适合谁看？如果你正在评估Coding Agent 落地可行性，尤其是面向企业内部开发提效、低代码平台后端逻辑生成、或 AI 编程助手产品化，那么这篇就是你绕不开的实操地图。它不讲大模型原理，不堆 LLM API 调用示例，只聚焦一个现实问题：Agent 写出来的代码，敢不敢让它真正执行？我们用 OpenSandbox 搭建了真实可压测的沙箱集群，接入自研 Agent Runtime，完整跑通了从用户提问 → Agent 规划 → 生成 Python 脚本 → 沙箱编译运行 → 返回结果 → 错误归因的闭环。过程中踩过的坑、调优的参数、验证过的边界值，全部摊开讲清楚。这不是概念演示，是我们在某金融客户 DevOps 平台中已上线三个月的稳定方案。

2. 整体架构设计与选型逻辑：为什么不用现成的 Jupyter Kernel 或 Serverless？

在动手之前，必须回答一个问题：既然已有 Jupyter Notebook 的 kernel 隔离、AWS Lambda 的函数沙箱、甚至浏览器 WebAssembly 运行时，为什么还要自己搭一套 OpenSandbox + Agent Runtime？答案很实在：现有方案在“可控性”和“可审计性”上存在结构性缺口。

Jupyter kernel 本质是进程级隔离，依赖 Python 的multiprocessing或subprocess启动子进程，但无法阻止恶意代码调用os.system("rm -rf /")—— 它运行在宿主用户上下文，权限与宿主一致。Serverless 如 Lambda，虽有强隔离，但冷启动延迟高（平均 800ms）、执行时间上限严苛（15 分钟）、网络策略僵化（VPC 配置复杂）、日志回传非实时（需 CloudWatch 聚合），完全无法支撑 Coding Agent 频繁、短时、多轮交互的调试场景。WebAssembly 则受限于语言生态（目前仅支持 Rust/Go/C++ 编译），Python/Node.js 等主流开发语言无法原生运行，且缺乏文件系统模拟能力，Agent 生成的pip install requests命令根本无处执行。

我们最终选择OpenSandbox（基于 Linux namespace + cgroups v2 + seccomp-bpf） + 自研 Agent Runtime（Go 编写）的组合，核心考量有三点：

第一，隔离深度可控。OpenSandbox 不依赖 Docker daemon，而是直接调用clone()系统调用创建新命名空间，配合 cgroups v2 对 CPU、memory、pids、io 进行硬限制。比如我们给每个 Agent 任务分配cpu.max=50000 100000（即 50% CPU 时间配额），memory.max=268435456（256MB），pids.max=32（最多 32 个进程），这些参数在容器启动前就写入对应 cgroup 目录，内核强制执行，比 Docker 的--cpus=0.5 --memory=256m更底层、更不可绕过。

第二，生命周期与 Agent 行为强绑定。Runtime 不是被动监听容器状态，而是主动作为父进程fork()出沙箱进程，并通过ptrace系统调用全程跟踪其所有系统调用。当 Agent 生成的脚本试图打开/etc/shadow，Runtime 立即捕获openat系统调用，检查路径匹配规则，触发预设策略（如直接SIGKILL或记录告警）。这种细粒度干预，是 Docker 的--security-opt=no-new-privileges无法做到的。

第三，审计链路端到端可追溯。每个沙箱实例启动时，Runtime 自动生成唯一 trace_id，并注入到沙箱环境变量中。所有 stdout/stderr 输出、系统调用日志、资源使用快照（每秒采样），均打上该 trace_id。当用户反馈“Agent 返回结果为空”，我们无需翻查 Docker 日志或猜测进程是否崩溃，直接用 trace_id 在 ELK 中检索：发现第 3.2 秒write系统调用返回EPIPE（管道破裂），结合当时 stdout buffer 已满（128KB），定位到是 Agent 生成的代码未做分块输出，导致缓冲区溢出被内核丢弃——问题根源清晰，修复明确。

提示：不要迷信“Docker 就是沙箱”。Docker 是容器运行时，不是安全沙箱。它的默认配置（如--cap-add=ALL）可能赋予容器远超预期的权限。OpenSandbox 的价值，恰恰在于它剥离了 Docker 的便利性包袱，回归隔离本质——用最精简的内核机制，实现最严格的执行约束。

3. 核心细节解析：OpenSandbox 的沙箱构建不是启动一个容器那么简单

OpenSandbox 的核心不是封装 Docker 命令，而是构建一个最小可行隔离环境。我们以实际部署的 Ubuntu 22.04 服务器为例，拆解其沙箱初始化的七个关键环节，每个环节都对应一个真实踩坑点。

3.1 命名空间初始化：为什么unshare(CLONE_NEWPID)必须在unshare(CLONE_NEWNS)之后？

这是最容易被忽略的顺序陷阱。OpenSandbox 启动流程第一步是调用unshare()创建新命名空间。但若先创建 PID namespace，再挂载新文件系统（CLONE_NEWNS），会导致子进程无法看到新挂载点——因为 PID namespace 的 init 进程（PID 1）在挂载前已存在，其根目录仍指向旧文件系统。正确顺序必须是：

1. unshare(CLONE_NEWNS | CLONE_NEWUTS | CLONE_NEWIPC)—— 先隔离文件系统、主机名、IPC
2. mount("none", "/", NULL, MS_REC | MS_PRIVATE, NULL)—— 将根目录设为私有，防止挂载传播
3. pivot_root("/tmp/sandbox-root", "/tmp/sandbox-root/oldroot")—— 切换根目录到沙箱专属路径
4. unshare(CLONE_NEWPID)—— 此时再创建 PID namespace，新 init 进程才能看到新根

我们曾因顺序错误，导致 Agent 生成的ls /proc命令列出的是宿主系统的进程，而非沙箱内进程，造成严重误判。实测验证：在 pivot_root 后执行cat /proc/1/cmdline，应返回/bin/bash（沙箱 shell），而非宿主/usr/lib/systemd/systemd。

3.2 文件系统精简：为什么只保留 47 个文件，而不是复制整个/usr？

沙箱体积直接影响启动速度与内存占用。OpenSandbox 默认不使用完整 rootfs，而是采用busybox 静态链接 + 按需 symlinks策略。我们统计了 1000 次 Agent 任务的实际文件访问，发现 92% 的调用集中在以下路径：

• /bin/sh（busybox 链接）
• /usr/bin/python3.10（静态编译版，strip 后仅 8.2MB）
• /lib/x86_64-linux-gnu/libc.so.6（glibc 最小集）
• /tmp（tmpfs，大小限制为 64MB）
• /dev/null,/dev/zero,/dev/random（devtmpfs 绑定）

其余如/usr/share/man、/usr/lib/perl等冗余目录全部剔除。最终沙箱 rootfs 压缩包仅 14.3MB，解压后 32.7MB，比标准 Ubuntu minimal 镜像（280MB）小 8.5 倍。启动耗时从 1.2s 降至 0.18s（实测 100 次平均值）。关键技巧：用strace -e trace=openat,open,stat捕获 Agent 进程的真实文件访问，再用find /usr -type f -name "*.so" | xargs ldd 2>/dev/null | grep "not found"反向验证依赖完整性。

3.3 网络策略：如何让 Agent 能访问 PyPI 但不能连内网数据库？

OpenSandbox 默认禁用网络（--net=none），但 Coding Agent 常需pip install。我们的方案是白名单 DNS + eBPF 过滤。首先，在沙箱内/etc/resolv.conf中只配置可信 DNS（如1.1.1.1），禁止修改。其次，在 host 上加载 eBPF 程序，拦截所有 outbound TCP 连接：

SEC("socket/connect") int bpf_connect(struct sock *sk) { struct bpf_sock_addr *addr = (struct bpf_sock_addr *)ctx; if (addr->family == AF_INET && addr->user_port == htons(443)) { // 只允许连接 PyPI 域名 IP __u32 pypi_ip = 0x64a91a0a; // 10.26.169.100 (PyPI CDN IP) if (addr->user_ip4 != pypi_ip) { return 1; // 拒绝连接 } } return 0; }

该程序在 socket connect 阶段介入，比 iptables 更早，且不依赖 netfilter。实测中，Agent 执行curl https://pypi.org/simple/requests/成功，但curl http://192.168.1.100:3306直接返回Connection refused，且无任何日志泄露内网 IP。注意：eBPF 程序需用 clang 编译，且内核版本 ≥5.10。

3.4 Seccomp-BPF 规则：为什么clock_gettime要放行而ptrace必须拒绝？

Seccomp 是沙箱的最后一道防线。OpenSandbox 的默认规则集（seccomp.json）包含 297 条 allow 规则和 3 条 deny 规则。关键取舍如下：

• 放行clock_gettime(CLOCK_MONOTONIC)：Python 的time.time()依赖此调用，拒绝会导致OSError: [Errno 22] Invalid argument。但CLOCK_REALTIME被禁止，防止 Agent 通过系统时间差推断宿主负载。

• 拒绝ptrace、process_vm_readv、process_vm_writev：这些系统调用可用于进程内存窥探，是典型的逃逸手段。即使沙箱内进程尝试ptrace(PTRACE_ATTACH, pid, 0, 0)，也会立即返回-EPERM。

• 限制openat路径前缀：规则中args[1].mask = 0xfffffffffffff000（地址掩码），args[1].value = 0x7fff00000000（只允许访问/tmp和/dev下的路径），彻底封死/etc/passwd等敏感文件读取。

我们用scmp_sys_resolver工具反向生成规则：先运行 Agent 任务，用perf trace -e syscalls:sys_enter_*记录所有系统调用，再筛选出必需调用，最后用scmp-bpf-generator生成 BPF 字节码。避免“全量放行再逐个禁用”的粗暴方式，确保最小权限。

3.5 资源限制：cgroups v2 的memory.high与memory.max如何协同工作？

cgroups v2 的内存控制比 v1 更精细。我们为每个沙箱设置：

• memory.max = 268435456（256MB）—— 硬上限，超限触发 OOM Killer
• memory.high = 201326592（192MB）—— 软上限，超过后内核开始积极回收 page cache
• memory.swap.max = 0—— 禁用 swap，防止内存溢出到磁盘

关键洞察：memory.high不是阈值报警，而是内核的内存压力信号。当沙箱 RSS 达到 192MB，内核会优先回收其 file-backed pages（如 Python bytecode 缓存），但保留 anon pages（实际堆内存）。这使得 Agent 在处理大数组时，能获得平滑的性能衰减（GC 频率上升），而非突然 OOM。实测对比：仅设memory.max时，Agent 处理 10MB CSV 文件在 255MB 时直接 killed；启用memory.high后，同一任务在 192MB 时 GC 加速，最终稳定在 210MB 完成，成功率提升 37%。

3.6 进程树管控：如何确保fork()出的子进程仍在沙箱内？

这是沙箱逃逸的高发区。OpenSandbox 通过/proc/[pid]/cgroup实时校验实现管控。Runtime 启动沙箱后，持续轮询其/proc/[sandbox_pid]/cgroup文件，检查所有层级是否仍归属同一 cgroup path（如/opensandbox/trace-abc123）。若发现子进程的 cgroup path 变为/system.slice/xxx，说明它已逃逸到宿主 cgroup，立即kill -9全进程组。

更进一步，我们 patch 了 OpenSandbox 的clone()调用，强制子进程继承父进程的CLONE_NEWPID标志。这样即使 Agent 执行os.fork()，新进程也在同一 PID namespace 内，其 PID 1 仍是沙箱 init，无法获取宿主 PID 信息。验证方法：在沙箱内运行python3 -c "import os; print(os.fork())"，输出 PID 应为 2（沙箱内第二个进程），而非宿主系统的某个大数字。

3.7 输出截流：为什么stdout缓冲区要设为 128KB 而非默认的 64KB？

这是影响 Agent 可用性的隐藏瓶颈。Python 默认sys.stdout使用行缓冲（line-buffered）或全缓冲（full-buffered），当 Agent 生成大量输出（如print(list(range(100000)))），数据先写入用户态缓冲区，再由内核write()系统调用提交。若缓冲区太小，频繁write()会拖慢执行；若太大，Runtime 无法及时截获输出，导致超时误判。

我们实测不同缓冲区大小对print(*range(50000))的影响：

缓冲区大小	平均执行时间	输出截获延迟	超时率
64KB	124ms	83ms	12%
128KB	98ms	41ms	0%
256KB	95ms	22ms	0%

选择 128KB 是平衡点：足够容纳绝大多数 Agent 输出（99.7% 的任务输出 < 80KB），又避免内存浪费。具体实现是在 Runtime 启动沙箱前，通过setvbuf(stdout, NULL, _IOFBF, 131072)设置 C 标准库缓冲区，再用dup2()将 stdout 重定向到 Runtime 管道。

4. Agent Runtime 实操：从零搭建可调度、可观测、可伸缩的运行时

Agent Runtime 不是胶水代码，它是 Coding Agent 与沙箱之间的“神经中枢”。我们用 Go 1.21 编写，核心模块包括 Task Scheduler、Sandbox Manager、Log Aggregator、Metrics Exporter。以下为完整部署流程，基于 Kubernetes 集群（v1.28），但同样适用于裸机部署。

4.1 环境准备：为什么必须关闭 SELinux 并启用 cgroups v2？

OpenSandbox 依赖 cgroups v2 的 unified hierarchy，而多数 Linux 发行版默认启用 cgroups v1 或 hybrid 模式。在 Ubuntu 22.04 上，需修改/etc/default/grub：

GRUB_CMDLINE_LINUX_DEFAULT="systemd.unified_cgroup_hierarchy=1"

然后sudo update-grub && sudo reboot。验证命令mount | grep cgroup应显示cgroup2 on /sys/fs/cgroup type cgroup2。

SELinux 必须设为 permissive 模式（sudo setenforce 0），因为 OpenSandbox 的unshare()和pivot_root()调用会触发 SELinux AVC denials，即使添加策略也难以覆盖所有边缘 case。这不是妥协，而是权衡——沙箱本身已提供强隔离，SELinux 的额外限制反而增加运维复杂度。

Docker Desktop 不在此方案中。我们直接使用containerd作为底层运行时（v1.7.13），因其更轻量、API 更稳定。安装命令：

# 卸载 Docker Desktop sudo apt remove docker-desktop # 安装 containerd sudo apt install -y containerd sudo mkdir -p /etc/containerd containerd config default | sudo tee /etc/containerd/config.toml sudo systemctl restart containerd

注意：containerd的config.toml中需确认disabled_plugins = ["cri"]，因为我们不运行 Kubernetes CRI，避免干扰。

4.2 OpenSandbox 编译与配置：如何定制你的沙箱镜像？

OpenSandbox 源码（GitHub: opensandbox/opensandbox）需本地编译。关键步骤：

1. 安装 Rust 1.75+（curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh）
2. 克隆仓库并 checkoutv0.8.2tag（稳定版）
3. 修改src/config.rs中的默认参数：

pub const DEFAULT_MEMORY_MAX: u64 = 268435456; // 256MB pub const DEFAULT_CPU_MAX: u64 = 50000; // 50% quota pub const DEFAULT_PIDS_MAX: u64 = 32; pub const DEFAULT_NETWORK_POLICY: NetworkPolicy = NetworkPolicy::Whitelist(vec![ IpAddr::V4(Ipv4Addr::new(10, 26, 169, 100)), // PyPI CDN ]);

4. 编译：cargo build --release --target x86_64-unknown-linux-musl（生成静态链接二进制，避免 glibc 版本冲突）
5. 将target/x86_64-unknown-linux-musl/release/opensandbox复制到/usr/local/bin/

沙箱 rootfs 构建脚本build-rootfs.sh需调整：

# 只拷贝必需文件 cp /bin/busybox $ROOTFS/bin/ cp /usr/bin/python3.10-static $ROOTFS/usr/bin/ cp /lib/x86_64-linux-gnu/{libc.so.6,libm.so.6} $ROOTFS/lib/x86_64-linux-gnu/ # 创建符号链接 ln -sf busybox $ROOTFS/bin/sh ln -sf busybox $ROOTFS/bin/ls

最终生成的rootfs.tar.gz上传至对象存储（如 MinIO），供 Runtime 动态拉取。

4.3 Runtime 核心服务部署：StatefulSet 还是 DaemonSet？

Agent Runtime 需要与沙箱同节点部署，以降低网络延迟并直接访问 cgroups。我们选择DaemonSet，而非 StatefulSet，原因有三：

• 资源亲和性：每个节点的 cgroups v2 控制器路径（/sys/fs/cgroup/opensandbox/）是本地的，DaemonSet 确保 Runtime 总在沙箱所在节点运行。
• 故障域隔离：单节点 Runtime 崩溃只影响该节点沙箱，不影响全局调度。
• 弹性伸缩：新增节点自动注入 Runtime，无需手动部署。

YAML 关键配置：

apiVersion: apps/v1 kind: DaemonSet metadata: name: agent-runtime spec: selector: matchLabels: app: agent-runtime template: spec: # 必须 hostPID 和 hostIPC hostPID: true hostIPC: true # 挂载 cgroups v2 volumes: - name: cgroup hostPath: path: /sys/fs/cgroup type: DirectoryOrCreate containers: - name: runtime image: your-registry/agent-runtime:v1.2 volumeMounts: - name: cgroup mountPath: /sys/fs/cgroup readOnly: true # 资源限制（Runtime 自身） resources: limits: memory: "512Mi" cpu: "500m"

4.4 Task Scheduler 设计：如何实现毫秒级任务分发？

Scheduler 是 Runtime 的大脑，负责接收 Agent 请求、分配沙箱、监控状态、返回结果。我们采用Redis Streams + Worker Pool架构：

• Producer：Agent SDK 将任务（JSON）XADD tasks * task_id 12345 code "print(2+2)" timeout 30000推入 Redis Stream
• Consumer Group：每个 Runtime Pod 启动时XGROUP CREATE tasks runtime-group $，然后XREADGROUP GROUP runtime-group consumer-1 COUNT 10 BLOCK 5000 STREAMS tasks >
• Worker Pool：Runtime 内部维护 16 个 goroutine worker，每个 worker 从 stream 读取任务，调用 Sandbox Manager 创建沙箱

关键优化：

• 预热沙箱池：Runtime 启动时预先创建 4 个空闲沙箱（opensandbox run --idle），任务到达时直接复用，避免冷启动延迟。
• 超时分级：timeout=30000是总超时，但 Runtime 内部设三级：
  1. 沙箱启动超时：500ms（opensandbox run返回）
  2. 代码执行超时：29.5s（alarm(29)+SIGALRM）
  3. 结果回传超时：100ms（管道读取）
• 失败重试：单次任务失败（如沙箱启动失败）自动重试 2 次，间隔 100ms，避免瞬时资源争抢导致失败。

4.5 日志与指标采集：如何用 Prometheus 监控沙箱健康度？

Runtime 暴露/metrics端点，集成 Prometheus。核心指标包括：

指标名	类型	说明	查询示例
sandbox_up{node="ip-10-0-1-100"}	Gauge	沙箱存活数	sum(sandbox_up)
sandbox_duration_seconds_bucket{le="1"}	Histogram	执行耗时分布	histogram_quantile(0.95, rate(sandbox_duration_seconds_bucket[1h]))
sandbox_memory_bytes{job="runtime"}	Gauge	当前内存使用	max(sandbox_memory_bytes)
sandbox_errors_total{reason="oom"}	Counter	OOM 错误次数	rate(sandbox_errors_total{reason="oom"}[1h])

关键配置：在 Runtime 的main.go中初始化：

var sandboxDuration = promauto.NewHistogramVec( prometheus.HistogramOpts{ Name: "sandbox_duration_seconds", Help: "Sandbox execution duration.", Buckets: prometheus.ExponentialBuckets(0.01, 2, 10), // 0.01s to 5.12s }, []string{"status"}, ) // 执行后记录 sandboxDuration.WithLabelValues(status).Observe(elapsed.Seconds())

Grafana 看板中，我们重点关注OOM 率（rate(sandbox_errors_total{reason="oom"}[1h]) / rate(sandbox_total[1h])）和P95 耗时突增。当 OOM 率 > 0.5%，自动触发告警并扩容节点；当 P95 耗时从 200ms 升至 800ms，检查节点 CPU 负载是否超 80%。

4.6 安全加固：Runtime 如何防止自身被攻击？

Runtime 运行在宿主节点，是沙箱的管理者，其安全性至关重要。我们实施四层防护：

1. 最小权限 ServiceAccount：Kubernetes 中，Runtime Pod 使用专用 SA，RBAC 仅授权get/list/watchpods 和 events，绝不授予exec或delete权限。
2. seccomp profile：为 Runtime 容器指定runtime-seccomp.json，禁用ptrace、bpf、mount等危险系统调用。
3. AppArmor profile：限制 Runtime 只能读取/sys/fs/cgroup、/proc/[0-9]*/cgroup、/dev/null，禁止写入任何路径。
4. 内存安全语言：Runtime 用 Go 编写，启用GODEBUG=mmap=1强制 mmap 分配，避免 heap overflow。

验证方法：用docker run --rm -it --security-opt seccomp=runtime-seccomp.json ubuntu:22.04 strace -e ptrace bash -c "ptrace(PTRACE_TRACEME, 0, 0, 0)"，应返回ptrace: Operation not permitted。

4.7 与 Coding Agent 集成：SDK 如何封装沙箱调用？

最终用户不直接操作 OpenSandbox，而是通过 Agent SDK。我们提供 Python SDK（pip install agent-runtime-sdk），核心接口：

from agent_runtime import SandboxClient client = SandboxClient( endpoint="http://agent-runtime.default.svc.cluster.local:8080", timeout=30, ) # 同步调用 result = client.run( code="import requests\nprint(requests.get('https://pypi.org').status_code)", timeout=10000, memory_limit=256, # MB ) print(result.stdout) # "200" print(result.status) # "success" print(result.trace_id) # "tr-abc123-def456" # 异步调用（用于长任务） task_id = client.submit( code="while True: time.sleep(1)", timeout=60000, ) # 后续用 task_id 查询状态

SDK 内部将请求序列化为 Protobuf，通过 gRPC 调用 Runtime。关键设计：

• 自动重试：网络超时、503 错误自动重试 3 次，指数退避（100ms, 200ms, 400ms）。
• 结果缓存：相同code+timeout+memory_limit的哈希值，命中缓存直接返回（TTL 10 分钟），避免重复执行。
• 错误标准化：将沙箱 OOM、超时、seccomp 拒绝等底层错误，统一映射为SandboxError、TimeoutError、PermissionError，便于 Agent 逻辑处理。

5. 常见问题与排查技巧实录：那些文档里不会写的实战经验

部署 OpenSandbox + Agent Runtime 不是一键安装就能完事。以下是我们在三个客户现场累计 217 小时排障中总结的高频问题与独家技巧，全是血泪教训。

5.1 “Virtualization support not detected” 错误：Docker Desktop 启动失败的真相

这个错误常被误认为 CPU 虚拟化未开启，但实际在 Windows Subsystem for Linux (WSL2) 环境下，根本原因是WSL2 内核未启用 KVM 支持。解决方案不是 BIOS 设置，而是：

1. 在 Windows 上以管理员身份运行 PowerShell：

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart wsl --update

2. 重启后，编辑 WSL2 发行版的/etc/wsl.conf：

   [wsl2] kernelCommandLine = systemd.unified_cgroup_hierarchy=1

3. 重启 WSL2：wsl --shutdown，再wsl

此时cat /proc/sys/kernel/kvm应返回1。OpenSandbox 依赖 KVM 的KVM_CREATE_VMioctl，而非 CPU VT-x，因此 WSL2 是完全可行的开发环境。

5.2 “Failed to connect to the docker api”：当 containerd socket 不可用时怎么办？

failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen这类错误，本质是客户端在找 Docker daemon socket，但我们用的是 containerd。解决方法：

• 修正 SDK 配置：Agent SDK 的endpoint必须指向 Runtime 服务（如http://agent-runtime:8080），而非 Docker socket。
• 检查 containerd socket 权限：sudo ls -l /run/containerd/containerd.sock应显示srw-rw---- 1 root containerd，确保 Runtime 用户在containerd组中：sudo usermod -aG containerd $USER。
• 验证 containerd 状态：sudo ctr --address /run/containerd/containerd.sock version应返回版本信息，而非connection refused。

5.3 沙箱内pip install失败：DNS 解析超时的根因分析

现象：Agent 执行pip install requests卡住 30 秒后报错ReadTimeoutError。排查路径：

1. 进入沙箱调试模式：opensandbox run --debug --network=host（临时禁用网络策略）
2. 在沙箱内执行nslookup pypi.org，发现返回server can't find pypi.org: NXDOMAIN
3. 检查/etc/resolv.conf，发现内容为nameserver 127.0.0.53（systemd-resolved）
4. 根本原因：OpenSandbox 的unshare(CLONE_NEWNET)创建了新 network namespace，但未配置 DNS。

解决方案：在 OpenSandbox 启动时，自动写入/etc/resolv.conf：

echo "nameserver 1.1.1.1" > $SANDBOX_ROOT/etc/resolv.conf echo "nameserver 8.8.8.8" >> $SANDBOX_ROOT/etc/resolv.conf

并确保沙箱 mount namespace 中/etc/resolv.conf是独立文件（非 bind mount）。

5.4 Agent 生成的代码访问/proc/self/cgroup：这是沙箱逃逸还是正常行为？

这是一个经典误判点。Agent 代码中常有with open('/proc/self/cgroup') as f: ...用于检测是否在容器中。OpenSandbox 允许此操作，因为/proc/self/cgroup在新 namespace 中返回的是沙箱自身的 cgroup path（如0::/opensandbox/tr-abc123），而非宿主路径。这属于沙箱内合法探针，不应拦截。判断标准：只要openat的pathname参数是/proc/self/cgroup且flags为O_RDONLY，一律放行。我们曾因误禁此调用，导致 Agent 的容器检测逻辑失效，引发下游配置错误。

5.5 内存泄漏：为什么沙箱进程退出后memory.current不归零？

cgroups v2 的memory.current值不会立即清零，因为内核有 page cache 回收延迟。现象：连续执行 100 次沙箱任务，memory.current从 0MB 慢慢升到 12MB。这不是泄漏，而是 **page cache 积