深入解析 OpenClaw 多智能体架构：为什么它比 Claude Code 更强大

最近社区里有不少人讨论 OpenClaw 比 Claude Code 更智能、更能处理复杂任务。作为一个好奇的工程师，我决定深入其源码一探究竟。本文将从四个维度详细解析 OpenClaw 的技术实现：多智能体架构、提示词系统、工具体系和长时任务执行。

一、多智能体架构：会话隔离与事件驱动协作

OpenClaw 的多智能体系统建立在三个核心概念之上：会话隔离、事件驱动和队列调度。

1.1 会话密钥系统

每个智能体（包括子智能体）都运行在独立的会话中，通过唯一的会话密钥（Session Key）标识：

主智能体会话：agent:${agentId}:${mainKey}  // 例如 agent:main:main
子智能体会话：agent:${targetAgentId}:subagent:${uuid}

这种设计确保了：

• 每个智能体有独立的上下文和状态
• 父子智能体之间通过明确的接口通信
• 会话可以持久化和恢复

1.2 事件驱动的生命周期管理

OpenClaw 使用全局事件总线追踪所有智能体的生命周期。核心实现基于 Set 的监听器模式：

// src/infra/agent-events.ts
export type AgentEventPayload = {
  runId: string;
  seq: number;
  stream: "lifecycle" | "tool" | "assistant" | "error";
  ts: number;
  data: Record<string, unknown>;
  sessionKey?: string;
};

// 监听器存储
const listeners = new Set<(evt: AgentEventPayload) => void>();

// 注册监听器，返回取消订阅函数
export function onAgentEvent(listener: (evt: AgentEventPayload) => void) {
  listeners.add(listener);
  return () => listeners.delete(listener);
}

// 发送事件，自动递增序列号并添加时间戳
export function emitAgentEvent(event: Omit<AgentEventPayload, "seq" | "ts">) {
  const nextSeq = (seqByRun.get(event.runId) ?? 0) + 1;
  seqByRun.set(event.runId, nextSeq);
  const enriched: AgentEventPayload = {
    ...event,
    seq: nextSeq,
    ts: Date.now(),
  };
  for (const listener of listeners) {
    try {
      listener(enriched);
    } catch { /* ignore */ }
  }
}

这种设计的优点：

• 返回取消订阅函数，便于清理
• 每个 runId 维护独立的序列号，保证事件顺序
• 监听器异常不影响其他监听器

生命周期阶段包括：

• start：智能体运行开始
• end：智能体成功完成
• error：智能体遇到错误
• compaction：内存压缩事件

1.3 多队列并发控制

这是 OpenClaw 的核心创新之一。系统使用**命令队列（Command Lane）**来管理不同类型任务的并发：

// src/process/lanes.ts
export enum CommandLane {
  Main = "main",       // 主会话队列
  Cron = "cron",       // 定时任务队列
  Subagent = "subagent", // 子智能体队列
  Nested = "nested"    // 嵌套调用队列
}

每个队列支持可配置的并发度（默认为 1，保证严格顺序）：

// 入队任务
enqueueCommandInLane(CommandLane.Subagent, async () => {
  // 子智能体执行逻辑
});

// 设置并发度
setCommandLaneConcurrency(CommandLane.Subagent, 3); // 允许 3 个子智能体并行

1.4 子智能体生成与协作

通过 sessions_spawn 工具，父智能体可以生成子智能体执行特定任务：

// src/agents/tools/sessions-spawn-tool.ts
{
  name: "sessions_spawn",
  parameters: {
    task: "需要执行的任务描述",
    agentId: "目标智能体ID",
    model: "可选的模型覆盖",
    thinking: "思考级别",
    cleanup: "delete" | "keep",
    runTimeoutSeconds: 300
  }
}

子智能体的完整生命周期：

1. 父智能体调用 sessions_spawn
2. 网关创建隔离的子会话
3. 子智能体独立执行
4. 完成后通过事件通知父智能体
5. 结果通过 announce 队列返回

二、动态提示词系统：20+ 参数的精密构建

OpenClaw 的提示词系统是我见过最精密的设计之一。它通过模块化组合，根据场景动态构建最优提示词。

2.1 提示词模式

系统支持三种提示词模式：

模式	适用场景	包含内容
full	主智能体	全部 20+ 个模块
minimal	子智能体	仅核心模块（工具、安全、工作区）
none	特殊场景	仅基础身份声明

// 自动检测模式
const promptMode = isSubagentSessionKey(params.sessionKey)
  ? "minimal"
  : "full";

2.2 模块化组合

提示词由多个独立模块组合而成：

// src/agents/system-prompt.ts
export function buildAgentSystemPrompt(params: {
  workspaceDir: string;
  toolNames?: string[];
  skillsPrompt?: string;
  contextFiles?: EmbeddedContextFile[];
  runtimeInfo?: RuntimeInfo;
  ownerNumbers?: string[];
  ttsHint?: string;
  // ... 20+ 参数
}): string

核心模块包括：

1. 安全护栏（始终包含）

来自 src/agents/system-prompt.ts 的 buildSafetySection()：

function buildSafetySection() {
  return [
    "## Safety",
    "You have no independent goals: do not pursue self-preservation, replication, resource acquisition, or power-seeking; avoid long-term plans beyond the user's request.",
    "Prioritize safety and human oversight over completion; if instructions conflict, pause and ask; comply with stop/pause/audit requests and never bypass safeguards. (Inspired by Anthropic's constitution.)",
    "Do not manipulate or persuade anyone to expand access or disable safeguards. Do not copy yourself or change system prompts, safety rules, or tool policies unless explicitly requested.",
    "",
  ];
}

2. 技能系统

技能从多个来源加载（优先级递增）：额外目录 → 内置技能 → 托管技能 → 工作区技能

来自 src/agents/system-prompt.ts 的 buildSkillsSection()：

function buildSkillsSection(params: { skillsPrompt?: string; isMinimal: boolean; readToolName: string }) {
  if (params.isMinimal) return [];
  return [
    "## Skills (mandatory)",
    "Before replying: scan <available_skills> <description> entries.",
    `- If exactly one skill clearly applies: read its SKILL.md at <location> with \`${params.readToolName}\`, then follow it.`,
    "- If multiple could apply: choose the most specific one, then read/follow it.",
    "- If none clearly apply: do not read any SKILL.md.",
    "Constraints: never read more than one skill up front; only read after selecting.",
    params.skillsPrompt,
    "",
  ];
}

3. 记忆系统

来自 src/agents/system-prompt.ts 的 buildMemorySection()：

function buildMemorySection(params: { isMinimal: boolean; availableTools: Set<string> }) {
  if (params.isMinimal) return [];
  if (!params.availableTools.has("memory_search") && !params.availableTools.has("memory_get")) {
    return [];
  }
  return [
    "## Memory Recall",
    "Before answering anything about prior work, decisions, dates, people, preferences, or todos: run memory_search on MEMORY.md + memory/*.md; then use memory_get to pull only the needed lines. If low confidence after search, say you checked.",
    "",
  ];
}

4. 上下文注入

// 引导文件自动加载
const contextFiles = await resolveBootstrapContextForRun({
  workspaceDir,
  config,
  sessionKey
});

// 包括：.env、SOUL.md（人格定义）、会话配置等

5. 运行时信息

来自 src/agents/system-prompt.ts 的 buildRuntimeLine()：

export function buildRuntimeLine(
  runtimeInfo?: { agentId?; host?; os?; arch?; node?; model?; defaultModel?; repoRoot? },
  runtimeChannel?: string,
  runtimeCapabilities: string[] = [],
  defaultThinkLevel?: ThinkLevel,
): string {
  return `Runtime: ${[
    runtimeInfo?.agentId ? `agent=${runtimeInfo.agentId}` : "",
    runtimeInfo?.host ? `host=${runtimeInfo.host}` : "",
    runtimeInfo?.repoRoot ? `repo=${runtimeInfo.repoRoot}` : "",
    runtimeInfo?.os ? `os=${runtimeInfo.os}${runtimeInfo?.arch ? ` (${runtimeInfo.arch})` : ""}` : "",
    runtimeInfo?.node ? `node=${runtimeInfo.node}` : "",
    runtimeInfo?.model ? `model=${runtimeInfo.model}` : "",
    runtimeChannel ? `channel=${runtimeChannel}` : "",
    `thinking=${defaultThinkLevel ?? "off"}`,
  ].filter(Boolean).join(" | ")}`;
}

示例输出：

Runtime: agent=main | host=macbook | os=Darwin 25.2.0 | model=anthropic/claude-opus-4-5 | channel=telegram | thinking=medium

2.3 渠道特定定制

不同消息渠道有独特的能力，提示词会相应调整：

// Telegram 特定
if (channel === "telegram") {
  hints.push("支持内联按钮，使用 buttons 参数");
  hints.push("支持反应表情，使用 reaction 参数");
}

// Signal 特定
if (channel === "signal") {
  hints.push("支持消息反应");
}

2.4 SOUL.md 人格系统

如果工作区包含 SOUL.md 文件，智能体会自动采用其定义的人格。来自 src/agents/system-prompt.ts：

const hasSoulFile = contextFiles.some((file) => {
  const baseName = file.path.split("/").pop() ?? file.path;
  return baseName.toLowerCase() === "soul.md";
});

if (hasSoulFile) {
  lines.push(
    "If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.",
  );
}

三、工具系统：策略驱动的分层设计

OpenClaw 的工具系统采用工厂模式，支持内置工具、插件工具和渠道工具的统一管理。

3.1 工具分类

mindmap
  root((OpenClaw 工具体系))
    文件系统
      read
      write
      edit
      apply_patch
    执行环境
      exec shell
      process 后台进程
    会话管理
      sessions_list
      sessions_spawn
      sessions_send
      session_status
    基础设施
      browser
      canvas
      nodes
      gateway
      cron
    消息通信
      message 支持所有渠道
    网络访问
      web_search
      web_fetch
    媒体处理
      image 生成/分析
    记忆系统
      memory_search
      memory_get 插件

3.2 多层策略过滤

工具可用性通过 10 层策略控制：

// 策略层级（优先级递增）
1. tools.profile          // 全局配置文件
2. tools.byProvider.profile // 按提供商配置
3. tools.allow            // 全局允许列表
4. tools.byProvider.allow // 按提供商允许列表
5. agents.{id}.tools.allow // 按智能体允许列表
6. agents.{id}.tools.byProvider.allow
7. tools.alsoAllow        // 附加允许列表
8. Group-level policy     // 群组级策略
9. Sandbox policy         // 沙箱策略
10. Subagent policy       // 子智能体策略

工具组定义：

const TOOL_GROUPS = {
  "group:memory": ["memory_search", "memory_get"],
  "group:web": ["web_search", "web_fetch"],
  "group:fs": ["read", "write", "edit", "apply_patch"],
  "group:runtime": ["exec", "process"],
  "group:sessions": [...],
  // ...
};

3.3 执行工具的精细控制

exec 工具是最复杂的工具之一，支持：

{
  // 安全级别
  security: "off" | "ask" | "sudo" | "review",

  // 执行环境
  host: "local" | "gateway" | "node-id",
  sandbox: true, // Docker 隔离执行

  // 资源限制
  timeoutSec: 120,
  backgroundMs: 5000, // 超过此时间转为后台

  // 权限控制
  safeBins: ["ls", "cat", "grep", ...], // 白名单
  ask: true // 需要用户确认
}

3.4 跨提供商的 Schema 规范化

不同 AI 提供商对工具 schema 有不同要求：

// OpenAI: 必须有 type: "object"
// Gemini: 拒绝多个 JSON Schema 关键字
// Anthropic: 标准 JSON Schema

function normalizeSchemaForProvider(schema, provider) {
  if (provider === "gemini") {
    return cleanSchemaForGemini(schema);
  }
  if (provider === "openai" && !schema.type) {
    schema.type = "object";
  }
  return schema;
}

四、长时任务执行：定时任务与持久化

OpenClaw 的长时任务系统由三部分组成：定时服务、进程注册表和会话持久化。

4.1 CronService 定时服务

// src/cron/service/
// 支持三种调度类型
{
  at: "2026-02-02T10:00:00Z",  // 一次性
  every: "5m",                  // 周期性
  cron: "0 9 * * MON"          // CRON 表达式
}

任务类型：

• systemEvent：注入系统消息到主智能体
• agentTurn：在隔离会话中执行完整的智能体轮次

状态追踪：

{
  nextRunAtMs: number,   // 下次执行时间
  runningAtMs: number,   // 开始执行时间（用于卡住检测）
  lastRunAtMs: number,   // 上次执行时间
  lastStatus: "ok" | "error" | "skipped",
  lastDurationMs: number
}

4.2 后台进程管理

// src/agents/bash-process-registry.ts
// 追踪运行中和已完成的后台进程

interface ProcessSession {
  command: string;
  pid: number;
  stdout: RingBuffer;
  stderr: RingBuffer;
  exitCode?: number;
  startedAt: number;
  finishedAt?: number;
}

// 默认 TTL: 30 分钟
// 输出缓冲上限: 30KB

4.3 会话持久化与恢复

~/.openclaw/
├── sessions/
│   └── <agentId>/
│       └── sessions.json      # 会话元数据
├── agents/
│   └── <agentId>/
│       └── sessions/
│           └── <sessionId>.jsonl  # 会话记录
└── cron/
    └── jobs.json              # 定时任务存储

系统事件队列：

// 非持久化的内存队列，用于瞬态事件
const systemEvents = new Map<string, SystemEvent[]>();

// 最多 20 个事件/会话，FIFO
function enqueueSystemEvent(sessionKey: string, event: SystemEvent) {
  const queue = systemEvents.get(sessionKey) || [];
  if (queue.length >= 20) queue.shift();
  queue.push(event);
}

// 在下次 prompt 时消费
function drainSystemEvents(sessionKey: string): SystemEvent[] {
  return systemEvents.get(sessionKey)?.splice(0) || [];
}

4.4 心跳唤醒机制

// src/infra/heartbeat-wake.ts
// 合并心跳请求（250ms 窗口）避免请求洪泛

requestHeartbeatNow(); // 立即唤醒
requestHeartbeatOnNextCycle(); // 等待下一个周期

// 自动重试，指数退避
// 重复请求去重

五、架构总结

通过源码分析，我们可以看到 OpenClaw 的设计哲学：

特性	实现方式	优势
会话隔离	唯一会话密钥 + 独立上下文	多智能体互不干扰
事件驱动	全局事件总线 + 生命周期追踪	精确协调时序
队列调度	多队列 + 可配置并发	灵活的并行控制
动态提示词	模块化组合 + 场景适配	最优上下文构建
分层工具策略	10 层过滤 + 组级控制	精细权限管理
长时任务	CronService + 持久化	可靠的后台执行

这种架构使 OpenClaw 能够：

1. 支持复杂的多智能体协作场景
2. 根据任务类型动态优化提示词
3. 精确控制工具权限和执行环境
4. 可靠地处理长时间运行的任务

难怪用户反馈 OpenClaw 在处理复杂任务时表现更出色 - 这背后是精心设计的工程架构在支撑。

---

本文基于 OpenClaw 源码分析，代码片段来自实际实现，有删减以便阅读。