Helio

Helio

面向 MCP Agent 的开源治理：提供实用的自主能力，而不赋予无限权限。

快速入门 · 文档 · 参与贡献

---

Helio 是一个 MCP 代理，位于你的 AI Agent 与其使用的工具之间。每次工具调用都会经过 Helio，由它执行策略、要求满足前置条件、检查证据、转交审批、限制累计支出并记录所有操作——无需更改 Agent 代码或 MCP 服务。

2026-07-28 版 MCP 修订使协议本身变为无状态：没有握手、没有协议级会话，跨调用状态则由模型在工具之间传递句柄。此模式适用于应用状态，却不适用于治理状态，因为模型能看到的预算键也能被模型更改。Helio 会在代理中保留会话身份、预算和证据，使其脱离 Agent 的上下文；因此，即使协议不再跟踪会话，这些控制措施仍然有效。请参阅无状态协议，有状态治理。

npx @gethelio/proxy init

@gethelio/proxy 是你需要安装的唯一 Node 包。它将代理运行时与打包好的仪表板 UI 资源一并提供。

ALLOW      read_customer
APPROVE    refund > £50
DENY       production.delete
BUDGET     £500/day across matching paid tools
REQUIRE    order.lookup succeeded before refund

为什么选择 Helio？

你的 Agent 刚刚调用了一个你意料之外的 API。它花掉了你未授权的资金。它修改了一条难以撤销的生产记录。

模型提供商正在为自家平台构建治理功能，但你的 Agent 运行在 Claude、ChatGPT、LangChain、CrewAI 和自定义框架上。没有任何单一平台能够治理全局，也没有任何平台能治理 Stripe、Salesforce 或 GitHub 等下游系统中发生的事情。

Helio 可跨任意兼容 MCP 的 Agent、工具和平台，治理 Agent 对外部世界所做的事情。

Helio 中的规则不会被遗忘，也无法在不被察觉的情况下弱化。规则不在模型的上下文中，因此长时间会话无法将其挤出，注入也无法说服模型忽略规则；执行机制位于提示词之外：经由 Helio 路由的工具调用会在转发前得到裁决，不受模型接收过的指令影响。每次尝试重新加载策略文件（包括移除规则的操作）都会生成审计记录；每条记录都附带写入时生效的配置哈希，因此配置更改会与其下的决策一并显现。“无法在不被察觉的情况下弱化”这一说法有一个前提，详见执行等级。

工作原理

两种集成方式：

1. 仅代理：将 MCP 客户端指向 Helio，而不是 MCP 服务。无需更改代码。立即获得治理能力。
2. 代理 + SDK：添加轻量级 Python SDK，用证据上下文和操作依赖关系标注工具调用。治理能力更丰富，代码量少于 500 行。

强制执行等级

Helio 会按每种方式在物理上所能达到的最高等级实施治理，并逐次调用记录等级：

• 结构级（stdio MCP）——Helio 拥有自己启动的子进程，因此 MCP 路径上的任何操作都无法绕过它；与其并列、可运行相同命令行的进程不属于此等级（见下方说明）。
• 网络级（HTTP MCP）——在你能控制上游服务出站流量的前提下，可达到结构级。
• 主机强制级（通过适配器 API接入的钩子适配器，例如 OpenClaw）——适用于在进程内运行工具、并通过钩子而非 MCP 传输公开接口的框架。由框架的钩子门控执行强制检查，Helio 负责决策。这是协作式方式，等级低于代理路径；Helio 会如实标明这一点，而不会夸大其能力。Helio 的决策仍无法从 Agent 的上下文中移除，也无法通过提示词注入篡改；任何绕过决策的尝试都会记录在审计追踪中。

以上三个等级都要求代理的配置、密钥和审计存储不在 Agent 的可访问范围内。默认的本地安装并非如此：代理与 Agent 以同一用户身份运行。SECURITY.md说明了这一边界，以及如何通过部署消除该限制。这也是“无法在无提示的情况下削弱保护”这一说法的前提：同一用户下的 Agent 可以不加载配置固定项而重启代理，也可以编辑或删除审计文件，因此只有在 Agent 无法写入审计文件时，重载记录和每条记录上的哈希才具有持久性；在此之前，事件流和 stderr 是唯一能在数据离开本机前保留记录的通道。按照文档中的方案，以独立用户或独立容器运行代理，即可消除这一限制。

快速开始（5 分钟）

1. 安装

npx @gethelio/proxy init

此软件包内置了已构建的仪表板 UI 资源包。

要在容器中运行 Agent？运行 npx @gethelio/proxy init --sandbox，即可改为写入边车布局；请参阅将 Helio 作为边车运行。

2. 配置

npx @gethelio/proxy init 已在项目根目录创建 helio.yaml。打开该文件（例如，运行 nano helio.yaml，或在编辑器中打开），并将 upstream.url 指向现有的 MCP 服务。单数形式的 upstream: 仍完全受支持；若要管理多个 MCP 服务，可改为声明一个命名的 upstreams: 列表（两者必须且只能设置一个）。工具集不会合并：每个命名的上游服务都通过各自的 /mcp/<name> 入口提供服务。请参阅配置参考。

不确定该服务提供了什么？运行 npx @gethelio/proxy scan --upstream http://localhost:8080/mcp，即可查看每个工具、服务是将其标记为具有破坏性还是沿用 MCP 默认设置，以及规则可匹配的参数。无需先编写规则，也无需启动代理。

请注意——Helio 默认以仅审计模式启动。 init 生成的 policies 部分默认已注释，因此 Helio 开箱即用时采用 default: allow 且没有任何规则：它会将每次工具调用记录到审计日志，但不会阻止任何调用。取消注释并编辑 policies（或粘贴自己的规则）即可开始执行策略。规则语法请参阅策略指南。

下面的代码块是一个示例配置目标——不是 init 生成的文件——展示了策略、预算、审计和仪表板密钥：

version: '1'

upstream:
  url: 'http://localhost:8080/mcp' # Your existing MCP server
  transport: streamable-http # streamable-http (default), sse, or stdio

listen:
  port: 3000 # Helio listens here

session:
  identity: # Ordered identity sources; first match wins
    - source: header
      name: x-helio-session-id # Agent harnesses set this once per run
    - source: legacy_header # Verbatim Mcp-Session-Id (deprecation window)
  on_unresolved: deny # deny | anonymous

policies:
  default: allow

  # These rules match on tool-name globs (deny / rate-limit / spend-limit):
  rules:
    # Block destructive operations
    - match:
        tool: 'delete_*'
      action: deny
      feedback:
        message: 'Destructive operations are disabled'

    # Rate limit expensive API calls
    - match:
        tool: 'search_*'
      action: rate_limit
      limits:
        max_calls: 100
        window: 1h
        key: tool

    # Spend limit on payment tools
    - match:
        tool: 'create_payment'
      action: spend_limit
      limits:
        max_spend:
          field: '$.amount'
          limit: 5000
          currency: 'GBP'
          window: 24h

budgets:
  # One depleting pot shared by every tool that spends.
  - name: agent-payments
    limit: 50
    currency: USD
    window: session
    key: session
    on_exceed: deny # or require_approval for a break-glass ticket
    contributors:
      - match:
          tool: 'stripe_*'
        field: '$.amount'
      - match:
          tool: 'paypal_*'
        field: '$.total'

audit:
  storage: sqlite
  retention: 90d
  include_responses: true

dashboard:
  enabled: true
  port: 3100
  api_secret: '${HELIO_DASHBOARD_SECRET}'

未列出的字段（如 listen.host、dashboard.host 和 audit.path）会采用安全的默认值（两个主机字段均为 127.0.0.1，仅限环回地址；审计路径为 ./helio-audit.db）。配置参考列出了所有字段、默认值及规范的章节顺序，是权威参考。

如果上游服务需要静态凭据（例如托管 MCP 服务上的 Authorization: Bearer …），请设置 upstream.headers——值支持 ${VAR} 插值，因此密钥无需写入文件。

没有可用于测试的 MCP 服务？Helio 附带了一个零依赖回显服务，只需一条命令即可运行——请参阅入门指南。

关于 dashboard.api_secret：

• 如果你运行了 npx @gethelio/proxy init，你的 helio.yaml 已包含生成的密钥的 SHA-256 摘要，而 init 只会打印一次密钥本身。请保留打印出的值；登录时需要使用它。跳过此步骤。

• 如果你使用上方所示的 ${HELIO_DASHBOARD_SECRET} 占位符手动编写了 helio.yaml，请在运行 start 前设置该变量：

  export HELIO_DASHBOARD_SECRET="$(openssl rand -hex 32)"
  

3. 启动 Helio

npx @gethelio/proxy start

4. 将 Agent 指向 Helio

{
  "mcpServers": {
    "my-tools": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

手边没有 Agent？ 无需 Agent 也能查看 Helio 的运行效果。将官方 MCP Inspector 指向 http://localhost:3000/mcp（运行 npx @modelcontextprotocol/inspector，传输方式选择：Streamable HTTP——Inspector 会通过自己的本地后端连接，该后端不会发送 Origin 标头；浏览器发送的 Origin 会按设计被拒绝），或者在终端中直接通过代理发送调用：

curl -s -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"London"}}}'

无论哪种方式，调用都会连同策略判定一起显示在仪表板中。（get_weather 是 Helio回显服务中的演示工具之一。）

5. 打开仪表板

http://localhost:3100

如果系统提示，请使用 init 打印的仪表板密钥登录（文件中只保存了它的摘要）。

就这样。现在，每次工具调用都会经过 Helio，并留下完整的审计记录，同时受到速率限制和支出控制。

想为写入操作启用人在环审批？完整的 Slack 和仪表板审批流程请参阅 docs/approvals.md，也可以复制 examples/slack-approvals/ 作为起点。

功能

策略引擎

使用声明式 YAML 规则，根据工具名称、注释、输入参数、环境和累积状态进行匹配。不可逆操作会被标记；干运行模式会运行完整流程，但不会转发到 MCP 服务。策略支持热重载，无需重启。

policies:
  rules:
    - match:
        tool: 'create_payment'
        input:
          '$.amount': { gt: 1000 }
      action: require_approval

多上游治理

一个代理即可治理多个 MCP 服务。命名的 upstreams: 列表取代单数形式的 upstream:（配置中只能使用其中一种形式，不能同时使用；仍支持单数形式），并且每个命名上游都通过各自的 /mcp/<name> 和 /sse/<name> 入口提供服务，不会合并工具集。

各入口统一治理：一个策略文件（规则可通过 match.upstreams 指定作用范围）、一个预算引擎、一个审批队列、一份审计记录和一个仪表板。请参阅配置参考中的 upstreams、策略指南中的 upstreams，以及多上游示例。

upstreams:
  - name: files
    url: 'http://localhost:8081/mcp'
  - name: payments
    url: 'http://localhost:8082/mcp'

跨工具支出预算

在多个工具和服务之间共用一个预算：一个逐步扣减的资金池会汇总所有接入工具的支出，无论工具位于哪个 MCP 服务之后，也无论金额来自哪个参数字段（Stripe 和 PayPal 共用一个上限）。预算在 MCP 关口确定性执行，通过持久化支出账本在重启后保留，并支持超额支出的紧急审批和实时仪表板视图。

budgets:
  - name: daily-cap
    limit: 50
    currency: USD
    window: 24h
    on_exceed: require_approval # a breach becomes a human decision
    contributors:
      - match:
          tool: 'stripe_*'
        field: '$.amount'
      - match:
          tool: 'paypal_*'
        field: '$.total'

预算适用于通过参数字段公开支出金额的工具。可在 Docker 快速入门演示或可运行的预算示例中查看完整流程：预算实时扣减、超限、紧急审批，以及获批的超额支出记入账本。

证据验证

要求提供由应用生成的最新证据。可选 SDK 会为会话提交一个证据密钥；代理会检查该密钥是否在策略允许列表中、是否存在以及是否过期（调用方为每个条目设置 TTL；SDK 默认值为 300 秒）。Helio 会验证证据信号是否存在且仍然有效，而不会检查其内容；SDK 令牌位于 Agent 的进程中，因此应将证据门控视为防止意外跳过某个步骤的保护措施，而非防止有意跳过该步骤的 Agent。请参阅 SECURITY.md。

policies:
  rules:
    - match:
        tool: 'process_refund'
      action: allow
      evidence:
        requires: ['orders.lookup']

# Optional SDK enrichment
from helio import HelioContext

# Mark a tool output as evidence
with HelioContext() as ctx:
    result = orders.lookup(order_id)
    ctx.mark_evidence("orders.lookup", "order_data", result)

SDK 通过带外 API 与代理通信（默认地址为 127.0.0.1:3200；可通过 sdk.host 配置绑定主机）。启用 SDK 带外通信（sdk.enabled: true，默认关闭）时，代理会在每次执行 helio start 时生成一个新的 32 字节十六进制令牌，并将其打印到标准错误：

SDK sideband listening on http://127.0.0.1:3200
SDK token (generated per-boot HELIO_SDK_TOKEN; pass as HELIO_SDK_TOKEN env var to your SDK clients):
  3f9c2b...d8a1

通过 HELIO_SDK_TOKEN 将相同的值传递给 SDK 进程，SDK 会自动在每次带外调用中附加 Authorization: Bearer <token>。带外接口还会拒绝任何携带非空 Origin 标头的请求，因此恶意本地 HTML 文件无法通过浏览器与之通信。需要在重启后使用固定令牌的运维人员，可以在代理的环境中显式设置 HELIO_SDK_TOKEN——代理会使用预设值，而不重新生成令牌，也不会将其回显到标准错误。

自我修复反馈

Helio 阻止某项操作时，会返回结构化反馈，说明失败原因以及 Agent 接下来应采取的操作。随后，Agent 可以自行纠正并重试。

{
  "blocked": true,
  "reason": "evidence_missing",
  "missing_evidence": ["orders.lookup"],
  "suggestion": "Call orders.lookup with the order ID before retrying"
}

操作依赖链

要求先成功执行前置操作。除非 orders.lookup 已在本次会话中成功执行，否则不予退款。代理会观察调用本身：默认情况下，只有路由后的工具调用返回了上游结果而非错误，依赖项才算满足。设置 requires_success: false 可将任何尝试都计为满足。

policies:
  rules:
    - match:
        tool: 'process_refund'
      action: allow
      requires: ['orders.lookup', 'customer.verify']

审批工作流

只升级需要您处理的事项，并向审批者展示参数。将敏感调用路由到 Slack、Webhook 或 Helio 仪表板；工单包含工具、上游服务、触发的规则以及调用参数，在人工决策之前不会执行该调用。支持配置超时和升级方式，并提供仅限仪表板使用的紧急覆盖功能（REST API 和仪表板 UI；不提供 Slack 按钮）。

速率与支出限制

可按工具和会话设置速率限制。可按规则设置支出限制，在匹配的工具达到自身上限时阻止调用——如需跨工具累计的支出上限，请参阅跨工具支出预算。

审计跟踪

记录每次工具调用：时间戳、Agent 身份、工具名称、输入、策略决策、证据链、审批状态、下游响应、延迟，以及写入记录时生效的配置哈希。可在仪表板中搜索。支持导出为 JSON 或 CSV。

Helio 的对比

	Helio	Obot	Cerbos	内置（Anthropic / OpenAI）	框架（LangChain / CrewAI）
治理对象	跨调用状态下的单次调用操作	可访问的工具/MCP	应用级授权决策	单个平台内 Agent 的权限	单个框架内 Agent 的行为
架构	进程外 MCP 代理	进程外 MCP 网关	Sidecar / 库	平台内	框架内
开源	✅ Apache 2.0	✅ Apache 2.0	✅ Apache 2.0	❌	不一
见效时间	5 分钟	视设置而定	数小时	内置	内置
无需更改 Agent 代码	✅	✅	❌	✅（在平台内）	❌
可治理非自建 Agent	✅ 任何 MCP Agent	✅ 任何 MCP Agent	✅（任何应用）	❌ 仅限单个平台	❌ 仅限单个框架
证据依据	✅ 跨调用累积	❌	❌	❌	有限
自我修复反馈	✅ 结构化重试提示	❌	❌	❌	有限
有状态支出 / 速率限制	✅ 跨工具预算 + 每条规则限制¹	基础	❌	❌	有限
审批工作流	✅ Slack、webhook、仪表板	✅	❌	有限	有限
审计跟踪（包括下游响应）	✅ 捕获上游 MCP 响应	决策日志	决策日志	平台遥测	框架日志

¹ 每条规则的速率和支出限制，以及命名的跨工具预算：持续扣减的资金池，超额时可通过紧急审批处理。

兼容对象

Helio 适用于任何兼容 MCP 的 Agent 或框架：

• Claude（Anthropic）
• ChatGPT（OpenAI）
• LangChain / LangGraph
• CrewAI
• AutoGen
• 使用任何 MCP 客户端 SDK 的自定义 Agent

文档

完整文档位于 monorepo 中，不包含在此软件包 tarball 中。

• 快速入门：在 5 分钟内完成安装和配置
• 配置参考：说明每个 YAML 选项
• 策略指南：如何编写规则及示例
• 扫描上游服务：在代理运行前，helio scan 会打印 MCP 服务的实际工具范围、提示来源、覆盖情况和参数候选项
• 审批工作流：通过 Slack、webhook 和仪表板进行审批
• 审计跟踪：记录哪些内容、如何搜索以及如何导出
• 将 Helio 作为 Sidecar 运行：将其部署在编码 Agent 或开发容器旁边，使上游服务和配置无法被其访问，并让 Helio 与其网络隔离
• 以独立用户身份运行 Helio：在 Ubuntu 24.04 上端到端运行独立用户级别的部署

示例

适用于常见场景的即用型配置：

• 基础配置：拒绝破坏性操作，允许其他所有操作
• Slack 审批：将破坏性操作发送到 Slack 审批
• 支出限额：管理支付工具的使用
• 预算：在 Stripe 和 PayPal 工具之间设置跨工具预算，并配合紧急超额审批；另设类别上限，仅对声明了支出类别的调用计费
• 多上游服务：在一个代理后配置两个命名上游服务，并设置按入口范围生效的速率限制和预算

贡献

欢迎贡献。请参阅 CONTRIBUTING.md，了解设置说明、编码规范和 PR 流程。

适合初次参与的问题已标记为 good-first-issue。

社区

• GitHub Issues：错误报告和功能请求
• Twitter/X：更新和公告

许可证

Apache 2.0 — 详见 LICENSE。