OpenClaw Agents 执行引擎深度解析：拆解 AI 的“思考与行动”核心

流程图核心解读（新手必看）

• 核心逻辑闭环：从'收消息'到'返结果'的全流程无外部依赖，所有决策都在 Agent 内部完成；
• 安全卡点：工具策略管道是'重中之重'，80% 的安全问题都靠这层拦截；
• 性能优化点：Session Lock 防止并发混乱，会话压缩控制上下文长度，都是提升执行效率的关键。

3. 关键步骤深度拆解：代码 + 实战避坑

每个步骤都会贴核心简化代码，补充实战调试技巧和常见坑点，帮助快速理解并避开踩坑：

步骤 1：获取 Session Lock（防并发冲突）

核心代码

// agents/pi-embedded-runner/run.ts 核心锁逻辑
import { acquireLock, releaseLock } from '../../utils/lock-manager.ts';

// 锁 Key 与会话绑定，确保同一会话串行处理
const lockKey = `session:${session.id}`;
try {
  // 最多等待 30 秒，超时返回系统繁忙
  await acquireLock(lockKey, { timeout: 30000, ttl: 60000 });
  // 后续执行逻辑...
} finally {
  // 无论成功/失败，最终都释放锁（关键！）
  await releaseLock(lockKey);
}

实战解读

• 核心作用：防止同一会话同时处理多条消息，导致上下文混乱（比如前一条消息的历史还没写入，后一条就读取了）；
• 调试坑点：如果忘记在 finally 里释放锁，会导致该会话后续所有消息都提示'系统繁忙'；
• 优化建议：调试时可把 timeout 改短（如 5000ms），快速发现锁未释放的问题。

步骤 2：构建 Prompt（上下文组装 + 安全清洗）

核心代码

// agents/pi-embedded-runner/prompt-builder.ts
export const buildPrompt = ({
  system,      // 系统提示词（如'你是一个安全的助手，仅执行白名单内的工具'）
  messages,    // 会话历史
  newMessage,  // 用户新消息
  maxTokens = 4096 // 模型最大上下文 token 数
}: PromptOptions): string => {
  // 1. 清洗敏感信息：过滤密码、token、私钥等
  const sanitizedMessages = sanitizeMessages([...messages, newMessage]);
  // 2. 截断历史：确保总 token 不超过 maxTokens 的 80%（留空间给模型输出）
  const truncatedHistory = truncateHistory(sanitizedMessages, maxTokens * 0.8);
  // 3. 组装最终 Prompt：system + 历史 + 新消息
  return formatPrompt({ system, messages: truncatedHistory });
};

实战解读

• sanitize 关键逻辑：用正则匹配 (\w+_)?token|password|secret|私钥 等关键词，替换为 [REDACTED]，防止敏感信息被 LLM 记住；
• 截断策略：不是简单按条数截断，而是按 token 数（用 gpt-tokenizer 计算），优先保留最近的消息；
• 调试技巧：在 buildPrompt 返回前打印最终 Prompt，就能知道模型实际收到的是什么内容，排查