Derbent

Derbent

为所有编码 Agent 提供一道受控关卡。

所有到达 Derbent 的工具调用，无论是 MCP 调用还是 CLI 内置工具调用，都会由同一套策略决定，并写入防篡改日志；你关注的调用则会等待你的批准。

Derbent 可防止错误和提示词注入，并保留审计记录。它不是沙箱：已经能以你的身份运行 shell 命令的 Agent 可以绕过它（参见限制）。

在土耳其历史上，derbent 是山口上的一处守卫岗哨：守卫决定谁可以通行，并记录每个通行者。Derbent 为你的编码 Agent 的工具调用做着同样的事。

Claude Code、Codex、GitHub Copilot CLI 和 Antigravity CLI 作为一个 MCP 服务连接到 Derbent，你的其他 MCP 服务则位于它之后。每个 CLI 的工具调用前钩子都会将其内置工具（例如 shell 和文件编辑）通过同一道关卡。每次调用都会依据你的规则做出决定，并记录下来。

Codex 和 Antigravity CLI 的支持目前仍属实验性（根据其文档进行配置，尚未在真实会话中验证）。

它是一个适用于 Windows、macOS 和 Linux 的单一二进制文件。它没有守护进程，也不监听网络：SQLite 文件是唯一的共享状态（ADR 0001）。

你将获得

• 允许、拒绝或询问的规则，可按 Agent、工具和参数设置。优先采用第一条匹配规则。这些规则适用于所有四种 CLI 中的 MCP 工具和 shell 等内置工具；仓库还可以添加只会进一步收紧规则的项目规则。
• 批准。 对于规则要求询问的调用，会一直等待，直到你在终端 UI 中按下 a；默认情况下，50 秒后会拒绝该调用。
• 回执。 每次调用都会生成一条哈希链式回执；若回执遭到编辑、移动、插入或删除，derbent verify 会指出链首次断裂的位置。保留它打印的头部哈希，也能发现最新回执被删除的情况。

此外：

• 共享记忆和交接。 Agent 会按仓库保存笔记，也可以为彼此留下任务。
• 固定项会在下游服务的工具定义发生变化时暂时拦截该工具。
• 预算可阻止陷入循环的 Agent。

安装

从最新版本下载适用于你系统的二进制文件和 SHA256SUMS，核对哈希，并将其放到 PATH 中，命名为 derbent（Windows 上为 derbent.exe）：

# Linux on amd64; the other files differ only in the end of the name
curl -LO https://github.com/tunahanaliozturk/derbent/releases/download/v1.0.0/derbent-v1.0.0-linux-amd64
curl -LO https://github.com/tunahanaliozturk/derbent/releases/download/v1.0.0/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
install -m 755 derbent-v1.0.0-linux-amd64 ~/.local/bin/derbent

或者使用 Go 1.27 或更高版本构建：

go install github.com/tunahanaliozturk/derbent/cmd/derbent@latest

Homebrew（brew install tunahanaliozturk/tap/derbent）和 Scoop 也可用于安装；请参阅安装和设置。

每个版本都可以从其标签逐字节重建。安装和设置还介绍了其他系统、如何检查版本，以及如何手动添加各个 CLI 的配置项。

快速开始

derbent init --preset balanced   # add Derbent to each CLI it finds, and write a first config
derbent doctor                   # check what init wrote
derbent                          # open the terminal UI in a terminal of its own

derbent init 会显示每项更改，并在执行前统一询问一次。它会先备份每个要修改的文件，且绝不会替换已有条目。使用 --dry-run 时，它只会显示更改内容。以下是实际运行时的两项输出，路径已缩短：

claude: ~/.claude.json
  copied first to ~/.claude.json.derbent-backup-20260930T205424Z
  runs:
    claude mcp add --scope user derbent -- ~/bin/derbent mcp --agent claude
derbent: ~/.config/derbent/config.toml
  a new file
  adds the balanced preset (derbent init --preset balanced --print shows it)

它还会将 derbent gate 钩子添加到每个 CLI 的设置中；安装与设置 列出了所有条目。照常启动 Agent。它们发出的调用现在会显示在 UI 中，而规则要求确认的调用会在此等待你处理。内置工具介绍了每个 CLI 的钩子所覆盖的范围。

如需将其他 MCP 服务接入门控，这样每个 Agent 只需配置一个 derbent 条目，请参阅下游服务。

如何决定是否放行调用

规则位于用户配置目录中的 config.toml（Windows 上为 %AppData%\derbent\，Linux 上为 ~/.config/derbent/，macOS 上为 ~/Library/Application Support/derbent/）。下游 MCP 服务的工具名称为 <server>__<tool>，CLI 的内置工具名称为 native__<tool>：

[[rule]]
tool   = "github__issue_read"
action = "allow"

[[rule]]
tool   = "github__*"          # every other GitHub tool waits for you
action = "ask"

[[rule]]
agent  = "claude"
tool   = "native__Bash"       # Claude Code's shell, through the hook
args   = { command = "git push*" }
action = "ask"

[[rule]]
action = "allow"              # the last rule has no condition

如需在调用发生前查看系统会如何决定：

derbent explain --agent claude --tool native__Bash --args '{"command":"git push origin main"}'

它会逐条显示规则及其匹配与否的原因，直到第一个匹配项；随后显示项目规则、预算、固定项和授权，最后针对上述规则给出此次调用的 verdict: ask (rule:3)。规则介绍了 glob 模式、三种预设（watch、balanced、strict）、项目规则、预算和规则建议。

回执

derbent verify                              # count, head hash, and whether the chain is intact
derbent receipts --agent codex --since 1h   # also --tool, --project, --limit, --json

回执会保留遮蔽机密后的参数，以及工具返回内容的大小和哈希（ADR 0004）。能够写入数据库的人仍可重写整条哈希链，或删除最新的回执；因此，如果你希望日后能够发现此类情况，请将链头哈希保存在其他位置。回执与验证介绍了无需数据库即可检查的导出内容。

命令

命令	功能	更多信息
derbent	终端 UI：等待中的调用、Agent、实时回执、记忆、授权	审批
derbent init、derbent doctor	将 Derbent 添加到每个 CLI，然后检查设置	安装
derbent mcp --agent <name>	每个 CLI 启动的 MCP 服务	安装
derbent gate --agent <name>	内置工具的调用前钩子	内置工具
derbent pending、approve、deny	在任意 shell 中处理等待中的调用	审批
derbent grants、revoke	列出并撤销会话授权	审批
derbent explain	显示系统会如何决定是否放行调用	规则
derbent suggest	打印你的回答所指向的规则	规则
derbent config check	验证配置并列出每个服务的工具	服务
derbent pins	查看并接受已更改的下游工具	服务
derbent receipts、verify	读取、导出和验证回执	回执
derbent handoffs	列出 Agent 留给彼此的任务	记忆与交接
derbent version	打印版本号

开销

于 2026-10-01 在 GitHub 托管的运行器上测得（Linux 运行于 Intel Xeon Platinum 8370C，Windows 运行于 AMD EPYC 9V74，每台均为 4 个 vCPU），取十次运行的 p50 中位数，数据来自 docs/benchmark-results：

	Linux	Windows
MCP 工具调用，直接调用服务	256.5 µs	293.0 µs
MCP 工具调用，经由 gate	756.0 µs	909.0 µs
启动二进制文件并退出	4.292 ms	40.40 ms
Hook 调用，derbent gate，已允许	6.421 ms	64.51 ms

在 Linux 上，gate 会为一次 MCP 调用增加 499.5 µs；在 Windows 上增加 616.0 µs，这部分开销来自额外的 stdio 跳转、规则判定、项目规则检查，以及写入 SQLite 的回执。Hook 调用比启动二进制文件在 Linux 上多花约 2.1 ms，在 Windows 上多花约 24 ms；后者的大部分开销来自进程启动。这些数据来自共享运行器上的一次运行，各次运行之间的差异可能超过一次运行的区间：前一天，在同一 Windows CPU 型号上运行相同代码时，gate 比直接调用 MCP 多花 459.5 µs，而这里为 616.0 µs。结果页面还列出了 p99、每秒调用次数和注意事项。

限制

完整列表及其原因见已知限制与风险。 首先需要了解的限制：

• 只有经过 gate 的调用才会被看到。CLI 从不展示其 Hook 的工具，例如 Codex 的托管网页搜索，不在其范围内。
• 顶部标记为实验性的 CLI，其条目和 Hook 适配器遵循各自 CLI 的文档，但尚未在真实会话中验证。Claude Code 和 Copilot CLI（1.0.88，2026-10-02）已验证。
• 参数 glob 匹配的是字符串，而非含义：git push* 不会匹配 cd repo && git push。
• 审批可防止 MCP 内的误操作和提示词注入，但无法阻止已经能以你的身份运行 shell 命令的 Agent：它可以自行运行 derbent approve。
• 回执导出只能通过你保留的 head，证明最近一次运行未被更改；但无法证明没有内容被遗漏。
• 建议功能会拒绝它能识别的 shell、启动器和运算符，但文本规则可能被绕过，且这些列表无法穷尽；同时，命令前缀的 allow 规则会放行任意选项。
• 交接地址只是标签，不是身份：任何能调用 handoff_take 的 Agent 都可以认领所有发给 * 的未完成交接。
• 审批依赖于有人查看。无人值守时，超时后 ask 会被视为拒绝。
• 固定项信任其看到的第一个定义，包括更新时添加到固定服务的新工具。因此，对于你不会审核更新的服务，请明确指定允许使用的工具。
• 同一时刻正在执行的调用可能会突破预算。
• CI 会在 Windows 和 Linux 上运行测试，但只会在 macOS 上构建。

面向团队

团队审计跟踪（回执从各台机器同步，并支持导出到 SIEM）目前只是一个想法，并非计划。如果你会用到它，请在此讨论帖中告知我们。

文档

• 安装与设置：各系统、验证发行版、手动配置各个 CLI
• 规则：规则、预设、explain、项目规则、预算、建议
• 审批与 UI：密钥、授权、从 shell 回答
• 内置工具：Hook、各 CLI 的工具名称、各 CLI 的覆盖范围
• 下游服务与工具固定项
• 回执与验证：回执内容、导出、verify --file
• 记忆与交接
• 演示：两个真实 Claude Code 会话共享一个 gate 的对话记录
• 设计，构建规范，以及背后的决策记录

变更记录见更新日志。如需构建、测试或提交更改，请参阅 CONTRIBUTING.md。如需报告漏洞，请参阅 SECURITY.md。

许可证

Apache 2.0。请参阅 LICENSE。