Codex Harness 安全沙箱机制原理：AI 编程代理如何安全地执行命令

Codex Harness 安全沙箱机制原理AI 编程代理如何安全地执行命令本文讨论 Codex 本地客户端与其命令执行 Harness 的通用安全模型。具体实现会随 Codex 版本、操作系统、宿主环境和管理员策略变化应以运行时显示的权限配置与官方文档为准。一、为什么 AI 编程代理需要沙箱传统聊天模型只生成文字而 Codex 这类编程代理会读取代码、修改文件、运行测试、调用 Git甚至执行安装依赖和网络请求。它的能力越接近一名真实开发者潜在影响范围也越大一条错误命令可能覆盖文件恶意仓库中的提示注入可能诱导代理读取密钥依赖安装脚本也可能执行任意代码。因此Codex 不能只依靠“提示词要求模型小心”。可靠的安全机制必须建立在操作系统能够强制执行的边界之上。Codex Harness 的核心作用就是把模型提出的操作转换成受约束的工具调用并在命令真正执行之前套上文件系统、网络、进程和审批策略。可以把整个体系理解为四层模型层分析任务提出命令或文件操作Harness 层检查工具参数、当前权限和审批条件沙箱层通过操作系统机制强制限制文件、网络和系统调用宿主系统层Linux、macOS、Windows 或云端容器提供最终执行环境。关键结论是模型决定“想做什么”Harness 决定“是否允许尝试”操作系统决定“实际上能不能做到”。二、沙箱与审批不是一回事Codex 的权限控制由两个相互独立、又彼此配合的概念组成。1. Sandbox Mode技术边界沙箱模式规定命令在操作系统层面能做什么。常见模式可以概括为模式文件读取文件写入网络适用场景read-only允许读取授权范围禁止或严格限制默认关闭代码审查、分析、制定方案workspace-write可读取必要路径仅允许写工作区等授权根目录默认关闭可单独配置日常编码、测试、构建danger-full-access接近宿主用户权限接近宿主用户权限取决于配置明确信任且确有必要的任务沙箱不是简单地检查命令字符串。例如禁止写/etc不能只靠拦截rm /etc/...因为程序还可以通过脚本、符号链接、子进程或另一个解释器写文件。真正的限制必须作用到进程最终发起的系统调用上。2. Approval Policy越界时由谁决定审批策略控制 Harness 何时停下来请求许可。命令若需要写工作区之外、访问被禁止的网络或使用更高权限Harness 可以拒绝、询问用户或把请求交给独立的自动审查器。因此沙箱解决能力边界问题审批解决越界授权问题审批通过后Harness 才会使用更宽的权限重新执行审批本身不会神奇地修改原沙箱中的进程权限。将二者分开非常重要。只有提示确认、没有 OS 沙箱一旦程序开始运行就很难约束只有沙箱、没有合理审批则许多正常开发任务会因为安装依赖、访问私有仓库或写入外部目录而无法完成。三、Linux 上的底层实现根据 Codex 官方公开说明Linux 与 WSL2 的当前实现主要组合使用Bubblewrap、seccomp并在兼容路径中使用Landlock。实际采用哪条强制路径取决于内核能力、用户命名空间是否可用以及宿主是否已经处于受限容器中。1. Bubblewrap构造受限的文件系统视图Bubblewrapbwrap是一个轻量级沙箱工具。它利用 Linux namespace 和 bind mount为目标进程创建新的挂载视图。它并不是完整虚拟机也不会模拟一套新内核沙箱进程与宿主共享内核但看到的文件系统可以完全不同。典型思路如下将系统目录以只读方式映射进沙箱将当前项目目录以可写方式映射隐藏或不映射敏感目录创建独立的/tmp、/proc等运行环境根据策略隔离网络、进程或其他 namespace最后在新环境中启动 shell、编译器或测试命令。这也解释了为什么 Bubblewrap 里“可以安装 Python”但含义需要区分如果宿主的 Python 被只读映射沙箱可以直接运行它如果工作区可写也可以把虚拟环境或依赖安装到工作区。要修改系统级/usr或使用系统包管理器则通常会被文件系统边界阻止除非显式提升权限。2. seccomp限制危险系统调用文件视图隔离仍不足以覆盖所有风险。Linux 程序最终通过系统调用访问内核seccomp 可以为进程安装过滤规则对特定 syscall 直接拒绝、返回错误或终止进程。它适合限制某些高风险内核接口缩小进程可用的攻击面。子进程通常会继承相关约束所以代理即使从 shell 再启动 Python、Node.js 或编译后的二进制也不能自然摆脱过滤器。seccomp 主要回答“允许调用哪些内核功能”而不是“允许访问哪个具体路径”。路径级权限通常需要挂载隔离、Landlock 或传统 Unix 权限共同完成。3. Landlock进程自我施加的文件访问控制Landlock 是 Linux 内核提供的无特权安全模块。进程可以为自己以及后代增加文件系统访问限制例如只允许读取某些目录、只允许在工作区写入。规则一旦生效通常只能继续收紧不能由被限制的进程自行放宽。Landlock 的优势是不一定要求 root适合本地开发工具对自身执行的命令施加限制。但它依赖内核版本和宿主配置并且不同 ABI 版本支持的权限类型不同。因此 Harness 必须先探测系统能力如果目标策略无法可靠执行应拒绝运行或选择明确的兼容路径而不能悄悄退化成无限制执行。4. 网络隔离Codex 默认关闭本地代理命令的网络访问以降低提示注入、恶意依赖下载和数据外传风险。在 Linux 上网络限制可以由 namespace、seccomp 或宿主策略组合实现具体手段取决于所选后端。联网并不是“沙箱开或关”的附属状态而是一项独立能力。合理策略可以允许文件写入工作区但禁网也可以在明确许可后为某次安装或查询开放网络。企业环境还可以叠加域名白名单、代理和防火墙策略。四、一次命令是怎样被执行的假设代理准备运行pipinstall-rrequirements.txtpytestHarness 大致会经历以下过程模型产生结构化工具调用而不是直接控制终端Harness 解析工作目录、命令、超时和所需权限当前策略判断工作目录是否在允许范围内以及该操作是否需要网络若权限不足命令会失败、被拒绝或触发审批若允许执行Harness 根据当前平台生成沙箱配置沙箱启动 shellshell 再启动pip与pytest所有后代进程继承沙箱边界Harness 收集标准输出、标准错误、退出码和超时状态并返回给模型模型根据结果继续修改、重试或向用户报告阻塞原因。这里最值得注意的是子进程继承。限制若只包裹最外层 shell、却不能约束其后代那么程序只需启动另一个解释器就能绕过控制沙箱便失去了意义。五、文件系统权限的细节workspace-write并不等于“项目目录中任何东西都绝对安全”。实际系统还需要处理以下边界问题。符号链接与路径逃逸工作区内的符号链接可能指向外部敏感路径。因此安全判断不能只检查字符串是否以工作区路径开头还必须依赖内核最终解析后的访问控制或在执行前进行可靠的路径解析与策略校验。Git 仓库与未提交修改沙箱可以限制写入范围却无法判断某次合法写入是否符合用户意图。例如覆盖工作区内未提交的代码在权限上可能完全合法但仍会造成数据损失。因此 Harness 还需要更高层的安全规则避免破坏性命令、尊重脏工作区、优先使用可恢复操作并在目标不明确时请求确认。临时目录和缓存目录编译器、测试框架与包管理器经常写/tmp、用户缓存或语言工具链目录。如果策略只开放项目目录一些命令会失败。这不是沙箱故障而是最小权限的直接结果。解决方式通常是把缓存重定向到工作区、增加一个精确的可写根目录或者对必要命令申请一次性授权。读取权限同样重要很多人只关注防止写坏系统却忽略读取 SSH 密钥、云凭据、浏览器数据和环境变量同样危险。尤其当网络被开放时“可读秘密 可访问外网”会形成数据外传通路。因此高安全配置应同时限制敏感文件读取、秘密在代理阶段的暴露和网络出口。六、云端 Codex 与本地沙箱的区别本地 Codex 的命令最终运行在用户机器上主要依赖平台原生强制机制Codex Cloud 则运行在 OpenAI 管理的隔离容器中与用户宿主系统天然分离。官方描述的云端模式通常区分两个阶段Setup 阶段可以按环境配置安装依赖并访问网络Agent 阶段默认离线执行任务除非为该环境启用互联网访问。配置给云环境的秘密可以只在 Setup 阶段出现并在 Agent 阶段开始前移除。这种设计把“准备可信构建环境”与“让模型自主操作”分开降低代理在处理仓库内容时接触长期凭据的机会。七、不同操作系统上的实现平台主要机制特点Linux / WSL2Bubblewrap、seccompLandlock 兼容路径利用 namespace、挂载视图、系统调用过滤和内核访问控制macOSSeatbelt sandbox profile使用系统原生沙箱规则限制文件与网络访问原生 Windows低权限用户或受限令牌、ACL、Firewall 等elevated模式强于unelevatedWSL2 使用 Linux 路径Codex CloudOpenAI 管理的隔离容器与本地主机分离可区分 Setup 与 Agent 网络/秘密权限这些实现追求相同的抽象目标但并非能力完全一致。例如某个平台无法表达特定的读写拆分策略时安全实现应拒绝该策略而不是静默地以更宽权限运行。八、它能防什么不能防什么沙箱主要能够降低以下风险意外修改工作区之外的系统或用户文件未经许可访问网络恶意仓库诱导代理读取或外传敏感信息构建脚本、测试程序和依赖安装器扩大影响范围利用部分危险系统调用攻击宿主。但沙箱不是万能边界已明确开放为可写的工作区仍可能被破坏工作区中本来就存在的秘密仍可能被读取一旦用户批准全权限OS 沙箱保护可能大幅减少沙箱与 Linux 宿主共享内核不能等同于虚拟机内核或沙箱工具自身的漏洞理论上可能导致逃逸允许网络后依赖投毒和外部恶意内容的风险会上升MCP、浏览器或外部应用工具可能拥有独立权限不能仅靠 shell 沙箱覆盖。因此更准确的说法是沙箱显著缩小爆炸半径但不能替代备份、代码审查、秘密管理、最小权限账户和供应链安全。九、推荐的安全配置思路对于日常开发推荐从以下原则出发默认使用workspace-write仅把实际项目目录设为可写默认关闭网络需要下载依赖时按任务临时开放代码审查和方案分析使用read-only不把 SSH 私钥、云凭据、生产配置放进代理可读工作区对外部仓库先审查项目级配置、Hook、AGENTS.md与安装脚本保持 Git 提交或其他备份以便恢复工作区内的合法但错误写入将全权限视为例外并限定到明确、短时、可核查的操作企业环境通过系统策略限制用户自行选择危险配置。一个典型的本地自动模式可采用如下思路codex--sandboxworkspace-write --ask-for-approval on-request它允许 Codex 在项目中读取、修改和运行常规命令当任务需要访问边界之外的资源时再进入审批流程。实际配置项和可用值应以当前 Codex 版本的帮助信息与配置参考为准。十、如何验证沙箱是否真的生效不要仅凭配置文件推断安全状态。Codex 提供平台沙箱调试命令可在与代理相同的边界中运行测试命令例如# Linuxcodex sandbox linuxbash-lctouch /tmp/codex-test curl https://example.com# macOScodex sandbox macosbash-lctouch /tmp/codex-test curl https://example.com# Windowscodex sandbox windows powershell-CommandGet-ChildItem测试时应检查工作区写入是否成功、外部路径写入是否失败、敏感文件读取是否受限、网络是否符合策略以及子进程是否继承相同限制。不要用生产秘密作为测试对象。十一、总结Codex Harness 的安全性不是来自单一技术而是来自一组互补机制模型只提出操作Harness 负责工具编排与审批操作系统沙箱负责不可绕过的强制限制Git、备份和秘密管理则承担更高层的数据保护。在 Linux 上Bubblewrap 负责构造受限运行视图seccomp 缩小可调用的内核接口Landlock提供文件访问限制与兼容路径网络权限又作为独立能力受到控制。审批机制位于沙箱边界之上使代理在低风险范围内保持自动化在确实需要越界时交还决定权。理解这一体系最简单的一句话是不要只信任 AI 会谨慎也不要只信任一条配置应让每个进程都在最小权限边界中运行并让每次越界都可见、可审查、可拒绝。参考资料OpenAI Codex Sandboxhttps://developers.openai.com/codex/sandboxingOpenAI Agent approvals securityhttps://developers.openai.com/codex/agent-approvals-securityOpenAI Codex Permissionshttps://developers.openai.com/codex/permissionsOpenAI Codex Configuration Referencehttps://developers.openai.com/codex/config-reference