Governance Gateway

governance-gateway

AI Agent 行动前运行的治理检查，旨在跟上 Agent 的步伐，而不是落在后面。

每个请求都会进行格式检查和个人数据（PII）扫描，绝不会跳过。安全分类器会标记有毒文本和越狱尝试，是一项较慢且可选的检查：只有在快速筛查发现文本可疑，并且仍能在请求截止时间前完成时才会运行。在负载较高时，检查所有内容的护栏会落后，等检查完成时 Agent 早已采取行动；本工具则能按时完成检查，绝不会跳过隐私检查。

它以 MCP 服务的形式在本地运行，因此文本不会离开你的设备，并且适用于任何 MCP 客户端：Claude Desktop、Claude Code、Cursor、VS Code、Gemini CLI 等。在 Claude Code 中，可选的钩子会强制检查 Agent 执行的每条命令、每次文件写入和每个 Web 请求。

安装

使用 uv，无需预先安装任何内容：

uvx governance-gateway --version

也可以使用 pip：pip install governance-gateway，然后运行 governance-gateway。 需要 Python 3.10 或更高版本；唯一的依赖项是 mcp 包。

添加到你的 AI 工具

Claude Desktop：在 claude_desktop_config.json 中（Settings > Developer > Edit Config）：

{
  "mcpServers": {
    "governance-gateway": { "command": "uvx", "args": ["governance-gateway"] }
  }
}

Cursor：在 ~/.cursor/mcp.json 中添加相同的代码块（或在项目中的 .cursor/mcp.json 中添加）。

Gemini CLI：在 ~/.gemini/settings.json 中添加相同的代码块。

VS Code（Copilot Agent 模式）：在 .vscode/mcp.json 中：

{
  "servers": {
    "governance-gateway": { "type": "stdio", "command": "uvx", "args": ["governance-gateway"] }
  }
}

Claude Code：

claude mcp add governance-gateway -- uvx governance-gateway

如果使用 pip 安装，请使用 "command": "governance-gateway"，且无需提供 args。

工具

工具	功能
check_message(text, deadline_ms=100)	运行检查。返回 allow、redact（屏蔽个人数据）或 block、原因、筛查和分类器是否运行，以及耗时。绝不回传文本。
governance_status()	目前为止的请求统计：判定结果、平均及 95 百分位延迟、按时完成的比例、跳过或筛查排除的分类器检查比例。
recent_decisions(limit=20)	最近的判定：判定结果、发现的个人数据类型、耗时。不含文本。
decision_matrix(...)	根据工作流的截止时间、流量形态、高峰时段系数、检测器召回率、目标和成本占比，判断全面检查是否足够、是否需要自适应检查，或是否只有增加容量才能解决问题。
simulate_load(load, deadline_ms, traffic, seconds)	在模拟时钟上，以实测检查成本，对比“检查所有内容”与考虑截止时间的护栏。

资源：governance://status 和 governance://policy（说明运行哪些检查、哪些检查为强制项，以及网关如何作出判定）。所有工具均为只读。

在 Claude Code 中强制执行检查

只有 Agent 决定调用时才会调用 MCP 工具。在 Claude Code 中，PreToolUse 钩子可以改为在每次操作前运行检查。最简单的方法是使用 governance-guard 插件，它会同时添加服务和钩子：

/plugin marketplace add tanishq-ctrl/governance-gateway
/plugin install governance-guard@governance-gateway

也可以自行将钩子添加到 ~/.claude/settings.json（或项目的 .claude/settings.json）中：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|WebFetch",
        "hooks": [
          {
            "type": "command",
            "command": "uvx",
            "args": ["--from", "governance-gateway", "governance-gateway-hook"],
            "timeout": 10,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

钩子会将每项操作的文本（命令、文件内容、URL）发送到运行中的网关，并将可用时间设为 GSL_HOOK_DEADLINE_MS（默认值为 200 ms）：

• 有害或格式错误：拒绝该操作，并告知 Agent 原因；
• 发现个人数据：询问你是否允许；
• 其他情况：不作任何更改，沿用你的常规权限。

如果网关未运行，钩子仍会自行执行个人数据扫描。如果检查完全无法运行，则会阻止该操作（设置 GSL_FAIL_OPEN=1 可改为允许操作）。GSL_ALLOW_EMAIL_DOMAINS 中的地址（默认值为 anthropic.com, users.noreply.github.com, example.com）会被忽略，因此提交尾注可以通过。

设置

选项	环境变量	默认值	含义
--cascade on/off	GSL_CASCADE	on	在分类器运行前执行可疑内容筛查
--estimator p90/mean	GSL_ESTIMATOR	p90	根据近期检查结果估算分类器的成本
--workers N	GSL_GATEWAY_WORKERS	1	处理队列的工作进程数
--audit-log PATH	GSL_AUDIT_LOG	none	每项决策追加一行 JSON（不含文本）
--port N	GSL_GATEWAY_PORT	8737	钩子的本地端口（仅限 127.0.0.1）
--no-hook-endpoint			不开放本地端口

检测内容与非检测内容

• 个人数据：通过模式匹配检测电子邮件地址、电话号码和美式国家身份证号码。不检测姓名、邮政地址及其他标识符。
• 有害文本：使用在 ToxicChat 上训练的 TF-IDF 和逻辑回归分类器。ToxicChat 是由人工标注的真实公共聊天机器人提示词数据集。在留出的 ToxicChat 消息中，它能捕获约 60% 的有害消息，精确率约为 0.78；它只是轻量级的第一道防线，并非完整的安全系统，且训练数据为英文。
• 筛查器在验证中放行了 95% 的有害消息，并将约 31% 的普通流量送交分类器。

请将其与贵组织自身的数据保护控制措施配合使用，而不要用它取代这些措施。

背景

该网关源自一个硕士项目，该项目测量了随着负载增长，治理检查与快速自动化决策之间的延迟差距。满负载时，检查所有内容会导致系统失效：在真实聊天机器人流量下，负载达到容量的 77% 时，系统就无法达到目标。截止期限规则将上限维持在 1.06；筛查器加截止期限规则则将上限维持在 1.44，同时确保隐私检查按时完成。

Prabhu，T. S.（2026）。量化 Agentic AI 生态系统中的“治理速度延迟”（GSL）：一种用于自适应实时数据合规的基于模拟的框架。
VIT 数据科学硕士项目。

源代码与问题反馈

https://github.com/tanishq-ctrl/governance-gateway

许可证

代码：MIT。随附的模型和工作负载数据源自 ToxicChat，仅限非商业用途（CC BY-NC 4.0）；详见 LICENSE-DATA.md。