古法编程

Appearance

OpenClaw 用 Pi 的 SDK 直接把 AI Agent 嵌入网关内部，不跑子进程也不走 RPC。核心是 createAgentSession() 建会话、runEmbeddedPiAgent() 执行一次 prompt，工具全部由 OpenClaw 接管（自定义 exec/process、消息、浏览器等），会话存为 JSONL 文件在 ~/.openclaw/agents/<agentId>/sessions/。常见报错如“上下文溢出”会自动触发压缩或故障转移；如果配置了 fallback 模型，还能自动切换 Provider 或档案。

OpenClaw Pi 集成架构：嵌入式 Agent 会话与工具配置指南 ​

OpenClaw 集成 pi-coding-agent 及其兄弟包（pi-ai、pi-agent-core、pi-tui）来驱动 AI Agent。以下详细说明架构和配置方式。

包依赖 ​

json
{
  "@earendil-works/pi-agent-core": "0.75.1",
  "@earendil-works/pi-ai": "0.75.1",
  "@earendil-works/pi-coding-agent": "0.75.1",
  "@earendil-works/pi-tui": "0.75.1"
}
包作用
pi-aiLLM 抽象层：Model、streamSimple、消息类型、Provider API
pi-agent-coreAgent 循环、工具执行、AgentMessage 类型
pi-coding-agent高阶 SDK：createAgentSession、SessionManager、AuthStorage、ModelRegistry、内置工具
pi-tui终端 UI 组件（用于 OpenClaw 的本地 TUI 模式）

核心文件结构 ​

src/agents/
├── pi-embedded-runner.ts               # 重导出 pi-embedded-runner/
├── pi-embedded-runner/
│   ├── run.ts                           # 主入口：runEmbeddedPiAgent()
│   ├── run/
│   │   ├── attempt.ts                   # 单次尝试，含会话设置
│   │   ├── params.ts                    # RunEmbeddedPiAgentParams 类型
│   │   ├── payloads.ts                  # 从运行结果构建响应载荷
│   │   ├── images.ts                    # 视觉模型图片注入
│   │   └── types.ts                     # EmbeddedRunAttemptResult
│   ├── abort.ts                         # 中止错误检测
│   ├── cache-ttl.ts                     # 缓存 TTL 追踪，用于上下文裁剪
│   ├── compact.ts                       # 手动/自动压缩逻辑
│   ├── extensions.ts                    # 加载 pi 扩展
│   ├── extra-params.ts                  # Provider 特定流参数
│   ├── google.ts                        # Google/Gemini turn 顺序修复
│   ├── history.ts                       # 历史限制（DM vs 群组）
│   ├── lanes.ts                         # 会话/全局命令通道
│   ├── logger.ts                        # 子系统日志
│   ├── model.ts                         # 通过 ModelRegistry 解析模型
│   ├── runs.ts                          # 活跃运行追踪、中止、队列
│   ├── sandbox-info.ts                  # 系统提示中的沙箱信息
│   ├── session-manager-cache.ts         # SessionManager 实例缓存
│   ├── session-manager-init.ts          # 会话文件初始化
│   ├── system-prompt.ts                 # 系统提示构建器
│   ├── tool-split.ts                    # 工具分为 builtIn vs custom
│   ├── types.ts                         # EmbeddedPiAgentMeta, EmbeddedPiRunResult
│   └── utils.ts                         # ThinkLevel 映射、错误描述
├── pi-embedded-subscribe.ts             # 会话事件订阅/分发
├── pi-embedded-subscribe.types.ts
├── pi-embedded-subscribe.handlers.ts
├── pi-embedded-subscribe.handlers.lifecycle.ts
├── pi-embedded-subscribe.handlers.types.ts
├── pi-embedded-block-chunker.ts         # 流式块回复分片
├── pi-embedded-messaging.ts             # 消息工具发送追踪
├── pi-embedded-helpers.ts               # 错误分类、turn 验证
├── pi-embedded-helpers/
├── pi-embedded-utils.ts                 # 格式化工具
├── pi-tools.ts                          # createOpenClawCodingTools()
├── pi-tools.abort.ts                    # AbortSignal 包装
├── pi-tools.policy.ts                   # 工具允许/拒绝策略
├── pi-tools.read.ts                     # Read 工具自定义
├── pi-tools.schema.ts                   # 工具 schema 规范化
├── pi-tools.types.ts                    # AnyAgentTool 类型别名
├── pi-tool-definition-adapter.ts        # AgentTool -> ToolDefinition 适配器
├── pi-settings.ts                       # 设置覆盖
├── pi-hooks/                            # 自定义 pi 扩展
│   ├── compaction-safeguard.ts          # 压缩安全保障
│   ├── compaction-safeguard-runtime.ts
│   ├── context-pruning.ts               # 缓存 TTL 上下文裁剪
│   └── context-pruning/
├── model-auth.ts                        # 认证档案解析
├── auth-profiles.ts                     # 档案存储、冷却、故障转移
├── model-selection.ts                   # 默认模型解析
├── models-config.ts                     # models.json 生成
├── model-catalog.ts                     # 模型目录缓存
├── context-window-guard.ts              # 上下文窗口验证
├── failover-error.ts                    # FailoverError 类
├── defaults.ts                          # DEFAULT_PROVIDER, DEFAULT_MODEL
├── system-prompt.ts                     # buildAgentSystemPrompt()
├── system-prompt-params.ts              # 系统提示参数解析
├── system-prompt-report.ts              # 调试报告生成
├── tool-summaries.ts                    # 工具描述摘要
├── tool-policy.ts                       # 工具策略解析
├── transcript-policy.ts                 # 转录验证策略
├── skills.ts                            # Skill 快照/提示构建
├── skills/
├── sandbox.ts                           # 沙箱上下文解析
├── sandbox/
├── channel-tools.ts                     # 频道特定工具注入
├── openclaw-tools.ts                    # OpenClaw 特定工具
├── bash-tools.ts                        # exec/process 工具
├── apply-patch.ts                       # apply_patch 工具（OpenAI）
├── tools/
│   ├── 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
│   └── ...
└── ...

频道特定动作的运行时代码现已迁移到插件自有扩展目录，例如 Discord、Slack、Telegram、WhatsApp 的动作运行时文件分别位于各插件目录中。

核心集成流程 ​

1. 运行嵌入式 Agent ​

主入口 runEmbeddedPiAgent() 在 pi-embedded-runner/run.ts：

typescript
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-6",
  timeoutMs: 120_000,
  runId: "run-abc",
  onBlockReply: async (payload) => {
    await sendToChannel(payload.text, payload.mediaUrls);
  },
});

2. 会话创建 ​

内部调用 runEmbeddedAttempt()，通过 Pi SDK 创建会话：

typescript
import {
  createAgentSession,
  DefaultResourceLoader,
  SessionManager,
  SettingsManager,
} from "@earendil-works/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() 订阅 AgentSession 事件：

typescript
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
  • compaction_start / compaction_end

4. 提示 ​

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

图片注入是 prompt-local 的：只从当前 prompt 加载图片，不会回扫历史 turns。

工具架构 ​

工具流水线 ​

  1. 基础工具：Pi 的 codingTools（read、bash、edit、write）
  2. 自定义替换：OpenClaw 用 exec/process 替换 bash，为沙箱自定义 read/edit/write
  3. OpenClaw 工具：messaging、browser、canvas、sessions、cron、gateway 等
  4. 频道工具：各 IM 渠道的动作工具
  5. 策略过滤：按档案、Provider、Agent、群组、沙箱策略过滤
  6. Schema 规范化：清理 Gemini/OpenAI 的 schema 不兼容
  7. AbortSignal 包装：工具支持中止信号

工具定义适配器 ​

pi-agent-core 的 AgentTool 与 pi-coding-agent 的 ToolDefinition 的 execute 签名不同，适配器 pi-tool-definition-adapter.ts 桥接：

typescript
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) => {
      return await tool.execute(toolCallId, params, signal, onUpdate);
    },
  }));
}

工具分割策略 ​

splitSdkTools() 把所有工具都作为 customTools 传入，builtInTools 留空（全部覆盖自定义工具），确保策略过滤和沙箱集成一致。

系统提示构建 ​

buildAgentSystemPrompt() 组装完整的系统提示，包含：

  • Tooling（工具说明）
  • Tool Call Style（工具调用风格）
  • Safety guardrails（安全护栏）
  • OpenClaw Control（OpenClaw 指令）
  • Skills、Docs、Workspace、Sandbox、Messaging
  • Assistant Output Directives（输出指令）
  • Voice、Silent Replies、Heartbeats
  • Runtime metadata（运行时元数据）
  • 可选的 Memory、Reactions、Context Files、Extra System Prompt

子 Agent 使用最小提示模式时会裁剪各节。

提示通过 applySystemPromptOverrideToSession() 在会话创建后应用。

会话管理 ​

会话文件 ​

JSONL 格式，树形结构（通过 id/parentId 链接）。Pi 的 SessionManager 负责持久化：

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

OpenClaw 用 guardSessionManager() 包装以保证工具结果安全。

会话缓存 ​

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

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

历史限制 ​

limitHistoryTurns() 根据频道类型（DM vs 群组）裁剪对话历史。

压缩 ​

上下文溢出时触发自动压缩。常见溢出错误签名包括：

request_too_large
context length exceeded
input exceeds the maximum number of tokens
input token count exceeds the maximum number of input tokens
input is too long for the model
ollama error: context length exceeded

手动压缩入口：

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

认证与模型解析 ​

认证档案 ​

每个 Provider 支持多个 API Key，档案存储自动轮换：

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

失败时冷却并轮换：

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

模型解析 ​

typescript
const { model, error, authStorage, modelRegistry } = resolveModel(
  provider,
  modelId,
  agentDir,
  config,
);
authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);

故障转移 ​

FailoverError 触发模型回退：

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

Pi 扩展 ​

OpenClaw 加载自定义扩展实现专用行为：

压缩安全保障 ​

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

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

上下文裁剪（Cache-TTL） ​

src/agents/pi-hooks/context-pruning.ts：基于缓存 TTL 的上下文裁剪。

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

流式传输与块回复 ​

块分片 ​

EmbeddedBlockChunker 将流式文本切分为离散回复块。

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

思考/最终标签剥离 ​

流式输出处理 &lt;think&gt;/&lt;thinking&gt; 块并提取 &lt;final&gt; 内容：

typescript
const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => {
  // 剥离 <think>...</think> 内容
  // 若 enforceFinalTag，只返回 <final>...</final> 内容
};

回复指令 ​

[[media:url]]、[[voice]]、[[reply:id]] 等指令被解析并提取。

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

错误处理 ​

错误分类 ​

typescript
isContextOverflowError(errorText)     // 上下文过大
isCompactionFailureError(errorText)   // 压缩失败
isAuthAssistantError(lastAssistant)   // 认证失败
isRateLimitAssistantError(...)        // 限速
isFailoverAssistantError(...)         // 应故障转移
classifyFailoverReason(errorText)     // "auth" | "rate_limit" | "quota" | "timeout" | ...

思考级别回退 ​

若思考级别不受支持，自动回退：

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

沙箱集成 ​

启用沙箱时，工具和路径受限：

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

if (sandboxRoot) {
  // 使用沙箱化的 read/edit/write 工具
  // Exec 在容器内运行
  // 浏览器使用桥接 URL
}

Provider 特殊处理 ​

Anthropic ​

  • 拒绝魔法字符串清理
  • 连续角色的 turn 验证
  • 严格的上游 Pi 工具参数校验

Google/Gemini ​

  • tool schema 清理

OpenAI ​

  • apply_patch 工具（用于 Codex 模型）
  • 思考级别降级处理

TUI 集成 ​

OpenClaw 内置本地 TUI 模式，直接使用 pi-tui：

typescript
// src/tui/tui.ts
import { ... } from "@earendil-works/pi-tui";

与 Pi CLI 的差异 ​

方面Pi CLIOpenClaw 嵌入式
调用方式pi 命令 / RPCSDK 调用 createAgentSession()
工具默认编码工具自定义 OpenClaw 工具套件
系统提示AGENTS.md + prompts动态按频道/上下文生成
会话存储~/.pi/agent/sessions/~/.openclaw/agents/<agentId>/sessions/ （或 $OPENCLAW_STATE_DIR/agents/<agentId>/sessions/）
认证单一凭证多档案轮换，支持故障转移
扩展从磁盘加载编程式 + 磁盘路径
事件处理TUI 渲染回调式（onBlockReply, onToolResult 等）

未来重构方向 ​

  1. 工具签名对齐：当前需适配 pi-agent-core 与 pi-coding-agent 签名
  2. SessionManager 包装：guardSessionManager 增加安全但增加复杂度
  3. 扩展加载：可改用 Pi 的 ResourceLoader 更直接
  4. 流式处理器复杂度：subscribeEmbeddedPiSession 已膨胀
  5. Provider 特殊路径：许多 provider 特定代码，未来 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 开发工作流。

常见问题 ​

怎么让 OpenClaw 用 Pi Agent 时自动切换 API Key 或模型？ ​

配置多个认证档案并在 openclaw.yaml 的 agents.defaults.failover 中指定 fallback 模型。运行时 FailoverError 会触发轮换，同时 auth-profiles.ts 管理冷却与重试。

会话文件超过模型上下文窗口后 Agent 会崩溃吗？ ​

不会。OpenClaw 内置两种自动处理：自动压缩（在 compact.ts 中检测溢出签名）和基于缓存 TTL 的上下文裁剪（pi-hooks/context-pruning.ts）。如果压缩失败，compactEmbeddedPiSessionDirect() 可手动触发。

为什么有些工具在 Gemini 下报 schema 错误？ ​

Google/Gemini 对工具参数 schema 要求严格，OpenClaw 通过 pi-tools.schema.ts 做规范化清理。如果还是报错，检查工具参数是否包含 additionalProperties 或 const 等 Gemini 不支持的关键字。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策