内容
# 执行器
**连接任意代理到所有应用。**
执行器是一个开源的 AI 代理集成层。配置所有集成（MCP 服务器、OpenAPI 规范、GraphQL API）并进行身份验证和每个工具的策略，然后从任何与 MCP 兼容的代理使用该目录。
[网站](https://executor.sh) · [文档](https://executor.sh/docs) · [Discord](https://discord.gg/eF29HBHwM6)
## 为什么使用执行器
您使用的每个代理（Claude Code、Cursor、ChatGPT 等）都需要其自己的每个集成的副本：相同的 API 密钥粘贴在三个位置，相同的 MCP 服务器连接，共享的工具概念。
执行器是中间层。添加一个工具一次，授予凭证一次，设置策略一次，所有代理通过 MCP 共享它。您的集成、身份验证和策略都存储在一个地方，而不是分散在每个客户端。
- **任意来源。** 对 MCP 服务器、OpenAPI、GraphQL 和 Google Discovery 提供一流支持。如果您可以用 JSON 模式描述它，它就可以成为一个集成。插件系统对任何来源类型开放。
- **一个目录，每个代理。** 任何与 MCP 兼容的连接都使用相同的工具集。
- **受策略管理。** 每个工具都允许、需要批准或被阻止，默认情况下会根据规范进行合理设置。
- **按需运行。** 本地 CLI、桌面应用程序、托管的 Executor Cloud 或在 Docker 或 Cloudflare 上自行托管。功能相同，包装不同。
## 工作原理
1. **添加集成**：MCP 服务器、OpenAPI 规范或 GraphQL API。
2. **创建连接**：一个配置（可选身份验证）的实例。该集成可以有多个连接。
3. **设置策略**：决定每个工具是始终允许、需要批准还是被阻止。
4. **将您的代理指向执行器** 通过 MCP。它们都共享相同的目录。
有关完整模型的更多信息，请参阅[概念](https://executor.sh/docs/concepts/integrations)。
## 快速入门
最快的路径是 **[Executor Cloud](https://executor.sh)**：注册，添加集成，然后将您的代理指向托管的 MCP 端点。不需要安装。
如果您想在本地运行（Node.js 20+）：
```bash
npm install -g executor # 或：pnpm add -g / bun add -g / yarn global add
executor install # 安装持久的后台服务
executor web # 在浏览器中打开网页界面
```
`executor install` 在重启后保持服务运行。对于一次性的前台运行时，请使用 `executor web --foreground`。从网页界面添加您的第一个集成并连接代理。
### 与您的代理一起设置
如果您希望让您的编码代理进行设置？复制[文档中的设置提示](https://executor.sh/docs)，并将其粘贴到 Claude、Cursor 或任何具有 MCP 功能的代理中。它将帮助您选择如何运行执行器、安装它、通过 MCP 连接并使您的第一个集成正常工作。
## 运行方式
每种形式都提供相同的功能，只是包装不同。
| 形式 | 最适合 | 文档 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Executor Cloud** | 最快的开始。使用它从许多代理（包括 ChatGPT 等云代理）中，无需在本地运行。免费层。 | [云](https://executor.sh/docs/hosted/cloud) |
| **CLI** | 无头或服务器环境。运行本地后台服务。 | [CLI](https://executor.sh/docs/local/cli) |
| **桌面应用程序** | 常规桌面（Mac、Windows、Linux）。相同的运行时，以原生应用程序的形式。 | [桌面](https://executor.sh/docs/local/desktop) |
| **自行托管（Docker）** | 您自己的基础设施，完全控制。 | [Docker](https://executor.sh/docs/hosted/docker) |
| **自行托管（Cloudflare）** | 将其部署为 Cloudflare Worker。 | [Cloudflare](https://executor.sh/docs/hosted/cloudflare) |
## 通过 MCP 连接代理
使用 [`add-mcp`](https://www.npmjs.com/package/add-mcp) 将执行器添加到任何 MCP 客户端（Claude Code、Cursor、OpenCode），它可以检测客户端并为您编写配置：
```bash
# 通过 HTTP（运行的服务提供可流式 HTTP 端点）
npx add-mcp http://127.0.0.1:4788/mcp --transport http --name executor
# 或通过 stdio，使用 executor CLI 在您的 PATH 上
npx add-mcp "executor mcp" --name executor
```
网页界面中的 **连接** 卡片显示了确切的命令（如果有不同的端口，则显示端口号），已填写完毕。大多数 MCP 客户端仅在启动时加载服务器，因此您可能需要在客户端重启或打开新聊天之前， Executor 工具才会出现。
## 添加集成
从网页界面，点击 **添加来源**，粘贴 OpenAPI、GraphQL 或 MCP URL，执行器检测类型，索引工具并处理身份验证。或者，从 CLI 添加：
```bash
executor call executor openapi addSource '{
"spec": "https://petstore3.swagger.io/api/v3/openapi.json",
"namespace": "petstore",
"baseUrl": "https://petstore3.swagger.io/api/v3"
}'
```
在 OpenAPI 文档具有相对 `servers` 条目时使用 `baseUrl`（例如 `"/api/v3"`）。使用 `executor tools sources` 确认它是否处于活动状态。
## 使用工具
### 从 CLI
```bash
executor tools search "发送电子邮件" # 按意图查找工具
executor call github issues --help # 浏览命名空间
executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
```
`executor call`、`executor resume` 和 `executor tools ...` 在需要时自动启动本地守护进程，并选择一个空闲端口，如果默认端口被占用。如果执行暂停进行身份验证或批准，请恢复它：
```bash
executor resume --execution-id exec_123
```
### 从您自己的代码
使用 TypeScript SDK（Promise API；也提供 Effect-native API）嵌入执行器：
```ts
import { createExecutor } from "@executor-js/sdk/promise";
import { openApiPlugin } from "@executor-js/plugin-openapi/promise";
const executor = await createExecutor({ plugins: [openApiPlugin()] });
// 添加集成，创建连接，然后列出和调用工具
const tools = await executor.tools.list({ integration: "inventory" });
const schema = await executor.tools.schema(tools[0].address);
await executor.close();
```
有关可运行的端到端脚本，请参阅 [`examples/`](examples)。
### CLI 参考
```bash
executor install # 安装/启动持久的后台服务
executor web # 打开正在运行的网页界面
executor web --foreground # 启动临时前台运行时 + 网页界面
executor daemon run # 在后台启动持久的本地守护进程
executor daemon status # 显示守护进程状态
executor daemon stop # 停止守护进程
executor daemon restart # 重启守护进程
executor mcp # 启动 MCP 端点（stdio）
executor call <path...> '{"k":"v"}' # 调用工具按路径段
executor call <path...> --help # 浏览命名空间/资源/方法
executor call <path...> --help --match "<text>" --limit <n> # 缩小巨大的命名空间
executor resume --execution-id <id> # 恢复暂停的执行
executor tools search "<query>" # 按意图搜索工具
executor tools sources # 列出配置的来源 + 工具计数
executor tools describe <path> # 显示工具 TypeScript/JSON 架构
```
## 项目布局
执行器是一个 Bun + Turborepo 多仓库。
```
apps/
cli/ executor CLI 和本地后台服务
desktop/ 桌面应用程序（Mac、Windows、Linux）
local/ 由 CLI 和桌面共享的本地运行时
cloud/ Executor Cloud（托管产品）
host-selfhost/ 自托管服务器（Docker）
host-cloudflare/ Cloudflare Worker 部署
marketing/ executor.sh 网站
docs/ executor.sh/docs 文档
packages/
core/ 合同、插件连接、作用域、策略、SDK、API、CLI 核心
kernel/ 执行运行时（QuickJS、Deno 子进程、动态工作器）
plugins/ 来源和提供者插件（openapi、graphql、mcp、google、
microsoft、1password、keychain、encrypted/file secrets、...）
hosts/ 主机适配器（MCP 接口、Cloudflare）
react/ 共享 React UI
app/ 网页应用程序 UI
examples/ 可运行的 SDK 示例
e2e/ 全栈端到端测试
```
## 本地开发
```bash
bun install
bun run bootstrap # 幂等：安装依赖、构建所需工件、获取 Playwright
bun run dev # 启动开发服务器（默认为 http://127.0.0.1:4788）
```
`bun run bootstrap` 在全新检出时是必需的：其构建步骤会生成工件，而开发服务器如果没有这些工件则会失败。有关开发服务器、端口和环境陷阱的信息，请参阅 [RUNNING.md](RUNNING.md)，有关贡献者合约的信息，请参阅 [AGENTS.md](AGENTS.md)。
### 测试
```bash
bun run test # 单元 + 集成套件
bun run test:e2e # 全栈端到端：启动云和自托管应用程序并驱动它们
```
浏览器端到端场景需要 Playwright 的 Chromium 每个机器一次：`bunx playwright install chromium`。
## 社区
加入 [Discord](https://discord.gg/eF29HBHwM6)。要了解更多信息，请访问 [executor.sh](https://executor.sh) 或 [Ask DeepWiki](https://deepwiki.com/UsefulSoftwareCo/executor)。
## 许可证
[MIT](LICENSE)
## 致谢
- 感谢 [Crystian](https://www.linkedin.com/in/crystian/) 提供 npm 包名 `executor`。
## 参考
作为我的编码过程的一部分，我让我的代理访问其他代码库的参考资料，以了解模式和其他人如何实现系统。非详尽列表：
- [FumaDB](https://github.com/fuma-nama/fumadb) - 存储适配器参考
- [Effect](https://github.com/Effect-TS/effect) - 一般代码模式
- [OpenCode](https://github.com/anomalyco/opencode) - 插件系统参考
- [OpenClaw](https://github.com/openclaw/openclaw) - 插件系统参考
- [Emdash](https://github.com/emdash-cms/emdash) - 插件系统参考
- [Pi](https://github.com/badlogic/pi-mono) - 插件系统参考
您也可以使用此代码库作为参考，以了解其实现方式。
