OpenClaw Agents 深度解析

——基于官方文档的系统化技术指南

本文按照 OpenClaw 官方文档结构编写，深入解析 Agents 核心机制。

一、Fundamentals

1.1 PI 集成架构

OpenClaw 使用 pi SDK 将 AI 编程 Agent 嵌入到消息 Gateway 架构中。通过 createAgentSession() 直接导入并实例化 pi 的 AgentSession，而非作为子进程或 RPC 模式。

核心入口：runEmbeddedPiAgent()

这是整个 Agent 运行的主入口函数，负责初始化并执行一个完整的 Agent 会话：

typescript

// src/agents/pi-embedded-runner/run.ts
// 作用：启动嵌入式 Agent 会话的核心入口函数
// 功能：验证参数 → 创建 Session → 执行 Agent 循环 → 返回结果
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,          // OpenClaw 配置
  prompt: "Hello",                // 用户输入
  provider: "anthropic",           // 模型提供商
  model: "claude-sonnet-4-20250514", // 使用的模型
  timeoutMs: 120_000,             // 超时时间（毫秒）
  runId: "run-abc",               // 此次运行的唯一标识
  onBlockReply: async (payload) => {  // 块回复回调
    await sendToChannel(payload.text, payload.mediaUrls);
  },
});

嵌入式方法的优势：

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

包依赖：

包	用途
`pi-ai`	核心 LLM 抽象：`Model`、`streamSimple`、消息类型
`pi-agent-core`	Agent 循环、工具执行、`AgentMessage` 类型
`pi-coding-agent`	高级 SDK：`createAgentSession`、`SessionManager`
`pi-tui`	终端 UI 组件

源码文件结构：

src/agents/
├── pi-embedded-runner/
│   ├── run.ts                     # 主入口 runEmbeddedPiAgent()
│   ├── run/
│   │   ├── attempt.ts             # 单次尝试逻辑
│   │   ├── params.ts              # 参数类型
│   │   ├── payloads.ts           # 构建响应负载
│   │   └── types.ts               # 结果类型
│   ├── compact.ts                 # 压缩逻辑
│   ├── model.ts                   # 模型解析
│   ├── system-prompt.ts           # 系统提示构建
│   ├── session-manager-cache.ts   # SessionManager 缓存
│   └── ...
├── pi-embedded-subscribe.ts       # 事件订阅/分发
├── pi-tools.ts                    # 创建 OpenClaw 工具
└── ...

1.2 整体架构

┌─────────────────────────────────────────────────────────────┐
│                      Gateway                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │WhatsApp │  │Telegram │  │Discord  │  │ ...20+  │       │
│  │ Baileys │  │ grammY  │  │  API    │  │Channels │       │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│       │            │            │            │             │
│       └────────────┴────────────┴────────────┘             │
│                         │                                   │
│              ┌──────────┴──────────┐                       │
│              │   Agent Runtime      │                       │
│              │  (pi-mono embedded)  │                       │
│              └──────────┘                            │
│                         │                                   │
│  ┌──────────────────────┼──────────────────────┐          │
│  │         Workspace / Agent Dir               │          │
│  └─────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────┘

1.3 Agent 核心概念

什么是 Agent？

Agent 是一个完整独立的"大脑"，每个 Agent 拥有：

独立的工作空间 (Workspace)
独立的状态目录 (Agent Dir)
独立的会话存储 (Session Store)
独立的认证配置

Agent Dir 结构：

~/.openclaw/agents/<agentId>/
├── agent/
│   ├── auth-profiles.json    # 认证配置（每个Agent独立）
│   └── models.json           # 模型配置
└── sessions/
    └── <SessionId>.jsonl     # 会话历史

1.4 Agent 循环生命周期

核心流程：

┌─────────────────────────────────────────────┐
│           Agent Loop 生命周期                 │
├─────────────────────────────────────────────┤
│ 1. 入口验证                                  │
│    └─ 验证参数 → 解析会话 → 持久化元数据    │
│                                             │
│ 2. Agent 命令执行                            │
│    ├─ 解析模型 + thinking/verbose 配置      │
│    ├─ 加载 Skills 快照                       │
│    └─ 调用 runEmbeddedPiAgent               │
│                                             │
│ 3. PI 运行时                                 │
│    ├─ 通过会话/全局队列序列化运行            │
│    ├─ 解析模型 + 认证配置                   │
│    ├─ 构建 PI 会话                          │
│    └─ 订阅 PI 事件并流式输出                │
│                                             │
│ 4. 事件桥接                                  │
│    ├─ tool events → stream: "tool"         │
│    ├─ assistant deltas → stream: "assistant" │
│    └─ lifecycle events → stream: "lifecycle" │
│                                             │
│ 5. 超时控制                                  │
│    └─ agents.defaults.timeoutSeconds (默认 600s) │
└─────────────────────────────────────────────┘

Session 创建内部流程

在 runEmbeddedPiAgent 内部，会调用 createAgentSession 来创建 pi 的会话对象：

typescript

// src/agents/pi-embedded-runner/run/attempt.ts
// 作用：创建 pi SDK 的 AgentSession 对象
// 功能：初始化资源加载器 → 配置认证存储 → 创建会话 → 应用系统提示
const { session } = await createAgentSession({
  cwd: resolvedWorkspace,           // 工作目录,
  agentDir                         // Agent 状态目录
  authStorage: params.authStorage,   // 认证存储
  modelRegistry: params.modelRegistry, // 模型注册表
  model: params.model,              // 使用的模型
  thinkingLevel: mapThinkingLevel(params.thinkLevel), // 推理级别
  tools: builtInTools,              // 内置工具
  customTools: allCustomTools,      // 自定义工具
  sessionManager,                   // 会话管理器
  settingsManager,                  // 设置管理器
  resourceLoader,                   // 资源加载器
});

// 应用系统提示覆盖（自定义提示词）
// src/agents/pi-embedded-runner/system-prompt.ts
applySystemPromptOverrideToSession(session, systemPromptOverride);

事件订阅机制

订阅 pi 会话的事件，以便实时处理 Agent 的输出：

typescript

// src/agents/pi-embedded-subscribe.ts
// 作用：订阅 AgentSession 的事件流
// 功能：监听工具执行、推理过程、块回复、生命周期事件
const subscription = subscribeEmbeddedPiSession({
  session: activeSession,          // 活动的会话对象
  runId: params.runId,              // 运行 ID
  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

1.5 系统提示词构建

Prompt 构建函数

构建系统提示词的核心函数：

typescript

// src/agents/pi-embedded-runner/system-prompt.ts
// 作用：构建完整的系统提示词
// 功能：组装 13 个章节，包括工具、安全、技能、工作空间等信息
export function buildAgentSystemPrompt(params: SystemPromptParams): string {
  // 构建完整提示词，包含 13 个章节
  // 返回格式化的提示词字符串
}

完整结构：

┌─────────────────────────────────────────────┐
│  1. Tooling — 工具列表 + 简短描述           │
│  2. Safety — 安全边界提醒                    │
│  3. Skills — 可用技能列表（按需）           │
│  4. OpenClaw Self-Update — 更新方式         │
│  5. Workspace — 工作目录                   │
│  6. Documentation — 文档路径                │
│  7. Sandbox — 沙箱信息（如果启用）          │
│  8. Current Date & Time — 当前时间          │
│  9. Reply Tags — 回复标签语法               │
│  10. Heartbeats — 心跳提示                  │
│  11. Runtime — 运行时信息                   │
│  12. Reasoning — 推理可见性                 │
│  13. Project Context — 注入的工作空间文件   │
└─────────────────────────────────────────────┘

Prompt 模式：

模式	用途	包含内容
`full`	主会话	所有章节
`minimal`	子 Agent	仅 AGENTS.md + TOOLS.md
`none`	极简	仅基础身份行

应用系统提示

将构建好的提示词应用到会话：

typescript

// src/agents/pi-embedded-runner/system-prompt.ts
// 作用：将自定义系统提示应用到会话
// 功能：覆盖默认提示，注入 OpenClaw 特定的指令
const systemPromptOverride = createSystemPromptOverride(appendPrompt);
applySystemPromptOverrideToSession(session, systemPromptOverride);

1.6 Context 上下文

Context 包含的内容：

System prompt（所有章节）
Conversation history（对话历史）
Tool calls + tool results（工具调用结果）
Attachments（附件/图片/音频）
Compaction summaries（压缩摘要）

上下文守卫

验证上下文窗口是否超出限制：

typescript

// src/agents/pi-embedded-runner/context-window-guard.ts
// 作用：验证当前上下文是否超出模型限制
// 功能：检查 token 数量，预防上下文溢出
export function validateContextWindow(context: Context): boolean {
  // 检查是否超过模型的上下文窗口
  // 返回是否需要触发压缩
}

上下文检查命令：

/status — 快速查看上下文使用情况
/context list — 查看注入的文件和大小
/context detail — 详细分解

1.7 Workspace 工作空间

默认位置：~/.openclaw/workspace

工作空间布局：

~/.openclaw/workspace/
├── AGENTS.md              # 核心指令（必选）
├── SOUL.md                # 人设定义（必选）
├── TOOLS.md               # 工具笔记
├── IDENTITY.md            # 身份信息
├── USER.md                # 用户信息
├── MEMORY.md              # 长期记忆
├── HEARTBEAT.md           # 心跳任务
├── memory/                # 每日笔记
│   └── YYYY-MM-DD.md
└── skills/                # 技能扩展

1.8 OAuth 认证

认证配置管理

管理多认证配置的存储和轮换：

typescript

// src/agents/auth-profiles.ts
// 作用：管理认证配置（API Key、OAuth Token）
// 功能：存储、加载、轮换认证凭证
class AuthProfileStore {
  // 认证配置存储、冷启动、故障转移
}

// src/agents/pi-embedded-helpers.ts
// 作用：分类故障转移原因
// 功能：识别错误类型，决定是否切换认证配置
classifyFailoverReason(errorText)  // 返回: "auth" | "rate_limit" | "quota" | "timeout"

支持的认证方式：

API Key
OAuth（支持 Claude Code、OpenAI、Google 等）
认证配置轮换 + 故障转移

二、Bootstrapping

2.1 什么是 Bootstrapping？

Bootstrapping 是 OpenClaw 的首次运行仪式，发生在 onboarding 之后、Agent 第一次启动时：

创建工作空间并播种初始文件
收集身份信息（通过问答形式）
生成角色定义（写入 IDENTITY.md、USER.md、SOUL.md）
删除仪式文件（BOOTSTRAP.md 仅执行一次）

2.2 Bootstrap 文件

文件	作用
`AGENTS.md`	Agent 操作指令
`SOUL.md`	人设、语气
`USER.md`	用户信息
`IDENTITY.md`	Agent 名称/emoji
`BOOTSTRAP.md`	首次仪式

注意：HEARTBEAT.md、MEMORY.md、TOOLS.md 是工作空间文件，但不是 Bootstrap 播种的。

2.3 文件大小限制

typescript

// src/agents/pi-embedded-runner/types.ts
// 作用：定义 Bootstrap 文件大小限制
interface EmbeddedPiAgentMeta {
  bootstrapMaxChars: number;      // 单文件最大字符数，默认 20,000
  bootstrapTotalMaxChars: number; // 总注入最大字符数，默认 150,000
}

单文件上限：agents.defaults.bootstrapMaxChars（默认 20,000 字符）
总注入上限：agents.defaults.bootstrapTotalMaxChars（默认 150,000 字符）

2.4 禁用 Bootstrap

json5

// ~/.openclaw/openclaw.json
// 作用：跳过 Bootstrap 流程
// 功能：禁用首次运行仪式，使用现有的工作空间文件
{
  agents: {
    skipBootstrap: true
  }
}

三、Sessions and Memory

3.1 Session 会话管理

会话 ID 结构：

agent:<agentId>:<mainKey>

DM 作用域模式：

模式	说明	适用
`main`（默认）	所有 DM 共享主会话	单用户
`per-peer`	按发送者隔离	多用户
`per-channel-peer`	按频道+发送者隔离	推荐多用户
`per-account-channel-peer`	按账号+频道+发送者隔离	多账号

安全警告：多人 DM 场景务必启用 per-channel-peer，否则会隐私泄露。

会话存储：

元数据：~/.openclaw/agents/<agentId>/sessions/sessions.json
历史：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

3.2 会话维护策略

json5

// ~/.openclaw/openclaw.json
// 作用：控制会话存储的自动清理
// 功能：自动删除过期会话、轮转大文件、限制磁盘使用
{
  session: {
    maintenance: {
      mode: "warn",           // warn = 仅警告，enforce = 执行清理
      pruneAfter: "30d",      // 无活动多少天后删除
      maxEntries: 500,        // 最大会话数
      rotateBytes: "10mb",   // 超过多少字节轮转
      maxDiskBytes: "1gb",   // 磁盘上限
    }
  }
}

3.3 Session Tool

会话操作工具

允许 Agent 操作会话的工具实现：

工具	功能	源码位置
`sessions_list`	列出会话	`src/agents/tools/session*.ts`
`sessions_history`	获取历史	`src/agents/tools/session*.ts`
`sessions_send`	跨会话发送	`src/agents/tools/session*.ts`
`sessions_spawn`	启动子 Agent	`src/agents/tools/session*.ts`

3.4 Memory 记忆机制

双层架构：

┌─────────────────────────────────────────────┐
│ Layer 1: 短期记忆                           │
│ memory/YYYY-MM-DD.md                         │
│ • 每日日志                                  │
│ • 会话开始时读取 今日 + 昨日                │
│                                             │
│ Layer 2: 长期记忆                          │
│ MEMORY.md                                   │
│ • 精选持久化记忆                            │
│ • 仅在主会话加载                            │
└─────────────────────────────────────────────┘

记忆工具

工具	功能	源码位置
`memory_search`	语义搜索	`src/agents/memory-*.ts`
`memory_get`	读取指定文件/行	`src/agents/memory-*.ts`

3.5 自动记忆刷新

压缩前的记忆刷新

在自动压缩触发前，提醒模型写入持久记忆：

typescript

// src/agents/pi-embedded-runner/compact.ts
// 作用：在会话压缩前触发静默的 Agent 轮次
// 功能：让模型有机会将重要信息写入持久记忆文件
export async function memoryFlushBeforeCompaction(params: FlushParams): Promise<void> {
  // 触发静默 Agent 轮次
  // 写入 memory/YYYY-MM-DD.md
}

json5

// ~/.openclaw/openclaw.json
// 作用：配置自动记忆刷新
// 功能：在上下文即将压缩前，提醒模型保存记忆
{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          enabled: true,                    // 是否启用
          softThresholdTokens: 4000,        // 触发阈值
        }
      }
    }
  }
}

3.6 向量搜索

支持对记忆建立向量索引：

远程：OpenAI / Gemini / Voyage / Mistral
本地：node-llama-cpp
可选后端：QMD（实验性）

3.7 Compaction 压缩

会话压缩逻辑

当上下文接近上限时，自动压缩旧历史：

typescript

// src/agents/pi-embedded-runner/compact.ts
// 作用：压缩会话历史，释放上下文空间
// 功能：保留最新对话 → 压缩旧历史为摘要 → 写入会话文件
export async function compactSession(params: CompactParams): Promise<CompactionResult> {
  // 保留最新对话
  // 压缩旧历史为摘要
  // 释放 token 空间
}

四、Multi-agent

4.1 多 Agent 架构

Multi-agent 允许同一 Gateway 运行多个隔离的 Agent：

独立工作空间
独立认证配置
独立会话存储
独立渠道绑定

4.2 Bindings 路由机制

绑定配置

决定消息路由到哪个 Agent：

json5

// ~/.openclaw/openclaw.json
// 作用：配置消息到 Agent 的路由规则
// 功能：根据渠道、账号等信息匹配 Agent
{
  agents: {
    list: [
      { id: "home", workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" }
    ]
  },
  bindings: [
    // WhatsApp 个人号 -> Home Agent
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    // Telegram -> Work Agent
    { agentId: "work", match: { channel: "telegram" } }
  ]
}

4.3 路由优先级

peer — 精确 DM/群组 ID
parentPeer — 线程继承
guildId + roles — Discord 角色
guildId — Discord 服务器
teamId — Slack
accountId — 渠道账号
频道级 — 通配
默认 Agent

4.4 多账号支持

json5

// ~/.openclaw/openclaw.json
// 作用：支持同一渠道的多个账号
// 功能：每个账号独立的认证和会话
{
  channels: {
    whatsapp: {
      accounts: {
        personal: {},   // 个人账号
        biz: {}        // 商务账号
      }
    }
  }
}

4.5 Presence 在线状态

显示 Agent 在线/离开状态
支持 Typing indicators
可追踪设备连接状态

五、Messages and Delivery

5.1 消息流程

Inbound message
      ↓
  路由/绑定 → session key
      ↓
  队列（如果正在运行）
      ↓
  Agent 运行（流式输出 + 工具调用）
      ↓
  出站回复（渠道限制 + 分块）

5.2 消息去重

渠道重连后可能重复投递，OpenClaw 使用短生命周期缓存避免重复触发。

5.3 消息防抖

防抖配置

合并短时间内的多次消息：

json5

// ~/.openclaw/openclaw.json
// 作用：防止快速连续消息触发多次 Agent 运行
// 功能：debounceMs 时间内只处理最后一条消息
{
  messages: {
    inbound: {
      debounceMs: 2000,              // 全局默认 2 秒
      byChannel: {
        whatsapp: 5000,  // WhatsApp 特殊处理 5 秒
        discord: 1500     // Discord 1.5 秒
      }
    }
  }
}

5.4 队列模式

队列模式配置

当 Agent 正在运行时，新消息的处理方式：

模式	行为
`steer`	注入当前运行
`followup`	结束后加入队列
`collect`	合并为单个轮次（默认）
`steer-backlog`	注入+保留后续
`interrupt`	中断当前运行

json5

// ~/.openclaw/openclaw.json
// 作用：配置消息队列行为
// 功能：控制并发消息的处理策略
{
  messages: {
    queue: {
      mode: "collect",        // 默认合并为单轮
      debounceMs: 1000,       // 等待静默时间
      cap: 20,               // 最大队列长度
      drop: "summarize"      // 溢出策略：生成摘要
    }
  }
}

5.5 Streaming 流式输出

块流式处理

将 Agent 输出分块发送，而非等待完整响应：

typescript

// src/agents/pi-embedded-block-chunker.ts
// 作用：将流式输出分块
// 功能：按字符数/段落分割，控制发送节奏
export function chunkBlockReply(params: ChunkParams): BlockChunk[] {
  // 分块逻辑：800-1200 字符，优先段落断点
  // 返回分块数组
}

Reply 指令解析

解析嵌入在回复中的特殊指令：

typescript

// src/agents/pi-embedded-runner/run/payloads.ts
// 作用：解析回复中的特殊指令
// 功能：提取 [[media:url]], [[voice]], [[reply:id]] 等指令
export function consumeReplyDirectives(chunk: string): ReplyDirectives {
  // 解析指令
  // 返回纯文本 + 指令参数
  const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk);
}

json5

// ~/.openclaw/openclaw.json
// 作用：配置流式输出行为
// 功能：块大小、断点、人类化延迟
{
  agents: {
    defaults: {
      blockStreamingDefault: "on",      // 开启块流式
      blockStreamingBreak: "text_end",   // 断点：text_end 或 message_end
      blockStreamingChunk: "800-1200",   // 块大小范围
      blockStreamingCoalesce: true,      // 空闲时合并
      humanDelay: 500                    // 块之间延迟（毫秒）
    }
  }
}

5.6 Retry 重试机制

错误分类

识别不同类型的错误，决定重试策略：

typescript

// src/agents/pi-embedded-helpers.ts
// 作用：分类错误类型
// 功能：根据错误信息判断错误原因，返回对应的处理策略

// 上下文溢出 - 需要压缩后重试
export function isContextOverflowError(errorText: string): boolean { }

// 压缩失败 - 记录日志，继续尝试
export function isCompactionFailureError(errorText: string): boolean { }

// 认证失败 - 切换认证配置
export function isAuthAssistantError(lastAssistant: string): boolean { }

// 速率限制 - 等待后重试
export function isRateLimitAssistantError(...args: unknown[]): boolean { }

// 应该触发故障转移
export function isFailoverAssistantError(...args: unknown[]): boolean { }

// 分类故障转移原因
export function classifyFailoverReason(errorText: string): "auth" | "rate_limit" | "quota" | "timeout" { }

Thinking Level 回退

当模型不支持指定推理级别时，自动降级：

typescript

// src/agents/pi-embedded-helpers.ts
// 作用：选择降级后的推理级别
// 功能：检查模型能力，选择最接近的可用级别
export function pickFallbackThinkingLevel(params: FallbackParams): ThinkingLevel | null {
  // 如果 thinking level 不支持，自动回退
}

5.7 推理可见性

/reasoning on|off|stream

模式	说明
`on`	显示推理
`off`	隐藏推理
`stream`	流式显示（Telegram）

六、工具系统

6.1 工具架构

工具管道

从原始工具到最终执行的完整处理流程：

1. Base Tools (pi codingTools)        # pi 内置的 read/bash/edit/write
      ↓
2. Custom Replacements (exec/process)  # 替换为 OpenClaw 版本
      ↓
3. OpenClaw Tools                     # 添加 messaging, browser, sessions 等
      ↓
4. Channel Tools                      # 添加 Discord/Telegram/WhatsApp 操作
      ↓
5. Policy Filtering                   # 根据 allow/deny 过滤
      ↓
6. Schema Normalization                # 适配不同 Provider 的 Schema
      ↓
7. AbortSignal Wrapping               # 包装以支持中止信号

Tool Definition Adapter

适配不同版本的 pi 工具定义接口：

typescript

// src/agents/pi-tool-definition-adapter.ts
// 作用：桥接 pi-agent-core 和 pi-coding-agent 的工具接口
// 功能：将 AgentTool 转换为 ToolDefinition
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);
    },
  }));
}

Tool Split Strategy

分离内置工具和自定义工具：

typescript

// src/agents/pi-embedded-runner/tool-split.ts
// 作用：分离内置工具和自定义工具
// 功能：决定哪些工具走 builtIn，哪些走 customTools
export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }): ToolSplitResult {
  return {
    builtInTools: [], // 全部覆盖为空，使用自定义
    customTools: toToolDefinitions(options.tools),
  };
}

6.2 内置工具

工具实现位置

工具	功能	源码位置
`read`	读取文件	`src/agents/pi-tools.read.ts`
`write`	写入文件	`src/agents/pi-tools.ts`
`edit`	编辑文件	`src/agents/pi-tools.ts`
`exec`	执行命令	`src/agents/bash-tools.ts`
`process`	管理进程	`src/agents/bash-tools.ts`
`browser`	浏览器自动化	`src/agents/tools/browser-tool.ts`
`message`	发送消息	`src/agents/tools/message-tool.ts`
`memory_search`	语义搜索	`src/agents/memory-*.ts`
`memory_get`	读取记忆	`src/agents/memory-*.ts`

工具源码结构：

src/agents/tools/
├── browser-tool.ts         # 浏览器控制
├── canvas-tool.ts          # Canvas 画布
├── cron-tool.ts           # 定时任务
├── discord-actions*.ts    # Discord 操作
├── gateway-tool.ts        # 网关操作
├── image-tool.ts          # 图片处理
├── message-tool.ts        # 消息发送
├── nodes-tool.ts          # 节点管理
├── session*.ts            # 会话操作
├── slack-actions.ts       # Slack 操作
└── whatsapp-actions.ts    # WhatsApp 操作

6.3 Skills 扩展

Skill 快照构建

加载并构建 Skill 的提示词：

typescript

// src/agents/pi-embedded-runner/skills.ts
// 作用：构建 Skill 的提示词
// 功能：加载 Skills → 提取描述 → 组装提示
export function buildSkillPrompt(skills: Skill[]): string {
  // 构建 Skill 提示
}

Skills 加载顺序（workspace 优先）：

Bundled（安装自带）
Managed：~/.openclaw/skills
Workspace：<workspace>/skills

6.4 工具策略

json5

// ~/.openclaw/openclaw.json
// 作用：控制工具的可用性
// 功能：白名单/黑名单过滤
{
  agents: {
    list: [{
      id: "family",
      tools: {
        allow: ["read", "message"],  // 只允许这些
        deny: ["exec", "write"]      // 禁止这些
      }
    }]
  }
}

七、沙箱与安全

7.1 沙箱集成

SandboxContext 解析

解析并初始化沙箱环境：

typescript

// src/agents/pi-embedded-runner/sandbox.ts
// 作用：解析沙箱配置并创建沙箱环境
// 功能：确定沙箱根目录 → 配置工具约束 → 设置执行环境
export async function resolveSandboxContext(params: SandboxParams): Promise<SandboxContext> {
  const sandbox = await resolveSandboxContext({
    config: params.config,
    sessionKey: sandboxSessionKey,
    workspaceDir: resolvedWorkspace,
  });

  if (sandboxRoot) {
    // 使用沙箱 read/edit/write 工具
    // Exec 在容器中运行
    // Browser 使用桥接 URL
  }
}

7.2 沙箱模式

json5

// ~/.openclaw/openclaw.json
// 作用：配置沙箱隔离
// 功能：限制 Agent 对系统资源的访问
{
  sandbox: {
    mode: "all",           // off = 无沙箱, non-main = 非主会话, all = 全部
    scope: "agent",        // shared = 共享, agent = 每个 Agent 独立
    docker: {
      setupCommand: "apt-get install -y git curl"  // 容器初始化命令
    }
  }
}

7.3 Provider 特定处理

Provider	特定处理	源码位置
Anthropic	拒绝魔术字符串清理、轮次验证、Claude Code 参数兼容	`src/agents/pi-embedded-runner/*.ts`
Google/Gemini	轮次顺序修复、工具 Schema 清理	`src/agents/pi-embedded-runner/google.ts`
OpenAI	`apply_patch` 工具、Thinking Level 降级处理	`src/agents/pi-tools.apply-patch.ts`

7.4 安全特性

设备配对认证
本地信任（loopback/Tailscale 自动批准）
消息 JSON Schema 验证
幂等性键

八、配置示例

json5

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "anthropic/claude-sonnet-4-5",
      timeoutSeconds: 600
    }
  },
  session: {
    dmScope: "per-channel-peer"
  },
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 2000
    }
  }
}

九、PI vs CLI 差异

方面	Pi CLI	OpenClaw 嵌入式
调用方式	`pi` 命令 / RPC	SDK via `createAgentSession()`
工具	默认编程工具	OpenClaw 自定义工具套件
系统提示	AGENTS.md + prompts	动态构建（按频道/上下文）
会话存储	`~/.pi/agent/sessions/`	`~/.openclaw/agents/<agentId>/sessions/`
认证	单凭证	多配置 + 轮换
事件处理	TUI 渲染	回调驱动

本文基于 OpenClaw 源码和官方文档深入分析写成。

数据截至：2026年3月3日

OpenClaw Agents 深度解析 ​

一、Fundamentals ​

1.1 PI 集成架构 ​

核心入口：runEmbeddedPiAgent() ​

1.2 整体架构 ​

1.3 Agent 核心概念 ​

1.4 Agent 循环生命周期 ​

Session 创建内部流程 ​

事件订阅机制 ​

1.5 系统提示词构建 ​

Prompt 构建函数 ​

应用系统提示 ​

1.6 Context 上下文 ​

上下文守卫 ​

1.7 Workspace 工作空间 ​

1.8 OAuth 认证 ​

认证配置管理 ​

二、Bootstrapping ​

2.1 什么是 Bootstrapping？ ​

2.2 Bootstrap 文件 ​

2.3 文件大小限制 ​

2.4 禁用 Bootstrap ​

三、Sessions and Memory ​

3.1 Session 会话管理 ​

3.2 会话维护策略 ​

3.3 Session Tool ​

会话操作工具 ​

3.4 Memory 记忆机制 ​

记忆工具 ​

3.5 自动记忆刷新 ​

压缩前的记忆刷新 ​

3.6 向量搜索 ​

3.7 Compaction 压缩 ​

会话压缩逻辑 ​

四、Multi-agent ​

4.1 多 Agent 架构 ​

4.2 Bindings 路由机制 ​

绑定配置 ​

4.3 路由优先级 ​

4.4 多账号支持 ​

4.5 Presence 在线状态 ​

五、Messages and Delivery ​

5.1 消息流程 ​

5.2 消息去重 ​

5.3 消息防抖 ​

防抖配置 ​

5.4 队列模式 ​

队列模式配置 ​

5.5 Streaming 流式输出 ​

块流式处理 ​

Reply 指令解析 ​

5.6 Retry 重试机制 ​

错误分类 ​

Thinking Level 回退 ​

5.7 推理可见性 ​

六、工具系统 ​

6.1 工具架构 ​

工具管道 ​

Tool Definition Adapter ​

Tool Split Strategy ​

6.2 内置工具 ​

工具实现位置 ​

6.3 Skills 扩展 ​

Skill 快照构建 ​

6.4 工具策略 ​

七、沙箱与安全 ​

7.1 沙箱集成 ​

SandboxContext 解析 ​

7.2 沙箱模式 ​

7.3 Provider 特定处理 ​

7.4 安全特性 ​

八、配置示例 ​

九、PI vs CLI 差异 ​

OpenClaw Agents 深度解析

一、Fundamentals

1.1 PI 集成架构

核心入口：runEmbeddedPiAgent()

1.2 整体架构

1.3 Agent 核心概念

1.4 Agent 循环生命周期

Session 创建内部流程

事件订阅机制

1.5 系统提示词构建

Prompt 构建函数

应用系统提示

1.6 Context 上下文

上下文守卫

1.7 Workspace 工作空间

1.8 OAuth 认证

认证配置管理

二、Bootstrapping

2.1 什么是 Bootstrapping？

2.2 Bootstrap 文件

2.3 文件大小限制

2.4 禁用 Bootstrap

三、Sessions and Memory

3.1 Session 会话管理

3.2 会话维护策略

3.3 Session Tool

会话操作工具

3.4 Memory 记忆机制

记忆工具

3.5 自动记忆刷新

压缩前的记忆刷新

3.6 向量搜索

3.7 Compaction 压缩

会话压缩逻辑

四、Multi-agent

4.1 多 Agent 架构

4.2 Bindings 路由机制

绑定配置

4.3 路由优先级

4.4 多账号支持

4.5 Presence 在线状态

五、Messages and Delivery

5.1 消息流程

5.2 消息去重

5.3 消息防抖

防抖配置

5.4 队列模式

队列模式配置

5.5 Streaming 流式输出

块流式处理

Reply 指令解析

5.6 Retry 重试机制

错误分类

Thinking Level 回退

5.7 推理可见性

六、工具系统

6.1 工具架构

工具管道

Tool Definition Adapter

Tool Split Strategy

6.2 内置工具

工具实现位置

6.3 Skills 扩展

Skill 快照构建

6.4 工具策略

七、沙箱与安全

7.1 沙箱集成

SandboxContext 解析

7.2 沙箱模式

7.3 Provider 特定处理

7.4 安全特性

八、配置示例

九、PI vs CLI 差异