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 具有模塊化架構，旨在為 AI 智能體提供安全的控制平面，將核心 API 服務器、數據庫模型、後端同步服務和 Web 前端控制檯分離。 如需系統組件、數據流和基礎設施的完整概念概述，請參閱 架構文檔。

前端與 CLI

• Preloop 控制檯（前端）：位於 frontend 目錄中，Web 界面提供治理控制、工具管理和儀表盤可見性。詳情請參閱 frontend/README.md。
• Preloop CLI：可從命令行管理策略和系統狀態。使用方法請參閱 cli/README.md。

📄 許可證

Preloop 是根據 Apache 許可證 2.0 許可的開源軟件。

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