preloop

🚀 Preloop：AI 智能体的策略引擎

Preloop 是一款全面的 MCP 防火墙，能让你完全掌控 AI 智能体的操作。你可以定义访问策略、审批流程和审计跟踪，根据条件允许、拒绝操作或要求审批。

Preloop 也正逐渐发展成为托管运行时的 AI 劳动力控制平面。现在，工作流可以通过 Preloop 拥有的兼容 OpenAI 的网关路由模型流量，从而集中实施使用情况、支出、运行时身份和预算的管理。

支持与 OpenClaw、Claude Code、Cursor、Codex 以及任何兼容 MCP 的智能体协同工作。

阅读官方文档：完整的指南和教程请访问 docs.preloop.ai。

🚀 快速开始

AI 智能体如 Claude Code、Cursor 和 OpenClaw 正在改变我们的工作方式。但强大的能力也伴随着巨大的风险，比如意外删除数据、泄露机密、成本失控和引入未测试的变更等。Preloop 可以定义策略，允许安全操作，拒绝危险操作，并对介于两者之间的操作要求人工审批，让你掌控全局，同时让 AI 处理日常工作。

✨ 主要特性

安全与控制

• 策略引擎：为任何工具或操作定义允许、拒绝和审批工作流。
• 访问规则：每个工具可设置多个有序规则，支持允许、拒绝或要求审批操作。
• 拖放排序：直观地重新排列规则评估优先级。
• 细粒度规则：策略可检查工具名称、参数值和上下文。
• 即时通知：通过移动应用、电子邮件、Slack 或 Mattermost 接收警报。
• 一键审批：可在手机、手表或桌面设备上批准或拒绝操作。
• 完整审计跟踪：记录每个 AI 操作和策略决策的完整日志。
• 异步审批模式：非阻塞式审批，工具立即返回，智能体轮询 get_approval_status 直到人工决策。
• 工具调用理由：要求智能体为每个工具调用提供理由，模式分为 必需（无理由则阻塞）或 可选（智能体可提供）。
• 灵活条件：使用 CEL 表达式实现上下文感知规则（企业版）。
• AI 审批（企业版）：由 AI 驱动的审批，可配置模型、提示、置信度阈值和回退行为。
• 团队审批：关键操作需要多个团队成员达成法定人数批准（企业版）。

集成与兼容性

• MCP 代理：与任何兼容模型上下文协议（MCP）的 AI 智能体协同工作。
• 零基础设施变更：即插即用的解决方案，无需修改代码。
• 内置工具：包含 11 个用于问题和 PR/MR 管理的工具。
• 外部 MCP 服务器：通过 Preloop 的安全层代理任何外部 MCP 服务器。
• 问题跟踪器同步：连接 Jira、GitHub、GitLab 以获取完整上下文。

自动化平台

• 智能体工作流：构建由 Webhook、调度或跟踪器事件触发的事件驱动工作流。
• 网关路由模型访问：托管工作流可使用 Preloop 拥有的模型网关进行集中成本控制、遥测和密钥管理。
• 向量搜索：使用嵌入技术进行智能相似度搜索。
• 重复检测：自动识别重叠问题。
• 合规指标：评估和提高问题质量。
• Web UI：采用 Lit、Vite 和 Shoelace 构建的现代界面。

📦 安装指南

前提条件

• Python 3.11 及以上版本
• PostgreSQL 14 及以上版本
• PostgreSQL 的 PGVector 扩展（用于向量搜索功能）

本地设置

# 克隆仓库
git clone https://github.com/preloop/preloop.git
cd preloop

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上使用：.venv\Scripts\activate

# 安装依赖
pip install -e ".[dev]"

# 设置数据库

# 配置环境
cp .env.example .env
# 编辑 .env 文件，根据需要进行设置

Docker 设置

# 克隆仓库
git clone https://github.com/preloop/preloop.git
cd preloop

# 运行完整的开发栈（后端 + 工作进程 + 支持热更新的前端）
docker compose up

# 使用标记的发布镜像运行（生产环境）
PRELOOP_VERSION=0.8.0 SECRET_KEY=$(openssl rand -hex 32) \
  docker compose -f docker-compose.release.yaml up -d

快速安装程序也可用：

# 安装独立的 CLI
curl -fsSL https://preloop.ai/install/cli | sh

# 安装开源栈
curl -fsSL https://preloop.ai/install/oss | sh

在执行上述命令之前设置 PRELOOP_VERSION=0.8.0 可指定特定版本，或者使用 https://preloop.ai/install/<script>?version=0.8.0。

Kubernetes 设置

Preloop 可以使用提供的 Helm 图表部署到 Kubernetes：

# 添加 Spacecode Helm 仓库（如果可用）
# helm repo add spacecode https://charts.spacecode.ai
# helm repo update

# 从本地图表安装
helm install preloop ./helm/preloop

# 或者从 GitHub 发布版本安装打包的图表
# helm install preloop https://github.com/preloop/preloop/releases/download/v0.8.0-beta.3/preloop-0.8.0-beta.3.tgz

# 或者使用自定义值安装
helm install preloop ./helm/preloop --values custom-values.yaml

有关 Helm 图表的更多详细信息，请参阅 chart README。

💻 使用示例

启动服务器

1. 设置环境变量： 确保你有一个配置好必要环境变量的 .env 文件（参考 .env.example）。关键变量包括数据库连接详细信息、API 密钥等。
2. 启动 Preloop API： 使用提供的脚本启动主 API 服务器：

./start.sh

此脚本通常会激活虚拟环境并启动服务器（例如 python -m preloop.server）。 3. 启动 Preloop 同步服务： 在另一个终端中，启动同步服务以开始从配置的跟踪器索引数据：

# 如果虚拟环境未激活，请先激活
# source .venv/bin/activate
preloop-sync scan all

此命令指示 Preloop Sync 扫描所有配置的跟踪器并更新数据库。

使用 REST API

Preloop 提供了一个 RESTful HTTP API：

import requests
import json

# Preloop API 的基础 URL
base_url = "http://localhost:8000/api/v1"

# 进行身份验证并获取令牌
auth_response = requests.post(
    f"{base_url}/auth/token",
    json={"username": "your-username", "password": "your-password"}
)
token = auth_response.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# 测试跟踪器连接
connection = requests.post(
    f"{base_url}/projects/test-connection",
    headers=headers,
    json={
        "organization": "spacecode",
        "project": "astrobot"
    }
)
print(json.dumps(connection.json(), indent=2))

# 搜索与身份验证相关的问题
results = requests.get(
    f"{base_url}/issues/search",
    headers=headers,
    params={
        "organization": "spacecode",
        "project": "astrobot",
        "query": "authentication problems",
        "limit": 5
    }
)
print(json.dumps(results.json(), indent=2))

# 创建一个新问题
issue = requests.post(
    f"{base_url}/issues",
    headers=headers,
    json={
        "organization": "spacecode",
        "project": "astrobot",
        "title": "Improve login error messages",
        "description": "Current error messages are not clear enough...",
        "labels": ["enhancement", "authentication"],
        "priority": "High"
    }
)
print(json.dumps(issue.json(), indent=2))

📚 详细文档

API 文档

运行时，API 文档可在以下地址访问：

http://localhost:8000/docs

OpenAPI 规范也可在以下地址获取：

http://localhost:8000/openapi.json

统一 WebSocket

Preloop 使用统一的 WebSocket 连接进行应用程序的实时更新：

• 连接地址：ws://localhost:8000/api/v1/ws/unified
• 消息路由：
  • 工作流执行更新（flow_executions 主题）
  • 审批请求通知（approvals 主题）
  • 系统活动更新（activity 主题）
  • 会话事件（system 主题）
• 特性：
  • 带指数退避的自动重连
  • 发布/订阅消息路由到订阅者
  • 基于主题的过滤以实现高效消息传递
  • 带活动跟踪的会话管理
  • 心跳监控

使用 MCP 工具的 API

Preloop API 包含集成的 MCP 工具端点，支持动态工具过滤，允许任何基于 HTTP 的 MCP 客户端直接连接。 阅读 docs.preloop.ai 中的 MCP 集成指南，了解如何对 Claude Code、Cursor 和 Windsurf 等客户端进行身份验证，以及设置工作流或超时。

移动推送通知（iOS/Android）

开源用户可以通过将请求代理到生产 Preloop 服务器（https://preloop.ai）来启用移动推送通知。 设置步骤：

1. 在 https://preloop.ai 创建一个账户。
2. 从设置页面生成一个具有 push_proxy 范围的 API 密钥。
3. 使用以下环境变量配置你的实例：

# 推送通知代理配置
PUSH_PROXY_URL=https://preloop.ai/api/v1/push/proxy
PUSH_PROXY_API_KEY=your-api-key-here

4. 在 Preloop 控制台的通知偏好设置页面中启用推送通知。
5. 通过扫描通知偏好设置中显示的 QR 码注册你的移动设备。

配置完成后，审批请求将在你注册的 iOS 或 Android 设备上触发推送通知。

版本检查与更新

默认情况下，Preloop 在启动时和每天一次会联系 https://preloop.ai 检查版本更新，这有助于你了解新版本和安全更新。

• 隐私说明：仅发送实例 UUID、版本号和 IP 地址，不传输用户数据。
• 选择退出：设置 PRELOOP_DISABLE_TELEMETRY=true 或 DISABLE_VERSION_CHECK=true 可完全禁用版本检查和遥测功能。

🔧 技术细节

核心功能

访问策略

可以为任何 AI 工具或操作定义细粒度的访问控制：

• 工具支持多个有序的 访问规则（不仅仅是简单的批准/拒绝）。
• 规则按优先级顺序评估，第一个匹配的规则生效。
• 每个规则有一个操作（允许/拒绝/要求审批）、可选的 CEL 条件和可选的拒绝消息。
• 规则可以在 UI 中通过拖放重新排序。

审批工作流

当 AI 尝试受保护的操作时，Preloop 会暂停并通知你：

• 即时通知：通过移动应用、电子邮件、Slack 或 Mattermost 发送。
• 一键审批：可在手机、手表或桌面设备上操作。
• 异步审批模式：工具立即返回一个轮询句柄，智能体轮询 get_approval_status 直到获得批准，然后接收工具结果（企业版）。
• 每个工具的理由说明：要求或可选地请求智能体在审批前解释 为什么 调用某个工具（企业版）。
• 基于团队的审批：具有法定人数要求（企业版）。
• 升级策略：用于时间敏感的操作（企业版）。

策略即代码

可以在 YAML 中定义策略，并通过 CLI 或 API 进行管理：

# 示例：生产部署需要审批
version: "1.0"
metadata:
  name: "Production Safeguards"
  description: "Require approval before deploying to production"
  tags: [security, production]

approval_workflows:
  - name: "deploy-approval"
    timeout_seconds: 600
    required_approvals: 1
    async_approval: true          # 智能体轮询而不是阻塞

tools:
  - name: "bash"
    source: mcp
    approval_workflow: "deploy-approval"
    justification: required        # 智能体必须解释调用原因
    conditions:
      - expression: "args.command.contains('deploy') && args.command.contains('production')"
        action: require_approval
        description: "Production deployments require approval"

• 版本控制：可以将策略与代码一起进行版本控制。
• GitOps 工作流：用于策略更改。
• CLI 管理：用于自动化和脚本编写。
• API 访问：用于程序化策略管理。

完整审计跟踪

每个 AI 操作都会记录完整的上下文信息：

• 尝试的操作（工具、参数、上下文）。
• 匹配的策略及其原因。
• 谁批准或拒绝了操作（以及时间）。
• 执行结果和持续时间。 这对于安全审查、合规性检查和调试至关重要。

AI 模型网关

Preloop 可以代表托管运行时终止模型流量，而不是直接将提供商凭证交给智能体容器：

• 兼容 OpenAI 的网关端点：GET /openai/v1/models、POST /openai/v1/chat/completions、POST /openai/v1/responses。
• 兼容 Anthropic 的网关端点：POST /anthropic/v1/messages。
• 支持聊天完成和响应的 SSE 流式传输。
• 每个请求归因于账户、工作流、工作流执行、API 密钥和运行时主体。
• 令牌和估计成本核算会持久化到网关使用分类账。
• 支持账户级和工作流级预算执行，带有软限制注释和硬停止功能。
• 提供面向产品的使用摘要端点，用于账户和工作流监控。
• 提供账户范围的运行时会话浏览器端点，用于浏览工作流之外的托管会话。
• 通过 GET /api/v1/flows/executions/{execution_id}/gateway-events 进行执行范围的网关事件检查。
• 提供控制台界面，用于浏览最近的运行时会话和搜索捕获的网关交互。

密钥管理

Preloop 现在将 AI 模型凭证存储在与提供商无关的密钥抽象后面：

• 内置 local_encrypted 后端，适用于简单的自托管部署。
• 用于工作流执行的仅哈希运行时 API 令牌。
• 可选的外部密钥后端路径，适用于 Vault/OpenBao 兼容的 KV v2 存储。
• 智能体运行时可以接收短期的 Preloop 网关令牌，而不是提供商密钥。

与 AWS Agent Core 的比较

| 特性 | Preloop | AWS Agent Core | |---------|:-------:|:--------------:| | 开源 | ✅ | ❌ | | 自托管选项 | ✅ | ❌ | | 策略即代码（YAML） | ✅ | 有限 | | MCP 原生支持 | ✅ | ❌ | | 与任何智能体兼容 | ✅ | 专注于 AWS | | 人工审批工作流 | ✅ | ✅ | | 审计跟踪 | ✅ | ✅ | | CLI 管理 | ✅ | AWS CLI | | 对 GitOps 友好 | ✅ | 有限 | | 移动应用审批 | ✅ | ❌ | | 基于团队的审批 | ✅（企业版） | ✅ |

架构

Preloop 具有模块化架构，旨在为 AI 智能体提供安全的控制平面，将核心 API 服务器、数据库模型、后端同步服务和 Web 前端控制台分离。 如需系统组件、数据流和基础设施的完整概念概述，请参阅 架构文档。

前端与 CLI

• Preloop 控制台（前端）：位于 frontend 目录中，Web 界面提供治理控制、工具管理和仪表盘可见性。详情请参阅 frontend/README.md。
• Preloop CLI：可从命令行管理策略和系统状态。使用方法请参阅 cli/README.md。

📄 许可证

Preloop 是根据 Apache 许可证 2.0 许可的开源软件。

版权所有 (c) 2026 Spacecode AI Inc.