Pi Agent 应该如何通过 Agent SDK 正确连接 Claude 或 Codex？

作者：袖梨 2026-09-13

Pi Agent 连接 Claude 或 Codex 时，首先要区分“模型 Provider”和“Agent SDK”。如果只是让 Pi 使用某个模型，优先配置 Pi 原生支持的 Provider；只有当外部 SDK 提供了必须保留的 Agent 循环、沙箱、会话或追踪能力时，才应把它包装成受控工具或独立服务。直接把两个完整 Agent 循环套在一起，往往会造成工具重复、上下文膨胀、权限混乱和难以取消的问题。

三类组件分别负责什么

连接方案通常涉及三种不同组件：

Pi Coding Agent：终端 Harness，负责会话、提示、工具、扩展和界面。
模型 Provider：负责向 Claude 或 OpenAI 模型发送请求并返回流式结果。
Agent SDK：在应用代码中提供 Agent 循环、工具调用、会话、交接、护栏或沙箱。

Pi 本身已经拥有 Agent 循环。如果需求只是换模型，再接一层 Agent SDK 通常是重复建设。

先选择正确的连接模式

需求	推荐模式	原因
在 Pi 中直接使用 Claude 或 OpenAI 模型	Pi 原生 Provider	链路短，工具与会话仍由 Pi 统一管理
把 Pi 嵌入 Node.js 应用	Pi SDK 或 RPC	保留 Pi 的会话和扩展机制
调用 Claude 专用 Agent 工作流	Claude Agent SDK 独立服务	保留其 Agent 循环和工具语义
构建 OpenAI 多 Agent、护栏或追踪	OpenAI Agents SDK	直接使用 Agent、工具、交接和会话能力
让 Pi 委派一个封闭子任务	扩展工具调用外部服务	边界明确，容易超时和审计

方案一：使用 Pi 原生 Provider

Pi 官方支持多种模型提供商，可通过交互登录、API Key、模型配置或自定义 Provider 连接。若目标只是“让 Pi 使用 Claude”或“让 Pi 使用 OpenAI 编码模型”，这是首选方案。

这种结构只有一个 Agent 循环：

用户 → Pi 会话与工具 → 模型 Provider → Claude / OpenAI 模型

Pi 负责把工具结果发回模型，模型只决定下一步动作。上下文压缩、项目指令、文件写入和 Shell 都由同一 Harness 管理，行为更容易理解。

Provider 配置的安全原则

凭据通过环境变量、系统密钥存储或官方登录流程提供。
不要把 API Key 写入项目配置、提示词或版本库。
自定义 Provider 应使用公开、受支持的 API，不模拟官方客户端身份。
明确模型 ID、基础地址、超时和最大重试次数。
记录实际提供商与计费账号，避免把订阅额度和 API 计费混淆。

即使 Pi 支持某种订阅登录，也要以当前官方文档和服务条款为准，不能假定所有模型、功能和配额都与原生客户端一致。

方案二：用 Pi SDK 嵌入自己的应用

Pi SDK 适合让 Node.js 应用创建和控制 Pi 会话。资源加载器可以发现扩展，应用也可以选择启用哪些工具。若其他语言需要接入，可以考虑 Pi 的 RPC 或 JSON 事件流模式。

这一路径解决的是“应用如何控制 Pi”，而不是“Pi 如何调用 Claude Agent SDK”。应用仍应让 Pi 通过 Provider 使用模型，避免同时维护两套工具循环。

嵌入时至少需要管理：

每个会话对应的项目目录和用户身份。
资源加载范围及允许启用的扩展。
取消、超时、并发数和输出大小。
会话文件的生命周期和敏感信息清理。
工具执行日志与最终结果的关联。

方案三：把外部 Agent SDK 包装成工具

如果确实需要 Claude Agent SDK 或 OpenAI Agents SDK 的专用能力，可以为 Pi 注册一个工具，让该工具向独立进程或服务提交边界明确的子任务。

用户
  ↓
Pi：主任务、上下文选择、最终审查
  ↓ 单个结构化工具调用
SDK 服务：执行封闭子任务
  ↓ JSON 结果、补丁或工件
Pi：验证真实差异与测试

外部服务不应直接继承 Pi 的全部对话和系统提示。它只接收完成子任务所需的最小上下文，并返回结构化结果。

Claude Agent SDK 适合什么

Claude Agent SDK 位于直接 Messages API 与托管 Agent 之间：应用自行运行进程，同时获得 Agent 循环和工具执行能力。它适合需要 Claude 专用 Agent 行为，又希望控制本地或服务端运行环境的场景。

若用 Pi 调用它，应把它视为一个下游执行器。例如让 Claude Agent SDK 在隔离工作树中完成一次审查，返回发现列表；Pi 再决定如何展示或处理。不要让双方都能无限委派对方。

OpenAI Agents SDK 适合什么

OpenAI Agents SDK 提供 Agent、工具、交接、护栏、会话和追踪等原语。需要文件系统、Shell、补丁和可恢复状态时，可以使用 Sandbox Agent，而不是把普通文本 Agent 直接开放到宿主机。

如果目标是构建独立的 Codex 风格编码服务，Sandbox Agent 比简单调用模型更接近完整执行环境。但它仍不是 Codex CLI 的透明远程接口，应用需要明确配置工作区清单、能力与沙箱客户端。

不要混淆 Codex CLI 与 Agents SDK

OpenAI Agents SDK 是构建 Agent 应用的开发库，Codex CLI 是面向本地编码工作的成品客户端。二者可能使用相同模型，但会话、工具、权限和系统行为不同。

因此，“通过 Agents SDK 连接 Codex”应准确表达为“通过 SDK 构建使用 OpenAI 模型的编码 Agent”。如果必须保留 Codex CLI 的具体行为，应使用其受支持的非交互或 SDK 接口，而不是假设普通 Agents SDK 会复刻全部功能。

为什么不建议双重 Agent 循环

让 Pi 的模型调用一个外部 Agent，外部 Agent 又自主调用工具，会产生以下问题：

两层系统提示可能互相冲突。
同一仓库内容被重复发送，Token 快速增长。
双方都可能修改文件，难以确定变更归属。
外层取消任务时，内层进程可能继续运行。
权限审批难以跨进程映射。
错误日志和调用链分散，故障定位困难。

如果必须采用两层结构，外层只负责路由，内层只完成一个有限任务，并设置委派深度为一。

设计稳定的请求协议

Pi 调用 SDK 服务时，建议使用 JSON Schema 验证请求：

{
  "task_id": "review-1042",
  "operation": "review_patch",
  "workspace": "isolated-worktree-id",
  "inputs": ["src/auth.ts"],
  "constraints": ["read_only", "no_network"],
  "timeout_seconds": 180
}

不要直接传递任意宿主机路径，也不要把用户文本拼入 Shell 命令。工作区应由服务端根据已授权标识解析。

设计可验证的响应协议

{
  "status": "success",
  "summary": "发现两个认证错误处理问题",
  "artifacts": [],
  "changed_files": [],
  "tests": [],
  "warnings": []
}

响应应包含状态、工件、真实变更、测试证据和警告。Pi 不能只相信下游 Agent 的自然语言“已完成”，而应重新读取差异、退出码或生成文件。

会话应该由谁管理

简单子任务优先使用无状态调用。需要连续多轮时，由一方拥有主会话，另一方只维护与子任务绑定的短期状态。不要同时把 Pi 全量历史写入外部 SDK 会话，再由 SDK 把完整历史回传给 Pi。

会话标识必须绑定用户、仓库、分支和任务，并设置过期时间。跨项目复用会话可能泄露代码或让模型基于旧状态修改错误文件。

工具和权限边界

每个工具应有最小权限。例如代码审查只开放读取和差异查看，生成补丁开放写入临时工作树，部署操作则需要单独人工批准。不要让外部 SDK 默认继承启动 Pi 进程的全部环境变量。

沙箱至少要限制文件系统、网络、进程、时间和资源。提示词限制不是安全控制；扩展拦截也不应是唯一防线。

错误、取消与重试

为每次 SDK 调用设置硬超时和取消信号。
取消外层任务时终止下游进程和子进程树。
只对明确的瞬时错误重试，并采用退避。
写入操作不要自动重放，除非具有幂等键。
保留提供商请求 ID，但对日志中的凭据脱敏。

模型拒绝、工具失败、限流和网络断开应使用不同错误类型，便于 Pi 决定提示用户、重试还是停止。

最小验证清单

用只读任务确认模型、流式输出和结构化响应。
验证错误 API Key 不会进入日志。
验证超时能终止真实下游任务。
在临时仓库测试单文件修改和回滚。
模拟工具返回超长内容与非法 JSON。
验证两个并发会话不会共享工作目录。
检查上下文压缩后仍保留任务约束。
比较下游报告与真实 Git 差异和测试结果。

常见问题

只是使用 Claude 模型需要 Claude Agent SDK 吗

通常不需要。使用 Pi 的受支持 Provider 更直接，Agent 循环仍由 Pi 负责。

OpenAI Agents SDK 等于 Codex SDK 吗

不等于。它是通用 Agent 开发库，可以构建编码工作流，但不会自动复制 Codex CLI 的全部行为。

可以把两个 Agent 的工具全部开放吗

不建议。应明确单一工具所有者，并按子任务提供最小能力。

如何避免循环委派

将最大委派深度限制为一，给请求加入任务 ID 和调用链，并拒绝重复任务指纹。

总结

Pi Agent 正确连接 Claude 或 Codex 的原则是先选最短链路：只换模型就使用 Pi Provider；嵌入 Pi 就用 Pi SDK 或 RPC；必须使用外部 Agent 能力时，再把 Claude Agent SDK 或 OpenAI Agents SDK 封装成隔离、结构化、可取消的子任务服务。保持单一主 Agent 循环、单一工具所有者和明确的认证计费边界，才能避免双重编排带来的成本与安全问题。