PentAGI

目录

• 概述
• 功能
• 快速入门
• API访问
• 高级设置
• 开发
• LLM代理测试
• 嵌入配置与测试
• 使用ftester进行函数测试
• 构建
• 致谢
• 许可证

概述

PentAGI是一款创新的自动化安全测试工具，利用前沿的人工智能技术。该项目专为信息安全专业人士、研究人员和爱好者设计，旨在提供一个强大而灵活的解决方案，用于执行渗透测试。

您可以观看视频 PentAGI概览：

功能

• 安全隔离。所有操作均在沙箱化的Docker环境中进行，实现完全隔离。
• 全自动运行。由AI驱动的代理可自动确定并执行渗透测试步骤，支持可选的执行监控和智能任务规划，以提高可靠性。
• 专业渗透测试工具。内置超过20种专业安全工具，包括nmap、metasploit、sqlmap等。
• 智能记忆系统。长期存储研究结果和成功方法，供未来参考。
• 知识图谱集成。基于Graphiti的知识图谱，采用Neo4j技术，用于语义关系追踪和高级上下文理解。
• 网络情报功能。通过scraper内置浏览器，从网络资源中收集最新信息。
• 外部搜索系统。集成先进的搜索API，包括Tavily、Traversaal、Perplexity、DuckDuckGo、Google自定义搜索、Sploitus Search以及Searxng，以实现全面的信息收集。
• 专家团队。配备专门的AI代理，负责研究、开发和基础设施任务，并可通过可选的执行监控和智能任务规划进一步优化性能，尤其适用于小型模型。
• 全面监控。提供详细的日志记录，并与Grafana/Prometheus集成，实现实时系统观测。
• 详尽报告。生成包含漏洞利用指南的全面漏洞报告。
• 智能容器管理。根据具体任务需求自动选择Docker镜像。
• 现代化界面。简洁直观的Web UI，便于系统管理和监控。
• 全功能API。提供完整的REST和GraphQL API，支持Bearer令牌认证，方便自动化和集成。
• 持久化存储。所有命令和输出均存储在PostgreSQL数据库中，并使用pgvector扩展。
• 可扩展架构。基于微服务的设计，支持水平扩展。
• 自托管方案。完全掌控您的部署和数据。
• 灵活的身份验证。支持10多家LLM提供商（OpenAI、Anthropic、Google AI/Gemini、AWS Bedrock、Ollama、DeepSeek、GLM、Kimi、Qwen、自定义）以及聚合平台（OpenRouter、DeepInfra）。对于生产环境的本地部署，请参阅我们的vLLM + Qwen3.5-27B-FP8指南。
• API令牌认证。安全的Bearer令牌系统，用于程序化访问REST和GraphQL API。
• 快速部署。通过Docker Compose轻松完成设置，并提供全面的环境配置。

架构

系统上下文

flowchart TB
    classDef person fill:#08427B,stroke:#073B6F,color:#fff
    classDef system fill:#1168BD,stroke:#0B4884,color:#fff
    classDef external fill:#666666,stroke:#0B4884,color:#fff

    pentester["👤 安全工程师
    （系统用户）"]

    pentagi["✨ PentAGI
    （自主渗透测试系统）"]

    target["🎯 目标系统
    （被测试系统）"]
    llm["🧠 LLM提供商
    （OpenAI/Anthropic/Ollama/Bedrock/Gemini/自定义）"]
    search["🔍 搜索系统
    （Google/DuckDuckGo/Tavily/Traversaal/Perplexity/Sploitus/Searxng）"]
    langfuse["📊 LangFuse UI
    （LLM可观测性仪表盘）"]
    grafana["📈 Grafana
    （系统监控仪表盘）"]

    pentester --> |使用HTTPS| pentagi
    pentester --> |监控AI HTTPS| langfuse
    pentester --> |监控系统HTTPS| grafana
    pentagi --> |测试各种协议| target
    pentagi --> |查询HTTPS| llm
    pentagi --> |搜索HTTPS| search
    pentagi --> |报告HTTPS| langfuse
    pentagi --> |报告HTTPS| grafana

    class pentester person
    class pentagi system
    class target,llm,search,langfuse,grafana external

    linkStyle default stroke:#ffffff,color:#ffffff

graph TB
    subgraph 核心服务
        UI[前端UI<br/>React + TypeScript]
        API[后端API<br/>Go + GraphQL]
        DB[向量存储<br/>PostgreSQL + pgvector]
        MQ[任务队列<br/>异步处理]
        Agent[AI代理<br/>多智能体系统]
    end

    subgraph 知识图谱
        Graphiti[Graphiti<br/>知识图谱API]
        Neo4j[Neo4j<br/>图数据库]
    end

subgraph 监控
        Grafana[Grafana<br/>仪表盘]
        VictoriaMetrics[VictoriaMetrics<br/>时序数据库]
        Jaeger[Jaeger<br/>分布式追踪]
        Loki[Loki<br/>日志聚合]
        OTEL[OpenTelemetry<br/>数据采集]
    end

    subgraph 分析
        Langfuse[Langfuse<br/>LLM分析]
        ClickHouse[ClickHouse<br/>分析数据库]
        Redis[Redis<br/>缓存 + 限流器]
        MinIO[MinIO<br/>S3存储]
    end

    subgraph 安全工具
        Scraper[网页爬虫<br/>隔离浏览器]
        PenTest[安全工具<br/>20+专业工具<br/>沙箱执行]
    end

    UI --> |HTTP/WS| API
    API --> |SQL| 数据库
    API --> |事件| 消息队列
    消息队列 --> |任务| 代理
    代理 --> |命令| 渗透测试
    代理 --> |查询| 数据库
    代理 --> |知识| Graphiti
    Graphiti --> |图| Neo4j

    API --> |遥测| OTEL
    OTEL --> |指标| VictoriaMetrics
    OTEL --> |追踪| Jaeger
    OTEL --> |日志| Loki

    Grafana --> |查询| VictoriaMetrics
    Grafana --> |查询| Jaeger
    Grafana --> |查询| Loki

    API --> |分析| Langfuse
    Langfuse --> |存储| ClickHouse
    Langfuse --> |缓存| Redis
    Langfuse --> |文件| MinIO

    classDef core fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    classDef knowledge fill:#ffa,stroke:#333,stroke-width:2px,color:#000
    classDef monitoring fill:#bbf,stroke:#333,stroke-width:2px,color:#000
    classDef analytics fill:#bfb,stroke:#333,stroke-width:2px,color:#000
    classDef tools fill:#fbb,stroke:#333,stroke-width:2px,color:#000

    class UI,API,DB,MQ,Agent core
    class Graphiti,Neo4j knowledge
    class Grafana,VictoriaMetrics,Jaeger,Loki,OTEL monitoring
    class Langfuse,ClickHouse,Redis,MinIO analytics
    class Scraper,PenTest tools

erDiagram
    Flow ||--o{ Task : 包含
    Task ||--o{ SubTask : 包含
    SubTask ||--o{ Action : 包含
    Action ||--o{ Artifact : 产生
    Action ||--o{ Memory : 存储

    Flow {
        string id PK
        string name "Flow名称"
        string description "Flow描述"
        string status "active/completed/failed"
        json parameters "Flow参数"
        timestamp created_at
        timestamp updated_at
    }

    Task {
        string id PK
        string flow_id FK
        string name "Task名称"
        string description "Task描述"
        string status "pending/running/done/failed"
        json result "Task结果"
        timestamp created_at
        timestamp updated_at
    }

    SubTask {
        string id PK
        string task_id FK
        string name "子任务名称"
        string description "子任务描述"
        string status "queued/running/completed/failed"
        string agent_type "researcher/developer/executor"
        json context "Agent上下文"
        timestamp created_at
        timestamp updated_at
    }

    Action {
        string id PK
        string subtask_id FK
        string type "command/search/analyze/etc"
        string status "success/failure"
        json parameters "Action参数"
        json result "Action结果"
        timestamp created_at
    }

    Artifact {
        string id PK
        string action_id FK
        string type "file/report/log"
        string path "存储路径"
        json metadata "附加信息"
        timestamp created_at
    }

    Memory {
        string id PK
        string action_id FK
        string type "observation/conclusion"
        vector embedding "向量表示"
        text content "记忆内容"
        timestamp created_at
    }

sequenceDiagram
    participant O as Orchestrator
    participant R as Researcher
    participant D as Developer
    participant E as Executor
    participant VS as Vector Store
    participant KB as Knowledge Base

    Note over O,KB: Flow Initialization
    O->>VS: Query similar tasks
    VS-->>O: Return experiences
    O->>KB: Load relevant knowledge
    KB-->>O: Return context

    Note over O,R: Research Phase
    O->>R: Analyze target
    R->>VS: Search similar cases
    VS-->>R: Return patterns
    R->>KB: Query vulnerabilities
    KB-->>R: Return known issues
    R->>VS: Store findings
    R-->>O: Research results

    Note over O,D: Planning Phase
    O->>D: Plan attack
    D->>VS: Query exploits
    VS-->>D: Return techniques
    D->>KB: Load tools info
    KB-->>D: Return capabilities
    D-->>O: Attack plan

    Note over O,E: Execution Phase
    O->>E: Execute plan
    E->>KB: Load tool guides
    KB-->>E: Return procedures
    E->>VS: Store results
    E-->>O: Execution状态

graph TB
    subgraph "长期记忆"
        VS[(向量存储<br/>嵌入数据库)]
        KB[知识库<br/>领域专业知识]
        Tools[工具知识<br/>使用模式]
    end

    subgraph "工作记忆"
        Context[当前上下文<br/>任务状态]
        Goals[活跃目标<br/>目的]
        State[系统状态<br/>资源]
    end

    subgraph "情景记忆"
        Actions[过去行动<br/>命令历史]
        Results[行动结果<br/>成果]
        Patterns[成功模式<br/>最佳实践]
    end

    Context --> |查询| VS
    VS --> |检索| Context

    Goals --> |咨询| KB
    KB --> |指导| Goals

    State --> |记录| Actions
    Actions --> |学习| Patterns
    Patterns --> |存储| VS

    Tools --> |告知| State
    Results --> |更新| Tools

    VS --> |增强| KB
    KB --> |索引| VS

    classDef ltm fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    classDef wm fill:#bbf,stroke:#333,stroke-width:2px,color:#000
    classDef em fill:#bfb,stroke:#333,stroke-width:2px,color:#000

    class VS,KB,Tools ltm
    class Context,Goals,State wm
    class Actions,Results,Patterns em

flowchart TD
    A[输入链] --> B{需要摘要吗？}
    B -->|否| C[返回原始链]
    B -->|是| D[转换为ChainAST]
    D --> E[应用段落摘要]
    E --> F[处理过大的配对]
    F --> G[管理最后一节大小]
    G --> H[应用问答摘要]
    H --> I[用摘要重建链]
    I --> J{新链是否更小？}
    J -->|是| K[返回优化后的链]
    J -->|否| C

classDef process fill:#bbf,stroke:#333,stroke-width:2px,color:#000
    classDef decision fill:#bfb,stroke:#333,stroke-width:2px,color:#000
    classDef output fill:#fbb,stroke:#333,stroke-width:2px,color:#000

    class A,D,E,F,G,H,I process
    class B,J decision
    class C,K output

# 全局摘要器逻辑的默认值
SUMMARIZER_PRESERVE_LAST=true
SUMMARIZER_USE_QA=true
SUMMARIZER_SUM_MSG_HUMAN_IN_QA=false
SUMMARIZER_LAST_SEC_BYTES=51200
SUMMARIZER_MAX_BP_BYTES=16384
SUMMARIZER_MAX_QA_SECTIONS=10
SUMMARIZER_MAX_QA_BYTES=65536
SUMMARIZER_KEEP_QA_SECTIONS=1

# 助手摘要器逻辑的默认值
ASSISTANT_SUMMARIZER_PRESERVE_LAST=true
ASSISTANT_SUMMARIZER_LAST_SEC_BYTES=76800
ASSISTANT_SUMMARIZER_MAX_BP_BYTES=16384
ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS=7
ASSISTANT_SUMMARIZER_MAX_QA_BYTES=76800
ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS=3

PentAGI的架构设计具有模块化、可扩展性和安全性。以下是其关键组件：

1. 核心服务

   • 前端UI：基于React的Web界面，使用TypeScript以确保类型安全
   • 后端API：基于Go的REST和GraphQL API，采用Bearer令牌认证以支持程序化访问
   • 向量存储：PostgreSQL结合pgvector，用于语义搜索和记忆存储
   • 任务队列：异步任务处理系统，确保可靠运行
   • AI代理：多代理系统，各代理分工明确，以高效执行测试任务

2. 知识图谱

   • Graphiti：知识图谱API，用于跟踪语义关系和上下文理解
   • Neo4j：图数据库，用于存储和查询实体、动作及结果之间的关系
   • 自动捕获代理响应和工具执行记录，构建全面的知识库

3. 监控堆栈

   • OpenTelemetry：统一的可观测性数据收集与关联
   • Grafana：实时可视化与告警仪表盘
   • VictoriaMetrics：高性能的时间序列指标存储
   • Jaeger：端到端分布式追踪，便于调试
   • Loki：可扩展的日志聚合与分析

4. 分析平台

   • Langfuse：先进的LLM可观测性与性能分析工具
   • ClickHouse：面向列的分析数据仓库
   • Redis：高速缓存与限流功能
   • MinIO：兼容S3的对象存储，用于存储各类工件

5. 安全工具

   • 网页爬虫：隔离的浏览器环境，确保安全的网页交互
   • 渗透测试工具：包含20余种专业安全工具的完整套件
   • 沙箱执行：所有操作均在隔离容器中运行

6. 记忆系统

   • 长期记忆：持久存储知识与经验
   • 工作记忆：当前操作的活跃上下文与目标
   • 事件记忆：历史行动与成功模式
   • 知识库：结构化的领域专业知识与工具能力
   • 上下文管理：通过链式摘要技术智能管理不断增长的LLM上下文窗口

系统采用Docker容器实现隔离与便捷部署，核心服务、监控和分析模块分别使用独立网络，以确保严格的安全边界。每个组件均可水平扩展，并能在生产环境中配置为高可用架构。

快速入门

系统要求

• Docker与Docker Compose（或Podman——参见使用Podman运行PentAGI）
• 至少2个vCPU
• 至少4GB内存
• 20GB可用磁盘空间
• 具备互联网连接，以便下载镜像和更新

使用安装程序（推荐）

PentAGI提供了一个交互式安装程序，采用终端界面，可简化配置与部署流程。安装程序将引导您完成系统检查、LLM提供商设置、搜索引擎配置以及安全加固等步骤。

支持平台：

• Linux：amd64 下载 | arm64 下载
• Windows：amd64 下载
• macOS：amd64（Intel）下载 | arm64（M系列）下载

快速安装（Linux amd64）：

# 创建安装目录
mkdir -p pentagi && cd pentagi

# 下载安装程序
wget -O installer.zip https://pentagi.com/downloads/linux/amd64/installer-latest.zip

# 解压
unzip installer.zip

# 运行交互式安装程序
./installer

前提条件与权限：

安装程序需要适当的权限才能与 Docker API 交互以正常运行。默认情况下，它会使用 Docker 套接字 (/var/run/docker.sock)，这要求：

• 选项 1（推荐用于生产环境）： 以 root 用户身份运行安装程序：

  sudo ./installer
  

• 选项 2（开发环境）： 将您的用户添加到 docker 组，以获得对 Docker 套接字的访问权限：

  # 将当前用户添加到 docker 组
  sudo usermod -aG docker $USER
  
  # 注销并重新登录，或立即生效组更改
  newgrp docker
  
  # 验证 Docker 访问权限（无需 sudo 即可运行）
  docker ps
  

  ⚠️ 安全提示： 将用户加入 docker 组会赋予其与 root 用户相当的权限。请仅在受控环境中为可信用户执行此操作。对于生产部署，建议使用无 root 权限的 Docker 模式，或以 sudo 运行安装程序。

安装程序将执行以下步骤：

1. 系统检查：验证 Docker、网络连接及系统要求
2. 环境设置：创建并配置 .env 文件，使用最优默认值
3. 提供商配置：设置 LLM 提供商（OpenAI、Anthropic、Gemini、Bedrock、Ollama、自定义）
4. 搜索引擎：配置 DuckDuckGo、Google、Tavily、Traversaal、Perplexity、Sploitus、Searxng
5. 安全加固：生成安全凭据并配置 SSL 证书
6. 部署：使用 docker-compose 启动 PentAGI

适用于生产及增强安全性：

对于生产部署或安全敏感的环境，我们强烈建议采用分布式双节点架构，将工作负载隔离在独立服务器上。这样可以防止不可信代码的执行，并避免主系统上的网络访问问题。

查看详细指南：工作节点设置

双节点架构提供：

• 隔离执行：工作容器运行在专用硬件上
• 网络隔离：渗透测试拥有独立的网络边界
• 安全边界：基于 TLS 认证的 Docker-in-Docker 架构
• 带外攻击支持：专用于带外技术的端口范围

手动安装

1. 创建一个工作目录或克隆仓库：

mkdir pentagi && cd pentagi

2. 复制 .env.example 到 .env 或直接下载：

curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example

3. 创建示例文件（example.custom.provider.yml、example.ollama.provider.yml）或直接下载：

curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml

4. 在 .env 文件中填写所需的 API 密钥。

# 必需：至少选择一个 LLM 提供商
OPEN_AI_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key

# 可选：AWS Bedrock 提供商（企业级模型）
BEDROCK_REGION=us-east-1
# 选择一种认证方式：
BEDROCK_DEFAULT_AUTH=true                        # 选项 1：使用 AWS SDK 默认凭证链（推荐用于 EC2/ECS）
# BEDROCK_BEARER_TOKEN=your_bearer_token         # 选项 2：Bearer 令牌认证
# BEDROCK_ACCESS_KEY_ID=your_aws_access_key      # 选项 3：静态凭证
# BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key

# 可选：Ollama 提供商（本地或云端）
# OLLAMA_SERVER_URL=http://ollama-server:11434   # 本地服务器
# OLLAMA_SERVER_URL=https://ollama.com           # 云服务
# OLLAMA_SERVER_API_KEY=your_ollama_cloud_key    # 云端服务需提供，本地则为空

# 可选：中国 AI 提供商
# DEEPSEEK_API_KEY=your_deepseek_key             # DeepSeek（强推理能力）
# GLM_API_KEY=your_glm_key                       # GLM（智谱 AI）
# KIMI_API_KEY=your_kimi_key                     # Kimi（月之暗面，超长上下文）
# QWEN_API_KEY=your_qwen_key                     # Qwen（阿里云，多模态）

# 可选：本地 LLM 提供商（零成本推理）
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=your_model_name

# 可选：额外的搜索功能
DUCKDUCKGO_ENABLED=true
DUCKDUCKGO_REGION=us-en
DUCKDUCKGO_SAFESEARCH=
DUCKDUCKGO_TIME_RANGE=
SPLOITUS_ENABLED=true
GOOGLE_API_KEY=your_google_key
GOOGLE_CX_KEY=your_google_cx
TAVILY_API_KEY=your_tavily_key
TRAVERSAAL_API_KEY=your_traversaal_key
PERPLEXITY_API_KEY=your_perplexity_key
PERPLEXITY_MODEL=sonar-pro
PERPLEXITY_CONTEXT_SIZE=medium

# Searxng 元搜索引擎（整合多个来源结果）
SEARXNG_URL=http://your-searxng-instance:8080
SEARXNG_CATEGORIES=general
SEARXNG_LANGUAGE=
SEARXNG_SAFESEARCH=0
SEARXNG_TIME_RANGE=
SEARXNG_TIMEOUT=

## Graphiti 知识图谱设置
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_MODEL_NAME=gpt-5-mini

# Neo4j 设置（Graphiti 栈使用）
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687

# 助手配置
ASSISTANT_USE_AGENTS=false         # 创建新助手时的默认代理使用值

5. 修改 .env 文件中的所有安全相关环境变量以提升安全性。

6. 如果您希望在 VSCode 或其他 IDE 中将 .env 文件用作环境变量文件，请移除其中的所有内联注释：

perl -i -pe 's/\s+#.*$//' .env

7. 运行 PentAGI 堆栈：

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml
docker compose up -d

访问 localhost:8443 即可进入 PentAGI Web UI（默认用户名为 admin@pentagi.com，密码为 admin）。

[!NOTE] 如果您遇到关于 pentagi-network、observability-network 或 langfuse-network 的错误，则需要先运行 docker-compose.yml 来创建这些网络，然后再分别运行 docker-compose-langfuse.yml、docker-compose-graphiti.yml 和 docker-compose-observability.yml，以使用 Langfuse、Graphiti 和 Observability 服务。

要使用 PentAGI，您必须至少设置一个语言模型提供商（OpenAI、Anthropic、Gemini、AWS Bedrock 或 Ollama）。AWS Bedrock 提供来自领先 AI 公司的多种基础模型的企业级访问权限，而 Ollama 则在您拥有足够计算资源的情况下提供零成本的本地推理能力。此外，为搜索引擎配置额外的 API 密钥是可选的，但建议这样做以获得更好的结果。

对于使用高级模型的完全本地部署：请参阅我们的综合指南 使用 vLLM 和 Qwen3.5-27B-FP8 运行 PentAGI，了解生产级别的本地 LLM 配置。此配置在 4 张 RTX 5090 GPU 上实现了约 13,000 TPS 的提示处理速度和约 650 TPS 的完成速度，支持 12 个以上的并发流程，并且完全独立于云服务提供商。

LLM_SERVER_* 环境变量是一项实验性功能，未来可能会发生变化。目前，您可以使用它们来指定自定义的 LLM 服务器 URL 和适用于所有代理类型的单一模型。

PROXY_URL 是所有 LLM 提供商和外部搜索系统的全局代理 URL。您可以使用它来实现与外部网络的隔离。

docker-compose.yml 文件以 root 用户身份运行 PentAGI 服务，因为该服务需要访问 docker.sock 来管理容器。如果您使用 TCP/IP 网络连接到 Docker 而不是套接字文件，则可以移除 root 权限，改用默认的 pentagi 用户，从而提高安全性。

从外部网络访问 PentAGI

默认情况下，PentAGI 绑定到 127.0.0.1（仅限本地访问），以确保安全性。要从您网络中的其他设备访问 PentAGI，您需要配置外部访问权限。

配置步骤

1. 使用您的服务器 IP 地址更新 .env 文件：

# 网络绑定 - 允许外部连接
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443

# 公网 URL - 使用您实际的服务器 IP 或主机名
# 将 192.168.1.100 替换为您的服务器 IP 地址
PUBLIC_URL=https://192.168.1.100:8443

# CORS 源 - 列出所有将访问 PentAGI 的 URL
# 包括 localhost 以供本地访问，以及您的服务器 IP 以供外部访问
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443

[!IMPORTANT]

• 请将 192.168.1.100 替换为您实际的服务器 IP 地址
• 请勿在 PUBLIC_URL 或 CORS_ORIGINS 中使用 0.0.0.0，应使用实际的 IP 地址
• 为了灵活性，请在 CORS_ORIGINS 中同时包含 localhost 和您的服务器 IP

2. 重新创建容器以应用更改：

docker compose down
docker compose up -d --force-recreate

3. 验证端口绑定：

docker ps | grep pentagi

您应该会看到 0.0.0.0:8443->8443/tcp 或 :::8443->8443/tcp。

如果显示的是 127.0.0.1:8443->8443/tcp，则说明环境变量未被正确读取。在这种情况下，请直接编辑 docker-compose.yml 文件第 31 行：

ports:
  - "0.0.0.0:8443:8443"

然后再次重新创建容器。

4. 配置防火墙以允许端口 8443 的入站连接：

# Ubuntu/Debian 使用 UFW
sudo ufw allow 8443/tcp
sudo ufw reload

# CentOS/RHEL 使用 firewalld
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload

5. 访问 PentAGI：

• 本地访问： https://localhost:8443
• 网络访问： https://your-server-ip:8443

[!NOTE] 当您通过 IP 地址访问时，浏览器会提示您接受自签名的 SSL 证书警告。

使用 Podman 运行 PentAGI

PentAGI 完全支持 Podman 作为 Docker 的替代方案。然而，在使用 Podman 的无根模式 时，爬虫服务需要特殊配置，因为无根容器无法绑定特权端口（即 1024 以下的端口）。

Podman 无根模式配置

默认的爬虫配置使用 443 端口（HTTPS），这是一个特权端口。对于 Podman 无根模式，需要将爬虫配置为使用非特权端口：

1. 编辑 docker-compose.yml - 修改 scraper 服务（大约在第 199 行）：

scraper:
  image: vxcontrol/scraper:latest
  restart: unless-stopped
  container_name: scraper
  hostname: scraper
  expose:
    - 3000/tcp  # 从 443 改为 3000
  ports:
    - "${SCRAPER_LISTEN_IP:-127.0.0.1}:${SCRAPER_LISTEN_PORT:-9443}:3000"  # 映射到 3000 端口
  environment:
    - MAX_CONCURRENT_SESSIONS=${LOCAL_SCRAPER_MAX_CONCURRENT_SESSIONS:-10}
    - USERNAME=${LOCAL_SCRAPER_USERNAME:-someuser}
    - PASSWORD=${LOCAL_SCRAPER_PASSWORD:-somepass}
  logging:
    options:
      max-size: 50m
      max-file: "7"
  volumes:
    - scraper-ssl:/usr/src/app/ssl
  networks:
    - pentagi-network
  shm_size: 2g

2. 更新 .env 文件 - 将爬虫 URL 更改为使用 HTTP 和 3000 端口：

# Podman 无根模式下的爬虫配置
SCRAPER_PRIVATE_URL=http://someuser:somepass@scraper:3000/
LOCAL_SCRAPER_USERNAME=someuser
LOCAL_SCRAPER_PASSWORD=somepass

[!IMPORTANT] Podman 配置的关键变更：

• SCRAPER_PRIVATE_URL 使用 HTTP 而不是 HTTPS
• 使用 3000 端口 而不是 443
• 将内部 expose 改为 3000/tcp
• 更新端口映射，使其指向 3000 而不是 443

3. 重新创建容器：

podman-compose down
podman-compose up -d --force-recreate

4. 测试爬虫连通性：

# 在 pentagi 容器内测试
podman exec -it pentagi wget -O- "http://someuser:somepass@scraper:3000/html?url=http://example.com"

如果能看到 HTML 输出，则说明爬虫工作正常。

Podman 根模式

如果您以根模式运行 Podman（使用 sudo），则无需修改即可使用默认配置。爬虫将按预期在 443 端口上运行。

Docker 兼容性

所有 Podman 配置均与 Docker 完全兼容。非特权端口的方法在两种容器运行时中均可正常使用。

助手配置

PentAGI 允许您为助手配置默认行为：

ASSISTANT_USE_AGENTS 设置会影响在 UI 中创建新助手时“使用代理”切换按钮的初始状态：

• false（默认）：新助手默认创建时禁用代理委派
• true：新助手默认创建时启用代理委派

请注意，用户始终可以在创建或编辑助手时通过切换 UI 中的“使用代理”按钮来覆盖此设置。该环境变量仅控制初始默认状态。

🔌 API 访问

PentAGI 通过 REST 和 GraphQL API 提供全面的程序化访问功能，使您能够将渗透测试工作流集成到自动化流水线、CI/CD 流程以及自定义应用程序中。

生成 API Token

API Token 通过 PentAGI Web 界面进行管理：

1. 在 Web UI 中导航至 设置 → API Token
2. 单击 创建 Token 以生成新的 API Token
3. 配置 Token 属性：
   • 名称（可选）：Token 的描述性名称
   • 过期日期：Token 的过期时间（最短 1 分钟，最长 3 年）
4. 单击 创建 并立即复制 Token——出于安全考虑，它只会显示一次
5. 在您的 API 请求中将 Token 作为 Bearer Token 使用

每个 Token 都与您的用户账户关联，并继承您角色的权限。

使用 API Token

在您的 HTTP 请求的 Authorization 头中包含 API Token：

# GraphQL API 示例
curl -X POST https://your-pentagi-instance:8443/api/v1/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ flows { id title status } }"}'

# REST API 示例
curl https://your-pentagi-instance:8443/api/v1/flows \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API 探索与测试

PentAGI 提供交互式文档，用于探索和测试 API 端点：

GraphQL Playground

访问 GraphQL Playground：https://your-pentagi-instance:8443/api/v1/graphql/playground

1. 点击底部的 HTTP Headers 选项卡
2. 添加您的授权头：

   {
     "Authorization": "Bearer YOUR_API_TOKEN"
   }
   

3. 交互式地探索 Schema、运行查询并测试变更操作

Swagger UI

访问 REST API 文档：https://your-pentagi-instance:8443/api/v1/swagger/index.html

1. 点击 Authorize 按钮
2. 以 Bearer YOUR_API_TOKEN 格式输入您的 Token
3. 单击 Authorize 以应用
4. 直接从 Swagger UI 测试端点

生成 API 客户端

您可以使用 PentAGI 附带的 Schema 文件为首选编程语言生成类型安全的 API 客户端：

GraphQL 客户端

GraphQL Schema 可在以下位置获取：

• Web UI：导航至设置下载 schema.graphqls
• 直接文件：仓库中的 backend/pkg/graph/schema.graphqls

使用以下工具生成客户端：

• GraphQL Code Generator（JavaScript/TypeScript）：https://the-guild.dev/graphql/codegen
• genqlient（Go）：https://github.com/Khan/genqlient
• Apollo iOS（Swift）：https://www.apollographql.com/docs/ios

REST API 客户端

OpenAPI 规范可在以下位置获取：

• Swagger JSON：https://your-pentagi-instance:8443/api/v1/swagger/doc.json
• Swagger YAML：位于 backend/pkg/server/docs/swagger.yaml

使用以下工具生成客户端：

• OpenAPI Generator：https://openapi-generator.tech

  openapi-generator-cli generate \
    -i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
    -g python \
    -o ./pentagi-client
  

• Swagger Codegen：https://github.com/swagger-api/swagger-codegen

  swagger-codegen generate \
    -i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
    -l typescript-axios \
    -o ./pentagi-client
  

• swagger-typescript-api（TypeScript）：https://github.com/acacode/swagger-typescript-api

  npx swagger-typescript-api \
    -p https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
    -o ./src/api \
    -n pentagi-api.ts
  

API 使用示例

mutation CreateFlow {
  createFlow(
    modelProvider: "openai"
    input: "测试 https://example.com 的安全性"
  ) {
    id
    title
    status
    createdAt
  }
}

curl https://your-pentagi-instance:8443/api/v1/flows \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  | jq '.flows[] | {id, title, status}'

import requests

class PentAGIClient:
    def __init__(self, base_url, api_token):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_token}",
            "Content-Type": "application/json"
        }
    
    def create_flow(self, provider, target):
        query = """
        mutation CreateFlow($provider: String!, $input: String!) {
          createFlow(modelProvider: $provider, input: $input) {
            id
            title
            status
          }
        }
        """
        response = requests.post(
            f"{self.base_url}/api/v1/graphql",
            json={
                "query": query,
                "variables": {
                    "provider": provider,
                    "input": target
                }
            },
            headers=self.headers
        )
        return response.json()
    
    def get_flows(self):
        response = requests.get(
            f"{self.base_url}/api/v1/flows",
            headers=self.headers
        )
        return response.json()

# 使用
client = PentAGIClient(
    "https://your-pentagi-instance:8443",
    "your_api_token_here"
)

# 创建一个新流程
flow = client.create_flow("openai", "扫描 https://example.com 的漏洞")
print(f"创建的流程：{flow}")

# 列出所有流程
flows = client.get_flows()
print(f"总流程数: {len(flows['flows'])}")

import axios, { AxiosInstance } from 'axios';

interface Flow {
  id: string;
  title: string;
  status: string;
  createdAt: string;
}

class PentAGIClient {
  private client: AxiosInstance;

  constructor(baseURL: string, apiToken: string) {
    this.client = axios.create({
      baseURL: `${baseURL}/api/v1`,
      headers: {
        'Authorization': `Bearer ${apiToken}`,
        'Content-Type': 'application/json',
      },
    });
  }

  async createFlow(provider: string, input: string): Promise<Flow> {
    const query = `
      mutation CreateFlow($provider: String!, $input: String!) {
        createFlow(modelProvider: $provider, input: $input) {
          id
          title
          status
          createdAt
        }
      }
    `;

    const response = await this.client.post('/graphql', {
      query,
      variables: { provider, input },
    });

    return response.data.data.createFlow;
  }

  async getFlows(): Promise<Flow[]> {
    const response = await this.client.get('/flows');
    return response.data.flows;
  }

  async getFlow(flowId: string): Promise<Flow> {
    const response = await this.client.get(`/flows/${flowId}`);
    return response.data;
  }
}

// 使用示例
const client = new PentAGIClient(
  'https://your-pentagi-instance:8443',
  'your_api_token_here'
);

// 创建新流程
const flow = await client.createFlow(
  'openai',
  '对 https://example.com 执行渗透测试'
);
console.log('创建的流程:', flow);

// 列出所有流程
const flows = await client.getFlows();
console.log(`总流程数: ${flows.length}`);

安全最佳实践

在使用 API 令牌时：

• 切勿将令牌提交到版本控制系统——请使用环境变量或密钥管理工具。
• 定期轮换令牌——设置适当的过期日期，并定期生成新令牌。
• 为不同应用使用独立令牌——这样在需要时更容易撤销访问权限。
• 监控令牌使用情况——在“设置”页面查看 API 令牌的活动记录。
• 撤销未使用的令牌——禁用或删除不再需要的令牌。
• 仅使用 HTTPS——切勿通过未加密的连接发送 API 令牌。

令牌管理

• 查看令牌：在“设置”→“API 令牌”中查看所有有效令牌。
• 编辑令牌：更新令牌名称或撤销令牌。
• 删除令牌：永久移除令牌（此操作不可撤销）。
• 令牌 ID：每个令牌都有一个唯一的 ID，可复制以供参考。

令牌列表显示：

• 令牌名称（如果已提供）
• 令牌 ID（唯一标识符）
• 状态（启用/已撤销/已过期）
• 创建日期
• 过期日期

自定义 LLM 提供商配置

当使用 LLM_SERVER_* 变量配置自定义 LLM 提供商时，可以微调请求中使用的推理格式。

[!提示] 对于生产级本地部署，建议使用 vLLM 结合 Qwen3.5-27B-FP8 以获得最佳性能。请参阅我们的全面部署指南，其中包含硬件要求、配置模板（思考模式和非思考模式）以及性能基准测试结果，表明在 4 张 RTX 5090 显卡上可实现每秒 13,000 次提示处理。

LLM_SERVER_PROVIDER 设置在使用 LiteLLM 代理 时特别有用，因为它会在模型名称前添加提供商前缀。例如，通过 LiteLLM 连接到 Moonshot API 时，kimi-2.5 等模型会变为 moonshot/kimi-2.5。通过设置 LLM_SERVER_PROVIDER=moonshot，您可以使用相同的提供商配置文件来同时支持直接 API 访问和 LiteLLM 代理访问，而无需进行任何修改。

LLM_SERVER_LEGACY_REASONING 设置影响推理参数如何发送到 LLM：

• false（默认）：采用现代格式，将推理作为带有 max_tokens 参数的结构化对象发送。
• true：采用旧版格式，使用基于字符串的 reasoning_effort 参数。

此设置在与不同 LLM 提供商合作时非常重要，因为它们可能期望在 API 请求中使用不同的推理格式。如果您在使用自定义提供商时遇到与推理相关的问题，请尝试更改此设置。

LLM_SERVER_PRESERVE_REASONING 设置控制是否在多轮对话中保留推理内容：

• false（默认）：对话历史中不保留推理内容。
• true：保留推理内容并在后续 API 调用中发送。

此设置对于某些 LLM 提供商（如 Moonshot）是必需的，因为当多轮对话中未包含推理内容时，它们会返回类似“已启用思考功能，但助手工具调用消息中缺少 reasoning_content”的错误。如果您的提供商要求保留推理内容，请启用此设置。

Ollama 提供商配置

PentAGI 支持使用 Ollama 进行本地 LLM 推理（零成本、隐私性更强）以及 Ollama Cloud（提供免费层级的托管服务）。

配置变量

Ollama Cloud 配置

Ollama Cloud 提供托管推理服务，包含慷慨的免费层级和可扩展的付费方案。

免费层级设置（单模型）

# 免费层级一次只能使用一个模型
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_MODEL=gpt-oss:120b  # 示例：OpenAI OSS 120B 模型

付费层级设置（多模型与预建配置）

对于支持多个并发模型的付费层级，可以使用预建的 Ollama Cloud 配置：

# 使用预建的 Ollama Cloud 配置（包含在 Docker 镜像中）
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-cloud.provider.yml

预建的 ollama-cloud.provider.yml 配置包括针对所有代理类型的优化模型分配：

• 简单/助理：nemotron-3-super:cloud - 快速通用模型
• 主要代理：qwen3-coder-next:cloud - 高效模式下的高级推理
• 编码员/渗透测试员：qwen3-coder-next:cloud - 专门的编码模型
• 搜索者：qwen3.5:397b-cloud - 大上下文信息收集能力
• 精炼者/重构者：glm-5:cloud - 高质量文本精炼
• 顾问/增强者：minimax-m2.7:cloud - 高效的咨询任务
• 安装者：devstral-2:123b-cloud - 安装和设置任务

自定义配置（高级）

要创建您自己的代理配置，可以从主机文件系统挂载自定义文件：

# 使用自定义提供商配置
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama.provider.yml

# 从主机文件系统挂载自定义配置（在 .env 或 docker-compose 覆盖文件中）
PENTAGI_OLLAMA_SERVER_CONFIG_PATH=/path/on/host/my-ollama-config.yml

环境变量 PENTAGI_OLLAMA_SERVER_CONFIG_PATH 将您的主机配置文件映射到容器内的 /opt/pentagi/conf/ollama.provider.yml。

自定义配置示例（my-ollama-config.yml）：

primary_agent:
  model: "qwen3-coder-next:cloud"
  temperature: 1.0
  top_p: 0.9
  max_tokens: 32768
  reasoning:
    effort: high

coder:
  model: "qwen3-coder:32b"
  temperature: 1.0
  max_tokens: 20480

本地 Ollama 配置

对于自托管的 Ollama 实例：

# 基本本地 Ollama 设置
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0

# 生产环境设置，启用自动拉取和模型发现
OLLAMA_SERVER_URL=http://ollama-server:11434
OLLAMA_SERVER_PULL_MODELS_ENABLED=true
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900
OLLAMA_SERVER_LOAD_MODELS_ENABLED=true

# 使用 Docker 镜像中的预建配置
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
# 或
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml
# 或
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml

性能注意事项：

• 模型发现（OLLAMA_SERVER_LOAD_MODELS_ENABLED=true）：查询 Ollama API 会增加 1-2 秒的启动延迟。
• 自动拉取（OLLAMA_SERVER_PULL_MODELS_ENABLED=true）：首次启动可能需要几分钟下载模型。
• 拉取超时（OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900）：即 15 分钟。
• 静态配置：为加快启动速度，可禁用上述两个选项，并在配置文件中指定模型。

创建具有扩展上下文的自定义 Ollama 模型

PentAGI 需要使用比默认 Ollama 配置更大的上下文窗口的模型。您需要通过 Modelfile 创建具有更高 num_ctx 参数的自定义模型。虽然典型的代理工作流通常消耗约 64K 个标记，但 PentAGI 为了安全起见并应对复杂的渗透测试场景，采用了 110K 的上下文大小。

重要提示：num_ctx 参数只能在通过 Modelfile 创建模型时设置，创建后无法更改或在运行时覆盖。

示例：Qwen3 32B FP16 扩展上下文版本

创建名为 Modelfile_qwen3_32b_fp16_tc 的 Modelfile：

FROM qwen3:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.3
PARAMETER top_p 0.8
PARAMETER min_p 0.0
PARAMETER top_k 20
PARAMETER repeat_penalty 1.1

构建自定义模型：

ollama create qwen3:32b-fp16-tc -f Modelfile_qwen3_32b_fp16_tc

示例：QwQ 32B FP16 扩展上下文版本

创建名为 Modelfile_qwq_32b_fp16_tc 的 Modelfile：

FROM qwq:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.2
PARAMETER top_p 0.7
PARAMETER min_p 0.0
PARAMETER top_k 40
PARAMETER repeat_penalty 1.2

构建自定义模型：

ollama create qwq:32b-fp16-tc -f Modelfile_qwq_32b_fp16_tc

注意：QwQ 32B FP16 模型进行推理时大约需要 71.3 GB VRAM。请确保您的系统具备足够的 GPU 内存后再尝试使用此模型。

这些自定义模型已在预建的提供商配置文件中引用（ollama-qwen332b-fp16-tc.provider.yml 和 ollama-qwq32b-fp16-tc.provider.yml），这些文件位于 Docker 镜像的 /opt/pentagi/conf/ 目录下。

OpenAI 提供商配置

PentAGI 集成 OpenAI 的全面模型系列，具备先进的推理能力、扩展的思维链、增强工具集成的代理模型，以及专用于安全工程的代码模型。

配置变量

配置示例

# 基本的 OpenAI 设置
OPEN_AI_KEY=你的 OpenAI API 密钥
OPEN_AI_SERVER_URL=https://api.openai.com/v1

# 使用代理以增强安全性
OPEN_AI_KEY=你的 OpenAI API 密钥
PROXY_URL=http://你的代理:8080

支持的模型

PentAGI 支持 31 种具备工具调用、流式传输、推理模式和提示缓存功能的 OpenAI 模型。标有 * 的模型为默认配置中使用的模型。

GPT-5.2 系列 - 最新旗舰代理模型（2025 年 12 月）

GPT-5/5.1 系列 - 高级代理模型

GPT-5/5.1 Codex 系列 - 代码专用模型

GPT-4.1 系列 - 增强型智能模型

GPT-4o 系列 - 多模态旗舰模型

o 系列 - 高级推理模型

价格：每 100 万 tokens 计算。推理模型的输出定价中包含思维 tokens 的费用。

[!WARNING] GPT-5 模型 - 需要受信访问权限*

所有 GPT-5 系列模型（gpt-5、gpt-5.1、gpt-5.2、gpt-5-pro、gpt-5.2-pro 及所有 Codex 变体）在 PentAGI 中运行时不稳定，若未经过验证的访问权限，可能会触发 OpenAI 的网络安全防护机制。

要可靠地使用 GPT-5 模型：*

1. 个人用户：请前往 chatgpt.com/cyber 完成身份验证。
2. 企业团队：请通过您的 OpenAI 代表申请受信访问权限。
3. 安全研究人员：请申请 网络安全资助计划（包含价值 1000 万美元的 API 信用额度）。

推荐的无需验证的替代方案：

• 对于推理任务，建议使用 o 系列 模型（o3、o4-mini、o1）。
• 对于通用智能和函数调用任务，建议使用 gpt-4.1 系列。
• 所有 o 系列及 gpt-4.x 系列模型均可在无需特殊访问权限的情况下稳定运行。

推理努力程度：

• 高：最大推理深度（精炼者 - o3，高努力）
• 中：平衡推理（主要代理、助手、反思者 - o4-mini/o3，中等努力）
• 低：高效定向推理（编码员、安装者、渗透测试员 - o3/o4-mini，低努力；顾问 - gpt-5.2，低努力）

关键特性：

• 扩展推理：o系列模型具备思维链功能，适用于复杂的安全分析
• 智能体式智能：GPT-5/5.1/5.2系列具有增强的工具集成和自主能力
• 提示缓存：降低重复上下文的成本（输入价格的10%-50%）
• 代码专业化：专用Codex模型用于漏洞发现和漏洞利用开发
• 多模态支持：GPT-4o系列可用于基于视觉的安全评估
• 工具调用：所有模型均支持强大的函数调用功能，便于渗透测试工具编排
• 流式传输：实时响应流式传输，适用于交互式工作流程
• 成熟的应用记录：行业领先的模型已在CVE漏洞发现及实际安全应用中取得成果

Anthropic 提供商配置

PentAGI 集成了 Anthropic 的 Claude 模型，这些模型具备先进的扩展思维能力、卓越的安全机制以及对复杂安全情境的深刻理解，并支持提示缓存功能。

配置变量

配置示例

# 基本 Anthropic 设置
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1

# 在安全环境中使用代理
ANTHROPIC_API_KEY=your_anthropic_api_key
PROXY_URL=http://your-proxy:8080

支持的模型

PentAGI 支持 10 款带有工具调用、流式传输、扩展推理、自适应推理和提示缓存功能的 Claude 模型。标有 * 的模型为默认配置中使用的模型。

Claude 4 系列 - 最新模型（2025-2026年）

旧版模型 - 仍受支持

已弃用模型 - 请迁移到当前模型

价格：每100万标记符计价。缓存定价包括读取和写入成本。

扩展推理配置：

• 最大标记数4096：生成器（claude-opus-4-6）用于在复杂漏洞利用开发中实现最大推理深度
• 最大标记数2048：编码员（claude-sonnet-4-6）用于平衡的代码分析和漏洞研究
• 最大标记数1024：主要代理、助手、精炼者、顾问、反思者、搜索者、安装者、渗透测试员，用于特定任务的专注推理
• 扩展推理：所有 Claude 4.5+ 和 4.6 模型均支持可配置的扩展推理，以应对深度推理任务

关键特性：

• 扩展推理：所有 Claude 4.5+ 和 4.6 模型均支持可配置的思维链推理深度，适用于复杂的安全分析
• 自适应推理：Claude 4.6 系列（Opus/Sonnet）可根据任务复杂度动态调整推理深度，以达到最佳性能
• 提示缓存：通过单独的读写定价显著降低成本（读取费用为输入的10%，写入费用为输入的125%）
• 扩展上下文窗口：标准为20万标记符，最高可达100万标记符（测试版），适用于 Claude Opus/Sonnet 4.6 的全面代码库分析
• 工具调用：功能调用强大且准确，非常适合安全工具编排
• 流式传输：实时响应流式传输，适用于交互式渗透测试工作流
• 安全优先设计：内置安全机制，确保负责任的安全测试实践
• 多模态支持：最新模型具备视觉功能，可用于截图分析和UI安全评估
• 宪法式AI：先进的安全训练提供可靠且符合伦理的安全指导

Google AI（Gemini）提供商配置

PentAGI 通过 Google AI API 集成 Google 的 Gemini 模型，提供最先进的多模态推理能力，并支持扩展思考和上下文缓存功能。

配置变量

配置示例

# 基本 Gemini 设置
GEMINI_API_KEY=your_gemini_api_key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com

# 使用代理
GEMINI_API_KEY=your_gemini_api_key
PROXY_URL=http://your-proxy:8080

支持的模型

PentAGI 支持 13 种具备工具调用、流式传输、思考模式和上下文缓存功能的 Gemini 模型。标有 * 的模型为默认配置中使用的模型。

Gemini 3.1 系列 - 最新旗舰版（2026 年 2 月）

Gemini 3 系列（⚠️ gemini-3-pro-preview 已弃用 - 将于 2026 年 3 月 9 日停用）

Gemini 2.5 系列 - 高级思考模型

Gemini 2.0 系列 - 适用于代理的平衡型多模态模型

专用开源模型（免费）

价格：每 100 万 tokens（标准付费层级）。上下文窗口即输入 token 限制。

[!WARNING] Gemini 3 Pro Preview 已弃用

gemini-3-pro-preview 将于 2026 年 3 月 9 日停止服务。请迁移到 gemini-3.1-pro-preview 以避免服务中断。新模型具有以下优势：

• 更加完善的性能和可靠性
• 更好的思考能力和 token 效率
• 回答更加扎实、事实一致
• 更强的软件工程行为表现

关键特性：

• 扩展思考：用于复杂安全分析的逐步推理（所有 Gemini 3.x 和 2.5 系列）
• 上下文缓存：重复使用上下文时可大幅降低成本（降低至输入价格的 10%-90%）
• 超长上下文：100 万 tokens，适用于全面的代码库分析和文档审查
• 多模态支持：支持文本、图像、视频、音频和 PDF 处理，可用于全面评估
• 工具调用：通过函数调用与 20 多种渗透测试工具无缝集成
• 流式传输：实时响应流式传输，适用于交互式安全工作流
• 代码执行：内置代码执行功能，可用于攻击性工具测试和漏洞利用验证
• 搜索基础：集成 Google 搜索，用于威胁情报和 CVE 研究
• 文件搜索：文档检索和 RAG 功能，适用于基于知识的评估
• 批量 API：非实时批量处理可节省 50% 的成本

推理力度等级：

• 高：最大思考深度，适用于复杂的多步分析（generator）
• 中：平衡推理，适用于一般代理任务（primary_agent、assistant、refiner、adviser）
• 低：高效思考，适用于专注任务（coder、installer、pentester）

AWS Bedrock 提供商配置

PentAGI 与 Amazon Bedrock 集成，提供来自领先 AI 公司的 20 多种基础模型的访问权限，包括 Anthropic、Amazon、Cohere、DeepSeek、OpenAI、Qwen、Mistral 和 Moonshot。

配置变量

认证优先级：BEDROCK_DEFAULT_AUTH → BEDROCK_BEARER_TOKEN → BEDROCK_ACCESS_KEY_ID+BEDROCK_SECRET_ACCESS_KEY

配置示例

# 推荐：默认 AWS SDK 认证（EC2/ECS/Lambda 角色）
BEDROCK_REGION=us-east-1
BEDROCK_DEFAULT_AUTH=true

# Bearer 令牌认证（AWS STS、自定义认证）
BEDROCK_REGION=us-east-1
BEDROCK_BEARER_TOKEN=your_bearer_token

# 硬编码凭证（开发、测试）
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key

# 使用代理和自定义端点
BEDROCK_REGION=us-east-1
BEDROCK_DEFAULT_AUTH=true
BEDROCK_SERVER_URL=https://bedrock-runtime.us-east-1.vpce-xxx.amazonaws.com
PROXY_URL=http://your-proxy:8080

支持的模型

PentAGI 支持 21 种具有工具调用、流式传输和多模态能力的 AWS Bedrock 模型。标有 * 的模型在默认配置中使用。

价格：每 100 万 tokens。支持思考/推理的模型在推理阶段会产生额外的计算成本。

已测试但不兼容的模型

一些 AWS Bedrock 模型经过测试，但由于技术限制而 不被支持：

[!IMPORTANT] 速率限制与配额管理

AWS Bedrock 对于 Claude 模型的默认配额非常严格（新账户每分钟仅允许 2-20 次请求）。若要用于生产环境中的渗透测试：

1. 请通过 AWS Service Quotas 控制台为计划使用的模型申请提高配额。
2. 建议使用 Amazon Nova 系列模型——它们具有更高的默认配额且性能优异。
3. 启用预置吞吐量以确保高容量测试的一致性。
4. 密切监控使用情况——AWS 在达到配额上限时会采取严格的限流措施。

若未提高配额，将频繁出现延迟和工作流中断。

[!WARNING] Converse API 要求

PentAGI 使用 Amazon Bedrock 的 Converse API 来实现统一的模型接入。所有受支持的模型必须满足以下条件：

• ✅ 支持 Converse/ConverseStream API
• ✅ 支持工具调用（函数调用），以适应渗透测试工作流
• ✅ 支持流式工具调用，以便提供实时反馈

请在以下链接处确认各模型的功能支持情况：AWS Bedrock 模型功能

核心特性：

• 自动提示缓存：对于重复上下文，可降低 40%-70% 的成本（Claude 4.x 系列模型）。
• 扩展思维：针对复杂安全分析提供逐步推理能力（Claude、DeepSeek R1、OpenAI GPT）。
• 多模态分析：能够处理截图、图表、视频等，实现全面的测试（Nova、Claude、Mistral、Kimi）。
• 工具调用：通过函数调用与 20 多种渗透测试工具无缝集成。
• 流式传输：支持实时响应流式传输，适用于交互式的安全评估工作流。

DeepSeek 提供商配置

PentAGI 集成 DeepSeek 平台，提供具备强大推理能力、编码能力和上下文缓存功能的先进 AI 模型，价格极具竞争力。

配置变量

配置示例

# 直接使用 API
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com

# 使用 LiteLLM 代理
DEEPSEEK_API_KEY=your_litellm_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek  # 为模型名称添加前缀（如 deepseek/deepseek-chat），便于 LiteLLM 调用

支持的模型

PentAGI 支持两款 DeepSeek-V3.2 模型，它们均具备工具调用、流式传输、思维模式以及上下文缓存功能。这两款模型在默认配置中均可使用。

价格：按每 100 万 tokens 计算。缓存定价基于提示缓存（为输入费用的 10%）。支持“思维模式”的模型包含强化学习链式思维推理机制。

核心特性：

• 自动提示缓存：对于重复内容，可节省 40%-60% 的成本（提示缓存费用为输入费用的 10%）。
• 扩展思维：采用强化学习链式思维推理技术，适用于复杂的安全分析任务（deepseek-reasoner）。
• 强大的编码能力：专为代码生成和漏洞利用开发而优化。
• 工具调用：可通过函数调用与 20 多种渗透测试工具无缝集成。
• 流式传输：支持实时响应流式传输，适用于交互式工作流。
• 多语言支持：中文和英文表现尤为出色。
• 其他功能：JSON 输出、聊天前缀补全、FIM（中间填空）补全。

LiteLLM 集成：若使用 PentAGI 默认配置并通过 LiteLLM 代理调用模型，请设置 DEEPSEEK_PROVIDER=deepseek，以启用模型名称前缀。若直接使用 API，则保持为空即可。

GLM 提供商配置

PentAGI 集成来自智谱 AI（Z.AI）的 GLM 系列模型，这些模型采用 MoE 架构，具备强大的推理能力和代理式功能，由清华大学研发。

配置变量

配置示例

# 直接使用 API（国际服务端）
GLM_API_KEY=your_glm_api_key
GLM_SERVER_URL=https://api.z.ai/api/paas/v4

# 其他服务端
GLM_SERVER_URL=https://open.bigmodel.cn/api/paas/v4  # 中国境内
GLM_SERVER_URL=https://api.z.ai/api/coding/paas/v4   # 专门用于编码相关API

# 使用 LiteLLM 代理
GLM_API_KEY=your_litellm_key
GLM_SERVER_URL=http://litellm-proxy:4000
GLM_PROVIDER=zai  # 为 LiteLLM 添加模型名称前缀（zai/glm-4）

支持的模型

PentAGI 支持 12 款具备工具调用、流式输出、思考模式和提示缓存功能的 GLM 模型。标有 * 的模型为默认配置中使用的模型。

GLM-5 系列 - 旗舰 MoE（744B/40B 活性参数）

GLM-4.7 系列 - 高端，交错思考模式

GLM-4.6 系列 - 平衡型，自动思考模式

GLM-4.5 系列 - 统一推理/编码/智能体

GLM-4 旧版 - 密集架构

价格说明：每 100 万个 token 计算。缓存价格适用于提示词缓存。† 该模型需要 Coding Plan 订阅。

[!WARNING] Coding Plan 要求

glm-5-code 模型需要有效的 Coding Plan 订阅。若未订阅而尝试使用该模型，将出现以下错误：

API 返回意外状态码：403：您没有访问 glm-5-code 的权限

对于无需 Coding Plan 的代码专用任务，请改用 glm-5（通用旗舰模型）或 glm-4.7（具有交错思考模式的高端模型）。

思考模式：

• 强制启用：模型在每次响应前都会强制进入思考模式（GLM-5、GLM-4.7）
• 混合模式：模型会智能判断何时使用思考模式（GLM-4.7-FlashX、GLM-4.7-Flash）
• 自动启用：模型会自动决定何时需要进行推理（GLM-4.6、GLM-4.5 系列）

核心特性：

• 提示缓存：重复上下文可显著降低成本（缓存输入价格已标明）
• 交错思考模式：GLM-4.7 在每次响应和工具调用前都会进行思考，并在多轮对话中保持推理连贯性
• 超长上下文：GLM-5 和 GLM-4.7/4.6 系列支持 20 万 token，适合大规模代码库分析
• MoE 架构：高效 7440 亿参数，其中 400 亿参数处于活跃状态（GLM-5），3550 亿/320 亿参数（GLM-4.5），1060 亿/120 亿参数（GLM-4.5-Air）
• 工具调用：通过函数调用无缝集成 20 多种渗透测试工具
• 流式输出：实时响应流式传输，支持流式工具调用（GLM-4.6 及以上）
• 多语言支持：卓越的中文和英文 NLP 能力
• 免费选项：GLM-4.7-Flash 和 GLM-4.5-Flash 适用于原型设计和实验

LiteLLM 集成：设置 GLM_PROVIDER=zai 可在使用 PentAGI 默认配置与 LiteLLM 代理时启用模型名称前缀。若直接使用 API，则留空即可。

Kimi 提供者配置

PentAGI 与 Moonshot AI 的 Kimi 集成，提供具备多模态能力的超长上下文模型，非常适合分析大型代码库和文档。

配置变量

配置示例

# 直接使用 API（国际版端点）
KIMI_API_KEY=your_kimi_api_key
KIMI_SERVER_URL=https://api.moonshot.ai/v1

# 替代端点
KIMI_SERVER_URL=https://api.moonshot.cn/v1  # 中国境内

# 使用 LiteLLM 代理
KIMI_API_KEY=您的 liteLLM 密钥
KIMI_SERVER_URL=http://litellm-proxy:4000
KIMI_PROVIDER=moonshot  # 为 LiteLLM 添加模型名称前缀（如 moonshot/kimi-k2.5）

支持的模型

PentAGI 支持 11 种具备工具调用、流式传输、思考模式和多模态能力的 Kimi/Moonshot 模型。标有 * 的模型为默认配置中使用的模型。

Kimi K2.5 系列 - 高级多模态

Kimi K2 系列 - MoE 基础模型（1T 参数，32B 激活）

Moonshot V1 系列 - 通用文本生成

Moonshot V1 Vision 系列 - 多模态

价格：按每 100 万个 token 计算。Turbo 模型以更高的价格提供每秒 60–100 个 token 的输出速度。

关键特性：

• 超长上下文：最高可达 256K 个 token，适合全面的代码库分析
• 多模态能力：视觉模型支持图像理解，可用于截图分析（Kimi K2.5、V1 Vision 系列）
• 扩展思考：通过多步工具使用实现深度推理（kimi-k2.5、kimi-k2-thinking 模型）
• 高速 Turbo：每秒 60–100 个 token 的输出，适用于实时工作流程（Turbo 版本）
• 工具调用：通过函数调用与 20 多种渗透测试工具无缝集成
• 流式传输：实时响应流式传输，用于交互式安全评估
• 多语言支持：强大的中文和英文语言支持
• MoE 架构：K2 系列采用高效的 1T 总参数架构，其中 32B 参数处于激活状态

LiteLLM 集成：设置 KIMI_PROVIDER=moonshot 可在使用默认 PentAGI 配置时启用模型名称前缀，配合 LiteLLM 代理使用。若直接使用 API，则留空即可。

Qwen 提供者配置

PentAGI 集成来自阿里云 Model Studio（DashScope）的 Qwen，提供强大的多语言模型，具备推理能力和上下文缓存支持。

配置变量

配置示例

# 直接使用 API（全球/美国端点）
QWEN_API_KEY=您的 qwen_api_key
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1

# 其他端点
QWEN_SERVER_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1  # 国际版（新加坡）
QWEN_SERVER_URL=https://dashscope.aliyuncs.com/compatible-mode/v1       # 中国大陆版（北京）

# 使用 LiteLLM 代理
QWEN_API_KEY=您的 liteLLM 密钥
QWEN_SERVER_URL=http://litellm-proxy:4000
QWEN_PROVIDER=dashscope  # 为 LiteLLM 添加模型名称前缀（如 dashscope/qwen-plus）

支持的模型

PentAGI 支持 32 种具备工具调用、流式传输、思考模式和上下文缓存功能的 Qwen 模型。标有 * 的模型为默认配置中使用的模型。

广泛可用的模型（所有地区）

区域特定模型

开源 - Qwen3.5系列

开源 - Qwen3系列

开源 - QwQ & Qwen2.5系列

价格：以每100万tokens为单位。缓存定价基于隐式上下文缓存（占输入成本的20%）。支持思考能力的模型在思维链阶段会进行额外的推理计算。

区域可用性：

• 国际：新加坡区域（dashscope-intl.aliyuncs.com）
• 全球/美国：美国弗吉尼亚区域（dashscope-us.aliyuncs.com）
• 中国：中国内地北京区域（dashscope.aliyuncs.com）

核心功能：

• 自动上下文缓存：通过隐式缓存将重复上下文的成本降低30%-50%（仅需输入价格的20%）
• 扩展思维：针对复杂安全分析的思维链推理能力（Qwen3-Max、QwQ、Qwen3.5-Plus）
• 工具调用：通过函数调用与20余种渗透测试工具无缝集成
• 流式传输：实时响应流，适用于交互式工作流
• 多语言支持：强大的中文、英文及其他多语言支持
• 超长上下文：使用qwen-long-latest可支持高达1000万标记符，适用于大规模代码库分析

LiteLLM集成：设置QWEN_PROVIDER=dashscope，即可在使用LiteLLM代理的默认PentAGI配置时启用模型名称前缀。若直接使用API，则保持为空。

🔧 高级设置

Langfuse集成

Langfuse提供先进的AI智能体运行监控与分析能力。

1. 在现有的.env文件中配置Langfuse环境变量。

2. 在.env文件中为PentAGI服务启用Langfuse集成。

LANGFUSE_BASE_URL=http://langfuse-web:3000
LANGFUSE_PROJECT_ID= # 默认值来自${LANGFUSE_INIT_PROJECT_ID}
LANGFUSE_PUBLIC_KEY= # 默认值来自${LANGFUSE_INIT_PROJECT_PUBLIC_KEY}
LANGFUSE_SECRET_KEY= # 默认值来自${LANGFUSE_INIT_PROJECT_SECRET_KEY}

3. 启动Langfuse堆栈：

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-langfuse.yml
docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d

访问localhost:4000，使用.env文件中的凭据登录Langfuse Web界面：

• LANGFUSE_INIT_USER_EMAIL - 管理员邮箱
• LANGFUSE_INIT_USER_PASSWORD - 管理员密码

监控与可观测性

为了更细致地追踪系统运行情况，可以集成监控工具。

1. 在.env文件中为PentAGI启用OpenTelemetry及所有可观测性服务的集成。

OTEL_HOST=otelcol:8148

2. 启动可观测性堆栈：

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-observability.yml
docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d

访问localhost:3000，即可进入Grafana Web界面。

[!注意] 若希望同时使用Langfuse和可观测性堆栈，需在.env文件中设置LANGFUSE_OTEL_EXPORTER_OTLP_ENDPOINT为http://otelcol:4318。

若要同时启动所有可用堆栈（Langfuse、Graphiti和可观测性）：

docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d

您还可以在Shell中为这些命令设置别名，以加快执行速度：

alias pentagi="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml"
alias pentagi-up="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d"
alias pentagi-down="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml down"

知识图谱集成（Graphiti）

PentAGI集成了由Neo4j驱动的时间知识图谱系统Graphiti，以提供高级语义理解和关系追踪功能，助力AI智能体的运行。vxcontrol分支提供了专为渗透测试设计的自定义实体和边类型。

什么是Graphiti？

Graphiti能够自动从智能体交互中提取并存储结构化知识，构建实体、关系及时间上下文的图谱。这使得：

• 语义记忆：存储并回忆工具、目标、漏洞和技巧之间的关系
• 情境理解：跟踪不同渗透测试行为随时间的关联
• 知识复用：从过往渗透测试中学习，并将洞见应用于新的评估
• 高级查询：搜索复杂模式，例如“哪些工具对类似目标有效？”

启用Graphiti

Graphiti知识图谱是可选的，默认情况下未启用。要启用它：

1. 在.env文件中配置Graphiti相关环境变量：

## Graphiti知识图谱设置
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_MODEL_NAME=gpt-5-mini

# Neo4j设置（Graphiti堆栈使用）
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687

# OpenAI API密钥（Graphiti用于实体提取所需）
OPEN_AI_KEY=your_openai_api_key

2. 运行Graphiti堆栈以及主PentAGI服务：

# 如有需要，下载Graphiti的Compose文件
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml

# 启动包含Graphiti的PentAGI
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d

3. 验证Graphiti是否正常运行：

# 检查服务状态
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j

# 查看Graphiti日志
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti

# 访问Neo4j浏览器（可选）
# 前往http://localhost:7474，使用NEO4J_USER/NEO4J_PASSWORD登录

# 访问Graphiti API（可选，用于调试）

# 访问 http://localhost:8000/docs 获取 Swagger API 文档

[!NOTE] Graphiti 服务在 docker-compose-graphiti.yml 中被定义为一个独立的堆栈。必须同时运行这两个 compose 文件才能启用知识图谱功能。默认使用预构建的 Docker 镜像 vxcontrol/graphiti:latest。

存储的内容

启用后，PentAGI 会自动捕获：

• 代理响应：所有代理的推理、分析和决策
• 工具执行：执行的命令、使用的工具及其结果
• 上下文信息：流程、任务及子任务层级结构

GitHub 和 Google OAuth 集成

通过与 GitHub 和 Google 的 OAuth 集成，用户可以使用这些平台上的现有账户进行身份验证。这带来了多项优势：

• 简化登录流程，无需创建单独的凭据
• 通过受信任的身份提供商提升安全性
• 可访问 GitHub/Google 账户中的用户个人资料信息
• 与现有开发工作流无缝集成

要使用 GitHub OAuth，您需要在 GitHub 账户中创建一个新的 OAuth 应用程序，并在 .env 文件中设置 OAUTH_GITHUB_CLIENT_ID 和 OAUTH_GITHUB_CLIENT_SECRET。

要使用 Google OAuth，您需要在 Google 账户中创建一个新的 OAuth 应用程序，并在 .env 文件中设置 OAUTH_GOOGLE_CLIENT_ID 和 OAUTH_GOOGLE_CLIENT_SECRET。

Docker 镜像配置

PentAGI 允许您配置用于执行各种任务的 Docker 镜像选择。系统会根据任务类型自动选择最合适的镜像，但您可以通过指定首选镜像来限制这一选择：

当设置这些环境变量后，AI 代理将仅限于您指定的镜像选项。这对于以下场景特别有用：

• 安全策略实施：仅允许使用经过验证的可信镜像
• 环境标准化：在所有操作中统一使用企业或自定义镜像
• 性能优化：利用已安装必要工具的预构建镜像

配置示例：

# 为通用任务使用自定义镜像
DOCKER_DEFAULT_IMAGE=mycompany/custom-debian:latest

# 为渗透测试使用专用镜像
DOCKER_DEFAULT_IMAGE_FOR_PENTEST=mycompany/pentest-tools:v2.0

[!NOTE] 如果用户在其任务中明确指定了特定的 Docker 镜像，系统将优先使用该镜像，而忽略这些设置。这些变量仅影响系统的自动镜像选择过程。

💻 开发

开发要求

• golang
• nodejs
• docker
• postgres
• commitlint

环境设置

后端设置

运行一次 cd backend && go mod download 来安装所需的包。

要生成 swagger 文件，需先运行

swag init -g ../../pkg/server/router.go -o pkg/server/docs/ --parseDependency --parseInternal --parseDepth 2 -d cmd/pentagi

然后再通过以下命令安装 swag 包：

go install github.com/swaggo/swag/cmd/swag@v1.8.7

要生成 graphql 解析器文件，需运行

go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml

之后，您可以在 pkg/graph 文件夹中看到生成的文件。

要从 sqlc 配置生成 ORM 方法（数据库包），可运行以下命令：

docker run --rm -v $(pwd):/src -w /src --network pentagi-network -e DATABASE_URL="{URL}" sqlc/sqlc:1.27.0 generate -f sqlc/sqlc.yml

要从 OpenAPI 规范生成 Langfuse SDK，可运行以下命令：

fern generate --local

并安装 fern-cli：

npm install -g fern-api

测试

运行测试时，请进入 backend 目录并执行：cd backend && go test -v ./...

前端设置

运行一次 cd frontend && npm install 来安装所需的包。

要生成 graphql 文件，需运行 npm run graphql:generate，该命令会使用 graphql-codegen.ts 文件。

请确保您已全局安装 graphql-codegen：

npm install -g graphql-codegen

之后，您可以运行：

• npm run prettier 检查代码格式是否正确
• npm run prettier:fix 自动修复格式问题
• npm run lint 检查代码是否符合规范
• npm run lint:fix 自动修正不符合规范的地方

要生成 SSL 证书，需运行 npm run ssl:generate，该命令会使用 generate-ssl.ts 文件；或者在您运行 npm run dev 时，SSL 证书将自动生成。

后端配置

编辑 .vscode/launch.json 文件中的后端配置：

• DATABASE_URL：PostgreSQL 数据库 URL（例如 postgres://postgres:postgres@localhost:5432/pentagidb?sslmode=disable）
• DOCKER_HOST：Docker SDK API（例如，在 macOS 上为 DOCKER_HOST=unix:///Users/<my-user>/Library/Containers/com.docker.docker/Data/docker.raw.sock）更多信息

可选：

• SERVER_PORT：服务器运行端口（默认：8443）
• SERVER_USE_SSL：启用服务器 SSL（默认：false）

前端配置

编辑 .vscode/launch.json 文件中的前端配置：

• VITE_API_URL：后端 API URL。请省略协议部分（例如，localhost:8080 而不是 http://localhost:8080）
• VITE_USE_HTTPS：启用服务器 SSL（默认：false）
• VITE_PORT：服务器运行端口（默认：8000）
• VITE_HOST：服务器运行主机（默认：0.0.0.0）

运行应用

后端

在 backend 文件夹中运行以下命令：

• 使用 .env 文件设置环境变量，例如 source .env
• 运行 go run cmd/pentagi/main.go 启动服务器

[!NOTE] 第一次运行可能需要一些时间，因为需要下载依赖项和 Docker 镜像来搭建后端环境。

前端

在 frontend 文件夹中运行以下命令：

• 运行 npm install 安装依赖
• 运行 npm run dev 启动 Web 应用
• 运行 npm run build 构建 Web 应用

打开浏览器并访问 Web 应用的 URL。

测试 LLM 代理

PentAGI 内置了一个强大的工具 ctester，用于测试和验证 LLM 代理的能力。该工具可以帮助您确保 LLM 提供商的配置能够正确地与不同类型的代理配合使用，从而为每个特定角色的代理优化模型选择。 该工具支持多代理并行测试、详细的报告输出以及灵活的配置选项。

核心功能

• 并行测试：同时测试多个智能体，以加快测试速度
• 全面的测试套件：评估基础完成度、JSON响应、函数调用以及渗透测试知识
• 详细报告：生成包含成功率和性能指标的 Markdown 报告
• 灵活配置：可根据需要测试特定智能体或测试组
• 专用测试组：包含针对网络安全和渗透测试场景的领域特定测试

使用场景

针对开发者（本地 Go 环境）

如果您已克隆仓库并安装了 Go：

# 使用 .env 文件的默认配置
cd backend
go run cmd/ctester/*.go -verbose

# 自定义提供商配置
go run cmd/ctester/*.go -config ../examples/configs/openrouter.provider.yml -verbose

# 生成报告文件
go run cmd/ctester/*.go -config ../examples/configs/deepinfra.provider.yml -report ../test-report.md

# 仅测试特定类型的智能体
go run cmd/ctester/*.go -agents simple,simple_json,primary_agent -verbose

# 仅测试特定的测试组
go run cmd/ctester/*.go -groups basic,advanced -verbose

针对用户（使用 Docker 镜像）

如果您更倾向于使用预构建的 Docker 镜像而无需搭建开发环境：

# 使用 Docker 运行默认环境下的测试
docker run --rm -v $(pwd)/.env:/opt/pentagi/.env vxcontrol/pentagi /opt/pentagi/bin/ctester -verbose

# 使用自定义提供商配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  -v $(pwd)/my-config.yml:/opt/pentagi/config.yml \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/config.yml -agents simple,primary_agent,coder -verbose

# 生成详细报告
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  -v $(pwd):/opt/pentagi/output \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/output/report.md

使用预配置的提供商

Docker 镜像内置支持主流提供商（OpenAI、Anthropic、Gemini、Ollama），并提供针对其他服务的预配置提供商文件（OpenRouter、DeepInfra、DeepSeek、Moonshot、Novita）：

# 使用 OpenRouter 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/openrouter.provider.yml

# 使用 DeepInfra 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepinfra.provider.yml

# 使用 DeepSeek 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -provider deepseek

# 使用 GLM 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -provider glm

# 使用 Kimi 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -provider kimi

# 使用 Qwen 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -provider qwen

# 使用 DeepSeek 的自定义提供商配置文件进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepseek.provider.yml

# 使用 Moonshot 的自定义提供商配置文件进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/moonshot.provider.yml

# 使用 Novita 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/novita.provider.yml

# 使用 OpenAI 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -type openai

# 使用 Anthropic 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -type anthropic

# 使用 Gemini 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -type gemini

# 使用 AWS Bedrock 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -type bedrock

# 使用自定义 OpenAI 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml

# 使用 Ollama 配置进行本地推理测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-llama318b.provider.yml

# 使用 Ollama Qwen3 32B 配置进行测试（需自定义模型）
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml

# 使用 Ollama QwQ 32B 配置进行测试（需自定义模型且需要 71.3GB 显存）
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml

要使用这些配置，您的 .env 文件只需包含以下内容：

LLM_SERVER_URL=https://openrouter.ai/api/v1      # 或 https://api.deepinfra.com/v1/openai 或 https://api.openai.com/v1 或 https://api.novita.ai/openai
LLM_SERVER_KEY=your_api_key
LLM_SERVER_MODEL=                                # 留空，因为模型已在配置中指定
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/openrouter.provider.yml  # 或 deepinfra.provider.ymll 或 custom-openai.provider.yml 或 novita.provider.yml
LLM_SERVER_PROVIDER=                             # LiteLLM 代理的提供商名称（如 openrouter、deepseek、moonshot、novita）
LLM_SERVER_LEGACY_REASONING=false                # 控制推理格式，对于 OpenAI 必须为 true（默认：false）
LLM_SERVER_PRESERVE_REASONING=false              # 在多轮对话中保留推理内容（Moonshot 要求，默认：false）

# 对于 OpenAI（官方 API）
OPEN_AI_KEY=your_openai_api_key                  # 您的 OpenAI API 密钥
OPEN_AI_SERVER_URL=https://api.openai.com/v1     # OpenAI API 端点

# 对于 Anthropic（Claude 模型）
ANTHROPIC_API_KEY=your_anthropic_api_key         # 您的 Anthropic API 密钥
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1  # Anthropic API 端点

# 对于 Gemini（Google AI）
GEMINI_API_KEY=your_gemini_api_key               # 您的 Google AI API 密钥
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com  # Google AI API 端点

# 对于 AWS Bedrock（企业级基础模型）
BEDROCK_REGION=us-east-1                         # AWS 区域，用于 Bedrock 服务

# 身份验证（选择一种方法，优先级：DefaultAuth > BearerToken > AccessKey）：
BEDROCK_DEFAULT_AUTH=false                       # 使用 AWS SDK 凭证链（环境变量、EC2 角色、~/.aws/credentials）
BEDROCK_BEARER_TOKEN=                            # Bearer 令牌身份验证（优先于静态凭证）
BEDROCK_ACCESS_KEY_ID=your_aws_access_key        # AWS 访问密钥 ID（静态凭证）
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key    # AWS 秘密访问密钥（静态凭证）
BEDROCK_SESSION_TOKEN=                           # AWS 会话令牌（可选，用于使用静态认证的临时凭证）
BEDROCK_SERVER_URL=                              # 可选的自定义 Bedrock 终端节点（VPC 终端节点、本地测试）

# 用于 Ollama（本地服务器或云）
OLLAMA_SERVER_URL=                               # 本地：http://ollama-server:11434，云：https://ollama.com
OLLAMA_SERVER_API_KEY=                           # Ollama Cloud 所需（https://ollama.com/settings/keys），本地则留空
OLLAMA_SERVER_MODEL=
OLLAMA_SERVER_CONFIG_PATH=
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=
OLLAMA_SERVER_PULL_MODELS_ENABLED=
OLLAMA_SERVER_LOAD_MODELS_ENABLED=

# 用于 DeepSeek（具有强大推理能力的中文 AI）
DEEPSEEK_API_KEY=                                # DeepSeek API 密钥
DEEPSEEK_SERVER_URL=https://api.deepseek.com     # DeepSeek API 终端节点
DEEPSEEK_PROVIDER=                               # 可选：LiteLLM 前缀（例如 'deepseek'）

# 用于 GLM（智谱 AI）
GLM_API_KEY=                                     # GLM API 密钥
GLM_SERVER_URL=https://api.z.ai/api/paas/v4      # GLM API 国际终端节点（国际版）
GLM_PROVIDER=                                    # 可选：LiteLLM 前缀（例如 'zai'）

# 用于 Kimi（月之暗面 AI）
KIMI_API_KEY=                                    # Kimi API 密钥
KIMI_SERVER_URL=https://api.moonshot.ai/v1       # Kimi API 国际终端节点（国际版）
KIMI_PROVIDER=                                   # 可选：LiteLLM 前缀（例如 'moonshot'）

# 用于 Qwen（阿里云 DashScope）
QWEN_API_KEY=                                    # Qwen API 密钥
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1  # Qwen API 美国终端节点
QWEN_PROVIDER=                                   # 可选：LiteLLM 前缀（例如 'dashscope'）

# 对于 Ollama（本地推理），请使用上述变量
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
OLLAMA_SERVER_PULL_MODELS_ENABLED=false
OLLAMA_SERVER_LOAD_MODELS_ENABLED=false

使用未验证组织的 OpenAI

对于未验证组织且无法访问最新推理模型（o1、o3、o4-mini）的 OpenAI 账户，需要使用自定义配置。

要为未验证组织账户使用 OpenAI，请按如下方式配置 .env 文件：

LLM_SERVER_URL=https://api.openai.com/v1
LLM_SERVER_KEY=your_openai_api_key
LLM_SERVER_MODEL=                                # 留空，模型将在配置中指定
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/custom-openai.provider.yml
LLM_SERVER_LEGACY_REASONING=true                 # OpenAI 推理格式所需

此配置使用预建的 custom-openai.provider.yml 文件，将所有代理类型映射到未验证组织可用的模型，使用 o3-mini 替代 o1、o3 和 o4-mini 等模型。

您可以通过以下命令测试此配置：

# 使用针对未验证账户的自定义 OpenAI 配置进行测试
docker run --rm \
  -v $(pwd)/.env:/opt/pentagi/.env \
  vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml

[!NOTE] LLM_SERVER_LEGACY_REASONING=true 设置对于 OpenAI 兼容性至关重要，因为它确保推理参数以 OpenAI API 所期望的格式发送。

使用 LiteLLM 代理

当使用 LiteLLM 代理访问各种 LLM 提供商时，模型名称会加上提供商前缀（例如 moonshot/kimi-2.5 而不是 kimi-2.5）。为了使相同的提供商配置文件既能用于直接 API 访问，也能用于 LiteLLM 代理，需设置 LLM_SERVER_PROVIDER 变量：

# 直接访问 Moonshot API
LLM_SERVER_URL=https://api.moonshot.ai/v1
LLM_SERVER_KEY=your_moonshot_api_key
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/moonshot.provider.yml
LLM_SERVER_PROVIDER=                             # 直接访问时留空

# 通过 LiteLLM 代理访问
LLM_SERVER_URL=http://litellm-proxy:4000
LLM_SERVER_KEY=your_litellm_api_key
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/moonshot.provider.yml
LLM_SERVER_PROVIDER=moonshot                     # LiteLLM 的提供商前缀

设置 LLM_SERVER_PROVIDER=moonshot 后，系统会自动在配置文件中的所有模型名称前加上 moonshot/ 前缀，使其与 LiteLLM 的模型命名规范兼容。

LiteLLM 提供商名称映射：

使用 LiteLLM 代理时，设置相应的 *_PROVIDER 变量以启用模型前缀：

• deepseek - 用于 DeepSeek 模型（DEEPSEEK_PROVIDER=deepseek → deepseek/deepseek-chat）
• zai - 用于 GLM 模型（GLM_PROVIDER=zai → zai/glm-4）
• moonshot - 用于 Kimi 模型（KIMI_PROVIDER=moonshot → moonshot/kimi-k2.5）
• dashscope - 用于 Qwen 模型（QWEN_PROVIDER=dashscope → dashscope/qwen-plus）
• openai、anthropic、gemini - 用于主要的云提供商
• openrouter - 用于 OpenRouter 聚合器
• deepinfra - 用于 DeepInfra 托管
• novita - 用于 Novita AI
• 您的 LiteLLM 实例中配置的任何其他提供商名称

LiteLLM 示例：

# 通过 LiteLLM 代理使用 DeepSeek 模型，并添加模型前缀
DEEPSEEK_API_KEY=your_litellm_proxy_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek  # 模型变为 deepseek/deepseek-chat、deepseek/deepseek-reasoner，适用于 LiteLLM

# 直接使用 DeepSeek API（无需前缀）
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com
# DEEPSEEK_PROVIDER 留空

这种方法允许您：

• 对于直接访问和代理访问使用相同的配置文件
• 在不修改配置文件的情况下切换提供商
• 轻松测试 LiteLLM 的不同路由策略

在生产环境中运行测试

如果您已经有一个正在运行的 PentAGI 容器，并希望测试当前配置：

# 在现有容器中使用当前环境变量运行 ctester
docker exec -it pentagi /opt/pentagi/bin/ctester -verbose

# 使用确定性顺序测试特定代理类型
docker exec -it pentagi /opt/pentagi/bin/ctester -agents simple,primary_agent,pentester -groups basic,knowledge -verbose

# 在容器内生成报告文件
docker exec -it pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/data/agent-test-report.md

# 从主机访问报告
docker cp pentagi:/opt/pentagi/data/agent-test-report.md ./

命令行选项

该工具接受多个选项：

• -env <path> - 环境文件路径（默认：.env）
• -type <provider> - 提供商类型：custom、openai、anthropic、ollama、bedrock、gemini（默认：custom）
• -config <path> - 自定义提供商配置文件路径（默认：来自环境变量 LLM_SERVER_CONFIG_PATH）
• -tests <path> - 自定义测试 YAML 文件路径（可选）
• -report <path> - 报告文件输出路径（可选）
• -agents <list> - 要测试的代理类型逗号分隔列表（默认：all）
• -groups <list> - 要运行的测试组逗号分隔列表（默认：all）
• -verbose - 启用详细输出，显示每个代理的详细测试结果

可用代理类型

代理将按以下确定性顺序进行测试：

1. simple - 基本完成任务
2. simple_json - JSON 结构化响应
3. primary_agent - 主要推理代理
4. assistant - 交互式助手模式
5. generator - 内容生成
6. refiner - 内容精炼与改进
7. adviser - 专家建议与咨询
8. reflector - 自我反思与分析
9. searcher - 信息收集与搜索
10. enricher - 数据丰富与扩展
11. coder - 代码生成与分析
12. installer - 安装与设置任务
13. pentester - 渗透测试与安全评估

可用测试组

• basic - 基础完成与提示响应测试
• advanced - 复杂推理与函数调用测试
• json - JSON 格式验证与结构测试（专为 simple_json 代理设计）
• knowledge - 领域特定的网络安全与渗透测试知识测试

注意：json 测试组专为 simple_json 代理类型设计，而其他所有代理则会使用 basic、advanced 和 knowledge 组进行测试。这种专业化确保了对每个代理预期用途的最佳测试覆盖。

示例提供商配置

提供商配置定义了不同代理类型应使用的模型：

simple:
  model: "provider/model-name"
  temperature: 0.7
  top_p: 0.95
  n: 1
  max_tokens: 4000

simple_json:
  model: "provider/model-name"
  temperature: 0.7
  top_p: 1.0
  n: 1
  max_tokens: 4000
  json: true

# ... 其他代理类型 ...

优化工作流程

1. 创建基线：使用默认配置运行测试，以建立基准性能
2. 分析代理特定性能：查看确定性的代理排序，找出表现不佳的代理
3. 测试专用配置：针对每个代理类型，使用提供商特定的配置尝试不同的模型
4. 关注领域知识：特别注意网络安全专业知识的知识组测试
5. 验证函数调用：确保关键代理类型的工具测试能够持续通过
6. 比较结果：寻找在所有测试组中最佳的成功率和性能
7. 部署最优配置：使用优化后的设置投入生产

此工具有助于确保您的 AI 代理为其特定任务使用最有效的模型，从而提高可靠性并优化成本。

嵌入配置与测试

PentAGI 使用向量嵌入进行语义搜索、知识存储和内存管理。该系统支持多种嵌入提供商，可根据您的需求和偏好进行配置。

支持的嵌入提供商

PentAGI 支持以下嵌入提供商：

• OpenAI（默认）：使用 OpenAI 的文本嵌入模型
• Ollama：通过 Ollama 使用本地嵌入模型
• Mistral：Mistral AI 的嵌入模型
• Jina：Jina AI 的嵌入服务
• HuggingFace：来自 HuggingFace 的模型
• GoogleAI：Google 的嵌入模型
• VoyageAI：VoyageAI 的嵌入模型

# 主要嵌入配置
EMBEDDING_PROVIDER=openai       # 提供商类型（openai、ollama、mistral、jina、huggingface、googleai、voyageai）
EMBEDDING_MODEL=text-embedding-3-small  # 要使用的模型名称
EMBEDDING_URL=                  # 可选的自定义 API 端点
EMBEDDING_KEY=                  # 提供商的 API 密钥（如果需要）
EMBEDDING_BATCH_SIZE=100        # 每批处理的文档数量
EMBEDDING_STRIP_NEW_LINES=true  # 是否在嵌入前移除文本中的换行符

# 高级设置
PROXY_URL=                      # 所有 API 调用的可选代理
HTTP_CLIENT_TIMEOUT=600         # 外部 API 调用的超时时间（秒）（默认：600，0 表示无超时）

# SSL/TLS 证书配置（用于与 LLM 后端及工具服务器的外部通信）
EXTERNAL_SSL_CA_PATH=           # 容器内自定义 CA 证书文件路径（PEM 格式）
                                # 必须指向 /opt/pentagi/ssl/ 目录（例如：/opt/pentagi/ssl/ca-bundle.pem）
EXTERNAL_SSL_INSECURE=false     # 跳过证书验证（仅用于测试）

# 默认位置（如果未设置 PENTAGI_SSL_DIR）
cp ca-bundle.pem ./pentagi-ssl/

# 或自定义位置（如果在 docker-compose.yml 中使用 PENTAGI_SSL_DIR）
cp ca-bundle.pem /path/to/your/ssl/dir/

# pentagi-ssl 卷被挂载到容器内的 /opt/pentagi/ssl
EXTERNAL_SSL_CA_PATH=/opt/pentagi/ssl/ca-bundle.pem
EXTERNAL_SSL_INSECURE=false

docker compose restart pentagi

嵌入测试工具 (etester)

PentAGI 包含一个专门的 etester 工具，用于测试、管理和调试嵌入功能。该工具对于诊断和解决与向量嵌入及知识存储相关的问题至关重要。

# 测试嵌入供应商和数据库连接
cd backend
go run cmd/etester/main.go test -verbose

# 显示嵌入数据库的相关统计信息
go run cmd/etester/main.go info

# 删除嵌入数据库中的所有文档（谨慎使用！）
go run cmd/etester/main.go flush

# 为所有文档重新计算嵌入（更换供应商后）
go run cmd/etester/main.go reindex

# 在嵌入数据库中搜索文档
go run cmd/etester/main.go search -query "如何安装 PostgreSQL" -limit 5

# 测试嵌入供应商
docker exec -it pentagi /opt/pentagi/bin/etester test

# 显示详细的数据库信息
docker exec -it pentagi /opt/pentagi/bin/etester info -verbose

# 按文档类型筛选
docker exec -it pentagi /opt/pentagi/bin/etester search -query "安全漏洞" -doc_type guide -threshold 0.8

# 按流程 ID 筛选
docker exec -it pentagi /opt/pentagi/bin/etester search -query "代码示例" -doc_type code -flow_id 42

# 所有可用的搜索选项
docker exec -it pentagi /opt/pentagi/bin/etester search -help

🔍 功能测试工具 ftester

PentAGI 包含一个多功能工具 ftester，用于调试、测试和开发特定功能及 AI 代理行为。虽然 ctester 专注于测试 LLM 模型的能力，但 ftester 允许您直接调用系统中的各个功能以及 AI 代理组件，并精确控制执行上下文。

主要特点

• 直接访问功能：无需运行整个系统即可测试单个功能。
• 模拟模式：无需实际部署 PentAGI 即可使用内置模拟进行功能测试。
• 交互式输入：以交互方式填写函数参数，便于探索性测试。
• 详细输出：终端输出带颜色编码，格式化显示响应和错误信息。
• 上下文感知测试：可在特定流程、任务和子任务的上下文中调试 AI 代理。
• 可观测性集成：所有函数调用都会记录到 Langfuse 和可观测性堆栈中。

使用模式

命令行参数

通过命令行直接指定函数和参数运行 ftester：

# 基本用法（模拟模式）
cd backend
go run cmd/ftester/main.go [function_name] -[arg1] [value1] -[arg2] [value2]

# 示例：在模拟模式下测试终端命令
go run cmd/ftester/main.go terminal -command "ls -la" -message "列出文件"

# 使用真实流程上下文
go run cmd/ftester/main.go -flow 123 terminal -command "whoami" -message "检查用户"

# 在特定任务/子任务上下文中测试 AI 代理
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 pentester -message "查找漏洞"

交互模式

不带参数运行 ftester，进入引导式交互体验：

# 启动交互模式
go run cmd/ftester/main.go [function_name]

# 例如，交互式填写浏览器工具参数
go run cmd/ftester/main.go browser

# 列出系统中的所有流程
go run cmd/ftester/main.go describe

# 显示特定流程的所有任务和子任务
go run cmd/ftester/main.go -flow 123 describe

# 显示特定任务的详细信息
go run cmd/ftester/main.go -flow 123 -task 456 describe

# 显示特定子任务的详细信息
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 describe

# 显示包含完整描述和结果的详细输出
go run cmd/ftester/main.go -flow 123 describe -verbose

# 获取特定函数的帮助
go run cmd/ftester/main.go [function_name] -help

# 示例：
go run cmd/ftester/main.go terminal -help
go run cmd/ftester/main.go browser -help
go run cmd/ftester/main.go describe -help

go run cmd/ftester/main.go

# 测试 Google 搜索 API 配置
go run cmd/ftester/main.go google -query "pentesting tools"

# 测试浏览器访问外部网站
go run cmd/ftester/main.go browser -url "https://example.com"

go run cmd/ftester/main.go -flow 123 terminal -command "env | grep -i proxy" -message "检查代理设置"

# 在正在运行的 PentAGI 容器中运行 ftester
docker exec -it pentagi /opt/pentagi/bin/ftester [arguments]

# 示例：
docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 describe
docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 terminal -command "ps aux" -message "列出进程"

命令行选项

主工具接受多个选项：

• -env <path> - 环境文件路径（可选，默认为 .env）
• -provider <type> - 使用的提供商类型（默认为 custom，可选值：openai、anthropic、ollama、bedrock、gemini、custom）
• -flow <id> - 用于测试的流程 ID（0 表示使用模拟数据，默认为 0）
• -task <id> - 用于代理上下文的任务 ID（可选）
• -subtask <id> - 用于代理上下文的子任务 ID（可选）

特定于函数的参数在函数名称后使用 -name value 格式传递。

构建

构建 Docker 镜像

Docker 构建过程会自动嵌入来自 Git 标签的版本信息。为了正确地为构建打上版本标签，请使用提供的脚本：

Linux/macOS

# 加载版本变量
source ./scripts/version.sh

# 标准构建
docker build \
  --build-arg PACKAGE_VER=$PACKAGE_VER \
  --build-arg PACKAGE_REV=$PACKAGE_REV \
  -t pentagi:$PACKAGE_VER .

# 多平台构建
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg PACKAGE_VER=$PACKAGE_VER \
  --build-arg PACKAGE_REV=$PACKAGE_REV \
  -t pentagi:$PACKAGE_VER .

# 构建并推送
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg PACKAGE_VER=$PACKAGE_VER \
  --build-arg PACKAGE_REV=$PACKAGE_REV \
  -t myregistry/pentagi:$PACKAGE_VER \
  --push .

Windows (PowerShell)

# 加载版本变量
. .\scripts\version.ps1

# 标准构建
docker build `
  --build-arg PACKAGE_VER=$env:PACKAGE_VER `
  --build-arg PACKAGE_REV=$env:PACKAGE_REV `
  -t pentagi:$env:PACKAGE_VER .

# 多平台构建
docker buildx build `
  --platform linux/amd64,linux/arm64 `
  --build-arg PACKAGE_VER=$env:PACKAGE_VER `
  --build-arg PACKAGE_REV=$env:PACKAGE_REV `
  -t pentagi:$env:PACKAGE_VER .

不带版本号的快速构建

对于不进行版本跟踪的开发构建：

docker build -t pentagi:dev .

[!NOTE]

• 构建脚本会自动从 Git 标签中确定版本号
• 发布版（在标签提交时）没有修订后缀
• 开发版（标签之后）会将提交哈希作为修订号（例如 1.1.0-bc6e800）
• 若要在本地使用构建好的镜像，请更新 docker-compose.yml 中的镜像名称，或直接使用 build 选项

致谢

本项目得以实现，得益于以下研究与开发工作：

• LLM 应用的新兴架构
• 自主 LLM 代理综述
• Andriy Semenets 的 Codel —— 基于代理的自动化设计的初始灵感来源

许可证

PentAGI 采用 MIT 许可证授权。

版权所有 © 2025 PentAGI 开发团队

第三方依赖

所有第三方依赖均采用与 MIT 兼容的许可证。详细许可证信息请参阅 licenses/ 目录。

VXControl 云服务

⚠️ 注意： 虽然 VXControl 云 SDK 的代码采用 MIT 许可证，但访问 VXControl 云服务（威胁情报、AI 支持、高级功能）需要单独的许可证密钥，并遵守 服务条款。

SDK 代码本身可免费使用，但需注册才能访问相关服务。

如有疑问，请联系：info@pentagi.com 或 info@vxcontrol.com

PentAGI 快速上手指南

PentAGI 是一款基于人工智能的自动化渗透测试工具，专为安全研究人员和伦理黑客设计。它利用大语言模型（LLM）自主规划并执行渗透测试步骤，内置 20+ 专业安全工具，并在隔离的 Docker 环境中运行以确保安全。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+/Debian) 或 macOS。Windows 用户建议使用 WSL2。
• Docker & Docker Compose: 必须安装最新版本的 Docker Engine 和 Docker Compose 插件。
  • 验证安装：docker --version 和 docker compose version
• 硬件资源:
  • CPU: 至少 4 核（推荐 8 核+）
  • 内存: 至少 8GB RAM（推荐 16GB+，若运行本地大模型需更多）
  • 磁盘: 至少 20GB 可用空间
• LLM API Key: 您需要一个可用的大模型服务密钥。支持 OpenAI, Anthropic, Google Gemini, AWS Bedrock, Ollama, DeepSeek, Qwen 等。
  • 国内开发者提示: 推荐使用 DeepSeek, Qwen (通义千问) 或通过 OpenRouter 聚合接入，以获得更稳定的连接和更低延迟。

安装步骤

PentAGI 采用微服务架构，通过 Docker Compose 一键部署是最便捷的方式。

1. 克隆项目仓库

git clone https://github.com/vxcontrol/pentagi.git
cd pentagi

2. 配置环境变量

复制示例配置文件并根据您的需求进行编辑。您需要在此处填入 LLM Provider 的 API Key 和其他必要配置。

cp .env.example .env
nano .env

关键配置项说明 (.env):

• LLM_PROVIDER: 选择提供商 (例如: openai, anthropic, deepseek, qwen, ollama)
• LLM_API_KEY: 填入您的 API Key
• LLM_MODEL: 指定模型名称 (例如: gpt-4o, deepseek-chat, qwen-plus)
• SEARCH_PROVIDER: 选择搜索引擎 (例如: tavily, duckduckgo, searxng)
  • 注: 若使用 Tavily 等国外服务网络不稳定，可考虑搭建本地 SearXNG 或使用支持国内访问的搜索 API。

3. 启动服务

使用 Docker Compose 启动所有核心服务（包括前端、后端、向量数据库、知识图谱及监控组件）：

docker compose up -d

注意: 首次启动时，Docker 会拉取多个镜像（包括 PostgreSQL+pgvector, Neo4j, Grafana 等），根据网络状况可能需要几分钟时间。

国内加速建议: 如果拉取镜像缓慢，请配置 Docker 镜像加速器（如阿里云、腾讯云镜像加速地址）后再执行上述命令。

4. 验证安装

检查所有容器是否正常运行：

docker compose ps

确保状态均为 Up 或 healthy。

基本使用

安装完成后，您可以通过 Web 界面或 API 与 PentAGI 交互。

1. 访问 Web 控制台

打开浏览器访问默认地址：

http://localhost:3000

• 功能: 在界面中创建新的渗透测试任务（Flow），查看实时日志、生成的报告以及知识图谱可视化。
• 监控: 系统集成了 Grafana (http://localhost:3001) 和 Langfuse (LLM 观测)，可用于监控系统性能和 AI 决策过程。

2. 发起第一个渗透测试任务 (API 方式)

您也可以通过 curl 命令直接调用 API 发起任务。以下是一个简单的示例，假设目标为本地测试环境（请勿对未授权目标进行测试）：

curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "query": "mutation CreateFlow($input: CreateFlowInput!) { createFlow(input: $input) { id name status } }",
    "variables": {
      "input": {
        "name": "Initial Scan",
        "description": "Automated nmap scan and vulnerability assessment",
        "target": "192.168.1.100", 
        "parameters": {
          "tools": ["nmap", "nikto"],
          "depth": "basic"
        }
      }
    }
  }

• 获取 Token: YOUR_API_TOKEN 可在 .env 文件中预设，或通过系统初始化后的输出获取。
• 查看进度: 任务提交后，可在 Web UI 的 "Flows" 页面查看实时执行步骤、AI 思考过程及最终生成的漏洞报告。

3. 查看结果

任务完成后，PentAGI 会自动生成详细的报告，包含：

• 发现的开放端口和服务
• 潜在的安全漏洞
• 利用建议
• 执行过程中的所有命令输出和截图（如有）

数据持久化存储在 PostgreSQL 中，您可以随时回溯历史任务记录。