executor：给 AI 代理装一个统一的工具网关
人工智能代理缺失的集成层。让他们在安全环境中调用任何 OpenAPI / MCP / GraphQL / 自定义 js 函数。
秒懂
- 它是什么？
- executor 是一个开源的集成层，让 Claude Code、Cursor 等 MCP 兼容代理共享同一套工具目录、凭据和权限策略。本文基于仓库文档，拆解它的工作方式、运行形态和适用边界。
- 适合谁用？
- executor 适合那些在多个 MCP 客户端之间重复配置同一批 API 的团队，尤其是希望把认证和权限集中到一处、又不愿为每个代理单独维护配置的人。如果你的代理全部运行在云端且无法连接本地服务，或者你只需要单个工具的轻量封装，executor 的目录和策略模型可能反而增加复杂度。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
代理集成困境与 executor 的定位
每个 AI 代理，从 Claude Code 到 Cursor，都需要各自接线。同一个 API 密钥要粘贴三遍，同一个 MCP 服务器要反复配置，每个工具允许做什么没有统一说法。executor 想解决的就是这个重复劳动。它把自己放在代理和工具之间，成为一个集成层。你添加一次工具，配置一次凭据，设置一次策略，所有 MCP 兼容的代理就能共享同一个目录。这个定位很明确：不是又一个工具封装库，而是集中式的工具网关。
核心模型：集成、连接、策略三层分离
executor 的概念模型把配置拆成三层。集成（integration）是抽象定义，比如一个 OpenAPI 规范或一个 MCP 服务器地址。连接（connection）是集成的一个具体实例，可以带不同的认证配置。同一个集成可以创建多个连接，这为多环境或多租户场景留了空间。策略（policy）决定每个工具的行为：总是允许、需要审批、或者阻止。文档说默认值会从规范中推导，这省去了逐条配置的麻烦，但具体如何推导没有展开。三层分离的思路清晰，但文档没有说明连接级策略是否可行，目前看来策略只挂在工具上。
从安装到首次调用：CLI 的实际路径
本地运行需要 Node.js 20 以上。全局安装后，executor install 会安装一个持久的后台服务，executor web 打开网页界面。想临时跑一下就用 --foreground 参数。添加集成可以从界面操作，也可以走 CLI。README 给出了一个具体例子：executor call executor openapi addIntegration，传入 OpenAPI 规范地址、命名空间和 baseUrl。这里有个值得注意的细节：当 OpenAPI 文档里的 servers 是相对路径时，必须手动指定 baseUrl，否则工具调用可能打到错误的地址。添加后可以用 executor tools integrations 确认工具是否生效。
与代理连接：HTTP 与 stdio 两种方式
executor 的服务通过 streamable HTTP 暴露 MCP 端点，默认端口 4788。用 npx add-mcp 可以自动检测客户端类型并写入配置，这比手动编辑 MCP 配置文件省事。HTTP 方式适合远程或后台服务，stdio 方式则直接调用 executor mcp 命令。README 提醒，大多数 MCP 客户端只在启动时加载服务器，所以添加后需要重启客户端或开新会话，工具才会出现。这个限制不是 executor 特有的，但如果你习惯在会话中途添加工具，会感到不便。
工具调用与审批恢复机制
CLI 提供了按意图搜索工具的命令：executor tools search "send email"。调用工具时用 executor call 加上命名空间和操作名，例如 executor call github issues create，参数以 JSON 形式传入。文档提到，如果执行过程中因为等待认证或审批而暂停，可以用 executor resume --execution-id 恢复。这个机制对需要人工介入的流程很实用，但 README 没有说明审批超时或拒绝后的行为，实际使用中可能需要自己摸索。
TypeScript SDK：嵌入自有代码的入口
除了 CLI 和代理连接，executor 还提供 TypeScript SDK。README 展示了一个 Promise API 的用法：创建 executor 实例，传入插件数组，然后列出工具、获取 schema、调用工具。文档特别提到还有一个 Effect-native API 可用，这暗示项目对函数式编程生态有额外支持。SDK 的粒度比 CLI 更细，适合把 executor 嵌入到自己的应用里，而不是仅仅作为代理的后端。不过示例代码只展示了列出和调用工具，没有展示如何创建连接或设置策略，这些关键步骤在文档中应该更完整。
运行形态与适用场景的取舍
executor 提供五种运行方式：云托管、CLI、桌面应用、Docker 自托管、Cloudflare Worker。文档声称每种形态功能相同，只是打包方式不同。这听起来很理想，但实际差异需要验证。比如 Cloudflare Worker 跑在边缘，而 MCP 客户端可能需要长连接，两者能否完全等价存疑。免费云托管对快速试用有吸引力，但如果你处理敏感数据，自托管才是稳妥选择。Docker 和 Cloudflare 两种自托管路径给了不同基础设施偏好的团队各自的选择，但 README 没有给出具体的部署命令，需要去文档站查。
替代方案与边界条件
最直接的替代方案是每个代理各自配置 MCP 服务器，不使用任何中间层。那种方式配置分散，但每个代理独立演进，故障隔离更清晰。另一个思路是直接在自己的代码里调用 API SDK，跳过 MCP 和目录层，适合工具数量少、不需要策略控制的场景。executor 的取舍在于：它换来集中管理，却引入了额外服务依赖。你的代理必须能访问 executor 的端点，如果代理运行在隔离的云环境里，本地 CLI 方案就不适用。文档没有给出性能数据，对于高吞吐的工具调用，中间层可能成为瓶颈，这一点需要自行压测验证。
编辑结论
executor 适合那些在多个 MCP 客户端之间重复配置同一批 API 的团队，尤其是希望把认证和权限集中到一处、又不愿为每个代理单独维护配置的人。如果你的代理全部运行在云端且无法连接本地服务，或者你只需要单个工具的轻量封装，executor 的目录和策略模型可能反而增加复杂度。采用前先验证三件事：确认你的代理客户端支持 streamable HTTP 或 stdio 方式连接；检查 OpenAPI 文档中相对 servers 条目是否需要额外指定 baseUrl；明确你需要的策略粒度是工具级还是连接级，因为文档只提到工具级策略。
社区笔记