21 KiB

Raw Blame History

read_when

summary

title

x-i18n

理解 OpenClaw 中 Pi SDK 集成设计时

修改 Pi 的智能体会话生命周期、工具或提供商接线时

OpenClaw 内嵌 Pi 智能体集成与会话生命周期的架构

Pi 集成架构

generated_at	model	provider	source_hash	source_path	workflow
2026-03-29T04:10:02Z	gpt-5.4	openai	43a5d646ed66fab1492b6f18fb1623d895922ecf539e52e069d99e7e83c0be11	pi.md	15

Pi 集成架构

本文档介绍 OpenClaw 如何与 pi-coding-agent 及其同级软件包（pi-ai、pi-agent-core、pi-tui）集成，以提供其 AI 智能体能力。

概览

OpenClaw 使用 pi SDK 将 AI 编码智能体嵌入到其消息 Gateway 网关架构中。OpenClaw 不会将 pi 作为子进程启动，也不会使用 RPC 模式，而是通过 createAgentSession() 直接导入并实例化 pi 的 AgentSession。这种内嵌方式提供了：

对会话生命周期和事件处理的完全控制
自定义工具注入（消息、沙箱、渠道特定操作）
按渠道 / 上下文定制系统提示词
支持分支 / 压缩的会话持久化
带故障转移的多账户凭证配置轮换
与提供商无关的模型切换

软件包依赖

{
  "@mariozechner/pi-agent-core": "0.61.1",
  "@mariozechner/pi-ai": "0.61.1",
  "@mariozechner/pi-coding-agent": "0.61.1",
  "@mariozechner/pi-tui": "0.61.1"
}

软件包	用途
`pi-ai`	核心 LLM 抽象：`Model`、`streamSimple`、消息类型、提供商 API
`pi-agent-core`	智能体循环、工具执行、`AgentMessage` 类型
`pi-coding-agent`	高层 SDK：`createAgentSession`、`SessionManager`、`AuthStorage`、`ModelRegistry`、内置工具
`pi-tui`	终端 UI 组件（用于 OpenClaw 的本地 TUI 模式）

文件结构

src/agents/
├── pi-embedded-runner.ts          # Re-exports from pi-embedded-runner/
├── pi-embedded-runner/
│   ├── run.ts                     # Main entry: runEmbeddedPiAgent()
│   ├── run/
│   │   ├── attempt.ts             # Single attempt logic with session setup
│   │   ├── params.ts              # RunEmbeddedPiAgentParams type
│   │   ├── payloads.ts            # Build response payloads from run results
│   │   ├── images.ts              # Vision model image injection
│   │   └── types.ts               # EmbeddedRunAttemptResult
│   ├── abort.ts                   # Abort error detection
│   ├── cache-ttl.ts               # Cache TTL tracking for context pruning
│   ├── compact.ts                 # Manual/auto compaction logic
│   ├── extensions.ts              # Load pi extensions for embedded runs
│   ├── extra-params.ts            # Provider-specific stream params
│   ├── google.ts                  # Google/Gemini turn ordering fixes
│   ├── history.ts                 # History limiting (DM vs group)
│   ├── lanes.ts                   # Session/global command lanes
│   ├── logger.ts                  # Subsystem logger
│   ├── model.ts                   # Model resolution via ModelRegistry
│   ├── runs.ts                    # Active run tracking, abort, queue
│   ├── sandbox-info.ts            # Sandbox info for system prompt
│   ├── session-manager-cache.ts   # SessionManager instance caching
│   ├── session-manager-init.ts    # Session file initialization
│   ├── system-prompt.ts           # System prompt builder
│   ├── tool-split.ts              # Split tools into builtIn vs custom
│   ├── types.ts                   # EmbeddedPiAgentMeta, EmbeddedPiRunResult
│   └── utils.ts                   # ThinkLevel mapping, error description
├── pi-embedded-subscribe.ts       # Session event subscription/dispatch
├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams
├── pi-embedded-subscribe.handlers.ts # Event handler factory
├── pi-embedded-subscribe.handlers.lifecycle.ts
├── pi-embedded-subscribe.handlers.types.ts
├── pi-embedded-block-chunker.ts   # Streaming block reply chunking
├── pi-embedded-messaging.ts       # Messaging tool sent tracking
├── pi-embedded-helpers.ts         # Error classification, turn validation
├── pi-embedded-helpers/           # Helper modules
├── pi-embedded-utils.ts           # Formatting utilities
├── pi-tools.ts                    # createOpenClawCodingTools()
├── pi-tools.abort.ts              # AbortSignal wrapping for tools
├── pi-tools.policy.ts             # Tool allowlist/denylist policy
├── pi-tools.read.ts               # Read tool customizations
├── pi-tools.schema.ts             # Tool schema normalization
├── pi-tools.types.ts              # AnyAgentTool type alias
├── pi-tool-definition-adapter.ts  # AgentTool -> ToolDefinition adapter
├── pi-settings.ts                 # Settings overrides
├── pi-hooks/                      # Custom pi hooks
│   ├── compaction-safeguard.ts    # Safeguard extension
│   ├── compaction-safeguard-runtime.ts
│   ├── context-pruning.ts         # Cache-TTL context pruning extension
│   └── context-pruning/
├── model-auth.ts                  # Auth profile resolution
├── auth-profiles.ts               # Profile store, cooldown, failover
├── model-selection.ts             # Default model resolution
├── models-config.ts               # models.json generation
├── model-catalog.ts               # Model catalog cache
├── context-window-guard.ts        # Context window validation
├── failover-error.ts              # FailoverError class
├── defaults.ts                    # DEFAULT_PROVIDER, DEFAULT_MODEL
├── system-prompt.ts               # buildAgentSystemPrompt()
├── system-prompt-params.ts        # System prompt parameter resolution
├── system-prompt-report.ts        # Debug report generation
├── tool-summaries.ts              # Tool description summaries
├── tool-policy.ts                 # Tool policy resolution
├── transcript-policy.ts           # Transcript validation policy
├── skills.ts                      # Skill snapshot/prompt building
├── skills/                        # Skill subsystem
├── sandbox.ts                     # Sandbox context resolution
├── sandbox/                       # Sandbox subsystem
├── channel-tools.ts               # Channel-specific tool injection
├── openclaw-tools.ts              # OpenClaw-specific tools
├── bash-tools.ts                  # exec/process tools
├── apply-patch.ts                 # apply_patch tool (OpenAI)
├── tools/                         # Individual tool implementations
│   ├── browser-tool.ts
│   ├── canvas-tool.ts
│   ├── cron-tool.ts
│   ├── gateway-tool.ts
│   ├── image-tool.ts
│   ├── message-tool.ts
│   ├── nodes-tool.ts
│   ├── session*.ts
│   ├── web-*.ts
│   └── ...
└── ...

渠道特定的消息操作运行时现在位于插件自有的扩展目录中，而不是放在 src/agents/tools 下，例如：

extensions/discord/src/actions/runtime*.ts
extensions/slack/src/action-runtime.ts
extensions/telegram/src/action-runtime.ts
extensions/whatsapp/src/action-runtime.ts

核心集成流程

1. 运行内嵌智能体

主入口是 pi-embedded-runner/run.ts 中的 runEmbeddedPiAgent()：

import { runEmbeddedPiAgent } from "./agents/pi-embedded-runner.js";

const result = await runEmbeddedPiAgent({
  sessionId: "user-123",
  sessionKey: "main:whatsapp:+1234567890",
  sessionFile: "/path/to/session.jsonl",
  workspaceDir: "/path/to/workspace",
  config: openclawConfig,
  prompt: "Hello, how are you?",
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  timeoutMs: 120_000,
  runId: "run-abc",
  onBlockReply: async (payload) => {
    await sendToChannel(payload.text, payload.mediaUrls);
  },
});

2. 创建会话

在 runEmbeddedAttempt()（由 runEmbeddedPiAgent() 调用）内部，会使用 pi SDK：

import {
  createAgentSession,
  DefaultResourceLoader,
  SessionManager,
  SettingsManager,
} from "@mariozechner/pi-coding-agent";

const resourceLoader = new DefaultResourceLoader({
  cwd: resolvedWorkspace,
  agentDir,
  settingsManager,
  additionalExtensionPaths,
});
await resourceLoader.reload();

const { session } = await createAgentSession({
  cwd: resolvedWorkspace,
  agentDir,
  authStorage: params.authStorage,
  modelRegistry: params.modelRegistry,
  model: params.model,
  thinkingLevel: mapThinkingLevel(params.thinkLevel),
  tools: builtInTools,
  customTools: allCustomTools,
  sessionManager,
  settingsManager,
  resourceLoader,
});

applySystemPromptOverrideToSession(session, systemPromptOverride);

3. 事件订阅

subscribeEmbeddedPiSession() 会订阅 pi 的 AgentSession 事件：

const subscription = subscribeEmbeddedPiSession({
  session: activeSession,
  runId: params.runId,
  verboseLevel: params.verboseLevel,
  reasoningMode: params.reasoningLevel,
  toolResultFormat: params.toolResultFormat,
  onToolResult: params.onToolResult,
  onReasoningStream: params.onReasoningStream,
  onBlockReply: params.onBlockReply,
  onPartialReply: params.onPartialReply,
  onAgentEvent: params.onAgentEvent,
});

处理的事件包括：

message_start / message_end / message_update（流式文本 / 思考）
tool_execution_start / tool_execution_update / tool_execution_end
turn_start / turn_end
agent_start / agent_end
auto_compaction_start / auto_compaction_end

4. 发送提示

完成设置后，会向会话发送提示：

await session.prompt(effectivePrompt, { images: imageResult.images });

SDK 会处理完整的智能体循环：发送给 LLM、执行工具调用、流式返回响应。

图像注入仅限当前提示：OpenClaw 会从当前提示中加载图像引用，并仅通过 images 将其传入该轮。它不会重新扫描较早的历史轮次来重新注入图像负载。

工具架构

工具流水线

基础工具：pi 的 codingTools（read、bash、edit、write）
自定义替换：OpenClaw 用 exec / process 替换 bash，并为沙箱定制 read / edit / write
OpenClaw 工具：消息、浏览器、画布、会话、cron、Gateway 网关等
渠道工具：Discord / Telegram / Slack / WhatsApp 特定操作工具
策略过滤：按配置、提供商、智能体、群组、沙箱策略过滤工具
模式归一化：清理模式以适配 Gemini / OpenAI 的特殊行为
AbortSignal 包装：包装工具以遵循中止信号

工具定义适配器

pi-agent-core 的 AgentTool 与 pi-coding-agent 的 ToolDefinition 在 execute 签名上不同。pi-tool-definition-adapter.ts 中的适配器用于桥接这一差异：

export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
  return tools.map((tool) => ({
    name: tool.name,
    label: tool.label ?? name,
    description: tool.description ?? "",
    parameters: tool.parameters,
    execute: async (toolCallId, params, onUpdate, _ctx, signal) => {
      // pi-coding-agent signature differs from pi-agent-core
      return await tool.execute(toolCallId, params, signal, onUpdate);
    },
  }));
}

工具拆分策略

splitSdkTools() 会通过 customTools 传入所有工具：

export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) {
  return {
    builtInTools: [], // Empty. We override everything
    customTools: toToolDefinitions(options.tools),
  };
}

这样可以确保 OpenClaw 的策略过滤、沙箱集成和扩展工具集在不同提供商之间保持一致。

系统提示词构建

系统提示词在 buildAgentSystemPrompt()（system-prompt.ts）中构建。它会组装完整提示词，包含工具、工具调用风格、安全护栏、OpenClaw CLI 参考、Skills、文档、工作区、沙箱、消息、回复标签、语音、静默回复、心跳、运行时元数据等部分，并在启用时包含 Memory 和 Reactions，以及可选的上下文文件和额外系统提示词内容。为子智能体使用的最小提示词模式会对各部分进行裁剪。

系统提示词会在会话创建后通过 applySystemPromptOverrideToSession() 应用：

const systemPromptOverride = createSystemPromptOverride(appendPrompt);
applySystemPromptOverrideToSession(session, systemPromptOverride);

会话管理

会话文件

会话是具有树状结构（通过 id / parentId 关联）的 JSONL 文件。Pi 的 SessionManager 负责持久化：

const sessionManager = SessionManager.open(params.sessionFile);

OpenClaw 通过 guardSessionManager() 对其进行包装，以保证工具结果安全。

会话缓存

session-manager-cache.ts 会缓存 SessionManager 实例，以避免重复解析文件：

await prewarmSessionFile(params.sessionFile);
sessionManager = SessionManager.open(params.sessionFile);
trackSessionManagerAccess(params.sessionFile);

历史限制

limitHistoryTurns() 会根据渠道类型（私信与群组）裁剪对话历史。

压缩

上下文溢出时会触发自动压缩。compactEmbeddedPiSessionDirect() 负责手动压缩：

const compactResult = await compactEmbeddedPiSessionDirect({
  sessionId, sessionFile, provider, model, ...
});

身份验证与模型解析

凭证配置

OpenClaw 维护一个凭证配置存储，为每个提供商保存多个 API 密钥：

const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile });

配置会在失败时轮换，并跟踪冷却状态：

await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir });
const rotated = await advanceAuthProfile();

模型解析

import { resolveModel } from "./pi-embedded-runner/model.js";

const { model, error, authStorage, modelRegistry } = resolveModel(
  provider,
  modelId,
  agentDir,
  config,
);

// Uses pi's ModelRegistry and AuthStorage
authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);

故障转移

配置了回退时，FailoverError 会触发模型故障转移：

if (fallbackConfigured && isFailoverErrorMessage(errorText)) {
  throw new FailoverError(errorText, {
    reason: promptFailoverReason ?? "unknown",
    provider,
    model: modelId,
    profileId,
    status: resolveFailoverStatus(promptFailoverReason),
  });
}

Pi 扩展

OpenClaw 会加载自定义的 pi 扩展，以实现专门行为：

压缩保护

src/agents/pi-hooks/compaction-safeguard.ts 会为压缩添加护栏，包括自适应 token 预算，以及工具失败和文件操作摘要：

if (resolveCompactionMode(params.cfg) === "safeguard") {
  setCompactionSafeguardRuntime(params.sessionManager, { maxHistoryShare });
  paths.push(resolvePiExtensionPath("compaction-safeguard"));
}

上下文裁剪

src/agents/pi-hooks/context-pruning.ts 实现了基于 cache-TTL 的上下文裁剪：

if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") {
  setContextPruningRuntime(params.sessionManager, {
    settings,
    contextWindowTokens,
    isToolPrunable,
    lastCacheTouchAt,
  });
  paths.push(resolvePiExtensionPath("context-pruning"));
}

流式传输与分块回复

分块处理

EmbeddedBlockChunker 负责将流式文本管理为离散的回复块：

const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null;

思考 / 最终标签剥离

流式输出会经过处理，以去除 <think> / <thinking> 块并提取 <final> 内容：

const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => {
  // Strip <think>...</think> content
  // If enforceFinalTag, only return <final>...</final> content
};

回复指令

会解析并提取诸如 [[media:url]]、[[voice]]、[[reply:id]] 之类的回复指令：

const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk);

错误处理

错误分类

pi-embedded-helpers.ts 会对错误进行分类，以便进行适当处理：

isContextOverflowError(errorText)     // Context too large
isCompactionFailureError(errorText)   // Compaction failed
isAuthAssistantError(lastAssistant)   // Auth failure
isRateLimitAssistantError(...)        // Rate limited
isFailoverAssistantError(...)         // Should failover
classifyFailoverReason(errorText)     // "auth" | "rate_limit" | "quota" | "timeout" | ...

思考级别回退

如果某个思考级别不受支持，它会回退：

const fallbackThinking = pickFallbackThinkingLevel({
  message: errorText,
  attempted: attemptedThinking,
});
if (fallbackThinking) {
  thinkLevel = fallbackThinking;
  continue;
}

沙箱集成

启用沙箱模式时，工具和路径都会受到约束：

const sandbox = await resolveSandboxContext({
  config: params.config,
  sessionKey: sandboxSessionKey,
  workspaceDir: resolvedWorkspace,
});

if (sandboxRoot) {
  // Use sandboxed read/edit/write tools
  // Exec runs in container
  // Browser uses bridge URL
}

提供商特定处理

Anthropic

清理拒绝魔法字符串
针对连续角色的轮次验证
Claude Code 参数兼容性

Google / Gemini

轮次顺序修复（applyGoogleTurnOrderingFix）
工具模式净化（sanitizeToolsForGoogle）
会话历史净化（sanitizeSessionHistory）

OpenAI

面向 Codex 模型的 apply_patch 工具
思考级别降级处理

TUI 集成

OpenClaw 还提供本地 TUI 模式，可直接使用 pi-tui 组件：

// src/tui/tui.ts
import { ... } from "@mariozechner/pi-tui";

这提供了与 pi 原生模式类似的交互式终端体验。

与 Pi CLI 的关键差异

方面	Pi CLI	OpenClaw 内嵌版
调用方式	`pi` 命令 / RPC	通过 `createAgentSession()` 使用 SDK
工具	默认编码工具	自定义 OpenClaw 工具套件
系统提示词	AGENTS.md + prompts	按渠道 / 上下文动态生成
会话存储	`~/.pi/agent/sessions/`	`~/.openclaw/agents/<agentId>/sessions/`（或 `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`）
身份验证	单一凭证	支持轮换的多配置
扩展	从磁盘加载	通过编程方式 + 磁盘路径
事件处理	TUI 渲染	基于回调（`onBlockReply` 等）

未来考虑

潜在的重构方向包括：

工具签名对齐：当前需要在 pi-agent-core 与 pi-coding-agent 的签名之间进行适配
会话管理器包装：guardSessionManager 增加了安全性，但也提高了复杂度
扩展加载：可以更直接地使用 pi 的 ResourceLoader
流式处理器复杂度：subscribeEmbeddedPiSession 已经变得较大
提供商特殊行为：存在许多提供商特定代码路径，未来 pi 或许可以统一处理

测试

Pi 集成的覆盖范围包括以下测试套件：

src/agents/pi-*.test.ts
src/agents/pi-auth-json.test.ts
src/agents/pi-embedded-*.test.ts
src/agents/pi-embedded-helpers*.test.ts
src/agents/pi-embedded-runner*.test.ts
src/agents/pi-embedded-runner/**/*.test.ts
src/agents/pi-embedded-subscribe*.test.ts
src/agents/pi-tools*.test.ts
src/agents/pi-tool-definition-adapter*.test.ts
src/agents/pi-settings.test.ts
src/agents/pi-hooks/**/*.test.ts

实时 / 按需启用：

src/agents/pi-embedded-runner-extraparams.live.test.ts（启用 OPENCLAW_LIVE_TEST=1）

有关当前运行命令，请参见 Pi 开发工作流。

21 KiB Raw Blame History Unescape Escape

Pi 集成架构

概览

软件包依赖

文件结构

核心集成流程

1. 运行内嵌智能体

2. 创建会话

3. 事件订阅

4. 发送提示

工具架构

工具流水线

工具定义适配器

工具拆分策略

系统提示词构建

会话管理

会话文件

会话缓存

历史限制

压缩

身份验证与模型解析

凭证配置

模型解析

故障转移

Pi 扩展

压缩保护

上下文裁剪

流式传输与分块回复

分块处理

思考 / 最终标签剥离

回复指令

错误处理

错误分类

思考级别回退

沙箱集成

提供商特定处理

Anthropic

Google / Gemini

OpenAI

TUI 集成

与 Pi CLI 的关键差异

未来考虑

测试

21 KiB

Raw Blame History