OpenClaw 智能体引擎工作流程及实现代码分析

1. 智能体引擎概述

OpenClaw 智能体引擎是基于 @mariozechner/pi-agent-core 构建的完整 AI 智能体执行系统，提供从简单的单智能体执行到复杂的多智能体协作的完整功能。它支持多种工具类型、安全沙箱执行、详细的会话管理和高度可扩展的架构。

2. 核心架构组件

2.1 主要入口文件

文件	功能
pi-embedded-runner.ts	智能体引擎主入口，导出所有核心功能
pi-embedded-runner/run.ts	核心执行逻辑，处理智能体运行流程
pi-embedded.ts	整合所有智能体相关功能的统一入口
agent-scope.ts	智能体配置解析和管理
workspace.ts	智能体工作区管理

2.2 核心执行流程

// 主执行函数
runEmbeddedPiAgent()
  → buildEmbeddedRunPayloads()  // 构建运行 payload
  → runEmbeddedAttempt()        // 执行单次尝试
    → resolveModel()            // 解析模型配置
    → 工具调用和交互
    → 结果处理和清理

3. 智能体引擎工作流程详解

3.1 初始化阶段

// 位置: src/agents/pi-embedded-runner/run.ts
export async function runEmbeddedPiAgent(params: RunEmbeddedPiAgentParams) {
  // 1. 解析会话和通道信息
  const sessionLane = resolveSessionLane(params.sessionKey?.trim() || params.sessionId);
  const globalLane = resolveGlobalLane(params.lane);

  // 2. 初始化工作区
  const workspaceResolution = resolveRunWorkspaceDir({
    workspaceDir: params.workspaceDir,
    sessionKey: params.sessionKey,
    agentId: params.agentId,
    config: params.config,
  });

  // 3. 解析模型配置
  const { model, error, authStorage, modelRegistry } = resolveModel(
    provider,
    modelId,
    agentDir,
    params.config,
  );

  // 4. 初始化认证
  const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
  const profileOrder = resolveAuthProfileOrder({
    cfg: params.config,
    store: authStore,
    provider,
    preferredProfile: preferredProfileId,
  });
}

3.2 执行阶段

// 位置: src/agents/pi-embedded-runner/run/attempt.ts
export async function runEmbeddedAttempt(params: EmbeddedRunAttemptParams) {
  // 1. 解析沙箱上下文
  const sandbox = await resolveSandboxContext({
    config: params.config,
    sessionKey: sandboxSessionKey,
    workspaceDir: resolvedWorkspace,
  });

  // 2. 加载技能和环境变量
  const skillEntries = loadWorkspaceSkillEntries(effectiveWorkspace);
  restoreSkillEnv = applySkillEnvOverrides({
    skills: skillEntries ?? [],
    config: params.config,
  });

  // 3. 创建工具实例
  const toolsRaw = createOpenClawCodingTools({
    exec: {
      ...params.execOverrides,
      elevated: params.bashElevated,
    },
    sandbox,
    messageProvider: params.messageChannel ?? params.messageProvider,
    // ... 其他配置
  });

  // 4. 构建系统提示
  const appendPrompt = buildEmbeddedSystemPrompt({
    workspaceDir: effectiveWorkspace,
    defaultThinkLevel: params.thinkLevel,
    reasoningLevel: params.reasoningLevel ?? "off",
    extraSystemPrompt: params.extraSystemPrompt,
    // ... 其他配置
  });

  // 5. 创建会话
  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,
  });

  // 6. 处理提示和执行
  await activeSession.prompt(effectivePrompt, { images: imageResult.images });
}

3.3 工具调用和交互阶段

// 位置: src/agents/pi-tools.ts
export function createOpenClawCodingTools(options?: {
  // ... 配置选项
}): AnyAgentTool[] {
  // 1. 解析工具策略
  const {
    agentId,
    globalPolicy,
    globalProviderPolicy,
    agentPolicy,
    agentProviderPolicy,
    profile,
    providerProfile,
    profileAlsoAllow,
    providerProfileAlsoAllow,
  } = resolveEffectiveToolPolicy({
    config: options?.config,
    sessionKey: options?.sessionKey,
    modelProvider: options?.modelProvider,
    modelId: options?.modelId,
  });

  // 2. 创建编码工具
  const base = (codingTools as unknown as AnyAgentTool[]).flatMap((tool) => {
    if (tool.name === readTool.name) {
      return [createReadTool(workspaceRoot)];
    }
    // ... 其他工具创建
  });

  // 3. 创建系统工具
  const execTool = createExecTool({
    // ... 配置
  });
  const processTool = createProcessTool({
    // ... 配置
  });

  // 4. 应用工具策略
  const toolsByAuthorization = applyOwnerOnlyToolPolicy(tools, senderIsOwner);
  const subagentFiltered = applyToolPolicyPipeline({
    tools: toolsByAuthorization,
    toolMeta: (tool) => getPluginToolMeta(tool),
    warn: logWarn,
    steps: [
      // ... 策略步骤
    ],
  });

  return withAbort;
}

3.4 结果处理和清理阶段

// 位置: src/agents/pi-embedded-runner/run.ts
export async function runEmbeddedPiAgent(params: RunEmbeddedPiAgentParams) {
  // ... 执行逻辑 ...

  // 处理执行结果
  const payloads = buildEmbeddedRunPayloads({
    assistantTexts: attempt.assistantTexts,
    toolMetas: attempt.toolMetas,
    lastAssistant: attempt.lastAssistant,
    lastToolError: attempt.lastToolError,
    config: params.config,
    sessionKey: params.sessionKey ?? params.sessionId,
    provider: activeErrorContext.provider,
    model: activeErrorContext.model,
    // ... 其他配置
  });

  // 标记认证配置文件状态
  if (lastProfileId) {
    await markAuthProfileGood({
      store: authStore,
      provider,
      profileId: lastProfileId,
      agentDir: params.agentDir,
    });
    await markAuthProfileUsed({
      store: authStore,
      profileId: lastProfileId,
      agentDir: params.agentDir,
    });
  }

  return {
    payloads: payloads.length ? payloads : undefined,
    meta: {
      durationMs: Date.now() - started,
      agentMeta,
      aborted,
      systemPromptReport: attempt.systemPromptReport,
      stopReason: attempt.clientToolCall ? "tool_calls" : undefined,
      pendingToolCalls: attempt.clientToolCall
        ? [
            {
              id: `call_${Date.now()}`,
              name: attempt.clientToolCall.name,
              arguments: JSON.stringify(attempt.clientToolCall.params),
            },
          ]
        : undefined,
    },
    // ... 其他返回信息
  };
}

4. 智能体引擎关键功能

4.1 工具系统

工具类型

工具类别	功能
编码工具	read、write、edit、apply-patch
Bash 工具	exec、process
通道工具	消息发送、媒体处理
OpenClaw 工具	Web 搜索、图像处理、会话管理、子智能体工具、浏览器工具、定时任务工具

工具策略

// 位置: src/agents/pi-tools.policy.ts
export function resolveEffectiveToolPolicy(params: {
  config?: OpenClawConfig;
  sessionKey?: string;
  modelProvider?: string;
  modelId?: string;
}): EffectiveToolPolicy {
  // 解析全局策略
  const globalPolicy = params.config?.tools?.allow;
  const globalProviderPolicy = params.config?.tools?.[params.modelProvider]?.allow;

  // 解析智能体策略
  const agentPolicy = resolveAgentConfig(params.config, agentId)?.tools?.allow;
  const agentProviderPolicy = resolveAgentConfig(params.config, agentId)?.tools?.[params.modelProvider]?.allow;

  // 解析配置文件策略
  const profilePolicy = resolveToolProfilePolicy(profile);
  const providerProfilePolicy = resolveToolProfilePolicy(providerProfile);

  return {
    agentId,
    globalPolicy,
    globalProviderPolicy,
    agentPolicy,
    agentProviderPolicy,
    profile,
    providerProfile,
    profileAlsoAllow: profile?.alsoAllow,
    providerProfileAlsoAllow: providerProfile?.alsoAllow,
  };
}

4.2 沙箱系统

// 位置: src/agents/sandbox/config.ts
export async function resolveSandboxContext(params: {
  config: OpenClawConfig;
  sessionKey: string;
  workspaceDir: string;
}): Promise<SandboxContext | null> {
  const sandboxConfig = params.config?.agents?.defaults?.sandbox;
  if (!sandboxConfig?.enabled) {
    return null;
  }

  const containerName = `openclaw-sandbox-${hashString(params.sessionKey).slice(0, 8)}`;
  const workspaceDir = params.workspaceDir;

  return {
    enabled: true,
    containerName,
    workspaceDir,
    containerWorkdir: "/workspace",
    docker: {
      image: sandboxConfig.image ?? "openclaw/sandbox:latest",
      env: sandboxConfig.env ?? {},
    },
    fsBridge: createSandboxFsBridge(containerName, workspaceDir),
    browser: {
      bridgeUrl: `http://localhost:${sandboxConfig.browserPort ?? 9222}`,
    },
    browserAllowHostControl: sandboxConfig.browserAllowHostControl ?? false,
    workspaceAccess: sandboxConfig.workspaceAccess ?? "rw",
    tools: sandboxConfig.tools,
  };
}

4.3 会话管理

// 位置: src/agents/session-manager-init.ts
export async function prepareSessionManagerForRun(params: {
  sessionManager: ReturnType<typeof SessionManager.open>;
  sessionFile: string;
  hadSessionFile: boolean;
  sessionId: string;
  cwd: string;
}): Promise<void> {
  // 初始化会话管理器
  if (!params.hadSessionFile) {
    params.sessionManager.init();
  }

  // 设置工作区
  params.sessionManager.setWorkspace(params.cwd);

  // 配置会话参数
  params.sessionManager.setSessionId(params.sessionId);
}

4.4 内存管理

// 位置: src/agents/compaction.ts
export async function compactEmbeddedPiSessionDirect(params: CompactEmbeddedPiSessionParams) {
  const sessionManager = SessionManager.open(params.sessionFile);
  const settingsManager = SettingsManager.create(params.workspaceDir, params.agentDir);

  // 压缩会话上下文
  const compactResult = await sessionManager.compact({
    reserveTokens: resolveCompactionReserveTokensFloor(params.config),
    maxTokens: params.maxTokens,
  });

  return {
    compacted: compactResult.compacted,
    reason: compactResult.reason,
  };
}

5. 智能体引擎配置文件

智能体引擎使用以下配置文件（位于工作区）：

文件	功能
AGENTS.md	智能体定义
SOUL.md	智能体个性和行为
TOOLS.md	工具配置和策略
IDENTITY.md	身份信息
USER.md	用户信息
HEARTBEAT.md	心跳配置
BOOTSTRAP.md	引导配置
MEMORY.md	记忆存储

6. 执行流程示例

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

// 简单的智能体执行示例
async function runSimpleAgent() {
  const result = await runEmbeddedPiAgent({
    sessionId: "test-session",
    prompt: "请帮我创建一个简单的 Node.js 服务器",
    config: {},
    agentId: "default",
    workspaceDir: "./workspace",
    thinkLevel: "off",
    verboseLevel: "off",
  });

  console.log("智能体响应:", result.payloads);
}

// 带工具调用的智能体执行示例
async function runAgentWithTools() {
  const result = await runEmbeddedPiAgent({
    sessionId: "tool-session",
    prompt: "请列出当前目录的文件并创建一个 package.json 文件",
    config: {},
    agentId: "default",
    workspaceDir: "./workspace",
    thinkLevel: "off",
    verboseLevel: "off",
  });

  console.log("智能体响应:", result.payloads);
}

7. 扩展性和定制

7.1 插件开发

// 示例插件
import { OpenClawPlugin } from "./src/plugin-sdk";

export class MyPlugin implements OpenClawPlugin {
  name = "my-plugin";

  async beforeAgentStart(params: BeforeAgentStartParams) {
    console.log("智能体即将启动");
    return {
      systemPrompt: "这是我的自定义系统提示",
    };
  }

  async afterAgentEnd(params: AfterAgentEndParams) {
    console.log("智能体执行完成");
  }
}

7.2 自定义工具

// 示例自定义工具
import { createAgentTool } from "./src/agents/pi-tools";

export const myCustomTool = createAgentTool({
  name: "my-custom-tool",
  description: "我的自定义工具",
  parameters: {
    type: "object",
    properties: {
      input: { type: "string" },
    },
    required: ["input"],
  },
  async execute(params: { input: string }) {
    return {
      output: `你输入了: ${params.input}`,
    };
  },
});

8. 测试系统

8.1 单元测试

// 位置: src/agents/pi-embedded-runner/run.test.ts
import { describe, it, expect } from "vitest";
import { runEmbeddedPiAgent } from "./run";

describe("智能体引擎", () => {
  it("应该能够执行简单的智能体", async () => {
    const result = await runEmbeddedPiAgent({
      sessionId: "test-session",
      prompt: "请说你好",
      config: {},
      agentId: "default",
      workspaceDir: "./workspace",
      thinkLevel: "off",
      verboseLevel: "off",
    });

    expect(result.payloads).toBeDefined();
    expect(result.payloads.length).toBeGreaterThan(0);
  });
});

8.2 E2E 测试

// 位置: src/agents/pi-embedded-runner/run.e2e.test.ts
import { describe, it, expect } from "vitest";
import { runEmbeddedPiAgent } from "./run";

describe("智能体引擎 E2E 测试", () => {
  it("应该能够执行带工具调用的智能体", async () => {
    const result = await runEmbeddedPiAgent({
      sessionId: "e2e-session",
      prompt: "请列出当前目录的文件",
      config: {},
      agentId: "default",
      workspaceDir: "./workspace",
      thinkLevel: "off",
      verboseLevel: "off",
    });

    expect(result.payloads).toBeDefined();
    expect(result.payloads.length).toBeGreaterThan(0);
  });
});

9. 性能优化

9.1 会话压缩与上下文管理

OpenClaw 智能体引擎通过会话压缩技术来优化长时间运行会话的性能，防止上下文窗口溢出。

// 位置: src/agents/compaction.ts

// 会话压缩的核心算法
export async function summarizeInStages(params: {
  messages: AgentMessage[];
  model: NonNullable<ExtensionContext["model"]>;
  apiKey: string;
  signal: AbortSignal;
  reserveTokens: number;
  maxChunkTokens: number;
  contextWindow: number;
  customInstructions?: string;
  previousSummary?: string;
  parts?: number;
  minMessagesForSplit?: number;
}): Promise<string> {
  // 1. 检查是否需要分阶段处理
  const minMessagesForSplit = Math.max(2, params.minMessagesForSplit ?? 4);
  const parts = normalizeParts(params.parts ?? DEFAULT_PARTS, messages.length);
  const totalTokens = estimateMessagesTokens(messages);

  // 2. 如果不需要分阶段，直接使用 fallback 方法
  if (parts <= 1 || messages.length < minMessagesForSplit ||
      totalTokens <= params.maxChunkTokens) {
    return summarizeWithFallback(params);
  }

  // 3. 分阶段总结
  const splits = splitMessagesByTokenShare(messages, parts).filter((chunk) => chunk.length > 0);
  const partialSummaries: string[] = [];

  for (const chunk of splits) {
    partialSummaries.push(
      await summarizeWithFallback({
        ...params,
        messages: chunk,
        previousSummary: undefined,
      }),
    );
  }

  // 4. 合并部分总结
  const summaryMessages: AgentMessage[] = partialSummaries.map((summary) => ({
    role: "user",
    content: summary,
    timestamp: Date.now(),
  }));

  return summarizeWithFallback({
    ...params,
    messages: summaryMessages,
    customInstructions: MERGE_SUMMARIES_INSTRUCTIONS,
  });
}

压缩策略特点：

• 自适应分块：根据消息大小和数量自动决定是否分阶段处理
• 安全边界检查：防止单消息过大导致的压缩失败
• 渐进式 fallback：从完整总结到部分总结再到最终 fallback
• 令牌估算优化：考虑估算误差，添加安全边际

9.2 上下文修剪（Context Pruning）

上下文修剪是一种轻量级的性能优化技术，用于在会话进行中动态减少上下文大小。

// 位置: src/agents/pi-extensions/context-pruning/pruner.ts

export function pruneContextMessages(params: {
  messages: AgentMessage[];
  settings: EffectiveContextPruningSettings;
  ctx: Pick<ExtensionContext, "model">;
  isToolPrunable?: (toolName: string) => boolean;
  contextWindowTokensOverride?: number;
}): AgentMessage[] {
  // 1. 估算上下文大小
  const charWindow = contextWindowTokens * CHARS_PER_TOKEN_ESTIMATE;
  const totalCharsBefore = estimateContextChars(messages);

  // 2. 检查是否需要修剪
  if (totalCharsBefore / charWindow < settings.softTrimRatio) {
    return messages;
  }

  // 3. 识别可修剪的工具结果
  const prunableToolIndexes: number[] = [];
  for (let i = pruneStartIndex; i < cutoffIndex; i++) {
    const msg = messages[i];
    if (msg?.role === "toolResult" && isToolPrunable(msg.toolName)) {
      prunableToolIndexes.push(i);
    }
  }

  // 4. 软修剪：保留工具结果的头部和尾部
  for (const i of prunableToolIndexes) {
    const trimmed = softTrimToolResultMessage({
      msg: messages[i] as unknown as ToolResultMessage,
      settings,
    });
    if (trimmed) {
      // 替换原始消息为修剪后的版本
    }
  }

  // 5. 硬修剪：完全清除工具结果内容
  if (totalChars / charWindow >= settings.hardClearRatio) {
    for (const i of prunableToolIndexes) {
      (next ?? messages)[i] = {
        ...messages[i],
        content: [asText(settings.hardClear.placeholder)],
      };
    }
  }

  return next ?? messages;
}

上下文修剪特性：

• 工具级别的精细控制：可配置哪些工具结果可以被修剪
• 渐进式修剪策略：从软修剪到硬修剪的梯度控制
• 保护关键上下文：保留最后N个助手消息不被修剪
• 图像处理优化：对包含图像的工具结果特殊处理

9.3 令牌估算与上下文窗口管理

// 位置: src/agents/compaction.ts

// 自适应块比例计算
export function computeAdaptiveChunkRatio(messages: AgentMessage[], contextWindow: number): number {
  const totalTokens = estimateMessagesTokens(messages);
  const avgTokens = totalTokens / messages.length;

  // 应用安全边际以应对估算不准确
  const safeAvgTokens = avgTokens * SAFETY_MARGIN;
  const avgRatio = safeAvgTokens / contextWindow;

  // 如果平均消息大小超过上下文的10%，减少块比例
  if (avgRatio > 0.1) {
    const reduction = Math.min(avgRatio * 2, BASE_CHUNK_RATIO - MIN_CHUNK_RATIO);
    return Math.max(MIN_CHUNK_RATIO, BASE_CHUNK_RATIO - reduction);
  }

  return BASE_CHUNK_RATIO;
}

// 超大消息检查
export function isOversizedForSummary(msg: AgentMessage, contextWindow: number): boolean {
  const tokens = estimateTokens(msg) * SAFETY_MARGIN;
  return tokens > contextWindow * 0.5;
}

9.4 性能优化策略总结

OpenClaw 智能体引擎采用了多层次的性能优化策略：

优化层级	核心技术	实现位置	主要作用
会话管理	分阶段总结	compaction.ts	处理长会话上下文压缩
上下文修剪	动态消息修剪	context-pruning/	防止上下文窗口溢出
资源管理	令牌估算与控制	compaction.ts	优化 API 调用成本

这些优化技术共同确保了 OpenClaw 智能体引擎在长时间运行和高负载场景下的稳定性和效率。

10. 总结

OpenClaw 智能体引擎是一个完整且复杂的系统，提供了从简单的单智能体执行到复杂的多智能体协作的完整功能。它支持多种工具类型、安全沙箱执行、详细的会话管理和高度可扩展的架构。

主要特性：

• 多智能体支持
• 子智能体系统
• 工具调用和策略管理
• 安全沙箱执行
• 会话管理和压缩
• 高度可扩展的插件系统
• 详细的错误处理和恢复机制

通过对智能体引擎的分析，我们可以看到 OpenClaw 提供了一个强大且灵活的 AI 智能体执行平台，适用于各种应用场景。