DeadBolt 深度解析：为 AI Agent 工具调用构建执行边界

当 AI Agent 能够写文件、调服务、发消息时，一次错误决策就可能变成真实世界的变更。Next.11 推出的 DeadBolt 是一个免费、开源的执行门禁（execution gate），目标很明确：在 Agent 的下一步受保护动作落地之前，由受信任的调度器做出确定性裁决。

本文基于官方 walkthrough 视频整理，涵盖集成方式、策略控制、审批机制与实测验证。

为什么需要执行边界

OpenAI 当前的 Agent 文档建议：把校验逻辑放在产生副作用的工具旁边。OWASP 的过度代理（excessive agency）指南则提出了三条工程原则——最小权限、高影响动作需审批、对每个下游请求做授权。

这些是建立执行边界的工程理由，但并非法律层面的统一要求。具体义务取决于你的应用场景、合同条款与司法辖区。

DeadBolt 提供的只是这套更大设计中的一环确定性控制。官方明确建议将它与其他措施组合使用：收窄的工具集、真实的服务权限、Schema 校验，以及与运行环境匹配的操作系统隔离。

过度代理（Excessive Agency） 是 OWASP 针对 LLM 应用提出的核心风险类别之一，指 AI 系统因权限过大、目标模糊或缺乏约束而执行了超出预期的破坏性动作。其典型场景包括 Agent 凭自主判断调用支付接口、删除生产数据或向外部发送敏感信息。OWASP 为此给出的缓解方向包括：限定工具集到完成任务所必需的最小范围、对高影响操作强制引入人类审批、以及在每个下游服务调用点做独立授权校验。理解这一概念有助于把握 DeadBolt 的定位——它不是解决过度代理的完整方案，而是把「授权校验」这一环从模型侧剥离到可信调度器侧的工程实践。

核心工作流：模型提议，应用验证

DeadBolt 的执行模型可以概括为一条链路：

• 模型提议工作：模型只能提出调用意图，不掌握执行权。
• 可信应用验证：由应用校验参数、分配运行身份与路由后的工具名称。
• DeadBolt 检查租约与策略：对照当前 lease 和 policy 做出裁决。
• 调度器仅在明确 allow 后启动函数体：其他任何结果都会阻断受保护动作。

操作员通过独立的控制路径管理策略、审批与撤销。官方反复强调一点：这些控制手段绝不能作为模型工具暴露出去。调度器、数据库、操作员凭证与路由都必须保持可信——能绕过门禁或篡改其存储的调用方，本身就已在边界之外。

需要澄清 DeadBolt 的能力边界：它不是操作系统沙箱，也无法关停前沿模型。它做的是拒绝后续的受保护准入，且无法取消已经运行中的工具函数体。

版本选择决定集成路径

官方提醒，先确定版本，再选择集成示例。已发布的 1.0.3 版本支持成熟的 lease gate、原生 CLI、sidecar 与 MCP proxy。候选（candidate）示例则新增了 callback helpers、可安装管线、Python 客户端、可选 SDK 适配器、作用域凭证与精确动作审批——这些尚未进入已发布的归档包。

安装方式上有两条路径：

• 原生下载：无需 Rust 编译器。选择操作系统与处理器架构，校验 checksum，解压归档，然后运行 version 和 drill 命令。
• 源码安装：需要 Rust 与平台 C 编译器或构建工具，并应将候选版本固定到经完整审查的 commit。

截至本次审阅，crates.io 或 PyPI 上均无可用的包发布，应参照安装指南，而非假设注册表命令可用。

快速评估：sidecar + 临时文件调度器

最快的评估路径是本地 sidecar 配合临时文件调度器，只需 Python 标准库与原生可执行文件，无需模型账号。

评估脚本会自动完成：隔离状态供给、策略配置、尝试动作、检查文件是否真实存在。脚本展示了几类关键行为：

• 符合策略的写入成功执行
• 策略外工具被拒绝
• 不可逆动作需审批，且使用一次后重放被拒
• 父级撤销会阻断已注册的子级，而无关运行继续
• 停止 sidecar 会阻断下一次动作，重启后撤销状态仍保留

这 11 项检查在已发布归档与候选二进制上均通过。官方明确指出：它们验证的是这个调度器，不构成对任意 Agent 的隔离能力证明。

Sidecar 是一种部署模式：在不修改主应用进程的前提下，将辅助功能作为独立进程与主进程并行运行，两者通过本地 socket 或回环网络通信。在 DeadBolt 的语境中，sidecar 承载准入服务，Agent 宿主进程通过 Unix socket 或经认证的 loopback TCP 请求裁决，从而把执行门禁与 Agent 逻辑解耦。这样设计的好处是：门禁的凭证、策略与证据存储独立于可能不可信的工作负载进程，即使 Agent 被污染也无法直接改写准入逻辑。代价是引入额外的进程生命周期管理——sidecar 不可用时必须 fail closed，即拒绝而不是放行。

Rust 集成：fail closed 是底线

在 Rust 中，从 release tag 或经审阅的完整 revision 引入 deadbolt crate。包名为 n11-deadbolt，库名为 deadbolt。

创建 gate 时要启用 enforcement 并设置 fail closed，使用私有状态目录。在可信初始化阶段创建 run lease 并配置实际的工具策略。

候选版本的 dispatch helpers 接受真实回调，在调用前即时检查，保留返回值，且在拒绝时绝不调用回调。异步调度在 future 被 pull 时检查，而非构造时。已发布的 API 也可以使用「手动 admit 后立即执行函数体」的方式。

官方给出两条硬性约束：

• 保护每一条产生副作用的路径，不要为整个 session 缓存放行
• 不要把 one-shot 消耗在独立的事前检查上

Sidecar 与 MCP 集成

本地 sidecar 通过 Unix socket 或经过认证的 loopback TCP 暴露准入接口，Python 客户端仅用标准库，Node 客户端只用内置模块。服务端与操作员需配置匹配的数据库与证据路径，以及调度器端点。

对于 STDIO-MCP 集成，通过 DeadBolt 的 MCP proxy 启动服务器，并由 executor 分配 agent 身份。proxy 会在转发前检查每个被路由工具的调用，操作员控制始终停留在服务器之外。

一个值得注意的细节：子进程不会继承任何一个 DeadBolt bearer token。候选版本限制了帧与响应大小，并处理子进程终止与客户端断连。但这些检查不覆盖任意服务器启动、其他 MCP 方法或服务器内部的后台工作——服务器实现本身仍需保护与校验。

对于已有宿主，官方建议从一条收窄的工具路由开始，先证明允许与拒绝两种效果，再逐步扩大覆盖。

可选 SDK 适配器与租约语义

可选的 Python 适配器保护受测 OpenAI agent SDK 中的真实函数工具：把每个副作用函数上的 function tool 装饰器替换为 protected tool 装饰器，SDK 仍会构建 Schema、校验参数并生成新的函数工具装饰器。

适配器不会创建 lease、授予操作员审批，也不会自动保护托管工具。它把拒绝作为 typed cause 通过 SDK runner 上报，应用无需解析文案即可展示决策。已安装 wheel 的验收覆盖 19 个用例，使用真实 runner 与 sidecar，不发起 provider 请求。

租约语义上有几个关键点：

• lease 属于 agent 身份，而非厂商 API key
• 默认租约寿命为 60 秒，一次实时准入（包括普通拒绝）会刷新滑动租约
• 静默会让租约过期，且过期后不滑动
• 受保护的工具包装器不得静默续期已过期的身份

动作截止时间与准入凭证截止时间是固定的，不滑动。这三类寿命需要分别追踪，这样才能在不撤销共享模型 key、不打断无关动作的前提下，停止某个特定工作流。

操作员控制：Pause / Clip / Kill

DeadBolt 提供三种控制手段：

• Pause：临时阻断某个 agent 的所有受保护准入
• Clip：阻断该 agent 的某个特定工具
• Kill：撤销该 agent 及其注册的后代

Resume 会清除 pause 与 clip 并保留已配置策略，但无法让 kill 复活。选型逻辑是：需要调查时用 pause，单一能力需要停止时用 clip，运行必须保持撤销时用 kill。

有一条重要限制：在动作已被准入之后发出的控制，无法撤销该动作。操作员仍需在应用中准备取消与恢复机制。

策略：工具名、目标与支出

策略限制三个方面：agent 可用的工具名、可到达的声明目标 token、以及上报的支出。

未设置的列表保持开放，因此应主动配置收窄的策略。列表外的工具以 purpose exceeded 拒绝；外部 host 同样被拒绝。带目标列表时，缺失 host 的网络类工具会被拒绝，而没有目标的本地工具处理方式不同。

官方特别提醒：目标 token 必须从函数体真正使用的路由派生。DeadBolt 不强制 DNS、重定向，也不访问主机，它不做网络套接字或文件系统路径 jail。

支出由可信基础设施上报，这不是计费表或原子购买预留，只是越过配置上限后停止后续受保护准入。每个子级都需要自己的策略，并在调度前于可信初始化阶段配置完成。

审批机制：one-shot 与 exact action 的差异

现有不可逆工具策略需要操作员 one-shot：未经审批的尝试返回 needs human，操作员批准特定的 agent 与工具对，下一次被准入的调用消耗该审批，再尝试则需重新审阅。

这个机制适用于可信应用控制副作用的场景，但它的作用域仅限 agent 与工具对，不绑定接收方、消息文本、金额或其他参数。不要把它描述为「对精确消息的审批」。

当参数决定敏感结果时，应使用候选版本的 exact action 路径。它将执行器的 run、路由工具、目标、经校验的 JSON 参数、唯一 nonce 与固定截止时间绑定在一起。审阅请求需在可信代码中准备，审阅文件需保护，操作员批准的是审阅过的指纹。

版本 1 的指纹使用 SHA-256（原文写作 HA-256）对域分隔的 RFC 8785 规范化 JSON 信封求哈希，对对象、数字、Unicode 与请求大小都有明确规则。重复键、未知字段、非法数字与超大信封都会被拒绝。涉及金额时应使用安全整数最小单位或十进制字符串，避免精度歧义。

一个必须警惕的落差：grant 会随主 SQLite 证据自动消耗，但这并不等于外部效果恰好执行一次。崩溃或工具错误可能在消耗后留下「完成状态未知」，需要先对账应用结果并使用下游幂等性，再寻求新审批。grant 撤销也无法取消正在运行的工作。

RFC 8785（JSON Canonicalization Scheme，JCS） 定义了一套确定性的 JSON 序列化规则，使同一逻辑对象在不同实现下产生字节级一致的输出。其关键约定包括：对象键按 UTF-16 码元排序、数字采用 ECMAScript 最短表示、字符串按规范转义、禁止 NaN 与 Infinity。DeadBolt 的 exact action 指纹正是对域分隔后的 JCS 规范化 JSON 信封做 SHA-256，因此审阅者批准的是「这一组参数的确切字节序列」，任何参数改动都会改变指纹而无法复用审批。这也解释了为何重复键、未知字段、非法数字与超大信封都必须被拒绝——它们会破坏规范化的唯一性前提。

作用域凭证与血缘撤销

候选版本将工作负载的准入凭证与操作员 token 分离：可信初始化配置 lease 与策略，然后为某个 agent 签发一份带固定过期时间的私有凭证文件。工作负载可以为该身份请求 legacy 或 exact 准入，但无法创建 agent、修改策略、查看其他 agent、授予审批或上报支出。

实践建议很直接：从工作负载环境中移除操作员 token。SQLite 存储凭证哈希，bearer 本身保持私有；首次签发凭证后，仅凭 socket 访问不再授予匿名权限。

血缘方面，子级要在开始保护性工作前注册到父级之下，然后显式配置自己的策略。注册只创建血缘，不复制父级的工具或目标限制。杀掉父级会撤销已注册的后代，但不会撤销同一 store 中独立的身份。文件评估展示了这一行为：被杀的父级回调被阻断，子级回调被阻断，而无关联的 agent 仍在正常写入。

血缘（Lineage） 在 DeadBolt 中描述的是 agent 身份之间的父子派生关系：一个子 agent 在开始执行受保护工作之前必须向父级注册，从而形成可追溯的谱系树。注册动作本身只建立关系，不会复制父级的工具白名单或目标限制，子级必须显式配置自己的策略。这种设计让撤销具备传递性——对父级执行 Kill 会级联撤销所有已注册后代，而同一存储中未注册于此树下的独立身份不受影响。血缘的价值在于：当某一支工作流被判定为异常时，操作员可以一次性切断整条派生链，而不必逐个定位每个衍生身份。

证据链：能证明什么，不能证明什么

DeadBolt 用 SQLite 与 JSON lines 记录准入尝试和操作员变更。已观察事实与推断结论被明确区分：内容标识符对记录的 payload 求哈希，推断行会引用其前提。

Incident Command 可导出某个 agent 的决策历史、当前策略、撤销时间与已注册子级。但官方明确划出红线：这些记录无法识别持有 token 的人，无法证明外部操作已完成，也无法证明法律合规。生成的叙述不是证据行。

候选版本的动作记录包含元数据与指纹而非原始参数，但私有审阅文件仍包含实际内容，导出与保留策略需要相应保护。可选 witness 集成是独立的 sink，有自身的失败边界。这些记录用于调查，随后要与应用与 provider 的证据对账。

Fail closed：故障不得变成许可

调度器只应在一次新鲜的、明确的 allow 后运行函数体。sidecar 不可用、响应畸形、超时或认证失败，都不能变成许可。必须启用 enforcement 并 fail closed。

实测中，停止 sidecar 阻止了文件效果；重启后 killed 身份仍被保留，而无关的 lease 依然有效。数据库与证据路径要保持一致，使用私有状态目录并在本地绑定。仓库提供了容器与 systemd 指南，但目标部署仍需自行验收。SQLite 备份需保持一致，并在停止调度的情况下测试恢复。

候选迁移会新增表。旧二进制不会强制执行新的凭证或 exact action 边界，因此回滚需要经审阅的恢复方案。主 SQLite 事务不会让 JSON lines、witness 与外部效果成为全局事务。

Harness 实战与一个真实集成 Bug

演示使用了优化后的 Harness 可执行文件，复制到源码检出之外，启用 deadbolt 与 fail closed 并隔离状态。一个合成的 loopback provider 提议正常写文件，Harness 运行受保护工具，文件出现；在下次写入前，操作员 kill 掉文件，Harness 报告 killed denial，第二个文件不存在；另一个 Harness agent 成功写入自己的文件。

屏幕上展示的输出来自真实命令与工具结果，路径为可读性做了缩短。这是确定性集成测试，不构成对某个特定模型行为的断言。Harness 当前使用 legacy 准入，会正确拒绝 exact-only 工具，直到接入专门的 exact action 适配器。

本次审阅发现了一个有意义的集成 bug：Harness 在等待人工审阅前就做了工具准入，审阅后只检查存储的 kill 或 pause 状态。这意味着变更的策略或过期的 lease 可能被漏掉，而拒绝审阅可能过早消耗 one-shot。针对该行为有四个新回归用例失败。修正后，准入在审阅之后、注册函数体或审阅内容写入之前只执行一次，七个新回归用例覆盖这些路径，包括操作员 kill、clip 写入、审批保留与 exact-only 拒绝。25 项测试、优化套件 200 项、全部 15 项远程检查通过。

落地建议

官方给出的起步路径是：在应用里先接入一条收窄的工具路由 → 选择已发布或经审阅的候选 API → 配置私有 store、分配稳定身份、设置有用的策略 → 包装真实的副作用函数并测试其允许行为 → 验证策略拒绝、操作员撤销、过期、审批重放与门禁故障（不接受任何隐藏 fallback）→ 当参数决定敏感结果时加入 exact content review → 当工作负载不应持有操作员权限时加入作用域凭证 → 记录哪些路由已被覆盖，只有在其效果经过检查后才扩大范围。

DeadBolt 基于 Apache 2.0 协议免费开放，门禁本身不需要模型订阅。指南、可复现 fixture、源码 revision、字幕与证据随 walkthrough 一并提供。下一步，是在你自己的系统里做一次小型、独立验证的集成。