Openhook

Openhook

面向 AI Agent 的事件收件箱。创建一个公开 URL，等待回调，检查收到的内容，然后继续执行任务。

Openhook 运行自己的 HTTP、SMTP 和权威 DNS 捕获服务。事件存储在其 SQLite 数据库中。无需使用外部 webhook 服务。

立即试用或自行托管

无需账号即可创建免费收件箱，或连接你的 Agent。可选的托管 Pro 版提供持久收件箱和账号恢复功能；请参阅当前的服务情况和方案。自行托管仍采用 MIT 许可证，无需 Openhook 账号或订阅。

实用教程：本地转发、GitHub 推送回调和 Stripe 测试回调。

不到一分钟收到第一个回调

安装 Python 3 后，克隆此仓库并运行一次性示例：

git clone https://github.com/openhook-dev/openhook-inbox.git
cd openhook-inbox
python3 examples/first_callback.py

示例会在 openhook.dev 上创建一个免费收件箱，发送真实回调，验证原始字节，然后删除收件箱及其载荷。私有令牌仅保留在内存中。此示例无需账号、API 密钥或 Python 依赖项。删除后仍会保留最少的运行活动元数据。

安装 Agent 技能

适用于 Codex、Claude Code 及其他兼容 Agent Skills 的客户端：

npx skills add openhook-dev/openhook-inbox --skill openhook

技能设置和权限说明介绍了 MCP 连接、REST 备用方案、本地转发以及私有收件箱令牌的处理方式。安装技能不会安装或启动服务。

为 Gemini CLI 安装

gemini extensions install https://github.com/openhook-dev/openhook-inbox --ref main

安装后重启 Gemini CLI。该扩展会连接托管的 https://openhook.dev/mcp 端点，不会启动本地捕获服务。它还包含用于回调测试工作流的 Openhook Agent 技能。连接或创建一次性收件箱无需 Openhook 账号或 API 密钥。请对 create_webhook 返回的私有令牌保密：读取和删除该收件箱时，必须将令牌作为工具参数提供。托管的持久收件箱需要单独的 Openhook 账号密钥。

让 Agent 创建一个一次性收件箱，然后将其公开 URL 提供给你正在测试的系统。捕获到回调即可证明它已到达 Openhook；请另行检查应用程序状态，以确认其处理程序是否正常工作。

使用 gemini extensions uninstall openhook-inbox 移除扩展。

连接 OpenCode

将此条目合并到项目的 opencode.json 中（保留现有设置）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openhook": {
      "type": "remote",
      "url": "https://openhook.dev/mcp",
      "enabled": true
    }
  }
}

在该项目中运行 opencode mcp list 检查连接，然后让 OpenCode 创建一个一次性收件箱并检查模拟回调。一次性收件箱无需 Openhook 账号。请勿将其私有令牌写入配置文件或提交的文件；只向发送方提供公开回调 URL。检查完内容后删除测试收件箱。Openhook 收到事件并不能证明应用程序的处理程序已处理该事件。

此配置已通过 OpenCode 1.19.1 成功连接。这只能验证 MCP 连接，并不代表已完成由模型驱动的端到端工作流。客户端配置请参阅 OpenCode MCP 文档。如需断开连接，请移除 mcp.openhook 条目，或将其 enabled 值设为 false。

运行

在检出目录中安装 uv 并启动自己的服务：

uv sync
uv run openhook --http

打开 http://127.0.0.1:8788/app。网站、捕获 API 和 Streamable HTTP MCP 端点共用一个服务和一个持久化存储。

将 MCP 客户端连接到 http://127.0.0.1:8788/mcp，或使用 uv run openhook 通过 stdio 连接。如果本地 stdio 进程和正在运行的 HTTP 进程使用相同的 OPENHOOK_DATABASE， 它们会共用同一个数据库。HTTP 进程必须正在运行，才能接收 HTTP 回调。使用以下命令在自己的服务上检查相同流程： python3 examples/first_callback.py --url http://127.0.0.1:8788。 外部提供商需要可公开访问的源站；localhost 示例只能证明本地服务可正常运行。

GitHub releases 会在可用时提供 带版本号的源代码和 Python 发行包。目前 openhook-mcp 尚未发布到 PyPI；请使用源代码检出目录或发行包文件，不要假设可以通过包索引安装。

Agent 工作流

1. 调用 create_webhook。保存私有的 ohk_ 管理令牌。
2. 将返回的公共 HTTP URL、电子邮件地址或 DNS 名称提供给发送方。
3. 使用管理令牌调用 wait_for_request。
4. 检查事件并采取行动。使用返回的 next_since 游标重新连接。

公共捕获地址无法读取或删除事件。若管理令牌遭到泄露，请使用 rotate_webhook_token 轮换令牌。 轮换不会影响公共地址。

匿名收件箱会在七天内过期。每个收件箱最多可保留 1000 个事件。 达到上限后，捕获操作会返回容量错误，而不是淘汰已接受的事件。 单个事件的大小上限为 1 MB。只有在配置了相应监听器时，才会返回电子邮件和 DNS 地址。

原生工具

29 个工具涵盖收件箱创建、响应配置、令牌轮换、 事件检查、字面搜索、备注、JSON/CSV 导出、精确字节下载、 HTTP/电子邮件等待、测试事件、链接/代码提取、回调检查、 延迟响应、提供商订阅、删除和活动历史记录。请参阅生成的工具参考。

持久化活动历史记录

每次接受的 HTTP、电子邮件和 DNS 接收，以及每次成功的本地变更，都会在与状态变更相同的事务中写入 一条活动记录。重复的源投递也会获得记录。历史记录包括备注、响应设置、 延迟响应、令牌轮换、订阅、删除和过期信息。 使用 get_webhook_activity 读取，或向 /api/call 发送 POST 请求，并提供 action: activity、 私有的 token、since 游标和有上限的 limit。

删除和过期后，仍会保留最少的活动元数据。元数据不包括 私有令牌、提供商凭据、正文、备注和签名密钥。 现有事件会标记为已导入；无法重建其之前的变更历史。应用会追加记录；这不是具备密码学防篡改能力的日志。被拒绝的捕获不会作为已接受事件存储。

通过 configure_webhook 设置 verification_secret，即可要求对原始 HTTP 正文进行 SHA256 HMAC 验证。Openhook 接受 X-Openhook-Signature: sha256=… 和 GitHub 的 X-Hub-Signature-256。签名无效时会在捕获前拒绝请求。 Idempotency-Key 和 X-GitHub-Delivery 会在收件箱内对重试请求进行去重。

带有 ?openhook_wait=1 的传入 URL 会等待 Agent 响应，最长 20 秒。 发送此类请求前，请先启动 respond_to_next_request。

配置

环境变量	用途
OPENHOOK_ORIGIN	公共源站，默认值为 http://127.0.0.1:8788
OPENHOOK_DATABASE	SQLite 路径，默认值为 data/openhook.sqlite3
OPENHOOK_EMAIL_DOMAIN	自有入站邮件域名；未设置时禁用 SMTP
OPENHOOK_SMTP_PORT	SMTP 监听端口，默认值为 2525；将公共端口 25 映射到此端口
OPENHOOK_DNS_DOMAIN	自有委派回调区域；未设置时禁用 DNS
OPENHOOK_DNS_PORT	UDP/TCP DNS 监听端口，默认值为 5353；将公共端口 53 映射到此端口
OPENHOOK_DNS_ADDRESS	DNS A 查询返回的 IPv4 地址

SMTP 会拒绝发往未知收件箱的邮件，且绝不会转发邮件。DNS 仅对已配置的 区域提供应答，不提供递归查询。

部署

核心服务使用 Dockerfile。托管部署会构建其 hosted 目标；compose.dokploy.yaml 会在单独的 Dokploy 项目中选择该镜像。 将 Openhook 域名绑定到服务 openhook 的端口 8788。其命名数据 卷会在发布版本之间保留。请参阅部署说明。

提供方注册与本地投递

调用 register_github_webhook、register_stripe_webhook 或 register_linear_webhook，创建原生收件箱并在来源处订阅。 提供方 API 凭据仅临时使用，不会保存。捕获前会检查原始签名； Stripe 和 Linear 的时间戳会经过检查，以防重放。 请在收件箱过期前调用 unregister_webhook，以移除来源订阅。

要进行本地投递，请将 OPENHOOK_TOKEN 设为你的私有收件箱令牌，然后运行：

uv run openhook-listen --forward http://127.0.0.1:8080/webhook
# Or wake an already configured local OpenClaw:
uv run openhook-listen --openclaw

OpenClaw 投递还需要 OPENCLAW_HOOKS_TOKEN。未指定目标时， 监听器会以 JSON 格式打印事件。它会通过 HTTPS 向外建立连接，在 成功投递后保存游标，并重试失败的投递。投递至少一次：接收方应 按事件 ID 去重。每个目标都有自己的游标；每个目标和令牌都应运行一个监听器。 不包含托管 SSH 隧道的配置。

验证

网站采用居中的文本界面，使用自托管的 Paper Mono v1.000 可变字体和已批准的 Openhook 徽标。公共页面和实时工具 架构会在 JavaScript 运行前渲染为 HTML。Agent 入口包括 /agents.md、/skill.md、/llms.txt、/llms-full.txt、/docs.md 和 /openapi.json。其 webhook 演示会创建收件箱、发送真实回调， 并读取捕获的事件。编辑 web/ 后，请刷新资源版本：

bun run build

uv run --all-packages --extra dev pytest
node --check web/assets/app.js

测试涵盖原生 HTTP 捕获、私有令牌隔离、签名检查、 幂等性、持久化、过期、MCP，以及真实的本地 SMTP 和 UDP/TCP DNS。

采用 MIT 许可证。必需的第三方声明见 THIRD_PARTY_NOTICES.md。

托管开发与贡献

核心软件包不包含计费适配器，也不读取运营方的支付或登录 凭据。单独安装的 hosted/ 软件包增加了 GitHub 身份验证、可撤销的 Agent 密钥、自有收件箱，以及经过验证的付费发票权益。有关配置、 限制、测试模式要求和上线依赖项，请参阅托管运营。代码中包含相关功能 并不意味着存在真实商户或已付费上线。

请参阅贡献指南和安全问题报告。