> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/vxcontrol/pentagi) · [上游 README](https://github.com/vxcontrol/pentagi/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# PentAGI
Penetration testing Artificial General Intelligence
> **加入社区！** 与安全研究人员、AI 爱好者以及道德黑客（ethical hackers）同行交流。获取支持、分享见解，并及时了解 PentAGI 的最新进展。
[](https://discord.gg/2xrMh7qX6m)⠀[](https://t.me/+Ka9i6CNwe71hMWQy)
容器架构（点击展开）
```mermaid
graph TB
subgraph Core Services
UI[Frontend UI
React + TypeScript]
API[Backend API
Go + GraphQL]
DB[(Vector Store
PostgreSQL + pgvector)]
MQ[Task Queue
Async Processing]
Agent[AI Agents
Multi-Agent System]
end
subgraph Knowledge Graph
Graphiti[Graphiti
Knowledge Graph API]
Neo4j[(Neo4j
Graph Database)]
end
subgraph Monitoring
Grafana[Grafana
Dashboards]
VictoriaMetrics[VictoriaMetrics
Time-series DB]
Jaeger[Jaeger
Distributed Tracing]
Loki[Loki
Log Aggregation]
OTEL[OpenTelemetry
Data Collection]
end
subgraph Analytics
Langfuse[Langfuse
LLM Analytics]
ClickHouse[ClickHouse
Analytics DB]
Redis[Redis
Cache + Rate Limiter]
MinIO[MinIO
S3 Storage]
end
subgraph Security Tools
Scraper[Web Scraper
Isolated Browser]
PenTest[Security Tools
20+ Pro Tools
Sandboxed Execution]
end
UI --> |HTTP/WS| API
API --> |SQL| DB
API --> |Events| MQ
MQ --> |Tasks| Agent
Agent --> |Commands| PenTest
Agent --> |Queries| DB
Agent --> |Knowledge| Graphiti
Graphiti --> |Graph| Neo4j
API --> |Telemetry| OTEL
OTEL --> |Metrics| VictoriaMetrics
OTEL --> |Traces| Jaeger
OTEL --> |Logs| Loki
Grafana --> |Query| VictoriaMetrics
Grafana --> |Query| Jaeger
Grafana --> |Query| Loki
API --> |Analytics| Langfuse
Langfuse --> |Store| ClickHouse
Langfuse --> |Cache| Redis
Langfuse --> |Files| 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
```
实体关系（点击展开）
```mermaid
erDiagram
Flow ||--o{ Task : contains
Task ||--o{ SubTask : contains
SubTask ||--o{ Action : contains
Action ||--o{ Artifact : produces
Action ||--o{ Memory : stores
Flow {
string id PK
string name "Flow name"
string description "Flow description"
string status "active/completed/failed"
json parameters "Flow parameters"
timestamp created_at
timestamp updated_at
}
Task {
string id PK
string flow_id FK
string name "Task name"
string description "Task description"
string status "pending/running/done/failed"
json result "Task results"
timestamp created_at
timestamp updated_at
}
SubTask {
string id PK
string task_id FK
string name "Subtask name"
string description "Subtask description"
string status "queued/running/completed/failed"
string agent_type "researcher/developer/executor"
json context "Agent context"
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 parameters"
json result "Action results"
timestamp created_at
}
Artifact {
string id PK
string action_id FK
string type "file/report/log"
string path "Storage path"
json metadata "Additional info"
timestamp created_at
}
Memory {
string id PK
string action_id FK
string type "observation/conclusion"
vector embedding "Vector representation"
text content "Memory content"
timestamp created_at
}
```
Agent 交互（点击展开）
```mermaid
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 status
```
记忆系统（点击展开）
```mermaid
graph TB
subgraph "Long-term Memory"
VS[(Vector Store
Embeddings DB)]
KB[Knowledge Base
Domain Expertise]
Tools[Tools Knowledge
Usage Patterns]
end
subgraph "Working Memory"
Context[Current Context
Task State]
Goals[Active Goals
Objectives]
State[System State
Resources]
end
subgraph "Episodic Memory"
Actions[Past Actions
Commands History]
Results[Action Results
Outcomes]
Patterns[Success Patterns
Best Practices]
end
Context --> |Query| VS
VS --> |Retrieve| Context
Goals --> |Consult| KB
KB --> |Guide| Goals
State --> |Record| Actions
Actions --> |Learn| Patterns
Patterns --> |Store| VS
Tools --> |Inform| State
Results --> |Update| Tools
VS --> |Enhance| KB
KB --> |Index| 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
```
链式摘要（点击展开）
链式摘要（Chain Summarization）系统通过选择性摘要较早的消息来管理对话上下文的增长。这对于在保持对话连贯性的同时避免超出 token 限制至关重要。
```mermaid
flowchart TD
A[Input Chain] --> B{Needs Summarization?}
B -->|No| C[Return Original Chain]
B -->|Yes| D[Convert to ChainAST]
D --> E[Apply Section Summarization]
E --> F[Process Oversized Pairs]
F --> G[Manage Last Section Size]
G --> H[Apply QA Summarization]
H --> I[Rebuild Chain with Summaries]
I --> J{Is New Chain Smaller?}
J -->|Yes| K[Return Optimized Chain]
J -->|No| 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
```
该算法作用于对话链的结构化表示（ChainAST），保留包括工具调用及其响应在内的消息类型。所有摘要操作在缩减上下文大小的同时保持关键对话流程。
### 全局摘要器配置选项
| 参数 | 环境变量 | 默认值 | 说明 |
| --------------------- | -------------------------------- | ------- | ---------------------------------------------------------- |
| 保留最后一段 | `SUMMARIZER_PRESERVE_LAST` | `true` | 是否完整保留最后一段中的所有消息 |
| 使用 QA 配对 | `SUMMARIZER_USE_QA` | `true` | 是否使用 QA 配对摘要策略 |
| 摘要 QA 中的人类消息 | `SUMMARIZER_SUM_MSG_HUMAN_IN_QA` | `false` | 是否对 QA 配对中的人类消息进行摘要 |
| 最后一段大小 | `SUMMARIZER_LAST_SEC_BYTES` | `51200` | 最后一段的最大字节大小（50KB） |
| 最大正文配对大小 | `SUMMARIZER_MAX_BP_BYTES` | `16384` | 单个正文配对的最大字节大小（16KB） |
| 最大 QA 段数 | `SUMMARIZER_MAX_QA_SECTIONS` | `10` | 最多保留的 QA 配对段数 |
| 最大 QA 大小 | `SUMMARIZER_MAX_QA_BYTES` | `65536` | QA 配对段的最大字节大小（64KB） |
| 保留 QA 段数 | `SUMMARIZER_KEEP_QA_SECTIONS` | `1` | 保留最近 QA 段的数量（不进行摘要） |
### Assistant 摘要器配置选项
Assistant 实例可使用自定义摘要设置来微调上下文管理行为：
| 参数 | 环境变量 | 默认值 | 说明 |
| ------------------ | --------------------------------------- | ------- | -------------------------------------------------------------------- |
| 保留最后一段 | `ASSISTANT_SUMMARIZER_PRESERVE_LAST` | `true` | 是否保留 assistant 最后一段中的所有消息 |
| 最后一段大小 | `ASSISTANT_SUMMARIZER_LAST_SEC_BYTES` | `76800` | assistant 最后一段的最大字节大小（75KB） |
| 最大 Body Pair 大小 | `ASSISTANT_SUMMARIZER_MAX_BP_BYTES` | `16384` | assistant 上下文中单个 body pair 的最大字节大小（16KB） |
| 最大 QA 段数 | `ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS` | `7` | 在 assistant 上下文中保留的最大 QA 段数 |
| 最大 QA 大小 | `ASSISTANT_SUMMARIZER_MAX_QA_BYTES` | `76800` | assistant QA 段的最大字节大小（75KB） |
| 保留 QA 段数 | `ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS` | `3` | 不进行摘要而保留的最近 QA 段数量 |
与全局设置相比，assistant 摘要器配置为上下文保留提供更多内存，在保留更多近期对话历史的同时仍确保高效的 token 使用。
### 摘要器环境配置
```bash
# Default values for global summarizer logic
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
# Default values for assistant summarizer logic
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
```
高级 Agent 监管（点击展开）
PentAGI 包含复杂的多层 agent 监管机制，以确保高效的任务执行、防止无限循环，并在陷入卡住状态时提供智能恢复：
### 执行监控（Beta）
- **自动 Mentor 干预**：当执行模式表明可能存在问题时，会自动调用 Adviser agent（mentor）
- **模式检测**：监控相同的工具调用（阈值：5，可配置）和工具调用总数（阈值：10，可配置）
- **进度分析**：评估 agent 是否朝着子任务目标推进，检测循环和低效情况
- **替代策略**：当前策略失败时推荐不同方法
- **信息检索指导**：建议搜索已有解决方案，而非重新发明
- **增强响应格式**：工具响应同时包含 `` 和 `` 段
- **可配置**：通过 `EXECUTION_MONITOR_ENABLED` 启用（默认：false），使用 `EXECUTION_MONITOR_SAME_TOOL_LIMIT` 和 `EXECUTION_MONITOR_TOTAL_TOOL_LIMIT` 自定义阈值
**最适合**：较小模型（< 32B 参数）、需要持续指导的复杂攻击场景、防止 agent 卡在单一方法上
**性能影响**：执行时间和 token 使用量增加 2-3 倍，但根据 Qwen3.5-27B-FP8 的测试，**结果质量提升 2 倍**
### 智能任务规划（Beta）
- **自动分解**：Planner（规划模式下的 adviser）在 specialist agent 开始工作前生成 3-7 个具体可执行的步骤
- **上下文感知计划**：通过 enricher agent 分析完整执行上下文以制定知情计划
- **结构化分配**：原始请求包装在 `` 结构中，包含执行计划和指令
- **范围管理**：通过让 agent 仅专注于当前子任务来防止范围蔓延
- **增强指令**：计划突出关键操作、潜在陷阱和验证点
- **可配置**：通过 `AGENT_PLANNING_STEP_ENABLED` 启用（默认：false）
**最适合**：< 32B 参数的模型、复杂渗透测试工作流、提高复杂任务的成功率
**增强 Adviser 配置**：当 adviser agent 使用更强模型或增强设置时效果特别好。示例：对 adviser 使用相同基础模型并开启最大推理模式（参见 [`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)）可在相同模型架构下实现全面的任务分析和战略规划。
**性能影响**：增加规划开销，但显著提高完成率并减少冗余工作
### 工具调用限制（始终启用）
- **硬性限制**：无论监管模式状态如何，均可防止失控执行
- **按 Agent 类型区分**：
- 通用 agent（Assistant、Primary Agent、Pentester、Coder、Installer）：`MAX_GENERAL_AGENT_TOOL_CALLS`（默认：100）
- 受限 agent（Searcher、Enricher、Memorist、Generator、Reporter、Adviser、Reflector、Planner）：`MAX_LIMITED_AGENT_TOOL_CALLS`（默认：20）
- **优雅终止**：接近限制时 Reflector 引导 agent 正确完成
- **资源保护**：确保系统稳定并防止资源耗尽
### Reflector 集成（始终启用）
- **自动纠正**：LLM 在 3 次尝试后仍未能生成工具调用时触发
- **战略指导**：分析失败并引导 agent 正确使用工具或屏障工具（`done`、`ask`）
- **恢复机制**：根据特定失败模式提供上下文指导
- **限制执行**：达到工具调用限制时协调优雅终止
### 开源模型建议
**< 32B 参数模型必备**：
Qwen3.5-27B-FP8 的测试表明，对于较小的开源模型，同时启用执行监控和任务规划是**必不可少的**：
- **质量提升**：与无监管的基线执行相比，结果好 2 倍
- **循环预防**：显著减少无限循环和冗余工作
- **攻击多样性**：鼓励探索多种攻击向量，而非执着于单一方法
- **气隙部署**：在封闭网络环境中通过本地 LLM 推理实现生产级自主渗透测试
**权衡**：
- Token 消耗：由于 mentor/planner 调用增加 2-3 倍
- 执行时间：由于分析和规划步骤延长 2-3 倍
- 结果质量：完整性、准确性和攻击覆盖度提升 2 倍
- 模型要求：adviser 使用增强配置时效果最佳（更高推理参数、更强模型变体或不同模型）
**配置策略**：
为在较小模型上获得最佳性能，请为 adviser agent 配置增强设置：
- 使用相同模型并开启最大推理模式（示例：[`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)）
- 或为 adviser 使用更强模型，同时为其他 agent 保留基础模型
- 根据任务复杂度和模型能力调整监控阈值
PentAGI 的架构设计为模块化、可扩展且安全。以下是关键组件：
1. **核心服务**
- Frontend UI：基于 React 的 Web 界面，使用 TypeScript 确保类型安全
- Backend API：基于 Go 的 REST 和 GraphQL API，支持 Bearer token 认证以实现程序化访问
- Vector Store：PostgreSQL 配合 pgvector 用于语义搜索和记忆存储
- Task Queue：异步任务处理系统，确保可靠运行
- AI Agent：多 agent 系统，具有专门角色以实现高效测试
2. **知识图谱（Knowledge Graph）**
- Graphiti：用于语义关系追踪与上下文理解的知识图谱 API
- Neo4j：用于存储和查询实体、操作与结果之间关系的图数据库
- 自动捕获智能体响应与工具执行，以构建全面的知识库
3. **监控栈（Monitoring Stack）**
- OpenTelemetry：统一的可观测性数据采集与关联
- Grafana：实时可视化与告警仪表板
- VictoriaMetrics：高性能时序指标存储
- Jaeger：用于调试的端到端分布式追踪
- Loki：可扩展的日志聚合与分析
4. **分析平台（Analytics Platform）**
- Langfuse：高级 LLM 可观测性与性能分析
- ClickHouse：面向列的分析型数据仓库
- Redis：高速缓存与速率限制
- MinIO：用于存储产物的 S3 兼容对象存储
5. **安全工具（Security Tools）**
- Web Scraper：用于安全网页交互的隔离浏览器环境
- Pentesting Tools：包含 20+ 款专业安全工具的综合套件
- Sandboxed Execution：所有操作均在隔离容器中运行
6. **记忆系统（Memory Systems）**
- Long-term Memory：知识与经验的持久化存储
- Working Memory：当前操作的活跃上下文与目标
- Episodic Memory：历史操作与成功模式
- Knowledge Base：结构化的领域专业知识与工具能力
- Context Management：通过链式摘要智能管理不断增长的 LLM 上下文窗口
系统使用 Docker 容器实现隔离与便捷部署，为核心服务、监控和分析划分独立网络，以确保适当的安全边界。每个组件均支持水平扩展，并可针对生产环境配置为高可用。
## 快速开始
### 系统要求
- Docker 与 Docker Compose（或 Podman — 参见 [Podman 配置](#running-pentagi-with-podman)）
- 至少 2 个 vCPU
- 至少 4GB RAM
- 20GB 可用磁盘空间
- 可访问互联网以下载镜像与更新
### 使用安装程序（推荐）
PentAGI 提供带终端界面的交互式安装程序，用于简化配置与部署。安装程序会引导你完成系统检查、LLM 提供商设置、搜索引擎配置以及安全加固。
**支持的平台：**
- **Linux**：amd64 [download](https://pentagi.com/downloads/linux/amd64/installer-latest.zip) | arm64 [download](https://pentagi.com/downloads/linux/arm64/installer-latest.zip)
- **Windows**：amd64 [download](https://pentagi.com/downloads/windows/amd64/installer-latest.zip)
- **macOS**：amd64 (Intel) [download](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (M-series) [download](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip)
**快速安装（Linux amd64）：**
```bash
# Create installation directory
mkdir -p pentagi && cd pentagi
# Download installer
wget -O installer.zip https://pentagi.com/downloads/linux/amd64/installer-latest.zip
# Extract
unzip installer.zip
# Run interactive installer
./installer
```
**前提条件与权限：**
安装程序需要适当权限以与 Docker API 交互，从而正常运行。默认情况下，它使用 Docker 套接字（`/var/run/docker.sock`），这需要满足以下任一条件：
- **选项 1（生产环境推荐）：** 以 root 身份运行安装程序：
```bash
sudo ./installer
```
- **选项 2（开发环境）：** 将用户加入 `docker` 组，以授予其对 Docker 套接字的访问权限：
```bash
# Add your user to the docker group
sudo usermod -aG docker $USER
# Log out and log back in, or activate the group immediately
newgrp docker
# Verify Docker access (should run without sudo)
docker ps
```
⚠️ **安全提示：** 将用户加入 `docker` 组会授予与 root 等效的权限。仅在受控环境中的可信用户上执行此操作。对于生产部署，请考虑使用 rootless Docker 模式，或以 sudo 运行安装程序。
安装程序将执行以下步骤：
1. **系统检查**：验证 Docker、网络连接与系统要求
2. **环境设置**：创建并配置 `.env` 文件，采用最优默认值
3. **提供商配置**：设置 LLM 提供商（OpenAI、Anthropic、Gemini、Bedrock、Ollama、Custom）
4. **搜索引擎**：配置 DuckDuckGo、Google、Tavily、Traversaal、Perplexity、Sploitus、Searxng
5. **安全加固**：生成安全凭据并配置 SSL 证书
6. **部署**：使用 docker-compose 启动 PentAGI
### 当前 Web 设置覆盖范围
PentAGI Web 控制台在服务器启动运行后，已可管理多个设置区域：
- **Settings -> Providers**：为支持的提供商类型创建、编辑、删除并测试用户自定义的提供商配置文件。这些配置文件控制每个智能体的模型选择、运行时参数、推理选项以及定价元数据。
- **Settings -> Prompts**：管理系统、人类与工具提示词模板。
- **Settings -> PentAGI API**：创建并管理用于 REST 与 GraphQL 访问的 PentAGI Bearer 令牌。
- **其他由 UI 管理的偏好设置**：收藏流程以用户偏好形式存储，主题选择由主侧边栏/个人资料控件处理，而非 Settings 页面。
### 仍由服务器管理
以下配置区域仍需通过环境变量、compose 文件或挂载的配置文件在服务器端设置：
- **LLM 凭据与连接详情**：OpenAI、Anthropic、Bedrock、Ollama、自定义提供商及类似后端的 API 密钥、端点、认证模式与提供商特定连接设置；config-path 设置仅在受支持的场景下适用，例如 `OLLAMA_SERVER_CONFIG_PATH` 与 `LLM_SERVER_CONFIG_PATH`。
- **搜索提供商凭据与选项**：如 `DUCKDUCKGO_*`、`GOOGLE_*`、`TAVILY_API_KEY`、`TRAVERSAAL_API_KEY`、`PERPLEXITY_*`、`SEARXNG_*` 以及 `SPLOITUS_ENABLED` 等设置。
- **第三方集成**：Langfuse、Graphiti 及类似外部服务仍为服务器端配置。
- **MCP 服务器管理**：MCP 设置页面目前尚未作为实时 Web 控制台功能开放。
**面向生产环境与增强安全性：**
对于生产部署或安全敏感环境，我们**强烈建议**采用分布式双节点架构，将 worker 操作隔离在独立服务器上。这可防止不可信代码执行与主系统上的网络访问问题。
**详见详细指南**：[Worker Node Setup](examples/guides/worker_node.md)
双节点部署提供：
- **隔离执行**：Worker 容器在专用硬件上运行
- **网络隔离**：渗透测试采用独立的网络边界
- **安全边界**：带 TLS 认证的 Docker-in-Docker
- **OOB 攻击支持**：为带外（out-of-band）技术提供专用端口范围
### 手动安装
1. 创建工作目录或克隆仓库：
```bash
mkdir pentagi && cd pentagi
```
2. 将 `.env.example` 复制为 `.env`，或下载它：
```bash
curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example
```
3. 创建示例文件（`example.custom.provider.yml`、`example.ollama.provider.yml`），或下载它：
```bash
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 密钥。
```bash
# Required: At least one of these LLM providers
OPEN_AI_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
# Optional: AWS Bedrock provider (enterprise-grade models)
BEDROCK_REGION=us-east-1
# Choose one authentication method:
BEDROCK_DEFAULT_AUTH=true # Option 1: Use AWS SDK default credential chain (recommended for EC2/ECS)
# BEDROCK_BEARER_TOKEN=your_bearer_token # Option 2: Bearer token authentication
# BEDROCK_ACCESS_KEY_ID=your_aws_access_key # Option 3: Static credentials
# BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
# Optional: Ollama provider (local or cloud)
# OLLAMA_SERVER_URL=http://ollama-server:11434 # Local server
# OLLAMA_SERVER_URL=https://ollama.com # Cloud service
# OLLAMA_SERVER_API_KEY=your_ollama_cloud_key # Required for cloud, empty for local
# Optional: Chinese AI providers
# DEEPSEEK_API_KEY=your_deepseek_key # DeepSeek (strong reasoning)
# GLM_API_KEY=your_glm_key # GLM (Zhipu AI)
# KIMI_API_KEY=your_kimi_key # Kimi (Moonshot AI, ultra-long context)
# QWEN_API_KEY=your_qwen_key # Qwen (Alibaba Cloud, multimodal)
# Optional: Local LLM provider (zero-cost inference)
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=your_model_name
# Optional: Additional search capabilities
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 meta search engine (aggregates results from multiple sources)
SEARXNG_URL=http://your-searxng-instance:8080
SEARXNG_CATEGORIES=general
SEARXNG_LANGUAGE=
SEARXNG_SAFESEARCH=0
SEARXNG_TIME_RANGE=
SEARXNG_TIMEOUT=
## Graphiti knowledge graph settings
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_MODEL_NAME=gpt-5-mini
# Neo4j settings (used by Graphiti stack)
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687
# Assistant configuration
ASSISTANT_USE_AGENTS=false # Default value for agent usage when creating new assistants
```
5. 修改 `.env` 文件中所有与安全相关的环境变量，以提升安全性。
与安全相关的环境变量
### 主要安全设置
- `COOKIE_SIGNING_SALT` - 用于 Cookie 签名的盐值，请改为随机值
- `PUBLIC_URL` - 服务器的公开 URL（例如 `https://pentagi.example.com`）
- `SERVER_SSL_CRT` 和 `SERVER_SSL_KEY` - 现有 SSL 证书与密钥的自定义路径，用于 HTTPS（这些路径应在 docker-compose.yml 文件中作为卷挂载使用）
### 爬虫（Scraper）访问
- `SCRAPER_PUBLIC_URL` - 若要为公开 URL 使用不同的爬虫服务器，请设置爬虫的公开 URL
- `SCRAPER_PRIVATE_URL` - 爬虫的私有 URL（docker-compose.yml 文件中的本地爬虫服务器，用于访问本地 URL）
### 访问凭据
- `PENTAGI_POSTGRES_USER` 和 `PENTAGI_POSTGRES_PASSWORD` - PostgreSQL 凭据
- `NEO4J_USER` 和 `NEO4J_PASSWORD` - Neo4j 凭据（用于 Graphiti 知识图谱）
6. 若要在 VSCode 或其他 IDE 中将其作为 envFile 选项使用，请移除 `.env` 文件中的所有行内注释：
```bash
perl -i -pe 's/\s+#.*$//' .env
```
7. 运行 PentAGI 栈：
```bash
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml
docker compose up -d
```
访问 [localhost:8443](https://localhost:8443) 以打开 PentAGI Web UI（默认为 `admin@pentagi.com` / `admin`）
#### Web UI 账户
PentAGI 不会在登录页提供公开的自助注册。全新安装会创建默认的本地管理员账户：
- **Email**：`admin@pentagi.com`
- **Password**：`admin`
首次登录时，请在使用该实例进行实际工作前修改默认密码。若之后遗失管理员密码，可使用安装程序的维护菜单重置默认 `admin@pentagi.com` 账户密码。
对于多用户部署，已认证的管理员可通过 Users REST API（`/api/v1/users/`）管理本地用户。实例运行后，可在 `https://localhost:8443/api/v1/swagger/index.html` 访问 OpenAPI UI。
> [!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 服务。
>
> 必须至少配置一个语言模型（Language Model）提供商（OpenAI、Anthropic、Gemini、AWS Bedrock 或 Ollama）才能使用 PentAGI。AWS Bedrock 提供企业级访问，可调用多家领先 AI 公司的基础模型；若具备足够的计算资源，Ollama 可提供零成本的本地推理。搜索引擎的额外 API 密钥为可选项，但建议配置以获得更好效果。
>
> **完全本地部署并使用高级模型**：请参阅我们的完整指南 [使用 vLLM 与 Qwen3.5-27B-FP8 运行 PentAGI](examples/guides/vllm-qwen35-27b-fp8.md)，了解生产级本地 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`（仅 localhost），以确保安全。若要从网络中的其他机器访问 PentAGI，需要配置外部访问。
#### 配置步骤
1. **更新 `.env` 文件**，填入服务器的 IP 地址：
```bash
# Network binding - allow external connections
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443
# Public URL - use your actual server IP or hostname
# Replace 192.168.1.100 with your server's IP address
PUBLIC_URL=https://192.168.1.100:8443
# CORS origins - list all URLs that will access PentAGI
# Include localhost for local access AND your server IP for external access
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. **重新创建容器**以应用更改：
```bash
docker compose down
docker compose up -d --force-recreate
```
3. **验证端口绑定：**
```bash
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 行：
```yaml
ports:
- "0.0.0.0:8443:8443"
```
然后再次重新创建容器。
4. **配置防火墙**，允许 8443 端口的入站连接：
```bash
# Ubuntu/Debian with UFW
sudo ufw allow 8443/tcp
sudo ufw reload
# CentOS/RHEL with 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 无根（rootless）模式**时，爬虫服务需要特殊配置，因为无根容器无法绑定特权端口（1024 以下端口）。
#### Podman 无根模式配置
默认爬虫配置使用 443 端口（HTTPS），属于特权端口。对于 Podman 无根模式，需将爬虫重新配置为使用非特权端口：
**1. 编辑 `docker-compose.yml`** —— 修改 `scraper` 服务（约第 199 行）：
```yaml
scraper:
image: vxcontrol/scraper:latest
restart: unless-stopped
container_name: scraper
hostname: scraper
expose:
- 3000/tcp # Changed from 443 to 3000
ports:
- "${SCRAPER_LISTEN_IP:-127.0.0.1}:${SCRAPER_LISTEN_PORT:-9443}:3000" # Map to port 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 端口：
```bash
# Scraper configuration for Podman rootless
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`
> - 将端口映射目标从 `443` 更新为 `3000`
**3. 重新创建容器：**
```bash
podman-compose down
podman-compose up -d --force-recreate
```
**4. 测试爬虫连通性：**
```bash
# Test from within the pentagi container
podman exec -it pentagi wget -O- "http://someuser:somepass@scraper:3000/html?url=http://example.com"
```
若看到 HTML 输出，说明爬虫工作正常。
#### Podman 有根（Rootful）模式
若以有根模式运行 Podman（使用 sudo），可使用默认配置而无需修改。爬虫将按预期在 443 端口上工作。
#### Docker 兼容性
所有 Podman 配置与 Docker 完全兼容。非特权端口方案在两种容器运行时上的工作方式相同。
### 助手配置
PentAGI 允许你为助手配置默认行为：
| Variable | Default | Description |
| ---------------------- | ------- | ----------------------------------------------------------------------- |
| `ASSISTANT_USE_AGENTS` | `false` | 控制创建新助手时代理（agent）用量的默认值 |
`ASSISTANT_USE_AGENTS` 设置会影响在 UI 中创建新助手时「Use Agents」开关的初始状态：
- `false`（默认）：新助手默认创建时禁用代理委派
- `true`：新助手默认创建时启用代理委派
请注意，用户在创建或编辑助手时，始终可以通过 UI 中的「Use Agents」按钮覆盖此设置。该环境变量仅控制初始默认状态。
## 登录后如何使用 PentAGI
堆栈运行且你可以登录 Web UI 后，最快的入门方式是通过 Flows 工作流。
### 1. 创建你的第一个 flow
1. 在侧边栏中打开 **Flows**。
2. 点击 **New Flow**。
3. 选择符合你目标的运行模式：
- **Automation**：针对你希望 PentAGI 端到端完成的测试目标，进行完全自主执行
- **Assistant**：当你希望逐步引导调查时，进行交互式来回协助。在此模式下，你还可以启用 **Use Agents** 开关，让 PentAGI 将子任务委派给专门的子代理（sub-agent），以应对更复杂的调查。
4. 选择要用于此 flow 的 LLM 提供商。
5. 在消息框中用自然语言描述目标与目的。
良好的首个提示通常包括：
- 目标系统或 URL
- 你想要的评估类型
- 任何范围限制或交战规则（rules of engagement）
- 你期望的结果，例如漏洞报告或对假设的验证
示例：
```text
Assess https://target.example for common web application vulnerabilities. Focus on authentication, file handling, and injection issues. Stay within the provided target only and summarize confirmed findings with reproduction steps.
```
仅测试你拥有或已获明确授权评估的系统。可接受使用要求请参阅 [EULA.md](EULA.md)。
### 2. 使用模板实现可重复的工作流
新建 flow 表单包含模板选择器，可用已保存的 flow 模板预填消息框。当你反复运行类似评估时，这很有用。
- 若你已在 **Templates** 中保存模板，可使用现有模板
- 若需要 Web 测试的实用基线，可从 [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md) 中的示例提示入手
- 启动 flow 前，请调整目标、范围和约束
模板只是起点。使用 PentAGI 无需特殊语法：只要目标与目的清晰，纯自然语言指令即可良好工作。
### 3. 监控执行并审阅输出
提交 flow 后，PentAGI 会自动打开 flow 页面。
- 使用主 flow 视图跟踪消息、代理活动与任务进度
- 在 flow 运行期间检查工具活动与终端输出
- 审阅生成的任务与子任务，以了解 PentAGI 正在做什么
当 flow 已有足够结果时，使用 flow 页面上的 **Report** 菜单可：
- 在 Web 视图中打开报告
- 将生成的报告复制到剪贴板
- 将报告下载为 Markdown
- 将报告下载为 PDF
### 4. 使用 Assistant 视图引导活跃的 flow
每个 flow 还包含用于交互式引导的 **Assistant** 视图。当自主运行发现需要人工指引而非硬性重启的情况时，这很有用。
- 在更改任何内容之前，若你想检查当前状态，请为同一 flow 打开 **Assistant** 视图。
- 使用助手检查 flow 状态、停止当前任务、提交后续指令，或在下一步运行前修补剩余计划子任务。
- 将其视为当前 flow 的显式控制路径，而非不可见的后台队列。若要改变方向，请明确说明，并使新指令与当前交战范围保持一致。
- 这最适合澄清范围、在中间发现后重定向优先级，或在不丢失其余 flow 上下文的情况下响应自动化检查点。
### 5. 管理 flow 范围内的文件
每个 flow 在 flow 页面都有各自的 **Files** 标签页。文件限定于父 flow：它们位于主机上的 `{dataDir}/flow-{id}-data/`，且绝不会泄漏到其他 flow。
该标签页展示三类文件来源：
- **Uploads**（`uploads/`）：你从 Web UI 提供的文件。使用 **Upload files** 操作，或直接拖放到 Files 标签页。代理容器运行时，上传的文件也会推送到其中的 `/work/uploads/`，以便代理用常规 shell 工具读取。
- **Resources**（`resources/`）：通过 **Attach resources from library** 从你已保存的用户资源库附加的文件。附加的资源会复制到 flow，并推送到运行中容器的 `/work/resources/`。
- **Container**（`container/`）：通过 **Pull file or directory from container** 从运行中的代理容器拉取的快照。它们在 flow 侧为只读，且绝不会发回容器。
Files 标签页中每个文件的操作包括 **Download**、**Copy path**、**Save as resource**（将 flow 文件提升到你可复用的资源库），以及 **Delete**。容器未运行时 Pull 操作会被禁用，工具提示为「Container is not running」。
上传的文件与附加资源会通过 `{{.UserFiles}}` 模板变量自动列在代理的系统提示中，该变量会渲染紧凑的 `` XML 块（含嵌套的 `` 与 `` 节），以便助手与自动化代理按路径引用它们，而无需你将内容粘贴到聊天中。容器快照仅在 UI 中可见，不会自动注入回提示。
需注意的当前限制：
- 单文件最大上传大小为 300 MB；单次上传请求最多 1000 个文件、总计 2 GB。文件名上限为 255 字节（约 255 个 ASCII 字符；非 ASCII 名称每个字符占用多个字节）。
- 上传与资源会镜像到运行中容器的固定路径 `/work/uploads/` 与 `/work/resources/`；写入其他容器路径的文件不会自动镜像回 flow 文件模型。容器快照可来自你拉取的任意容器路径（例如 `/etc/...`），并在 flow 侧缓存于 `container/` 下；它们不会推回容器。
- 容器快照为时间点拉取。在 UI 中编辑快照不会写回运行中的容器。
- 目前删除 flow 会移除 flow 记录及其长期记忆条目，但尚未归档或删除磁盘上该 flow 的 `flow-{id}-data/` 目录。若运维人员希望回收空间，仍需手动清理数据目录。
早期测试时，请从狭窄目标与单一清晰目的入手。这样输出更易审阅，也有助于在运行更大规模评估前优化提示。
## API 访问
PentAGI 通过 REST 与 GraphQL API 提供全面的程序化访问，使你能够将渗透测试工作流集成到自动化流水线、CI/CD 流程与自定义应用中。
### 生成 API 令牌
API 令牌通过 PentAGI Web 界面管理：
1. 在 Web UI 中导航至 **Settings** → **API Tokens**
2. 点击 **Create Token** 生成新的 API 令牌
3. 配置令牌属性：
- **Name**（可选）：令牌的描述性名称
- **Expiration Date**：令牌过期时间（最短 1 分钟，最长 3 年）
4. 点击 **Create** 并**立即复制令牌**——出于安全考虑，令牌仅显示一次
5. 在 API 请求中将该令牌用作 Bearer 令牌
每个令牌均与您的用户账户关联，并继承您角色所拥有的权限。
### 使用 API 令牌
在 HTTP 请求的 `Authorization` 请求头中包含 API 令牌：
```bash
# GraphQL API example
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 example
curl https://your-pentagi-instance:8443/api/v1/flows \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
### API 探索与测试
PentAGI 提供交互式文档，用于探索和测试 API 端点：
#### GraphQL Playground
在 `https://your-pentagi-instance:8443/api/v1/graphql/playground` 访问 GraphQL Playground
1. 点击底部的 **HTTP Headers** 标签页
2. 添加您的授权请求头：
```json
{
"Authorization": "Bearer YOUR_API_TOKEN"
}
```
3. 交互式地探索 schema、运行查询并测试变更（mutation）
#### Swagger UI
在 `https://your-pentagi-instance:8443/api/v1/swagger/index.html` 访问 REST API 文档
1. 点击 **Authorize** 按钮
2. 按以下格式输入您的令牌：`Bearer YOUR_API_TOKEN`
3. 点击 **Authorize** 以应用
4. 直接在 Swagger UI 中测试端点
### 生成 API 客户端
您可以使用 PentAGI 附带的 schema 文件，为偏好的编程语言生成类型安全的 API 客户端：
#### GraphQL 客户端
GraphQL schema 可通过以下方式获取：
- **Web UI**：前往 Settings 下载 `schema.graphqls`
- **直接文件**：仓库中的 `backend/pkg/graph/schema.graphqls`
可使用以下工具生成客户端：
- **GraphQL Code Generator**（JavaScript/TypeScript）：[https://the-guild.dev/graphql/codegen](https://the-guild.dev/graphql/codegen)
- **genqlient**（Go）：[https://github.com/Khan/genqlient](https://github.com/Khan/genqlient)
- **Apollo iOS**（Swift）：[https://www.apollographql.com/docs/ios](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](https://openapi-generator.tech)
```bash
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](https://github.com/swagger-api/swagger-codegen)
```bash
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](https://github.com/acacode/swagger-typescript-api)
```bash
npx swagger-typescript-api \
-p https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
-o ./src/api \
-n pentagi-api.ts
```
### API 使用示例
创建新 Flow（GraphQL）
```graphql
mutation CreateFlow {
createFlow(
modelProvider: "openai"
input: "Test the security of https://example.com"
) {
id
title
status
createdAt
}
}
```
列出 Flow（REST API）
```bash
curl https://your-pentagi-instance:8443/api/v1/flows \
-H "Authorization: Bearer YOUR_API_TOKEN" \
| jq '.flows[] | {id, title, status}'
```
Python 客户端示例
```python
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()
# Usage
client = PentAGIClient(
"https://your-pentagi-instance:8443",
"your_api_token_here"
)
# Create a new flow
flow = client.create_flow("openai", "Scan https://example.com for vulnerabilities")
print(f"Created flow: {flow}")
# List all flows
flows = client.get_flows()
print(f"Total flows: {len(flows['flows'])}")
```
TypeScript 客户端示例
```typescript
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 {
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 {
const response = await this.client.get('/flows');
return response.data.flows;
}
async getFlow(flowId: string): Promise {
const response = await this.client.get(`/flows/${flowId}`);
return response.data;
}
}
// Usage
const client = new PentAGIClient(
'https://your-pentagi-instance:8443',
'your_api_token_here'
);
// Create a new flow
const flow = await client.createFlow(
'openai',
'Perform penetration test on https://example.com'
);
console.log('Created flow:', flow);
// List all flows
const flows = await client.getFlows();
console.log(`Total flows: ${flows.length}`);
```
### 安全最佳实践
使用 API 令牌时：
- **切勿将令牌提交到版本控制** — 请使用环境变量或密钥管理服务
- **定期轮换令牌** — 设置合适的过期时间，并定期创建新令牌
- **为不同应用使用独立令牌** — 便于在需要时撤销访问权限
- **监控令牌使用情况** — 在 Settings 页面查看 API 令牌活动
- **撤销未使用的令牌** — 禁用或删除不再需要的令牌
- **仅使用 HTTPS** — 切勿通过未加密的连接发送 API 令牌
### 令牌管理
- **查看令牌**：在 Settings → API Tokens 中查看所有活跃令牌
- **编辑令牌**：更新令牌名称或撤销令牌
- **删除令牌**：永久删除令牌（此操作无法撤销）
- **令牌 ID**：每个令牌都有唯一的 ID，可复制以供参考
令牌列表显示：
- 令牌名称（如已提供）
- 令牌 ID（唯一标识符）
- 状态（active/revoked/expired）
- 创建日期
- 过期日期
### 自定义 LLM 提供商配置
将自定义 LLM 提供商与 `LLM_SERVER_*` 变量配合使用时，您可以微调请求中使用的推理格式。
> [!TIP]
> 对于生产级本地部署，建议使用 **vLLM** 配合 **Qwen3.5-27B-FP8** 以获得最佳性能。请参阅我们的[完整部署指南](examples/guides/vllm-qwen35-27b-fp8.md)，其中包含硬件要求、配置模板（[thinking mode](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml) 与 [non-thinking mode](examples/configs/vllm-qwen3.5-27b-fp8-no-think.provider.yml)），以及在 4× RTX 5090 GPU 上实现 13K TPS 提示词处理吞吐量的性能基准测试。
| Variable | Default | Description |
| ------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `LLM_SERVER_URL` | | 自定义 LLM API 端点的 Base URL |
| `LLM_SERVER_KEY` | | 自定义 LLM 提供商的 API 密钥 |
| `LLM_SERVER_MODEL` | | 默认使用的模型（可在提供商配置中覆盖） |
| `LLM_SERVER_CONFIG_PATH` | | Agent 专用模型的 YAML 配置文件路径 |
| `LLM_SERVER_PROVIDER` | | 模型名称的提供商名前缀（例如，LiteLLM proxy 使用 `openrouter`、`deepseek`） |
| `LLM_SERVER_LEGACY_REASONING` | `false` | 控制 API 请求中的推理（reasoning）格式 |
| `LLM_SERVER_PRESERVE_REASONING` | `false` | 在多轮对话中保留推理内容（部分提供商要求） |
`LLM_SERVER_PROVIDER` 设置在使用 **LiteLLM proxy** 时特别有用，该代理会为模型名称添加提供商前缀。例如，通过 LiteLLM 连接 Moonshot API 时，像 `kimi-2.5` 这样的模型会变成 `moonshot/kimi-2.5`。通过设置 `LLM_SERVER_PROVIDER=moonshot`，你可以使用同一份提供商配置文件，无需修改即可同时支持直接 API 访问和 LiteLLM proxy 访问。
`LLM_SERVER_LEGACY_REASONING` 设置影响推理参数如何发送至 LLM：
- `false`（默认）：使用现代格式，推理以结构化对象发送，并带有 `max_tokens` 参数
- `true`：使用旧版格式，采用基于字符串的 `reasoning_effort` 参数
在使用不同 LLM 提供商时，此设置很重要，因为各提供商可能在 API 请求中期望不同的推理格式。若在使用自定义提供商时遇到与推理相关的错误，请尝试更改此设置。
`LLM_SERVER_PRESERVE_REASONING` 设置控制是否在多轮对话中保留推理内容：
- `false`（默认）：对话历史中不保留推理内容
- `true`：保留推理内容并在后续 API 调用中发送
部分 LLM 提供商（例如 Moonshot）要求此设置；若多轮对话中未包含推理内容，可能返回类似 "thinking is enabled but reasoning_content is missing in assistant tool call message" 的错误。若你的提供商要求保留推理内容，请启用此设置。
### Ollama 提供商配置
PentAGI 支持 Ollama，可用于本地 LLM 推理（零成本、增强隐私）以及 Ollama Cloud（带免费额度的托管服务）。
#### 配置变量
| Variable | Default | Description |
| ----------------------------------- | ----------- | ----------------------------------------- |
| `OLLAMA_SERVER_URL` | | Ollama 服务器或 Ollama Cloud 的 URL |
| `OLLAMA_SERVER_API_KEY` | | Ollama Cloud 身份验证的 API 密钥 |
| `OLLAMA_SERVER_MODEL` | | 推理默认模型 |
| `OLLAMA_SERVER_CONFIG_PATH` | | 自定义 Agent 配置文件路径 |
| `OLLAMA_SERVER_PULL_MODELS_TIMEOUT` | `600` | 模型下载超时时间（秒） |
| `OLLAMA_SERVER_PULL_MODELS_ENABLED` | `false` | 启动时自动下载模型 |
| `OLLAMA_SERVER_LOAD_MODELS_ENABLED` | `false` | 向服务器查询可用模型 |
#### Ollama Cloud 配置
Ollama Cloud 提供托管推理服务，拥有慷慨的免费额度以及可扩展的付费方案。
**免费层级设置（单模型）**
```bash
# Free tier allows one model at a time
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_MODEL=gpt-oss:120b # Example: OpenAI OSS 120B model
```
**付费层级设置（多模型与预构建配置）**
对于支持多个并发模型的付费层级，请使用预构建的 Ollama Cloud 配置：
```bash
# Using pre-built Ollama Cloud configuration (included in Docker image)
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` 配置包含针对所有 Agent 类型的优化模型分配：
- **Simple/Assistant**：`nemotron-3-super:cloud` - 快速通用模型
- **Primary Agent**：`qwen3-coder-next:cloud` - 高努力模式的高级推理
- **Coder/Pentester**：`qwen3-coder-next:cloud` - 专用编码模型
- **Searcher**：`qwen3.5:397b-cloud` - 大上下文信息收集
- **Refiner/Refactor**：`glm-5:cloud` - 高质量文本精炼
- **Adviser/Enricher**：`minimax-m2.7:cloud` - 高效咨询任务
- **Installer**：`devstral-2:123b-cloud` - 安装与设置任务
**自定义配置（高级）**
要创建你自己的 Agent 配置，请从宿主机文件系统挂载自定义文件：
```bash
# Using custom provider configuration
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
# Mount custom configuration from host filesystem (in .env or docker-compose override)
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`）：
```yaml
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 实例：
```bash
# Basic local Ollama setup
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
# Production setup with auto-pull and model discovery
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
# Using pre-built configurations from Docker image
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
# or
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml
# or
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` 参数的自定义模型。虽然典型 Agent 工作流大约消耗 64K token，但 PentAGI 使用 110K 上下文大小，以留出安全余量并处理复杂的渗透测试场景。
**重要**：`num_ctx` 参数只能在通过 Modelfile 创建模型时设置——模型创建后无法更改，也无法在运行时覆盖。
##### 示例：带扩展上下文的 Qwen3 32B FP16
创建一个名为 `Modelfile_qwen3_32b_fp16_tc` 的 Modelfile：
```dockerfile
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
```
构建自定义模型：
```bash
ollama create qwen3:32b-fp16-tc -f Modelfile_qwen3_32b_fp16_tc
```
##### 示例：QwQ 32B FP16 扩展上下文
创建一个名为 `Modelfile_qwq_32b_fp16_tc` 的 Modelfile：
```dockerfile
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
```
构建自定义模型：
```bash
ollama create qwq:32b-fp16-tc -f Modelfile_qwq_32b_fp16_tc
```
> **注意**：QwQ 32B FP16 模型推理大约需要 **71.3 GB VRAM**。在尝试使用该模型之前，请确保系统拥有足够的 GPU 显存。
这些自定义模型会在 Docker 镜像中 `/opt/pentagi/conf/` 路径下附带的预构建提供商配置文件（`ollama-qwen332b-fp16-tc.provider.yml` 和 `ollama-qwq32b-fp16-tc.provider.yml`）中被引用。
### OpenAI 提供商配置
PentAGI 与 OpenAI 全面的模型阵容集成，具备扩展思维链（chain-of-thought）的高级推理能力、增强工具集成的智能体（agentic）模型，以及面向安全工程的专业代码模型。
#### 配置变量
| 变量 | 默认值 | 说明 |
| -------------------- | --------------------------- | --------------------------- |
| `OPEN_AI_KEY` | | OpenAI 服务的 API 密钥 |
| `OPEN_AI_SERVER_URL` | `https://api.openai.com/v1` | OpenAI API 端点 |
#### 配置示例
```bash
# Basic OpenAI setup
OPEN_AI_KEY=your_openai_api_key
OPEN_AI_SERVER_URL=https://api.openai.com/v1
# Using with proxy for enhanced security
OPEN_AI_KEY=your_openai_api_key
PROXY_URL=http://your-proxy:8080
```
#### 支持的模型
PentAGI 支持 31 个具备工具调用、流式输出、推理模式和提示缓存（prompt caching）的 OpenAI 模型。标记为 `*` 的模型用于默认配置。
**GPT-5.2 系列 - 最新旗舰智能体模型（2025 年 12 月）**
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-5.2`* | ✅ | $1.75/$14.00/$0.18 | 最新旗舰模型，具备增强推理与工具集成，适用于自主安全研究 |
| `gpt-5.2-pro` | ✅ | $21.00/$168.00/$0.00 | 高级版本，具备卓越智能体编码能力，适用于关键任务安全研究与零日漏洞发现 |
| `gpt-5.2-codex` | ✅ | $1.75/$14.00/$0.18 | 最先进的代码专用模型，支持上下文压缩，具备强大网络安全能力 |
**GPT-5/5.1 系列 - 高级智能体模型**
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-5` | ✅ | $1.25/$10.00/$0.13 | 顶级智能体模型，具备高级推理能力，适用于自主安全研究与漏洞利用链开发 |
| `gpt-5.1` | ✅ | $1.25/$10.00/$0.13 | 增强型智能体模型，具备自适应推理，适用于均衡渗透测试与强大工具协同 |
| `gpt-5-pro` | ✅ | $15.00/$120.00/$0.00 | 高级版本，具备重大推理改进与更少幻觉，适用于关键安全操作 |
| `gpt-5-mini` | ✅ | $0.25/$2.00/$0.03 | 在速度与智能之间高效平衡，适用于自动化漏洞分析与漏洞利用生成 |
| `gpt-5-nano` | ✅ | $0.05/$0.40/$0.01 | 最快的高吞吐量扫描模型，适用于侦察与批量漏洞检测 |
**GPT-5/5.1 Codex 系列 - 代码专用模型**
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-5.1-codex-max` | ✅ | $1.25/$10.00/$0.13 | 面向复杂编码的增强推理，适用于已验证 CVE 发现与系统化漏洞利用开发 |
| `gpt-5.1-codex` | ✅ | $1.25/$10.00/$0.13 | 标准代码优化模型，具备强大推理能力，适用于漏洞利用生成与漏洞分析 |
| `gpt-5-codex` | ✅ | $1.25/$10.00/$0.13 | 基础代码专用模型，适用于漏洞扫描与基础漏洞利用生成 |
| `gpt-5.1-codex-mini` | ✅ | $0.25/$2.00/$0.03 | 紧凑高性能模型，容量提升 4 倍，适用于快速漏洞检测 |
| `codex-mini-latest` | ✅ | $1.50/$6.00/$0.38 | 最新紧凑代码模型，适用于自动化代码审查与基础漏洞分析 |
**GPT-4.1 系列 - 增强智能模型**
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-4.1` | ❌ | $2.00/$8.00/$0.50 | 增强旗舰模型，具备卓越函数调用能力，适用于复杂威胁分析与高级漏洞利用开发 |
| `gpt-4.1-mini`* | ❌ | $0.40/$1.60/$0.10 | 性能均衡且效率更高，适用于常规安全评估与自动化代码分析 |
| `gpt-4.1-nano` | ❌ | $0.10/$0.40/$0.03 | 超快轻量模型，适用于批量安全扫描、快速侦察与持续监控 |
**GPT-4o 系列 - 多模态旗舰模型**
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-4o` | ❌ | $2.50/$10.00/$1.25 | 多模态旗舰模型，具备视觉能力，适用于图像分析、Web UI 评估与多工具编排 |
| `gpt-4o-mini` | ❌ | $0.15/$0.60/$0.08 | 紧凑多模态模型，具备强大函数调用能力，适用于高频扫描与高性价比批量操作 |
**o 系列 - 高级推理模型**
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `o4-mini`* | ✅ | $1.10/$4.40/$0.28 | 下一代推理模型，速度更快，适用于系统化安全评估与系统化漏洞利用开发 |
| `o3`* | ✅ | $2.00/$8.00/$0.50 | 高级推理强力模型，适用于多阶段攻击链与深度漏洞分析 |
| `o3-mini` | ✅ | $1.10/$4.40/$0.55 | 紧凑推理模型，支持扩展思考，适用于分步攻击规划与逻辑化漏洞串联 |
| `o1` | ✅ | $15.00/$60.00/$7.50 | 顶级推理模型，具备最大深度，适用于高级渗透测试与新型漏洞利用研究 |
| `o3-pro` | ✅ | $20.00/$80.00/$0.00 | 最先进推理模型，比 o1-pro 便宜 80%，适用于零日研究与关键安全调查 |
| `o1-pro` | ✅ | $150.00/$600.00/$0.00 | 上一代高级推理模型，适用于详尽安全分析与关键任务挑战 |
**价格**：按每 100 万 token 计费。推理模型的输出定价包含思考 token。
> [!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](https://chatgpt.com/cyber) 验证身份
> 2. **企业团队**：通过 OpenAI 代表申请可信访问权限
> 3. **安全研究人员**：申请 [网络安全资助计划（Cybersecurity Grant Program）](https://openai.com/form/cybersecurity-grant-program/)（包含 1000 万美元 API 额度）
>
> **无需验证的推荐替代方案：**
> - 推理任务使用 `o-series` 模型（o3、o4-mini、o1）
> - 通用智能与函数调用使用 `gpt-4.1` 系列
> - 所有 o 系列和 gpt-4.x 模型无需特殊访问权限即可稳定运行
**推理力度等级**：
- **High**：最大推理深度（refiner - o3，high effort）
- **Medium**：均衡推理（primary_agent、assistant、reflector - o4-mini/o3，medium effort）
- **Low**：高效定向推理（coder、installer、pentester - o3/o4-mini，low effort；adviser - gpt-5.2，low effort）
**核心特性**：
- **扩展推理（Extended Reasoning）**：o 系列模型配合思维链（chain-of-thought），用于复杂安全分析
- **智能体能力（Agentic Intelligence）**：GPT-5/5.1/5.2 系列，增强工具集成与自主能力
- **提示缓存（Prompt Caching）**：重复上下文可降低成本（约为输入价格的 10-50%）
- **代码专精**：专用 Codex 模型，用于漏洞发现与 exploit 开发
- **多模态支持**：GPT-4o 系列，用于基于视觉的安全评估
- **工具调用（Tool Calling）**：全系模型稳健函数调用，用于渗透测试工具编排
- **流式输出（Streaming）**：实时响应流，用于交互式工作流
- **成熟实绩**：行业领先模型，具备 CVE 发现与真实场景安全应用记录
### Anthropic 提供商配置
PentAGI 集成 Anthropic 的 Claude 模型，具备先进的扩展思考能力、卓越的安全机制，以及对复杂安全语境的深刻理解，并支持提示缓存。
#### 配置变量
| Variable | Default | Description |
| ---------------------- | ------------------------------ | ------------------------------ |
| `ANTHROPIC_API_KEY` | | Anthropic 服务 API 密钥 |
| `ANTHROPIC_SERVER_URL` | `https://api.anthropic.com/v1` | Anthropic API 端点 |
#### 配置示例
```bash
# Basic Anthropic setup
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1
# Using with proxy for secure environments
ANTHROPIC_API_KEY=your_anthropic_api_key
PROXY_URL=http://your-proxy:8080
```
> [!NOTE]
> **适用于 Claude 模型的 Google Vertex AI**
>
> PentAGI 目前在 `.env` 中尚未提供面向 Anthropic Claude 的专用 Google Vertex AI 配置路径。目前尚无独立的 Vertex AI API 密钥字段，现有 Anthropic 变量（`ANTHROPIC_API_KEY`、`ANTHROPIC_SERVER_URL`）指向 Anthropic 直连 API。Claude 的支持路由包括：
>
> - **Anthropic 直连 API**：`ANTHROPIC_API_KEY` 与 `ANTHROPIC_SERVER_URL`（见上文）。
> - **AWS Bedrock**：`BEDROCK_*` 相关变量（见 [AWS Bedrock 提供商配置](#aws-bedrock-provider-configuration)）。
>
> 若你当下需要使用 Vertex AI，最安全且受支持的变通方案是：通过 OpenAI 兼容代理或网关暴露 Vertex AI，将 Vertex AI 调用转换为 Chat Completions 格式，同时保留 PentAGI 所依赖的聊天与 tool-call 行为，然后通过 `LLM_SERVER_URL`、`LLM_SERVER_KEY` 与 `LLM_SERVER_MODEL` 将 Custom LLM 提供商指向该网关。此路径的可靠性取决于你所选网关。
#### 支持的模型
PentAGI 支持 10 款 Claude 模型，具备工具调用、流式输出、扩展思考、自适应思考与提示缓存。标有 `*` 的模型用于默认配置。
**Claude 4 系列 — 最新模型（2025-2026）**
| Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Use Case |
| ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- |
| `claude-opus-4-6`* | ✅ | May 2025 | $5.00/$25.00/$0.50/$6.25 | 面向自主智能体与编码的最强模型。扩展 + 自适应思考，用于复杂 exploit 开发、多阶段攻击模拟 |
| `claude-sonnet-4-6`* | ✅ | Aug 2025 | $3.00/$15.00/$0.30/$3.75 | 速度与智能的最佳平衡，具备自适应思考。多阶段安全评估、智能漏洞分析、实时威胁狩猎 |
| `claude-haiku-4-5`* | ✅ | Oct 2025 | $1.00/$5.00/$0.10/$1.25 | 速度最快、接近前沿智能的模型。高频扫描、实时监控、批量自动化测试 |
**旧版模型 — 仍受支持**
| Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Use Case |
| ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- |
| `claude-sonnet-4-5` | ✅ | Sep 2025 | $3.00/$15.00/$0.30/$3.75 | 顶尖推理能力（已被 4-6 取代）。复杂渗透测试、高级威胁分析 |
| `claude-opus-4-5` | ✅ | Nov 2025 | $5.00/$25.00/$0.50/$6.25 | 极致推理（已被 opus-4-6 取代）。关键安全研究、零日漏洞发现、红队行动 |
| `claude-opus-4-1` | ✅ | Aug 2025 | $15.00/$75.00/$1.50/$18.75 | 高级推理（已取代）。复杂渗透测试、精细威胁建模 |
| `claude-sonnet-4-0` | ✅ | May 2025 | $3.00/$15.00/$0.30/$3.75 | 高性能推理（已取代）。复杂威胁建模、多工具协同 |
| `claude-opus-4-0` | ✅ | May 2025 | $15.00/$75.00/$1.50/$18.75 | 第一代 Opus（已取代）。多步骤 exploit 开发、自主渗透测试工作流 |
**已弃用模型 — 请迁移至当前模型**
| Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Notes |
| ---------------------------- | -------- | ------------ | ------------------------------ | -------------------------------------------- |
| `claude-3-haiku-20240307` | ❌ | Mar 2024 | $0.25/$1.25/$0.03/$0.30 | 将于 2026 年 4 月 19 日停用。请迁移至 claude-haiku-4-5 |
**价格**：按每 100 万 token 计。缓存定价包含读与写成本。
**扩展思考配置**：
- **Max Tokens 4096**：Generator（claude-opus-4-6），用于复杂 exploit 开发的最大推理深度
- **Max Tokens 2048**：Coder（claude-sonnet-4-6），用于均衡的代码分析与漏洞研究
- **Max Tokens 1024**：Primary agent、assistant、refiner、adviser、reflector、searcher、installer、pentester，用于针对特定任务的聚焦推理
- **Extended Thinking**：所有 Claude 4.5+ 与 4.6 模型均支持可配置的扩展思考，用于深度推理任务
**核心特性**：
- **扩展思考（Extended Thinking）**：所有 Claude 4.5+ 与 4.6 模型，可配置思维链推理深度，用于复杂安全分析
- **自适应思考（Adaptive Thinking）**：Claude 4.6 系列（Opus/Sonnet）根据任务复杂度动态调整推理深度，以获得最佳性能
- **提示缓存（Prompt Caching）**：显著降低成本，读写分开计价（读为输入的 10%，写为输入的 125%）
- **扩展上下文窗口**：标准 200K token，Claude Opus/Sonnet 4.6 最高可达 1M token（beta），用于全面代码库分析
- **工具调用（Tool Calling）**：稳健的函数调用，精度出色，用于安全工具编排
- **流式输出（Streaming）**：实时响应流，用于交互式渗透测试工作流
- **安全优先设计**：内置安全机制，确保负责任的安全测试实践
- **多模态支持**：最新模型具备视觉能力，用于截图分析与 UI 安全评估
- **Constitutional AI**：先进安全训练，提供可靠且合乎伦理的安全指导
### Google AI（Gemini）提供商配置
PentAGI 通过 Google AI API 集成 Google 的 Gemini 模型，提供顶尖多模态推理能力，并支持扩展思考与上下文缓存。
#### 配置变量
| Variable | Default | Description |
| ------------------- | ------------------------------------------- | ------------------------------ |
| `GEMINI_API_KEY` | | Google AI 服务 API 密钥 |
| `GEMINI_SERVER_URL` | `https://generativelanguage.googleapis.com` | Google AI API 端点 |
#### 配置示例
```bash
# Basic Gemini setup
GEMINI_API_KEY=your_gemini_api_key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com
# Using with proxy
GEMINI_API_KEY=your_gemini_api_key
PROXY_URL=http://your-proxy:8080
```
#### 支持的模型
PentAGI 支持 9 款 Gemini 模型，具备工具调用（tool calling）、流式输出（streaming）、思考模式（thinking modes）和上下文缓存（context caching）能力。标记为 `*` 的模型用于默认配置。
**Gemini 3.5 系列 - 最新稳定版 Flash（2026 年 5 月）**
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemini-3.5-flash`* | ✅ | 1M | $1.50/$9.00/$0.15 | 最智能的 Flash 模型，在智能体与编码任务上持续保持前沿性能，搜索与 grounding 能力出众 |
**Gemini 3.1 系列 - 稳定版 Flash-Lite + Pro 预览版（2026 年 2 月至 5 月）**
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemini-3.1-pro-preview`* | ✅ | 1M | $2.00/$12.00/$0.20 | 最新旗舰模型，思考能力更精炼、token 效率更高，针对软件工程与智能体工作流优化 |
| `gemini-3.1-pro-preview-customtools` | ✅ | 1M | $2.00/$12.00/$0.20 | 面向 bash 与自定义工具（view_file、search_code）优先级的自定义工具端点 |
| `gemini-3.1-flash-lite`* | ✅ | 1M | $0.25/$1.50/$0.025 | 最具成本效益的稳定多模态模型，面向高吞吐量智能体任务与低延迟应用提供前沿级性能 |
**Gemini 2.5 系列 - 高级思考模型（活跃至 2026 年 10 月 16 日）**
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
| ---------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemini-2.5-pro` | ✅ | 1M | $1.25/$10.00/$0.125 | 复杂编码与推理的顶尖选择，擅长精细化威胁建模 |
| `gemini-2.5-flash` | ✅ | 1M | $0.30/$2.50/$0.03 | 首款支持思考预算（thinking budgets）的混合推理模型，大规模评估场景下性价比最佳 |
| `gemini-2.5-flash-lite` | ✅ | 1M | $0.10/$0.40/$0.01 | 体量最小、成本最低，适合大规模使用与高吞吐量扫描 |
**Gemma 4 开源模型（Apache 2.0，免费层）**
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemma-4-31b-it` | ✅ | 256K | Free/Free/Free | 最大的 Gemma 4 开源稠密模型（约 31B 参数），多模态文本+图像，支持 140+ 种语言，适用于本地部署安全运营 |
| `gemma-4-26b-a4b-it` | ✅ | 256K | Free/Free/Free | MoE 架构（总参数约 26B / 激活参数约 3.8B），在消费级 GPU 上高效推理，适合本地高吞吐量扫描 |
**价格**：按每 100 万 token 计费（Standard Paid 层）。上下文窗口为输入 token 上限。
> [!NOTE]
> **Gemini 2.5 系列下线**
>
> `gemini-2.5-pro`、`gemini-2.5-flash` 和 `gemini-2.5-flash-lite` 将于 **2026 年 10 月 16 日** **下线**。建议迁移路径：
>
> - `gemini-2.5-pro` → `gemini-3.1-pro-preview`（相同 $2.00 输入定价层）
> - `gemini-2.5-flash` → `gemini-3.5-flash`（增强的前沿能力）
> - `gemini-2.5-flash-lite` → `gemini-3.1-flash-lite`（相同 $0.25 输入定价）
**默认模型分配（config.yml）**：
- **`gemini-3.1-pro-preview`** - `primary_agent`、`assistant`、`generator`、`refiner`、`adviser`、`coder`、`pentester`
- **`gemini-3.5-flash`** - `reflector`、`searcher`、`enricher`、`installer`
- **`gemini-3.1-flash-lite`** - `simple`、`simple_json`
**核心特性**：
- **扩展思考（Extended Thinking）**：面向复杂安全分析的逐步推理（所有 Gemini 3.x、2.5 系列及 Gemma 4 均支持可切换的思考模式）
- **上下文缓存（Context Caching）**：重复上下文可显著降低成本（多数模型为输入价格的 10%）
- **超长上下文（Ultra-Long Context）**：Gemini 对话模型支持 1M token，Gemma 4 开源模型支持 256K token
- **多模态支持（Multimodal Support）**：支持文本、图像、视频、音频和 PDF 处理，便于全面评估
- **工具调用（Tool Calling）**：通过函数调用无缝集成 20+ 款渗透测试工具
- **流式输出（Streaming）**：实时响应流，适用于交互式安全工作流
- **代码执行（Code Execution）**：内置代码执行，用于攻击性工具测试与漏洞利用验证
- **搜索 Grounding（Search Grounding）**：集成 Google Search，用于威胁情报与 CVE 研究
- **文件搜索（File Search）**：文档检索与 RAG 能力，支持基于知识的评估
- **批量 API（Batch API）**：非实时批量处理可节省 50% 成本
- **自定义工具端点（Custom Tools Endpoint）**：专用 `gemini-3.1-pro-preview-customtools` 路由，面向偏好已注册工具而非 bash 的工具密集型智能体工作流
**推理力度级别（Reasoning Effort Levels）**：
- **High**：最大思考深度，适用于复杂多步分析（generator）
- **Medium**：均衡推理，适用于通用智能体任务（primary_agent、assistant、refiner、adviser）
- **Low**：高效思考，适用于聚焦型任务（coder、installer、pentester）
### AWS Bedrock 提供商配置
PentAGI 集成 Amazon Bedrock，可访问来自 Anthropic、Amazon、Cohere、DeepSeek、OpenAI、Qwen、Mistral 和 Moonshot 等领先 AI 公司的 20+ 款基础模型。
#### 配置变量
| Variable | Default | Description |
| --------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `BEDROCK_REGION` | `us-east-1` | Bedrock 服务所在的 AWS 区域 |
| `BEDROCK_DEFAULT_AUTH` | `false` | 使用 AWS SDK 默认凭证链（环境变量、EC2 角色、~/.aws/credentials）——优先级最高 |
| `BEDROCK_BEARER_TOKEN` | | Bearer token 认证——优先级高于静态凭证 |
| `BEDROCK_ACCESS_KEY_ID` | | 静态凭证的 AWS 访问密钥 ID |
| `BEDROCK_SECRET_ACCESS_KEY` | | 静态凭证的 AWS 秘密访问密钥 |
| `BEDROCK_SESSION_TOKEN` | | 临时凭证的 AWS 会话令牌（可选，与静态凭证配合使用） |
| `BEDROCK_SERVER_URL` | | 自定义 Bedrock 端点（VPC 端点、本地测试） |
**认证优先级**：`BEDROCK_DEFAULT_AUTH` → `BEDROCK_BEARER_TOKEN` → `BEDROCK_ACCESS_KEY_ID`+`BEDROCK_SECRET_ACCESS_KEY`
#### 配置示例
```bash
# Recommended: Default AWS SDK authentication (EC2/ECS/Lambda roles)
BEDROCK_REGION=us-east-1
BEDROCK_DEFAULT_AUTH=true
# Bearer token authentication (AWS STS, custom auth)
BEDROCK_REGION=us-east-1
BEDROCK_BEARER_TOKEN=your_bearer_token
# Static credentials (development, testing)
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
# With proxy and custom endpoint
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 模型。标有 `*` 的模型用于默认配置。
| Model ID | Provider | Thinking | Multimodal | Price (Input/Output) | Use Case |
| ------------------------------------------------ | --------------- | -------- | ---------- | -------------------- | --------------------------------------- |
| `us.amazon.nova-2-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.33/$2.75 | 自适应推理、高效思考 |
| `us.amazon.nova-premier-v1:0` | Amazon Nova | ❌ | ✅ | $2.50/$12.50 | 复杂推理、高级分析 |
| `us.amazon.nova-pro-v1:0` | Amazon Nova | ❌ | ✅ | $0.80/$3.20 | 准确度、速度与成本均衡 |
| `us.amazon.nova-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.06/$0.24 | 快速处理、高吞吐量操作 |
| `us.amazon.nova-micro-v1:0` | Amazon Nova | ❌ | ❌ | $0.035/$0.14 | 超低延迟、实时监控 |
| `us.anthropic.claude-opus-4-6-v1`* | Anthropic | ✅ | ✅ | $5.00/$25.00 | 世界级编码、企业级智能体 |
| `us.anthropic.claude-sonnet-4-6` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 前沿智能、企业级规模 |
| `us.anthropic.claude-opus-4-5-20251101-v1:0` | Anthropic | ✅ | ✅ | $5.00/$25.00 | 多日软件开发 |
| `us.anthropic.claude-haiku-4-5-20251001-v1:0`* | Anthropic | ✅ | ✅ | $1.00/$5.00 | 接近前沿性能、高速响应 |
| `us.anthropic.claude-sonnet-4-5-20250929-v1:0`* | Anthropic | ✅ | ✅ | $3.00/$15.00 | 真实场景智能体、卓越编码能力 |
| `us.anthropic.claude-sonnet-4-20250514-v1:0` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 性能均衡、可用于生产 |
| `us.anthropic.claude-3-5-haiku-20241022-v1:0` | Anthropic | ❌ | ❌ | $0.80/$4.00 | 最快模型、高性价比扫描 |
| `cohere.command-r-plus-v1:0` | Cohere | ❌ | ❌ | $3.00/$15.00 | 大规模操作、卓越 RAG |
| `deepseek.v3.2` | DeepSeek | ❌ | ❌ | $0.58/$1.68 | 长上下文推理、高效 |
| `openai.gpt-oss-120b-1:0`* | OpenAI (OSS) | ✅ | ❌ | $0.15/$0.60 | 强推理能力、科学分析 |
| `openai.gpt-oss-20b-1:0` | OpenAI (OSS) | ✅ | ❌ | $0.07/$0.30 | 高效编码、软件开发 |
| `qwen.qwen3-next-80b-a3b` | Qwen | ❌ | ❌ | $0.15/$1.20 | 超长上下文、旗舰级推理 |
| `qwen.qwen3-32b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | 推理均衡、研究场景 |
| `qwen.qwen3-coder-30b-a3b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | Vibe coding、自然语言优先 |
| `qwen.qwen3-coder-next` | Qwen | ❌ | ❌ | $0.45/$1.80 | 工具使用、函数调用优化 |
| `mistral.mistral-large-3-675b-instruct` | Mistral | ❌ | ✅ | $4.00/$12.00 | 高级多模态、长上下文 |
| `moonshotai.kimi-k2.5` | Moonshot | ❌ | ✅ | $0.60/$3.00 | 视觉、语言与代码一体化模型 |
**价格**：按每 100 万 token 计费。支持思考/推理的模型在推理阶段会产生额外计算成本。
#### 已测试但不兼容的模型
部分 AWS Bedrock 模型已完成测试，但由于技术限制**不受支持**：
| Model Family | Reason for Incompatibility |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| **GLM (Z.AI)** | 工具调用格式与 Converse API 不兼容（期望字符串而非 JSON） |
| **AI21 Jamba** | 严格的速率限制（1-2 req/min）导致无法可靠测试及用于生产环境 |
| **Meta Llama 3.3/3.1** | 工具调用结果处理不稳定，会在多轮工作流中引发意外失败 |
| **Mistral Magistral** | 模型不支持工具调用 |
| **Moonshot K2-Thinking** | 带工具调用的流式输出行为不稳定，在生产环境中不可靠 |
| **Qwen3-VL** | 带工具调用的流式输出不稳定，多模态与工具组合会间歇性失败 |
> [!IMPORTANT]
> **速率限制与配额管理**
>
> Claude 模型的默认 AWS Bedrock 配额**极其严格**（新账户为 2-20 requests/minute）。用于生产级渗透测试时：
>
> 1. **申请提高配额**——通过 AWS Service Quotas 控制台为计划使用的模型提交配额提升申请
> 2. **使用 Amazon Nova 模型**——默认配额更高，性能出色
> 3. **启用预置吞吐量（provisioned throughput）**——用于稳定的高吞吐量测试
> 4. **监控用量**——达到配额上限时 AWS 会进行激进限流
>
> 若不提高配额，预计会出现频繁延迟和工作流中断。
> [!WARNING]
> **Converse API 要求**
>
> PentAGI 使用 Amazon Bedrock **Converse API** 实现统一模型访问。所有受支持的模型均需满足：
>
> - ✅ 支持 Converse/ConverseStream API
> - ✅ 支持工具使用（function calling），用于渗透测试工作流
> - ✅ 支持流式工具使用，以实现实时反馈
>
> 请在以下地址核实模型能力：[AWS Bedrock Model Features](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html)
**核心特性**：
- **自动提示缓存（Automatic Prompt Caching）**：重复上下文成本降低 40-70%（Claude 4.x 模型）
- **扩展思考（Extended Thinking）**：针对复杂安全分析的逐步推理（Claude、DeepSeek R1、OpenAI GPT）
- **多模态分析（Multimodal Analysis）**：处理截图、图表、视频以进行全面测试（Nova、Claude、Mistral、Kimi）
- **工具调用（Tool Calling）**：通过函数调用与 20+ 渗透测试工具无缝集成
- **流式输出（Streaming）**：实时响应流，适用于交互式安全评估工作流
### DeepSeek 提供商配置
PentAGI 集成 DeepSeek，以具有竞争力的价格提供先进 AI 模型访问，具备强推理能力、编码能力以及上下文缓存。
#### 配置变量
| Variable | Default Value | Description |
| --------------------- | -------------------------- | --------------------------------------------------- |
| `DEEPSEEK_API_KEY` | | 用于身份验证的 DeepSeek API 密钥 |
| `DEEPSEEK_SERVER_URL` | `https://api.deepseek.com` | DeepSeek API 端点 URL |
| `DEEPSEEK_PROVIDER` | | 用于 LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```bash
# Direct API usage
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com
# With LiteLLM proxy
DEEPSEEK_API_KEY=your_litellm_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek # Adds prefix to model names (deepseek/deepseek-v4-flash) for LiteLLM
```
#### 支持的模型
PentAGI 支持 2 款 DeepSeek V4 模型，具备工具调用（tool calling）、流式输出（streaming）、混合思考/非思考模式以及上下文缓存（context caching）能力。两款模型默认启用思考模式，可通过 `extra_body` 切换为非思考模式。标有 `*` 的模型用于默认配置。
| Model ID | Thinking | Max Output | Context | Price (Input/Output/Cache) | Use Case |
| --------------------- | -------- | ---------- | ------- | -------------------------- | ---------------------------------------------------- |
| `deepseek-v4-flash`* | ✅ hybrid | 384K | 1M | $0.14/$0.28/$0.0028 | 实用型智能体、通用对话、快速工具调用 |
| `deepseek-v4-pro`* | ✅ hybrid | 384K | 1M | $1.74/$3.48/$0.0145 | 高级推理、复杂逻辑、安全分析 |
**价格**：按每 100 万 token 计费。缓存定价适用于从缓存提供的提示词 token（输入缓存命中，自 2026-04-26 起降至首发价格的 1/10）。两款模型均支持混合思考——默认启用 `thinking` 模式；传入 `extra_body.thinking.type: disabled` 可切换为非思考模式，以获得更快、更便宜的响应。
> **定价说明（deepseek-v4-pro）**：`deepseek-v4-pro` 的 75% 促销折扣已于 2026-05-31 15:59 UTC 正式结束。上表价格为促销结束后的标准定价。若你仍使用旧配置中的折扣价（$0.435/$0.87/$0.003625），请更新为当前费率，以便准确追踪成本。
> 旧版模型名称 `deepseek-chat` 和 `deepseek-reasoner` 已由 DeepSeek 计划于 2026-07-24 弃用。
> 引用这些旧名称的现有用户配置在此之前仍可正常使用；上表默认配置使用当前 V4 名称。`deepseek-chat` 映射至 `deepseek-v4-flash`
> 非思考模式；`deepseek-reasoner` 映射至 `deepseek-v4-flash` 思考模式。
**默认智能体配置**：
策略：优先将 `deepseek-v4-flash`（输入便宜 12 倍、输出便宜 12 倍）作为实用型/轻量级智能体的主力；将 `deepseek-v4-pro` 保留给复杂的多步推理任务。`installer` 智能体在 Flash 上运行并启用思考模式，因为环境搭建任务（shell 命令、配置编辑）通常不需要 Pro 级推理能力。在将更多智能体升级为 Pro 之前，请针对自身工作负载进行 A/B 测试。
| Agent Role | Default Model | Thinking | Reasoning Effort | Max Output | Temperature | Top P |
| ------------------------------------------- | -------------------- | -------- | ---------------- | ---------- | ----------- | ----- |
| Generator / Refiner | `deepseek-v4-pro` | Enabled | High | 32768 | (auto) | (auto) |
| Coder | `deepseek-v4-pro` | Enabled | High | 20480 | (auto) | (auto) |
| Primary Agent / Assistant / Pentester | `deepseek-v4-pro` | Enabled | High | 16384 | (auto) | (auto) |
| Adviser (mentor/planner) | `deepseek-v4-pro` | Enabled | High | 8192 | (auto) | (auto) |
| Installer | `deepseek-v4-flash` | Enabled | High | 12288 | (auto) | (auto) |
| Reflector / Searcher / Enricher | `deepseek-v4-flash` | Disabled | — | 4096 | 0.5 | 0.9 |
| Simple / Simple JSON | `deepseek-v4-flash` | Disabled | — | 2048 | 0.3 | 0.9 |
> **说明**：启用思考模式时，DeepSeek 会静默忽略 `temperature`、`top_p`、`presence_penalty` 和 `frequency_penalty`。当设置 `reasoning_effort` 时，langchaingo 客户端会自动将 `temperature`/`top_p` 置空，因此上表中显示为 "(auto)"。所有启用思考的智能体还会显式传入 `extra_body.thinking.type: enabled`，作为防御性编码，以应对未来提供商默认设置的变更。
**核心特性**：
- **混合思考模式（Hybrid Thinking Modes）**：通过 `extra_body.thinking.type` 在思考模式（深度推理）与非思考模式（快速响应）之间切换
- **自动提示词缓存（Automatic Prompt Caching）**：通过缓存命中定价（首发价格的 1/10）显著降低重复上下文的成本
- **扩展思考（Extended Thinking）**：面向复杂安全分析的强化学习 CoT（两款 V4 模型均支持）
- **强编码能力（Strong Coding）**：针对代码生成与漏洞利用开发进行优化
- **长上下文（Long Context）**：100 万 token 上下文窗口，最多 384K 输出 token
- **工具调用（Tool Calling）**：通过函数调用与 20+ 渗透测试工具无缝集成
- **流式输出（Streaming）**：为交互式工作流提供实时响应流
- **多语言（Multilingual）**：强大的中英文支持
- **其他特性（Additional Features）**：JSON 输出、Chat Prefix Completion（beta）、FIM/Fill-in-the-Middle Completion（仅非思考模式）
**并发限制**：`deepseek-v4-flash`：2500 个并发请求；`deepseek-v4-pro`：500 个并发请求。
**LiteLLM 集成**：设置 `DEEPSEEK_PROVIDER=deepseek` 可在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。直连 API 使用时请留空。
### GLM 提供商配置
PentAGI 集成智谱 AI（Z.AI）的 GLM，提供由清华大学开发、采用 MoE 架构、具备强推理与智能体能力的高级语言模型。
#### 配置变量
| Variable | Default Value | Description |
| ----------------- | ------------------------------- | ---------------------------------------------------------- |
| `GLM_API_KEY` | | 用于身份验证的 GLM API 密钥 |
| `GLM_SERVER_URL` | `https://api.z.ai/api/paas/v4` | GLM API 端点 URL（国际版） |
| `GLM_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```bash
# Direct API usage (international endpoint)
GLM_API_KEY=your_glm_api_key
GLM_SERVER_URL=https://api.z.ai/api/paas/v4
# Alternative endpoints
GLM_SERVER_URL=https://open.bigmodel.cn/api/paas/v4 # China
GLM_SERVER_URL=https://api.z.ai/api/coding/paas/v4 # Coding-specific
# With LiteLLM proxy
GLM_API_KEY=your_litellm_key
GLM_SERVER_URL=http://litellm-proxy:4000
GLM_PROVIDER=zai # Adds prefix to model names (zai/glm-4) for LiteLLM
```
#### 支持的模型
PentAGI 支持 13 款 GLM 模型，具备工具调用、流式输出、混合思考模式以及提示词缓存能力。标有 `*` 的模型用于默认配置。思考模式通过 `extra_body.thinking.type`（"enabled"/"disabled"）控制；与 Kimi 不同，GLM 在两种模式下对 temperature 的限制都较为宽松。
**GLM-5.x 系列 - 最新一代（200K 上下文，128K 最大输出）**
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
| ---------------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------------------------- |
| `glm-5.1`* | ✅ Hybrid | 200K | 128K | $1.40/$4.40/$0.26 | 最新旗舰：8 小时持续自主执行，对齐 Claude Opus 4.6（generator/refiner/adviser/coder/pentester 默认） |
| `glm-5` | ✅ Hybrid | 200K | 128K | $1.00/$3.20/$0.20 | 智能体工程（Agentic Engineering）基座，MoE 744B/40B active，Claude Opus 4.5 级编码能力 |
| `glm-5-turbo`* | ✅ Hybrid | 200K | 128K | $1.20/$4.00/$0.24 | OpenClaw 原生：针对工具调用、持久化任务、长链执行优化（primary_agent/assistant 默认） |
**GLM-4.7 系列 - 高级版，支持交错思考（Interleaved Thinking）**
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
| ----------------- | -------- | ------- | ---------- | -------------------------- | --------------------------------------------------- |
| `glm-4.7` | ✅ Hybrid | 200K | 128K | $0.60/$2.20/$0.11 | 增强编程能力，稳定的多步推理 |
| `glm-4.7-flashx` | ✅ Hybrid | 200K | 128K | $0.07/$0.40/$0.01 | 超低价且享有优先 GPU，但 RPM 限制较低（不适合高频使用） |
| `glm-4.7-flash` | ✅ Hybrid | 200K | 128K | Free/Free/Free | 免费约 30B SOTA 模型，1 个并发请求 |
**GLM-4.6 系列 - 均衡型，支持自动思考（Auto-Thinking）**
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
| --------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------- |
| `glm-4.6` | ✅ Auto | 200K | 128K | $0.60/$2.20/$0.11 | 均衡型、流式工具调用、省 token |
**GLM-4.5 系列 - 统一推理/编码/智能体**
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
| ---------------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------- |
| `glm-4.5` | ✅ Auto | 128K | 96K | $0.60/$2.20/$0.11 | 统一型，MoE 355B/32B 激活参数 |
| `glm-4.5-x` | ✅ Auto | 128K | 96K | $2.20/$8.90/$0.45 | 超快高端版，最低延迟 |
| `glm-4.5-air`* | ✅ Auto | 128K | 96K | $0.20/$1.10/$0.03 | 高性价比 MoE 106B/12B（simple/simple_json/reflector/searcher/enricher/installer 默认） |
| `glm-4.5-airx` | ✅ Auto | 128K | 96K | $1.10/$4.50/$0.22 | 加速版 Air，优先 GPU |
| `glm-4.5-flash` | ✅ Auto | 128K | 96K | Free/Free/Free | 免费，支持推理/编码/智能体 |
**GLM-4 旧版 - 稠密架构（Dense Architecture）**
| Model ID | Thinking | Context | Max Output | Price (Input/Output) | Use Case |
| --------------------- | -------- | ------- | ---------- | -------------------- | --------------------------------------------- |
| `glm-4-32b-0414-128k` | ❌ | 128K | 16K | $0.10/$0.10 | 超低成本稠密 32B，无推理的解析任务 |
**价格**：按每 100 万 token 计费。缓存价格为提示词缓存命中价格；根据 Z.AI 促销，缓存存储目前免费。GLM-4-32B 不支持缓存。
**默认智能体配置**：
策略：关键推理使用 `glm-5.1`（最新旗舰，输入 $1.40），编排使用 `glm-5-turbo`（OpenClaw 原生、面向智能体优化），所有 utility/installer 智能体使用 `glm-4.5-air`（低价 MoE，支持混合思考且 RPM 稳定）。由于 RPM 限制较低，高频调用时易出现 429 错误，默认配置避免使用 `glm-4.7-flashx`。
| Agent Role | Default Model | Thinking | Temperature | Top P | Max Output |
| ----------------------------------- | ------------- | -------- | ----------- | ----- | ---------- |
| 生成器 / 精炼器 | `glm-5.1` | 启用 | 1.0 | 0.95 | 32768 |
| 编码器 | `glm-5.1` | 启用 | 1.0 | 0.95 | 20480 |
| 顾问 / 渗透测试 | `glm-5.1` | 启用 | 1.0 | 0.95 | 16384 |
| 主智能体 / 助手 | `glm-5-turbo` | 启用 | 1.0 | 0.95 | 16384 |
| 安装器 | `glm-4.5-air` | 启用 | 1.0 | 0.95 | 16384 |
| Simple / Reflector | `glm-4.5-air` | 禁用 | 0.6 | 0.9 | 8192 |
| 搜索器 / 增强器 / Simple JSON | `glm-4.5-air` | 禁用 | 0.6 | 0.9 | 4096 |
> **关于 temperature 的说明**：根据 Z.AI 文档，GLM 在思考/非思考模式下均接受 `1.0` 和 `0.6`。langchaingo 的 `IsReasoningModel` 会匹配 `glm-4.5*`/`glm-4.6*`/`glm-4.7*` 前缀，并在 `createChatRequest` 中强制将 temperature 覆盖为 1.0——这对 GLM 无害（与 Kimi 不同），但意味着这些模型在 YAML 中的 temperature 值仅供参考。`glm-5`/`glm-5.1`/`glm-5-turbo` 不会被匹配，因此显式设置的值会原样传递。
**思考模式**：
- **Hybrid（混合）**（GLM-5.x、GLM-4.7）：通过 `extra_body.thinking.type` 显式切换
- **Auto（自动）**（GLM-4.6、GLM-4.5 系列）：模型自动判断何时需要推理
- **Preserved Thinking（保留思考）**（Z.AI Coding 能力）：PentAGI 中所有启用思考的智能体也会传递 `extra_body.thinking.clear_thinking: false`，以便在对话中保留先前助手轮次的 `reasoning_content`。这在标准 API 端点（`/api/paas/v4`）上是必需的——在 Coding Plan 端点上默认启用。可提升多轮工具调用链中的推理连续性和缓存命中率。
- 所有启用思考的智能体也会出于防御性目的传递 `extra_body.tool_choice: auto`
**核心特性**：
- **长程任务（Long-Horizon Tasks）**：GLM-5.1 支持最长 8 小时的持续自主执行，适合复杂的多阶段智能体工作流
- **OpenClaw 原生编排**：GLM-5-Turbo 专门针对工具调用、指令遵循和长链执行进行了优化
- **提示词缓存（Prompt Caching）**：重复上下文可显著降低成本（表中已列出缓存输入价格）
- **超长上下文**：GLM-5.x/4.7/4.6 系列支持 200K token
- **MoE 架构**：高效 744B/40B 激活参数（GLM-5/5.1）、355B/32B（GLM-4.5）、106B/12B（GLM-4.5-Air）
- **工具调用（Tool Calling）**：通过 function calling 与 20+ 渗透测试工具无缝集成
- **流式输出（Streaming）**：实时流式输出，支持流式工具调用（GLM-4.6+）
- **多语言**：出色的中英文 NLP 能力
- **免费选项**：GLM-4.7-Flash 和 GLM-4.5-Flash 可用于原型开发与实验
**LiteLLM 集成**：将 `GLM_PROVIDER=zai` 设置为启用模型名前缀，以便在使用 LiteLLM 代理的默认 PentAGI 配置时生效。直接调用 API 时请留空。
### Kimi 提供商配置
PentAGI 集成 Moonshot AI 的 Kimi，提供具备多模态能力的超长上下文模型，非常适合分析大型代码库和文档。
#### 配置变量
| Variable | Default Value | Description |
| ------------------ | -----------------------------| --------------------------------------------------- |
| `KIMI_API_KEY` | | Kimi API 密钥，用于身份验证 |
| `KIMI_SERVER_URL` | `https://api.moonshot.ai/v1` | Kimi API 端点 URL（国际版） |
| `KIMI_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```bash
# Direct API usage (international endpoint)
KIMI_API_KEY=your_kimi_api_key
KIMI_SERVER_URL=https://api.moonshot.ai/v1
# Alternative endpoint
KIMI_SERVER_URL=https://api.moonshot.cn/v1 # China
# With LiteLLM proxy
KIMI_API_KEY=your_litellm_key
KIMI_SERVER_URL=http://litellm-proxy:4000
KIMI_PROVIDER=moonshot # Adds prefix to model names (moonshot/kimi-k2.5) for LiteLLM
```
#### 支持的模型
PentAGI 支持 8 个具备工具调用、流式输出、混合思考模式及多模态能力（K2.x 支持文本/图像/视频）的 Kimi/Moonshot 模型。所有 `kimi-k2-*` 旧版模型（turbo-preview、0905-preview、0711-preview、thinking、thinking-turbo）已于 2026-05-25 被 Moonshot 弃用，未包含在内。标记为 `*` 的模型用于默认配置。
**Kimi K2.x 系列 - 多模态旗舰**
| Model ID | Thinking | Multimodal | Context | Price (Input Miss / Output / Cache Hit) | Use Case |
| ---------------- | -------- | ---------- | ------- | --------------------------------------- | ------------------------------------------------------- |
| `kimi-k2.6`* | ✅ hybrid | ✅ | 256K | $0.95 / $4.00 / $0.16 | 最新旗舰：原生多模态、更强代码能力、指令遵从性更佳（generator/refiner/adviser/coder/pentester 默认） |
| `kimi-k2.5`* | ✅ hybrid | ✅ | 256K | $0.60 / $3.00 / $0.10 | 上一代：输入价格低 36%，架构相同（primary/assistant/installer/utility 默认） |
**Moonshot V1 系列 - 生成模型（灵活参数）**
| Model ID | Thinking | Multimodal | Context | Price (Input / Output) | Use Case |
| ------------------- | -------- | ---------- | ------- | ---------------------- | ---------------------------------------------- |
| `moonshot-v1-8k` | ❌ | ❌ | 8K | $0.20 / $2.00 | 短文本生成，超低成本 |
| `moonshot-v1-32k` | ❌ | ❌ | 32K | $1.00 / $3.00 | 长文本生成 |
| `moonshot-v1-128k` | ❌ | ❌ | 128K | $2.00 / $5.00 | 超长上下文 |
**Moonshot V1 Vision 系列 - 图像理解**
| Model ID | Thinking | Multimodal | Context | Price (Input / Output) | Use Case |
| --------------------------------- | -------- | ---------- | ------- | ---------------------- | --------------------------------------- |
| `moonshot-v1-8k-vision-preview` | ❌ | ✅ | 8K | $0.20 / $2.00 | 视觉 + 短上下文 |
| `moonshot-v1-32k-vision-preview` | ❌ | ✅ | 32K | $1.00 / $3.00 | 视觉 + 中等上下文 |
| `moonshot-v1-128k-vision-preview` | ❌ | ✅ | 128K | $2.00 / $5.00 | 视觉 + 长上下文 |
**价格**：按每 100 万 token 计费。缓存定价适用于从自动上下文缓存（automatic context cache）提供的提示 token（仅 Kimi K2.x 模型支持缓存）。
> **重要 — Kimi K2.6/K2.5 参数约束**：API 对任何偏离将返回 `invalid_request_error`：
> - `temperature`：在 thinking 模式下 MUST 为 `1.0`，在非 thinking 模式下 MUST 为 `0.6`
> - `top_p`：MUST 为 `0.95`
> - `n`：MUST 为 `1`
> - `presence_penalty` 与 `frequency_penalty`：MUST 为 `0`（不可修改）
>
> Moonshot V1 模型使用标准 OpenAI 兼容参数，无此类约束。
**默认 Agent 配置**：
策略：优先选用 `kimi-k2.5` 作为高性价比主力模型（输入成本比 `kimi-k2.6` 低 36%）；将 `kimi-k2.6` 保留给关键推理任务。所有 `kimi-k2.x` agent 均配置 API 要求的固定参数（temp/top_p/n）及显式 `extra_body.thinking.type`。对于启用 thinking 的 agent，`extra_body.thinking.keep: "all"` 设置为在多轮工具调用链中保留历史 `reasoning_content`（若无此设置，Moonshot 将返回 "thinking is enabled but reasoning_content is missing"）。
| Agent Role | Default Model | Thinking | Temperature | Top P | Max Output |
| -------------------------------------------- | ------------- | -------- | ----------- | ----- | ---------- |
| Generator / Refiner | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 32768 |
| Coder | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 20480 |
| Pentester | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 16384 |
| Adviser (mentor/planner) | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 8192 |
| Primary Agent / Assistant | `kimi-k2.5` | Enabled (keep=all) | 1.0 | 0.95 | 16384 |
| Installer | `kimi-k2.5` | Enabled (keep=all) | 1.0 | 0.95 | 12288 |
| Reflector / Searcher / Enricher | `kimi-k2.5` | Disabled | 0.6 | 0.95 | 4096 |
| Simple / Simple JSON | `kimi-k2.5` | Disabled | 0.6 | 0.95 | 2048 |
**核心特性**：
- **超长上下文（Ultra-Long Context）**：最高 256K token（K2.x），适用于全面的代码库/文档分析
- **原生多模态（Native Multimodal）**：K2.6/K2.5 开箱即用地支持文本 + 图像 + 视频输入
- **混合思考（Hybrid Thinking）**：K2.6/K2.5 可通过 `extra_body.thinking.type` 在 thinking 与非 thinking 模式间切换
- **思考内容保留（Preserved Thinking）**（K2.6）：`thinking.keep: "all"` 在多轮对话中保留历史 `reasoning_content` — 多轮工具调用链所必需
- **自动上下文缓存（Automatic Context Caching）**：K2.x 模型缓存重复前缀（K2.6 约为未命中价格的 ~17%，K2.5 约为 ~17%）
- **工具调用（Tool Calling）**：K2.x 与 Moonshot V1 全面支持 function-calling
- **自我纠错（Self-Correction）**：K2.6 具备更强的指令遵循与自我纠错能力
- **多语言（Multilingual）**：强大的中文、英文及多语言支持
**Thinking + 工具调用的多轮对话**：PentAGI 的通用推理保留模式（`TextPartWithReasoning` + `WithPreserveReasoningContent`）自动确保按所需的 TextContent → ToolCall 顺序回传 `reasoning_content`，满足 Moonshot 对 "thinking is enabled but reasoning_content is missing in assistant tool call message" 的要求。
**LiteLLM 集成**：将 `KIMI_PROVIDER=moonshot` 设置为在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。直连 API 使用时留空即可。
### Qwen 提供商配置
PentAGI 集成阿里云百炼（DashScope）的 Qwen，提供具备推理能力与上下文缓存支持的强大多语言模型。
#### 配置变量
| Variable | Default Value | Description |
| ------------------ | ------------------------------------------------------ | --------------------------------------------------- |
| `QWEN_API_KEY` | | 用于身份验证的 Qwen API 密钥 |
| `QWEN_SERVER_URL` | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` | Qwen API 端点 URL（国际版） |
| `QWEN_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```bash
# Direct API usage (Global/US endpoint)
QWEN_API_KEY=your_qwen_api_key
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1
# Alternative endpoints
QWEN_SERVER_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1 # International (Singapore)
QWEN_SERVER_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # Chinese Mainland (Beijing)
# With LiteLLM proxy
QWEN_API_KEY=your_litellm_key
QWEN_SERVER_URL=http://litellm-proxy:4000
QWEN_PROVIDER=dashscope # Adds prefix to model names (dashscope/qwen-plus) for LiteLLM
```
#### 支持的模型
PentAGI 支持 33 款为 agent 工作流精选的 Qwen 模型：文本推理、代码生成及视觉语言（浏览器截图）。所有模型均为非快照主别名，支持工具调用、流式输出、thinking 模式及上下文缓存。标记有 `*` 的模型用于默认配置。
**旗舰模型（顶级推理）**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3.7-max`* | ✅ | ✅ | ✅ | ✅ | $2.50/$7.50/$0.50 | 面向 agent 时代的新一代旗舰（generator/refiner/adviser 默认） |
| `qwen3.6-max-preview` | ✅ | ✅ | ✅ | ✅ | $1.30/$7.80/$0.13 | 预览版 Max，增强 vibe coding 与前端技能 |
| `qwen3-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$6.00/$0.24 | 上一代旗舰，具备 agent 编程升级 |
| `qwen-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$4.00/$0.08 | 基于 Qwen3 的 Plus，可切换 thinking 模式 |
**均衡 Plus 模型（中档）**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3.6-plus`* | ✅ | ✅ | ✅ | ✅ | $0.50/$3.00/$0.05 | 原生 VL Plus，具备 agentic coding（primary/assistant/pentester 默认） |
| `qwen3.5-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$2.40/$0.04 | 上一代原生 VL，多模态能力强劲 |
**快速 Flash 模型（成本优化）**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3.6-flash` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.50/$0.025 | 最新 Flash，显著增强 agentic 编码能力 |
| `qwen3.5-flash`* | ✅ | ✅ | ✅ | ✅ | $0.10/$0.40/$0.01 | 超快轻量（simple/reflector/searcher/enricher 默认） |
| `qwen-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | Qwen3 系列 Flash，1M 上下文，阶梯定价 |
**代码专用模型**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3-coder-plus`* | ❌ | ✅ | ✅ | ✅ | $1.00/$5.00/$0.20 | 强力编码智能体，支持自主编程（coder 默认） |
| `qwen3-coder-flash`* | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/$0.06 | 快速代码生成，多轮工具调用稳定（installer 默认） |
| `qwen3-coder-next` | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/— | 开源代码生成，同规模 SOTA |
**视觉语言模型（浏览器与截图分析）**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3-vl-plus` | ✅ | ✅ | ✅ | ✅ | $0.20/$1.60/$0.04 | 具备视觉智能体能力的 VL，超长视频理解 |
| `qwen3-vl-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | 小型 VL，2D/3D 定位，用于浏览器分流 |
| `qvq-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$4.80/— | 视觉推理，支持思维链（chain-of-thought） |
**开源 Qwen3.6 系列**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3.6-27b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | 混合架构原生 VL，支持本地部署 |
| `qwen3.6-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.49/— | 高效 35B MoE（约 3B 活跃参数），适合持续监控 |
**开源 Qwen3.5 系列**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3.5-397b-a17b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | 最大 397B 参数（约 17B 活跃），卓越推理能力 |
| `qwen3.5-122b-a10b` | ✅ | ✅ | ✅ | ✅ | $0.40/$3.20/— | 大型 122B 参数（约 10B 活跃），强劲均衡 |
| `qwen3.5-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$2.00/— | 高效 35B MoE（约 3B 活跃参数），性价比高 |
| `qwen3.5-27b` | ✅ | ✅ | ✅ | ✅ | $0.30/$2.40/— | 中型 27B，混合线性注意力 + 稀疏 MoE |
**开源 Qwen3 Coder 系列**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ------------------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3-coder-480b-a35b-instruct` | ❌ | ✅ | ✅ | ✅ | $1.50/$7.50/— | 最大开源 Coder MoE（480B/约 35B 活跃） |
| `qwen3-coder-30b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.45/$2.25/— | 高效 30B MoE（约 3B 活跃参数），仓库级规模 |
**开源 Qwen3 Dense 与 MoE 系列**
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
| ------------------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
| `qwen3-next-80b-a3b-thinking` | ✅ | ✅ | ✅ | ✅ | $0.15/$1.20/— | 下一代 80B MoE（约 3B 活跃参数），仅思考模式 |
| `qwen3-next-80b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.15/$1.20/— | 下一代 80B MoE，指令遵循 |
| `qwen3-235b-a22b` | ✅ | ✅ | ✅ | ✅ | $0.70/$8.40/— | 双模式 235B MoE（约 22B 活跃） |
| `qwen3-32b` | ✅ | ✅ | ✅ | ✅ | $0.16/$0.64/— | 多功能 32B dense 双模式 |
| `qwen3-30b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.20/$2.40/— | 高效 30B MoE（约 3B 活跃参数） |
| `qwen3-14b` | ✅ | ✅ | ✅ | ✅ | $0.35/$4.20/— | 中型 14B dense，性能与成本均衡 |
| `qwen3-8b` | ✅ | ✅ | ✅ | ✅ | $0.18/$2.10/— | 紧凑 8B dense，高效 |
| `qwen3-4b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 轻量 4B dense，适合简单任务 |
| `qwen3-1.7b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 超紧凑 1.7B，基础检查 |
| `qwen3-0.6b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 最小 0.6B，边缘监控 |
**价格**：按每 100 万 token 计费。缓存价格反映隐式缓存命中（如可用）；MoE/dense 开源模型不提供缓存定价。阶梯模型（Max/Plus）显示最低档价格（通常 ≤32k 或 ≤256k 输入）；更大上下文按阿里云定价收取更高费率。
**区域可用性**：
- **Intl**（国际）：新加坡区域（`dashscope-intl.aliyuncs.com`）
- **Global/US**：美国弗吉尼亚区域（`dashscope-us.aliyuncs.com`）
- **China**：中国大陆北京区域（`dashscope.aliyuncs.com`）
**默认智能体配置**：
| Agent Role | Default Model | Tier |
| ------------------------------------------------ | -------------------- | --------- |
| Generator / Refiner / Adviser（规划、导师） | `qwen3.7-max` | Flagship |
| Primary / Assistant / Pentester | `qwen3.6-plus` | Balanced |
| Coder（漏洞利用开发） | `qwen3-coder-plus` | Code+ |
| Installer（环境配置） | `qwen3-coder-flash` | Code Fast |
| Simple / Reflector / Searcher / Enricher | `qwen3.5-flash` | Fast |
**核心特性**：
- **以 Agent 为中心的设计**：Qwen3.7-Max 专为长周期自主执行与工具调用而打造
- **自动上下文缓存（Automatic Context Caching）**：通过隐式缓存，在重复上下文场景下可降低 30-50% 成本
- **扩展思考（Extended Thinking）**：面向复杂安全分析的链式思维推理（Qwen3.7/3.6/3.5/3-Max、QVQ-Max）
- **代码专精**：Qwen3-Coder 系列支持多轮工具交互与仓库级理解
- **视觉-语言（Vision-Language）**：Qwen3-VL 系列适用于浏览器截图分诊、2D/3D 定位、OCR 级分析
- **工具调用（Tool Calling）**：通过 function calling 与 20+ 款渗透测试工具无缝集成
- **流式输出（Streaming）**：为交互式工作流提供实时响应流
- **多语言（Multilingual）**：对中文、英文及多种语言有良好支持
- **开源变体（Open-Source Variants）**：提供 0.6B 至 480B 的 Dense 与 MoE 模型，适用于本地部署/气隙（air-gapped）环境
**LiteLLM 集成**：将 `QWEN_PROVIDER=dashscope` 设置为在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。若直接调用 API，请留空。
#### 其他集成方式
DashScope 完全兼容 OpenAI，因此 Qwen 也可通过标准 OpenAI 客户端为 PentAGI 的另外两个子系统提供能力。
**作为嵌入（embedding）提供方**（`text-embedding-v4`，参见 [Alibaba Cloud Model Studio 定价](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=prices)):
```bash
EMBEDDING_PROVIDER=openai
EMBEDDING_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1 # International (Singapore)
# EMBEDDING_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # Chinese Mainland
EMBEDDING_KEY=sk-*******
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_BATCH_SIZE= # optional, default applies
EMBEDDING_STRIP_NEW_LINES= # optional, default applies
```
> 注意：Global/US DashScope 端点（`dashscope-us.aliyuncs.com`）**不**提供 embedding API —— 请使用 International 或 China 端点以配置 `text-embedding-v4`。
**作为 OpenAI 类型的自定义 LLM 提供方**：无需使用专用的 `QWEN_*` 变量，可将任意 Qwen 对话模型通过 PentAGI 的自定义 OpenAI 兼容提供方接入：将 `OPENAI_SERVER_URL`（或自定义 provider 条目）指向 DashScope 的 `/compatible-mode/v1` 端点，并选择所需的 Qwen 模型名称。适用于你已通过单一 OpenAI 形态客户端统一管理全部模型流量（例如与 LiteLLM/OneAPI 代理共用）的场景。
## 高级配置
### Langfuse 集成
Langfuse 为监控与分析 AI Agent 运行提供高级能力。
1. 在现有的 `.env` 文件中配置 Langfuse 环境变量。
Langfuse 重要环境变量
### 数据库凭据
- `LANGFUSE_POSTGRES_USER` 与 `LANGFUSE_POSTGRES_PASSWORD` - Langfuse PostgreSQL 凭据
- `LANGFUSE_CLICKHOUSE_USER` 与 `LANGFUSE_CLICKHOUSE_PASSWORD` - ClickHouse 凭据
- `LANGFUSE_REDIS_AUTH` - Redis 密码
### 加密与安全密钥
- `LANGFUSE_SALT` - Langfuse Web UI 中用于哈希的盐值
- `LANGFUSE_ENCRYPTION_KEY` - 加密密钥（32 字节十六进制）
- `LANGFUSE_NEXTAUTH_SECRET` - NextAuth 密钥
### 管理员凭据
- `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱
- `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码
- `LANGFUSE_INIT_USER_NAME` - 管理员用户名
### API 密钥与令牌
- `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` - 项目公钥（PentAGI 侧也会使用）
- `LANGFUSE_INIT_PROJECT_SECRET_KEY` - 项目私钥（PentAGI 侧也会使用）
### S3 存储
- `LANGFUSE_S3_ACCESS_KEY_ID` - S3 访问密钥 ID
- `LANGFUSE_S3_SECRET_ACCESS_KEY` - S3 秘密访问密钥
2. 在 `.env` 文件中为 PentAGI 服务启用 Langfuse 集成。
```bash
LANGFUSE_BASE_URL=http://langfuse-web:3000
LANGFUSE_PROJECT_ID= # default: value from ${LANGFUSE_INIT_PROJECT_ID}
LANGFUSE_PUBLIC_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY}
LANGFUSE_SECRET_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_SECRET_KEY}
```
3. 启动 Langfuse 栈：
```bash
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](http://localhost:4000) 以使用 `.env` 文件中的凭据登录 Langfuse Web UI：
- `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱
- `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码
### 监控与可观测性
如需详细跟踪系统运行，可集成监控工具。
1. 在 `.env` 文件中为 PentAGI 启用 OpenTelemetry 及全部可观测性服务集成。
```bash
OTEL_HOST=otelcol:8148
```
2. 启动可观测性栈：
```bash
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](http://localhost:3000) 以打开 Grafana Web UI。
> [!NOTE]
> 若要将可观测性栈与 Langfuse 一起使用，需在 `.env` 文件中启用集成，将 `LANGFUSE_OTEL_EXPORTER_OTLP_ENDPOINT` 设置为 `http://otelcol:4318`。
>
> 要同时运行所有可用栈（Langfuse、Graphiti 与 Observability）：
>
> ```bash
> docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d
> ```
>
> 你也可以在 shell 中为这些命令注册别名以便更快执行：
>
> ```bash
> 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）
> [!IMPORTANT]
> Graphiti 集成目前为 **beta** 功能，存在明显的提供方限制。在生产环境启用前，请参阅下文 [当前限制](#current-limitations)。
PentAGI 与 [Graphiti](https://github.com/vxcontrol/pentagi-graphiti), 集成 —— 这是一个由 Neo4j 驱动的时序知识图谱系统，可为 AI Agent 运行提供高级语义理解与关系追踪。vxcontrol 分支提供了针对渗透测试场景的自定义实体与边类型。
#### 什么是 Graphiti？
Graphiti 会自动从 Agent 交互中提取并存储结构化知识，构建实体、关系与时序上下文的图谱。由此可实现：
- **语义记忆（Semantic Memory）**：存储并回忆工具、目标、漏洞与技术之间的关联
- **上下文理解（Contextual Understanding）**：追踪不同渗透测试操作如何随时间相互关联
- **知识复用（Knowledge Reuse）**：从过往渗透测试中学习，并将洞察应用于新评估
- **高级查询（Advanced Querying）**：搜索复杂模式，例如「哪些工具对类似目标有效？」
#### 启用 Graphiti
Graphiti 知识图谱为**可选**功能，默认关闭。启用步骤：
1. 在 `.env` 文件中配置 Graphiti 环境变量：
```bash
## Graphiti knowledge graph settings
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_MODEL_NAME=gpt-5-mini
# Neo4j settings (used by Graphiti stack)
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687
# OpenAI API key (required by Graphiti for entity extraction)
OPEN_AI_KEY=your_openai_api_key
```
2. 与 PentAGI 主服务一并启动 Graphiti 栈：
```bash
# Download the Graphiti compose file if needed
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml
# Start PentAGI with Graphiti
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d
```
3. 验证 Graphiti 是否正在运行：
```bash
# Check service health
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j
# View Graphiti logs
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti
# Access Neo4j Browser (optional)
# Visit http://localhost:7474 and login with NEO4J_USER/NEO4J_PASSWORD
# Access Graphiti API (optional, for debugging)
# Visit http://localhost:8000/docs for Swagger API documentation
```
> [!NOTE]
> Graphiti 服务在 `docker-compose-graphiti.yml` 中定义为独立堆栈。你必须同时运行这两个 compose 文件才能启用知识图谱功能。默认使用预构建的 Docker 镜像 `vxcontrol/graphiti:latest`。
#### 存储内容
启用后，PentAGI 会自动捕获：
- **Agent 响应（Agent Responses）**：所有 agent 的推理、分析与决策
- **工具执行（Tool Executions）**：已执行的命令、使用的工具及其结果
- **上下文信息（Context Information）**：Flow、任务与子任务的层级结构
#### 当前限制
Graphiti 集成目前为 beta 功能。在生产环境中启用前，运维人员应针对以下约束做好规划：
- **仅支持 OpenAI 兼容 LLM。** 捆绑的 `vxcontrol/graphiti` 镜像针对通过 PentAGI 的 `.env` 变量 `OPEN_AI_KEY` 与 `OPEN_AI_SERVER_URL`（默认 `https://api.openai.com/v1`）配置的单一 OpenAI 兼容端点进行认证。`docker-compose-graphiti.yml` 会将其映射到容器内的 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL`，因此运维人员无需直接设置容器变量。PentAGI 中在其他位置为 Anthropic、Google AI（Gemini）、AWS Bedrock、DeepSeek、GLM、Kimi 或 Qwen 配置的提供商凭据**不会**被 Graphiti 用于实体抽取。若你的部署无法访问 OpenAI 兼容端点，请保持 `GRAPHITI_ENABLED=false`。
- **每个部署固定单一模型。** Graphiti 对所有抽取使用同一模型名称（`GRAPHITI_MODEL_NAME`，默认 `gpt-5-mini`）。无法按 agent 或 flow 选择模型。
- **独立计费。** 即使 flow 使用非 OpenAI 提供商运行，Graphiti 仍会在所配置的 OpenAI 兼容端点上产生费用。
- **尚无应用内图谱浏览器。** 浏览已捕获的图谱需依赖 `http://localhost:7474` 上的 Neo4j Browser 与 `http://localhost:8000/docs` 上的 Graphiti Swagger UI。目前 PentAGI 没有面向图谱的 UI 界面。
当 `GRAPHITI_ENABLED=false` 时，PentAGI 会继续使用其主内存与向量存储运行；仅跳过额外的知识图谱功能。
### GitHub 与 Google OAuth 集成
与 GitHub 和 Google 的 OAuth 集成允许用户使用这些平台上的现有账户进行身份验证。这带来多项好处：
- 简化登录流程，无需创建独立凭据
- 通过可信身份提供商增强安全性
- 可访问 GitHub/Google 账户中的用户资料信息
- 与现有开发工作流无缝集成
PentAGI 使用 `PUBLIC_URL` 作为 OAuth 重定向的公开源站/基础 URL。在默认部署中，GitHub 与 Google 回调均由以下端点处理：
```text
${PUBLIC_URL}/api/v1/auth/login-callback
```
GitHub OAuth：
1. 在你的 GitHub 账户中创建新的 OAuth App。
2. 将 **Homepage URL** 设置为你的 `PUBLIC_URL`。
3. 将 **Authorization callback URL** 设置为 `${PUBLIC_URL}/api/v1/auth/login-callback`。
4. 将客户端凭据添加到你的 `.env` 文件：
```bash
PUBLIC_URL=https://pentagi.example.com
OAUTH_GITHUB_CLIENT_ID=your_github_client_id
OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
```
Google OAuth：
1. 在你的 Google Cloud 项目中创建 OAuth 凭据。
2. 使用相同的回调端点：`${PUBLIC_URL}/api/v1/auth/login-callback`。
3. 将客户端凭据添加到你的 `.env` 文件：
```bash
PUBLIC_URL=https://pentagi.example.com
OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
```
请确保 `PUBLIC_URL` 与 PentAGI 实例对外可访问的 HTTPS 地址一致，且本身不包含回调路径。若在 OAuth 提供商处配置的 URL 与 PentAGI 生成的回调不完全匹配，提供商将因 redirect URI 不匹配而拒绝登录尝试。
### Docker 镜像配置
PentAGI 允许你配置用于执行各类任务的 Docker 镜像选择。系统会根据任务类型自动选择最合适的镜像，但你可以通过指定首选镜像来约束这一选择：
| Variable | Default | Description |
| ---------------------------------- | ---------------------- | ----------------------------------------------------------- |
| `PENTAGI_IMAGE` | `vxcontrol/pentagi:latest` | 主 PentAGI 应用服务使用的 Docker 镜像 |
| `DOCKER_DEFAULT_IMAGE` | `debian:latest` | 一般任务与模糊场景的默认 Docker 镜像 |
| `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` | `vxcontrol/kali-linux` | 安全/渗透测试任务的默认 Docker 镜像 |
`PENTAGI_IMAGE` 会更改 `docker-compose.yml` 中主 `pentagi` 服务所使用的镜像。`DOCKER_DEFAULT_IMAGE` 与 `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` 变量仅影响 PentAGI 内部任务执行时的自动 worker 镜像选择。它们不会改写 Compose 堆栈的其余部分，因此 `pgvector`、`scraper` 以及可选的 `graphiti` 堆栈等服务仍使用 compose 文件中定义的镜像引用。
当设置 `DOCKER_DEFAULT_IMAGE` 与 `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` 时，AI agent 将仅限于你指定的镜像选择。这在以下场景尤其有用：
- **安全强制（Security Enforcement）**：限制仅使用已验证且受信任的镜像
- **环境标准化（Environment Standardization）**：在所有操作中使用企业或定制镜像
- **性能优化（Performance Optimization）**：使用已预装必要工具的镜像
配置示例：
```bash
# Using a custom PentAGI application image
PENTAGI_IMAGE=registry.example.com/security/pentagi:latest
# Using a custom image for general tasks
DOCKER_DEFAULT_IMAGE=mycompany/custom-debian:latest
# Using a specialized image for penetration testing
DOCKER_DEFAULT_IMAGE_FOR_PENTEST=mycompany/pentest-tools:v2.0
```
> [!NOTE]
> 若用户在任务中显式指定了特定 Docker 镜像，系统将尝试使用该确切镜像，忽略这些设置。这些变量仅影响系统的自动镜像选择流程。
有关使用自定义渗透测试镜像进行高级 OpenVAS/GVM 实验，请参阅 [OpenVAS via a Custom Pentest Image](examples/guides/openvas-custom-image.md)。
#### 受限网络、Docker 镜像源与代理
若你的环境无法直接访问 Docker Hub（`docker.io`），仅修改 PentAGI 环境变量通常不足以解决镜像下载失败。PentAGI 仍依赖 Docker 自身的 registry 访问来管理 Compose 服务，安装程序的网络检查也会验证 Docker Hub 可达性。
对于受限网络：
1. 确认主机能够解析并访问 `docker.io`。
2. 若环境需要出站代理以访问 PentAGI 或安装程序的 HTTP 流量，请设置 `PROXY_URL` 环境变量。若要通过代理拉取 Docker 镜像，请单独配置 Docker 守护进程或 Docker Desktop 代理——Docker 不会使用 PentAGI 的 `PROXY_URL` 进行 registry 访问。
3. 若 Docker Hub 被封锁或严重限流，请在运行安装程序或 `docker compose up` 之前配置组织批准的 registry 镜像或 registry 代理。
4. 修改守护进程配置后重启 Docker，然后重新运行安装程序检查或 Compose 启动。
Docker 守护进程镜像源配置示例：
```json
{
"registry-mirrors": ["https://mirror.example.com"]
}
```
在 Linux 上，通常可在 `/etc/docker/daemon.json` 中进行配置。在 Docker Desktop 上，请使用等效的 Docker Engine 或代理设置。Docker Hub 镜像可覆盖 Docker Hub 托管的镜像（例如 `vxcontrol/*`），但主 Compose 栈已包含 `quay.io/prometheuscommunity/postgres-exporter`，可选的可观测性栈则包含 `gcr.io/cadvisor/cadvisor`。这些 registry 仍需要直连访问，或单独获批的代理/镜像路径。
请参阅官方 Docker 文档：[registry mirrors](https://docs.docker.com/docker-hub/image-library/mirror/) 和 [daemon proxy configuration](https://docs.docker.com/engine/daemon/proxy/).
## 开发
### 开发环境要求
- golang
- nodejs
- docker
- postgres
- commitlint
### 环境配置
#### 后端配置
运行一次 `cd backend && go mod download` 以安装所需软件包。
生成 swagger 文件需要运行
```bash
swag init -g ../../pkg/server/router.go -o pkg/server/docs/ --parseDependency --parseInternal --parseDepth 2 -d cmd/pentagi
```
然后通过以下方式安装 `swag` 软件包
```bash
go install github.com/swaggo/swag/cmd/swag@v1.8.7
```
生成 graphql resolver 文件需要运行
```bash
go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml
```
之后可在 `pkg/graph` 文件夹中查看生成的文件。
根据 sqlc 配置生成 ORM 方法（database 包）
```bash
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
```bash
fern generate --local
```
并安装 fern-cli
```bash
pnpm add -g fern-api
```
#### 测试
运行测试：`cd backend && go test -v ./...`
#### 前端配置
运行一次 `cd frontend && pnpm install` 以安装所需软件包。
生成 graphql 文件需要运行 `pnpm run graphql:generate`，它使用 `graphql-codegen.ts` 文件。
请确保已全局安装 `graphql-codegen`：
```bash
pnpm add -g graphql-codegen
```
之后可以运行：
* `pnpm run prettier` —— 检查代码格式是否正确
* `pnpm run prettier:fix` —— 修复格式问题
* `pnpm run lint` —— 检查代码 lint 是否正确
* `pnpm run lint:fix` —— 修复 lint 问题
生成 SSL 证书需要运行 `pnpm run ssl:generate`（使用 `generate-ssl.ts` 文件），或在运行 `pnpm run dev` 时会自动生成。
#### 后端配置
在 `.vscode/launch.json` 文件中编辑 `backend` 的配置：
- `DATABASE_URL` - PostgreSQL 数据库 URL（例如 `postgres://postgres:postgres@localhost:5432/pentagidb?sslmode=disable`）
- `DOCKER_HOST` - Docker SDK API（例如 macOS 上为 `DOCKER_HOST=unix:///Users//Library/Containers/com.docker.docker/Data/docker.raw.sock`）[更多信息](https://stackoverflow.com/a/62757128/5922857)
可选：
- `SERVER_PORT` - 服务器运行端口（默认：`8443`）
- `SERVER_USE_SSL` - 是否为服务器启用 SSL（默认：`false`）
##### PostgreSQL / pgvector 连接池大小
PentAGI 会向同一 Postgres 实例打开两个独立的连接池：
| 连接池 | 环境变量 | 默认值 | 使用者 |
|---|---|---|---|
| 共享 `sql.DB` | `DATABASE_MAX_OPEN_CONNS` | `25` | 所有 sqlc 查询与 GORM handler 共享同一个 `*sql.DB` |
| 共享 `pgxpool` | `DATABASE_VECTOR_MAX_CONNS` | `10` | 所有 pgvector 存储（agent memory + knowledge API）共享同一个连接池 |
额外调优参数：
- `DATABASE_MAX_IDLE_CONNS` — `sql.DB` 连接池在请求之间保持打开的最大空闲连接数（默认：`5`）。
**标准 `vxcontrol/pgvector` 镜像的连接预算**（`max_connections = 100`、`superuser_reserved_connections = 3`）：
```
Available for client connections = 97
pentagi sql.DB (DATABASE_MAX_OPEN_CONNS) = 25
pentagi pgxpool (DATABASE_VECTOR_MAX_CONNS) = 10
pgexporter = 3
autovacuum workers = 3
─────────────────────────────────────────
Total consumed = 41
Free buffer = 56 (≈ 58 %)
```
默认配置面向 **10 个并行 flow** 及并发 API 请求。若运行更多 flow，或在同一 Postgres 上部署多个 PentAGI 实例，请通过 `docker-compose.yml` 中的 `command` 覆盖提高 `max_connections`，并同比例增大连接池大小：
```yaml
pgvector:
image: vxcontrol/pgvector:latest
command: postgres -c max_connections=200
```
若要查看运行中部署的实时连接预算：
```bash
# Postgres limits
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
"SELECT name, setting FROM pg_settings
WHERE name IN ('"'"'max_connections'"'"', '"'"'superuser_reserved_connections'"'"');"'
# Current usage vs. available
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
"SELECT max_conn, used, max_conn - used AS available
FROM (SELECT current_setting('"'"'max_connections'"'"')::int AS max_conn,
count(*) AS used FROM pg_stat_activity) t;"'
# Breakdown by client
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
"SELECT application_name, client_addr, state, count(*)
FROM pg_stat_activity
WHERE pid <> pg_backend_pid()
GROUP BY 1, 2, 3 ORDER BY count DESC;"'
```
#### 前端配置
在 `.vscode/launch.json` 文件中编辑 `frontend` 的配置：
- `VITE_API_URL` - 后端 API URL。*省略* URL scheme（例如 `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` 文件夹中运行以下命令：
- 运行 `pnpm install` 安装依赖
- 运行 `pnpm run dev` 启动 Web 应用
- 运行 `pnpm run build` 构建 Web 应用
打开浏览器并访问 Web 应用 URL。
## 测试 LLM Agent
PentAGI 包含名为 `ctester` 的强大工具，用于测试和验证 LLM agent 能力。该工具可帮助确保你的 LLM 提供商配置能与不同 agent 类型正确配合，从而针对各 agent 角色优化模型选择。
该工具支持多 agent 并行测试、详细报告和灵活配置选项。
### 主要特性
- **并行测试（Parallel Testing）**：同时测试多个 agent，更快获得结果
- **全面测试套件（Comprehensive Test Suite）**：评估基础补全、JSON 响应、function calling 及渗透测试知识
- **详细报告（Detailed Reporting）**：生成包含成功率与性能指标的 markdown 报告
- **灵活配置（Flexible Configuration）**：按需测试特定 agent 或测试组
- **专用测试组（Specialized Test Groups）**：包含面向网络安全与渗透测试场景的领域专项测试
### 使用场景
#### 面向开发者（本地 Go 环境）
若已克隆仓库并安装 Go：
```bash
# Default configuration with .env file
cd backend
go run cmd/ctester/*.go -verbose
# Custom provider configuration
go run cmd/ctester/*.go -config ../examples/configs/openrouter.provider.yml -verbose
# Generate a report file
go run cmd/ctester/*.go -config ../examples/configs/deepinfra.provider.yml -report ../test-report.md
# Test specific agent types only
go run cmd/ctester/*.go -agents simple,simple_json,primary_agent -verbose
# Test specific test groups only
go run cmd/ctester/*.go -groups basic,advanced -verbose
```
#### 面向用户（使用 Docker 镜像）
若希望使用预构建 Docker 镜像、无需搭建开发环境：
```bash
# Using Docker to test with default environment
docker run --rm -v $(pwd)/.env:/opt/pentagi/.env vxcontrol/pentagi /opt/pentagi/bin/ctester -verbose
# Test with your custom provider configuration
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
# Generate a detailed report
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）提供了预配置的提供商文件：
```bash
# Test with OpenRouter configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/openrouter.provider.yml
# Test with DeepInfra configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepinfra.provider.yml
# Test with DeepSeek configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider deepseek
# Test with GLM configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider glm
# Test with Kimi configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider kimi
# Test with Qwen configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -provider qwen
# Test with DeepSeek configuration file for custom provider
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepseek.provider.yml
# Test with Moonshot configuration file for custom provider
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/moonshot.provider.yml
# Test with Novita configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/novita.provider.yml
# Test with OpenAI configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type openai
# Test with Anthropic configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type anthropic
# Test with Gemini configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type gemini
# Test with AWS Bedrock configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -type bedrock
# Test with Custom OpenAI configuration
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml
# Test with Ollama configuration (local inference)
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-llama318b.provider.yml
# Test with Ollama Qwen3 32B configuration (requires custom model creation)
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml
# Test with Ollama QwQ 32B configuration (requires custom model creation and 71.3GB VRAM)
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml
```
要使用这些配置，你的 `.env` 文件只需包含：
```
LLM_SERVER_URL=https://openrouter.ai/api/v1 # or https://api.deepinfra.com/v1/openai or https://api.openai.com/v1 or https://api.novita.ai/openai
LLM_SERVER_KEY=your_api_key
LLM_SERVER_MODEL= # Leave empty, as models are specified in the config
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/openrouter.provider.yml # or deepinfra.provider.ymll or custom-openai.provider.yml or novita.provider.yml
LLM_SERVER_PROVIDER= # Provider name for LiteLLM proxy (e.g., openrouter, deepseek, moonshot, novita)
LLM_SERVER_LEGACY_REASONING=false # Controls reasoning format, for OpenAI must be true (default: false)
LLM_SERVER_PRESERVE_REASONING=false # Preserve reasoning content in multi-turn conversations (required by Moonshot, default: false)
# For OpenAI (official API)
OPEN_AI_KEY=your_openai_api_key # Your OpenAI API key
OPEN_AI_SERVER_URL=https://api.openai.com/v1 # OpenAI API endpoint
# For Anthropic (Claude models)
ANTHROPIC_API_KEY=your_anthropic_api_key # Your Anthropic API key
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1 # Anthropic API endpoint
# For Gemini (Google AI)
GEMINI_API_KEY=your_gemini_api_key # Your Google AI API key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com # Google AI API endpoint
# For AWS Bedrock (enterprise foundation models)
BEDROCK_REGION=us-east-1 # AWS region for Bedrock service
# Authentication (choose one method, priority: DefaultAuth > BearerToken > AccessKey):
BEDROCK_DEFAULT_AUTH=false # Use AWS SDK credential chain (env vars, EC2 role, ~/.aws/credentials)
BEDROCK_BEARER_TOKEN= # Bearer token authentication (takes priority over static credentials)
BEDROCK_ACCESS_KEY_ID=your_aws_access_key # AWS access key ID (static credentials)
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key # AWS secret access key (static credentials)
BEDROCK_SESSION_TOKEN= # AWS session token (optional, for temporary credentials with static auth)
BEDROCK_SERVER_URL= # Optional custom Bedrock endpoint (VPC endpoints, local testing)
# For Ollama (local server or cloud)
OLLAMA_SERVER_URL= # Local: http://ollama-server:11434, Cloud: https://ollama.com
OLLAMA_SERVER_API_KEY= # Required for Ollama Cloud (https://ollama.com/settings/keys), leave empty for local
OLLAMA_SERVER_MODEL=
OLLAMA_SERVER_CONFIG_PATH=
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=
OLLAMA_SERVER_PULL_MODELS_ENABLED=
OLLAMA_SERVER_LOAD_MODELS_ENABLED=
# For DeepSeek (Chinese AI with strong reasoning)
DEEPSEEK_API_KEY= # DeepSeek API key
DEEPSEEK_SERVER_URL=https://api.deepseek.com # DeepSeek API endpoint
DEEPSEEK_PROVIDER= # Optional: LiteLLM prefix (e.g., 'deepseek')
# For GLM (Zhipu AI)
GLM_API_KEY= # GLM API key
GLM_SERVER_URL=https://api.z.ai/api/paas/v4 # GLM API endpoint (international)
GLM_PROVIDER= # Optional: LiteLLM prefix (e.g., 'zai')
# For Kimi (Moonshot AI)
KIMI_API_KEY= # Kimi API key
KIMI_SERVER_URL=https://api.moonshot.ai/v1 # Kimi API endpoint (international)
KIMI_PROVIDER= # Optional: LiteLLM prefix (e.g., 'moonshot')
# For Qwen (Alibaba Cloud DashScope)
QWEN_API_KEY= # Qwen API key
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1 # Qwen API endpoint (US)
QWEN_PROVIDER= # Optional: LiteLLM prefix (e.g., 'dashscope')
# For Ollama (local inference) use variables above
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` 文件：
```bash
LLM_SERVER_URL=https://api.openai.com/v1
LLM_SERVER_KEY=your_openai_api_key
LLM_SERVER_MODEL= # Leave empty, models are specified in config
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/custom-openai.provider.yml
LLM_SERVER_LEGACY_REASONING=true # Required for OpenAI reasoning format
```
该配置使用预构建的 `custom-openai.provider.yml` 文件，将所有 Agent 类型映射到未验证组织可用的模型，使用 `o3-mini`，而非 `o1`、`o3` 和 `o4-mini` 等模型。
你可以使用以下方式测试此配置：
```bash
# Test with custom OpenAI configuration for unverified accounts
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml
```
> [!NOTE]
> `LLM_SERVER_LEGACY_REASONING=true` 设置对于 OpenAI 兼容性至关重要，因为它可确保推理参数以 OpenAI API 所期望的格式发送。
#### 使用 LiteLLM Proxy
当使用 LiteLLM proxy 访问各类 LLM 提供商时，模型名称会带有提供商前缀（例如 `moonshot/kimi-2.5`，而非 `kimi-2.5`）。若要在直接 API 访问与 LiteLLM proxy 之间共用同一套提供商配置文件，请设置 `LLM_SERVER_PROVIDER` 变量：
```bash
# Direct access to 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= # Empty for direct access
# Access via LiteLLM proxy
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 # Provider prefix for LiteLLM
```
设置 `LLM_SERVER_PROVIDER=moonshot` 后，系统会自动为配置文件中的所有模型名称添加 `moonshot/` 前缀，使其与 LiteLLM 的模型命名约定兼容。
**LiteLLM 提供商名称映射：**
使用 LiteLLM proxy 时，请设置相应的 `*_PROVIDER` 变量以启用模型前缀：
- `deepseek` - 用于 DeepSeek 模型（`DEEPSEEK_PROVIDER=deepseek` → `deepseek/deepseek-v4-flash`）
- `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 示例：**
```bash
# Use DeepSeek models via LiteLLM proxy with model prefixing
DEEPSEEK_API_KEY=your_litellm_proxy_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek # Models become deepseek/deepseek-v4-flash, deepseek/deepseek-v4-pro for LiteLLM
# Direct DeepSeek API usage (no prefix needed)
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com
# Leave DEEPSEEK_PROVIDER empty
```
此方法可让你：
- 在直接访问与代理访问之间共用同一套配置文件
- 在不修改配置文件的情况下切换提供商
- 通过 LiteLLM 轻松测试不同的路由策略
#### 在生产环境中运行测试
如果你已有正在运行的 PentAGI 容器，并希望测试当前配置：
```bash
# Run ctester in an existing container using current environment variables
docker exec -it pentagi /opt/pentagi/bin/ctester -verbose
# Test specific agent types with deterministic ordering
docker exec -it pentagi /opt/pentagi/bin/ctester -agents simple,primary_agent,pentester -groups basic,knowledge -verbose
# Generate a report file inside the container
docker exec -it pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/data/agent-test-report.md
# Access the report from the host
docker cp pentagi:/opt/pentagi/data/agent-test-report.md ./
```
### 命令行选项
该工具接受以下选项：
- `-env ` - 环境文件路径（默认：`.env`）
- `-type ` - 提供商类型：`custom`、`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`（默认：`custom`）
- `-config ` - 自定义提供商配置路径（默认：来自 `LLM_SERVER_CONFIG_PATH` 环境变量）
- `-tests ` - 自定义测试 YAML 文件路径（可选）
- `-report ` - 报告文件写入路径（可选）
- `-agents ` - 要测试的 agent 类型列表，以逗号分隔（默认：`all`）
- `-groups ` - 要运行的测试组列表，以逗号分隔（默认：`all`）
- `-verbose` - 启用详细输出，显示每个 agent 的详细测试结果
### 可用的 Agent 类型
Agent 按以下确定性顺序进行测试：
1. **simple** - 基础补全任务
2. **simple_json** - JSON 结构化响应
3. **primary_agent** - 主推理 agent
4. **assistant** - 交互式助手模式
5. **generator** - 内容生成
6. **refiner** - 内容精炼与改进
7. **adviser** - 专家建议与咨询
8. **reflector** - 自我反思与分析
9. **searcher** - 信息收集与搜索
10. **enricher** - 数据丰富与扩展
11. **coder** - 代码生成与分析
12. **installer** - 安装与配置任务
13. **pentester** - 渗透测试与安全评估
### 可用的测试组
- **basic** - 基础补全与提示响应测试
- **advanced** - 复杂推理与函数调用（function calling）测试
- **json** - JSON 格式验证与结构测试（专为 `simple_json` agent 设计）
- **knowledge** - 特定领域的网络安全与渗透测试知识测试
> **注意**：`json` 测试组专为 `simple_json` agent 类型设计，而所有其他 agent 使用 `basic`、`advanced` 和 `knowledge` 组进行测试。这种专门化可确保针对每个 agent 的预期用途实现最优测试覆盖。
### 提供商配置示例
提供商配置定义了不同 agent 类型应使用哪些模型：
```yaml
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
# ... other agent types ...
```
### 优化工作流
1. **创建基线**：使用默认配置运行测试，建立基准性能
2. **分析各 agent 的性能**：查看确定性 agent 排序，识别表现不佳的 agent
3. **测试专用配置**：使用特定于提供商的配置，为各 agent 类型尝试不同模型
4. **关注领域知识**：特别关注 knowledge 组测试，以评估网络安全专业能力
5. **验证函数调用**：确保基于工具的测试对关键 agent 类型稳定通过
6. **对比结果**：在所有测试组中寻找最佳成功率与性能
7. **部署最优配置**：在生产环境中使用优化后的配置
该工具可帮助确保你的 AI agent 为其特定任务使用最有效的模型，在优化成本的同时提升可靠性。
## 嵌入（Embedding）配置与测试
PentAGI 使用向量嵌入（vector embeddings）进行语义搜索、知识存储与记忆管理。系统支持多种嵌入提供商，可根据你的需求与偏好进行配置。
### 支持的嵌入提供商
PentAGI 支持以下嵌入提供商：
- **OpenAI**（默认）：使用 OpenAI 的文本嵌入模型
- **Ollama**：通过 Ollama 使用本地嵌入模型
- **Mistral**：Mistral AI 的嵌入模型
- **Jina**：Jina AI 的嵌入服务
- **HuggingFace**：来自 HuggingFace 的模型
- **GoogleAI**：Google 的嵌入模型
- **VoyageAI**：VoyageAI 的嵌入模型
> **OpenAI 兼容第三方**：任何提供 OpenAI `/embeddings` API 的提供商，均可通过 `EMBEDDING_PROVIDER=openai` 配合自定义 `EMBEDDING_URL` 接入。例如，**Qwen DashScope** 通过 `/compatible-mode/v1` 端点提供 `text-embedding-v4`（仅限国际版与中国大陆地区——美国区域不提供嵌入服务）。完整配置片段请参阅 [Qwen Alternative Integrations](#alternative-integrations) 小节。
Embedding Provider Configuration (click to expand)
### 环境变量
要配置嵌入（embedding）提供方，请在 `.env` 文件中设置以下环境变量：
```bash
# Primary embedding configuration
EMBEDDING_PROVIDER=openai # Provider type (openai, ollama, mistral, jina, huggingface, googleai, voyageai)
EMBEDDING_MODEL=text-embedding-3-small # Model name to use
EMBEDDING_URL= # Optional custom API endpoint
EMBEDDING_KEY= # API key for the provider (if required)
EMBEDDING_BATCH_SIZE=100 # Number of documents to process in a batch
EMBEDDING_STRIP_NEW_LINES=true # Whether to remove new lines from text before embedding
EMBEDDING_MAX_TEXT_BYTES=8192 # Max bytes of text sent to embedding model per document (byte proxy for token limit)
# Advanced settings
PROXY_URL= # Optional proxy for all API calls
HTTP_CLIENT_TIMEOUT=600 # Timeout in seconds for external API calls (default: 600, 0 = no timeout)
TERMINAL_TOOL_TIMEOUT=1200 # Default timeout in seconds for terminal tool commands when timeout=0 or negative (range: 1–10800; values <= 0 or above 10800 are clamped to 10800 = 3 hours)
# SSL/TLS Certificate Configuration (for external communication with LLM backends and tool servers)
EXTERNAL_SSL_CA_PATH= # Path to custom CA certificate file (PEM format) inside the container
# Must point to /opt/pentagi/ssl/ directory (e.g., /opt/pentagi/ssl/ca-bundle.pem)
EXTERNAL_SSL_INSECURE=false # Skip certificate verification (use only for testing)
```
如何添加自定义 CA 证书（点击展开）
如果你看到此错误：`tls: failed to verify certificate: x509: certificate signed by unknown authority`
**步骤 1：** 获取 PEM 格式的 CA 证书包（可包含多个证书）
**步骤 2：** 将文件放在宿主机的 SSL 目录中：
```bash
# Default location (if PENTAGI_SSL_DIR is not set)
cp ca-bundle.pem ./pentagi-ssl/
# Or custom location (if using PENTAGI_SSL_DIR in docker-compose.yml)
cp ca-bundle.pem /path/to/your/ssl/dir/
```
**步骤 3：** 在 `.env` 文件中设置路径（路径必须在容器内部）：
```bash
# The volume pentagi-ssl is mounted to /opt/pentagi/ssl inside the container
EXTERNAL_SSL_CA_PATH=/opt/pentagi/ssl/ca-bundle.pem
EXTERNAL_SSL_INSECURE=false
```
**步骤 4：** 重启 PentAGI：
```bash
docker compose restart pentagi
```
**说明：**
- `pentagi-ssl` 卷会挂载到容器内的 `/opt/pentagi/ssl`
- 可在 docker-compose.yml 中使用 `PENTAGI_SSL_DIR` 变量更改宿主机目录
- 单个 PEM 文件可包含多个证书及中间 CA
- 仅将 `EXTERNAL_SSL_INSECURE=true` 用于测试（不建议用于生产环境）
### 各提供方特定限制
各提供方有特定的限制和支持的功能：
- **OpenAI**：支持所有配置选项
- **Ollama**：不支持 `EMBEDDING_KEY`，因其使用本地模型
- **Mistral**：不支持 `EMBEDDING_MODEL` 或自定义 HTTP 客户端
- **Jina**：不支持自定义 HTTP 客户端
- **HuggingFace**：需要 `EMBEDDING_KEY`，并支持所有其他选项
- **GoogleAI**：不支持 `EMBEDDING_URL`，需要 `EMBEDDING_KEY`
- **VoyageAI**：支持所有配置选项
如果未指定 `EMBEDDING_URL` 和 `EMBEDDING_KEY`，系统将尝试使用对应的 LLM 提供方设置（例如，当 `EMBEDDING_PROVIDER=openai` 时使用 `OPEN_AI_KEY`）。
### 为何嵌入提供方需保持一致
始终使用同一嵌入提供方至关重要，原因如下：
1. **向量兼容性（Vector Compatibility）**：不同提供方产生的向量在维度和数学属性上各不相同
2. **语义一致性（Semantic Consistency）**：更换提供方可能破坏先前已嵌入文档之间的语义相似性
3. **记忆污染（Memory Corruption）**：混用不同嵌入可能导致搜索结果变差，知识库功能失效
如果更换嵌入提供方，应清空并重新索引整个知识库（见下文 `etester` 工具）。
### 嵌入测试工具（etester）
PentAGI 包含专用的 `etester` 工具，用于测试、管理和调试嵌入功能。该工具对于诊断和解决与向量嵌入及知识存储相关的问题至关重要。
Etester 命令（点击展开）
```bash
# Test embedding provider and database connection
cd backend
go run cmd/etester/main.go test -verbose
# Show statistics about the embedding database
go run cmd/etester/main.go info
# Delete all documents from the embedding database (use with caution!)
go run cmd/etester/main.go flush
# Recalculate embeddings for all documents (after changing provider)
go run cmd/etester/main.go reindex
# Search for documents in the embedding database
go run cmd/etester/main.go search -query "How to install PostgreSQL" -limit 5
```
### 使用 Docker
如果你在 Docker 中运行 PentAGI，可在容器内使用 etester：
```bash
# Test embedding provider
docker exec -it pentagi /opt/pentagi/bin/etester test
# Show detailed database information
docker exec -it pentagi /opt/pentagi/bin/etester info -verbose
```
### 高级搜索选项
`search` 命令支持多种筛选条件以缩小结果范围：
```bash
# Filter by document type
docker exec -it pentagi /opt/pentagi/bin/etester search -query "Security vulnerability" -doc_type guide -threshold 0.8
# Filter by flow ID
docker exec -it pentagi /opt/pentagi/bin/etester search -query "Code examples" -doc_type code -flow_id 42
# All available search options
docker exec -it pentagi /opt/pentagi/bin/etester search -help
```
可用的搜索参数：
- `-query STRING`：搜索查询文本（必填）
- `-doc_type STRING`：按文档类型筛选（answer、memory、guide、code）
- `-flow_id NUMBER`：按 flow ID 筛选（正整数）
- `-answer_type STRING`：按回答类型筛选（guide、vulnerability、code、tool、other）
- `-guide_type STRING`：按指南类型筛选（install、configure、use、pentest、development、other）
- `-limit NUMBER`：最大结果数量（默认：3）
- `-threshold NUMBER`：相似度阈值（0.0-1.0，默认：0.7）
### 跨 Flow 的记忆生命周期
PentAGI 存储多种向量文档，各自用途不同：
- `memory` 记录与 flow 相关的执行历史，例如工具结果和 agent 观测
- `guide`、`answer` 和 `code` 用于可在后续运行中复用的知识
若要查看某次 engagement 中发生了什么，请使用相关的 `flow_id` 在向量存储中搜索。若希望知识在单次运行之外仍能保留，应显式将持久结果存储为 `guide`、`answer` 或 `code` 文档，而非仅依赖执行记忆。
例如，若目标存在重复出现的搭建说明、认证特性或目标专属测试方法，可指示 agent 将该信息保存为 `guide`，并在下次 engagement 开始时搜索它。若希望新 flow 以可复用上下文启动，这是当前最稳妥的工作流程。
删除 flow 会通过 PentAGI 的软删除机制将其从常规查询中移除，因此可复用知识应与各 flow 的执行历史分开管理。若启用本 README 前文所述的可选 Graphiti 知识图谱，应将其当前搜索上下文视为限定于活动 flow 或 engagement，除非你显式构建独立的跨 flow 复用工作流。
### 常见故障排查场景
1. **更换嵌入提供方后**：务必运行 `flush` 或 `reindex` 以确保一致性
2. **搜索结果不佳**：尝试调整相似度阈值，或检查嵌入是否正确生成
3. **数据库连接问题**：确认 PostgreSQL 正在运行且已安装 pgvector 扩展
4. **缺少 API 密钥**：检查所选嵌入提供方的环境变量
## 使用 ftester 进行函数测试
PentAGI 包含一款名为 `ftester` 的多功能工具，用于调试、测试和开发特定函数及 AI 智能体（agent）行为。`ctester` 侧重于测试 LLM 模型能力，而 `ftester` 则允许你直接调用各个系统函数和 AI 智能体组件，并对执行上下文进行精确控制。
### 主要特性
- **直接访问函数**：无需运行整个系统即可测试单个函数
- **Mock 模式**：使用内置 mock，无需在线 PentAGI 部署即可测试函数
- **交互式输入**：交互式填写函数参数，便于探索性测试
- **详细输出**：带颜色编码的终端输出，包含格式化的响应与错误信息
- **上下文感知测试**：在特定流程（flow）、任务（task）和子任务（subtask）的上下文中调试 AI 智能体
- **可观测性集成**：所有函数调用都会记录到 Langfuse 和 Observability 技术栈
### 使用模式
#### 命令行参数
在命令行中直接指定函数和参数来运行 ftester：
```bash
# Basic usage with mock mode
cd backend
go run cmd/ftester/main.go [function_name] -[arg1] [value1] -[arg2] [value2]
# Example: Test terminal command in mock mode
go run cmd/ftester/main.go terminal -command "ls -la" -message "List files"
# Using a real flow context
go run cmd/ftester/main.go -flow 123 terminal -command "whoami" -message "Check user"
# Testing AI agent in specific task/subtask context
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 pentester -message "Find vulnerabilities"
```
#### 交互模式
不带参数运行 ftester，获得引导式交互体验：
```bash
# Start interactive mode
go run cmd/ftester/main.go [function_name]
# For example, to interactively fill browser tool arguments
go run cmd/ftester/main.go browser
```
可用函数（点击展开）
### 环境函数
- **terminal**：在容器中执行命令并返回输出
- **file**：在容器中执行文件操作（读取、写入、列出）
### 搜索函数
- **browser**：访问网站并截取屏幕截图
- **google**：使用 Google Custom Search 搜索网络
- **duckduckgo**：使用 DuckDuckGo 搜索网络
- **tavily**：使用 Tavily AI 搜索引擎进行搜索
- **traversaal**：使用 Traversaal AI 搜索引擎进行搜索
- **perplexity**：使用 Perplexity AI 进行搜索
- **sploitus**：搜索安全漏洞利用、漏洞（CVE）和渗透测试工具
- **searxng**：使用 Searxng 元搜索引擎进行搜索（聚合多个引擎的结果）
### 向量数据库函数
- **search_in_memory**：在向量数据库中搜索信息
- **search_guide**：在向量数据库中查找指导文档
- **search_answer**：在向量数据库中查找问题的答案
- **search_code**：在向量数据库中查找代码示例
### AI 智能体函数
- **advice**：从 AI 智能体获取专家建议
- **coder**：请求生成或修改代码
- **maintenance**：运行系统维护任务
- **memorist**：在向量数据库中存储和组织信息
- **pentester**：执行安全测试和漏洞分析
- **search**：跨多个来源进行复杂搜索
### 工具函数
- **describe**：显示有关流程、任务和子任务的信息
调试流程上下文（点击展开）
`describe` 函数提供流程内任务和子任务的详细信息。当 PentAGI 遇到问题或卡住时，这对于诊断问题特别有用。
```bash
# List all flows in the system
go run cmd/ftester/main.go describe
# Show all tasks and subtasks for a specific flow
go run cmd/ftester/main.go -flow 123 describe
# Show detailed information for a specific task
go run cmd/ftester/main.go -flow 123 -task 456 describe
# Show detailed information for a specific subtask
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 describe
# Show verbose output with full descriptions and results
go run cmd/ftester/main.go -flow 123 describe -verbose
```
该函数可帮助你定位流程可能卡住的精确位置，并通过直接调用相应的智能体函数来恢复处理。
函数帮助与发现（点击展开）
每个函数都有帮助模式，可显示可用参数：
```bash
# Get help for a specific function
go run cmd/ftester/main.go [function_name] -help
# Examples:
go run cmd/ftester/main.go terminal -help
go run cmd/ftester/main.go browser -help
go run cmd/ftester/main.go describe -help
```
你也可以不带参数运行 ftester，查看所有可用函数的列表：
```bash
go run cmd/ftester/main.go
```
输出格式（点击展开）
`ftester` 工具使用颜色编码输出，便于解读：
- **蓝色标题**：章节标题和键名
- **青色 [INFO]**：一般信息消息
- **绿色 [SUCCESS]**：操作成功
- **红色 [ERROR]**：错误消息
- **黄色 [WARNING]**：警告消息
- **黄色 [MOCK]**：表示处于 mock 模式运行
- **洋红色值**：函数参数和结果
JSON 和 Markdown 响应会自动格式化，以提高可读性。
高级使用场景（点击展开）
### 调试卡住的 AI 流程
当 PentAGI 在流程中卡住时：
1. 通过 UI 暂停流程
2. 使用 `describe` 识别当前任务和子任务
3. 使用相同的任务/子任务 ID 直接调用智能体函数
4. 检查详细输出以定位问题
5. 根据需要恢复流程或手动干预
### 测试环境变量
验证 API 密钥和外部服务是否配置正确：
```bash
# Test Google search API configuration
go run cmd/ftester/main.go google -query "pentesting tools"
# Test browser access to external websites
go run cmd/ftester/main.go browser -url "https://example.com"
```
### 开发新的 AI 智能体行为
在开发新的提示词模板或智能体行为时：
1. 在 UI 中创建测试流程
2. 使用 ftester 以不同提示词直接调用智能体
3. 观察响应并相应调整提示词
4. 在 Langfuse 中查看所有函数调用的详细追踪记录
### 验证 Docker 容器配置
确保容器配置正确：
```bash
go run cmd/ftester/main.go -flow 123 terminal -command "env | grep -i proxy" -message "Check proxy settings"
```
Docker 容器用法（点击展开）
如果你在 Docker 中运行 PentAGI，可以在容器内使用 ftester：
```bash
# Run ftester inside the running PentAGI container
docker exec -it pentagi /opt/pentagi/bin/ftester [arguments]
# Examples:
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 "List processes"
```
这对于没有本地开发环境的生产部署特别有用。
与可观测性工具集成（点击展开）
通过 ftester 进行的所有函数调用都会记录到：
1. **Langfuse**：捕获完整的 AI 智能体交互链，包括提示词、响应和函数调用
2. **OpenTelemetry**：记录指标、追踪和日志，用于系统性能分析
3. **终端输出**：提供函数执行的即时反馈
要访问详细日志：
- 在 Langfuse UI 中查看 AI 智能体追踪记录（通常位于 `http://localhost:4000`）
- 使用 Grafana 仪表板查看系统指标（通常位于 `http://localhost:3000`）
- 检查终端输出以获取即时的函数结果和错误信息
### 命令行选项
主工具接受以下若干选项：
- `-env ` - 环境文件路径（可选，默认：`.env`）
- `-provider ` - 要使用的提供商类型（默认：`custom`，可选：`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`、`custom`）
- `-flow ` - 用于测试的 Flow ID（0 表示使用 mock，默认：`0`）
- `-task ` - 智能体上下文的 Task ID（可选）
- `-subtask ` - 智能体上下文的 Subtask ID（可选）
函数专属参数在函数名之后传递，格式为 `-name value`。
### 渗透测试提示词方法论
在为攻击性安全工作优化提示词时，应为智能体提供清晰的方法论，而非平铺直叙的载荷列表：
1. 首先明确范围、授权和成功标准
2. 先映射应用：角色、路由、参数、上传、集成和信任边界
3. 系统性地优先排序攻击面，而不是一次性测试所有内容
4. 在深入利用之前，用可复现的证据验证发现
5. 最后整理可直接用于报告的笔记，记录影响、前置条件和后续步骤
有关 PentAGI 专属的提示词指导，请参阅 [`backend/docs/prompt_engineering_pentagi.md`](backend/docs/prompt_engineering_pentagi.md)。如需实用的起点，可复用并调整 [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md)，以匹配目标应用、技术栈和项目范围。
## 构建
### 构建 Docker 镜像
Docker 构建过程会自动从 git 标签嵌入版本信息。要正确为构建打上版本号，请使用提供的脚本：
#### Linux/macOS
```bash
# Load version variables
source ./scripts/version.sh
# Standard build
docker build \
--build-arg PACKAGE_VER=$PACKAGE_VER \
--build-arg PACKAGE_REV=$PACKAGE_REV \
-t pentagi:$PACKAGE_VER .
# Multi-platform build
docker buildx build \
--platform linux/amd64,linux/arm64 \
--build-arg PACKAGE_VER=$PACKAGE_VER \
--build-arg PACKAGE_REV=$PACKAGE_REV \
-t pentagi:$PACKAGE_VER .
# Build and push
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）
```powershell
# Load version variables
. .\scripts\version.ps1
# Standard build
docker build `
--build-arg PACKAGE_VER=$env:PACKAGE_VER `
--build-arg PACKAGE_REV=$env:PACKAGE_REV `
-t pentagi:$env:PACKAGE_VER .
# Multi-platform build
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 .
```
#### 无版本信息的快速构建
适用于无需版本追踪的开发构建：
```bash
docker build -t pentagi:dev .
```
> [!NOTE]
> - 构建脚本会自动根据 git 标签确定版本
> - 发布构建（在标签提交上）没有修订后缀
> - 开发构建（标签之后）将提交哈希作为修订号（例如，`1.1.0-bc6e800`）
> - 要在本地使用构建的镜像，请在 `docker-compose.yml` 中更新镜像名称，或使用 `build` 选项
## 致谢
本项目的实现得益于以下研究与开发成果：
- [面向 LLM 应用的新兴架构](https://lilianweng.github.io/posts/2023-06-23-agent)
- [自主 LLM 智能体综述](https://arxiv.org/abs/2403.08299)
- [Codel](https://github.com/semanser/codel) by Andriy Semenets - 基于智能体的自动化初期架构灵感
## 许可证
**PentAGI** 根据 [MIT License](LICENSE) 授权。
Copyright (c) 2025 PentAGI Development Team
### 第三方依赖
所有第三方依赖均采用与 MIT 兼容的许可证。详见 [licenses/](licenses/) 目录中的详细许可证报告。
### VXControl Cloud Services
⚠️ **注意：** 虽然 VXControl Cloud SDK 代码采用 MIT 许可证，但访问 **VXControl Cloud Services**（威胁情报、AI 支持、高级功能）需要单独的 License Key，并须遵守 [服务条款](https://github.com/vxcontrol/cloud#license-and-terms).
SDK 代码本身可免费使用——服务访问需要注册。
如有疑问，请联系：**info@pentagi.com** 或 **info@vxcontrol.com**