cain-agent是一个面向授权渗透测试的 AI 安全评估工具，内置 AWS/Azure/GCP 与阿里云/腾讯云/华为云等云模块。它的默认执行引擎绑定 Anthropic，但通过--backend pi切换到 pi 后端后，你就可以自由接入deepseek、OpenAI、Google Gemini、OpenRouter 以及自建 LLM 网关，按成本与能力灵活混搭模型。本文是一份从零到跑通的多 Provider 接入指南。

为什么需要多 Provider 接入？

渗透测试流水线分recon → test → report三个阶段，token 消耗不小。多 Provider 带来三个直接好处：

• 💰成本优化：侦察是重复性枚举，用 deepseek 等低成本模型；测试需要高能力判断，再用旗舰模型
• 🧩灵活选型：不同团队手里的 API Key 不同，无需被单一供应商锁定
• 🏠自建网关：内网环境可指向私有 LLM 网关，模型不出域

关键前提：切换后端不改变任何安全约束。scope 白名单、发现≠校验双会话、默认拒绝、idle/total 双防线在 pi 后端与默认 claude 后端完全一致——每笔工具调用都要回 Python 侧判决后才执行（见 pi_executor.py 的PiExecutor实现）。

前置准备：一次性安装

pi 后端通过一个 Node 桥进程驱动 agent 运行时（源码见 bridge.mjs），首次使用前需要安装依赖：

cd toolchain/pi npm install

要求Node ≥ 20。未安装时--backend pi会给出明确错误并退出，默认claude后端不受影响。详见 toolchain/pi/README.md。

Python 侧则照常安装即可：

git clone https://gitcode.com/gh_mirrors/ca/cain-agent cd cain-agent pip install -e .

支持的 Provider 与 API Key 对照表

pi 桥内置 6 个 provider 注册项，各自的鉴权走标准环境变量约定（桥进程继承当前 shell 环境）：

5 步接入 deepseek（最简示例）

第 1 步：设置 API Key

export DEEPSEEK_API_KEY="sk-..."

第 2 步：指定 provider 与模型

cain-agent run --target http://your-range.example/ \ --backend pi --pi-provider deepseek --pi-model deepseek-chat

第 3 步：先用 dry-run 核对执行计划

cain-agent run --target http://your-range.example/ \ --backend pi --pi-provider deepseek --pi-model deepseek-chat --dry-run

dry-run 会打印后端配置（如pi provider/model: deepseek/deepseek-chat），零 token 消耗，确认无误再正式跑。

第 4 步：正式运行，产物照常落在workspace/report/（report.md、aggregated-report.json、validation-summary.json）。

第 5 步：换其他 Provider——只需改两件事：环境变量和--pi-provider/--pi-model：

export OPENAI_API_KEY="sk-..." cain-agent run --target http://your-range.example/ \ --backend pi --pi-provider openai --pi-model gpt-4o

自建网关接入：PI_BASE_URL 玩法

如果你的 LLM 网关实现了Anthropic Messages 协议（如内部推理平台、协议转发网关），可以用PI_BASE_URL把请求指向它：

export PI_BASE_URL="http://127.0.0.1:15721" # 网关地址 export ANTHROPIC_AUTH_TOKEN="your-gateway-token" # 网关凭证 cain-agent run --target http://your-range.example/ \ --backend pi --pi-model your-gateway-model-id

两种模型名的处理逻辑（见 bridge.mjs 中的makeAdHocModel）：

• 目录内模型：覆盖请求地址（baseUrl 指向网关）
• 目录外模型（网关自有模型 id）：透传构造 ad-hoc 模型，无需改代码

auth 仍走上述环境变量约定。项目内部全链路实测（pi-smoke-2026-08-25.md）就是用这种网关通道跑通了三阶段非 dry-run 运行的。

进阶：按阶段混搭模型，成本优化

侦察与测试可以各走各的引擎，缺省时阶段参数回落全局--backend/--pi-provider/--pi-model：

cain-agent run --target http://your-range.example/ \ --recon-backend pi --recon-provider deepseek --recon-model cheap-model-id \ --test-backend claude

另外 report 阶段的校验通道（零工具只读会话）可独立配置，实现"发现用高能力模型、校验用低成本模型"的组合：

cain-agent run --target http://your-range.example/ \ --backend pi --pi-model glm-5.3 --pi-validation-model glm-5.3-air

dry-run 会分别打印两条通道的配置，例如：

pi provider/model: anthropic/glm-5.3 pi 校验通道: anthropic/glm-5.3-air（零工具）

常见问题排查

Q: 提示pi bridge not found？没装 Node 依赖。执行cd toolchain/pi && npm install，并确认 Node ≥ 20。

Q: 提示unknown or unloaded provider？--pi-provider的值必须是上表 6 个之一；provider 模块动态加载，拼错名字不会静默成功。

Q: 返回 401 / 鉴权失败？核对环境变量名是否拼对（常见坑：Google 用的是GEMINI_API_KEY而不是GOOGLE_API_KEY）。桥会把 provider 错误传播到最终结果（ExecutorResult.is_error=True），不会把零 token 的空返回误报为成功。

Q: 切换 provider 后安全边界变了吗？没有。scope 判定单点在 Python 侧，桥自身不含任何放行逻辑；allowed_tools=[]时桥不给模型注册任何工具（见 PiExecutor 源码 中_judge的白名单二次拦截）。

小结

更多用法（安装、scope 配置、产物解读）见官方用户指南 docs/usage.md；pi 后端的协议与安全语义详见 toolchain/pi/README.md。