调研时间：2026-03-14
调研范围：Agent系统、工具集成框架、内存管理、模块化架构、任务处理流程

1. 概述

OpenClaw 是一个个人 AI 助手平台，运行在用户自己的设备上。它通过统一的 Gateway 控制平面，连接多种消息渠道（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、飞书等），并提供丰富的工具集成能力（浏览器控制、代码执行、Canvas、定时任务等）。

核心架构特点

┌─────────────────────────────────────────────────────────────┐
│                     Gateway（控制平面）                       │
│                   ws://127.0.0.1:18789                      │
├─────────────────────────────────────────────────────────────┤
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
│   │ WhatsApp │  │ Telegram │  │ Discord  │  │   WebChat   │ │
│   │ (Baileys)│  │ (grammY) │  │(discord) │  │             │ │
│   └──────────┘  └──────────┘  └──────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
│   │  Agent   │  │   CLI    │  │  macOS   │  │  iOS/Android│ │
│   │  Runtime │  │(openclaw)│  │   App    │  │   Nodes     │ │
│   └──────────┘  └──────────┘  └──────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────┘

2. Agent 系统设计原理和工作机制

2.1 Agent 运行时架构

OpenClaw 使用嵌入式的 pi-mono Agent 运行时（派生自 pi-mono 代码库），但会话管理、发现和工具连接由 OpenClaw 自己实现。

核心组件：

组件 职责 技术实现
agent RPC 接收消息并启动 Agent 运行 Gateway WebSocket API
agentCommand 运行 Agent 的核心逻辑 序列化运行、加载技能、调用 pi-agent-core
runEmbeddedPiAgent 嵌入式 pi-agent 运行器 订阅 pi 事件流、执行工具调用
subscribeEmbeddedPiSession 桥接 pi 事件到 OpenClaw 流 转换生命周期/助手/工具事件

2.2 Agent 循环生命周期

 消息接收  →   会话解析  → 上下文组装  →  模型推理 →  工具执行  →  流式回复  → 持久化存储
    │           │           │           │          │           │           │
    ▼           ▼           ▼           ▼          ▼           ▼           ▼
  Gateway   SessionMgr  PromptBuilder  LLM API   ToolExec   Streaming   JSONL

详细流程：

  1. 入口点：agent RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据
  2. agentCommand：
    • 解析模型 + 思考/详细默认设置
    • 加载技能快照
    • 调用 runEmbeddedPiAgent
  3. runEmbeddedPiAgent：
    • 通过会话 + 全局队列序列化运行
    • 解析模型 + 认证配置文件
    • 订阅 pi 事件并流式传输助手/工具增量
    • 强制执行超时
  4. subscribeEmbeddedPiSession：桥接 pi-agent-core 事件到 OpenClaw agent 流

2.3 会话管理

会话键格式：

  • 直接聊天：agent:<agentId>:<mainKey>（默认 main）
  • 群组聊天：agent:<agentId>:<channel>:group:<id>
  • 定时任务：cron:<job.id>
  • Webhook：hook:<uuid>

会话范围（dmScope）：

  • main：所有 DM 共享主会话（单用户设置默认）
  • per-peer：按发送者 ID 隔离
  • per-channel-peer：按渠道 + 发送者隔离（推荐多用户）
  • per-account-channel-peer：按账户 + 渠道 + 发送者隔离

会话生命周期：

  • 每日重置：默认凌晨 4:00（网关主机本地时间）
  • 空闲重置：可配置 idleMinutes
  • 手动重置：/new 或 /reset 命令

2.4 多 Agent 路由

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

路由规则优先级（最具体优先）：

  1. peer 匹配（精确 DM/群组/频道 ID）
  2. parentPeer 匹配（线程继承）
  3. guildId + roles（Discord 角色路由）
  4. guildId（Discord）
  5. teamId（Slack）
  6. accountId 匹配
  7. 渠道级匹配（accountId: "*"）
  8. 默认 Agent 回退

3. 工具集成框架和扩展机制

3.1 工具架构

OpenClaw 提供两类工具：

  • 核心工具：read, write, edit, exec, process, browser, canvas, sessions_*, message, cron, voice_call 等
  • 技能工具：通过 Skill 系统动态加载的工具

工具调用流程：

模型生成工具调用 → Gateway 接收 → 工具执行 → 结果序列化 → 注入会话历史 → 模型继续生成

3.2 技能系统（Skills）

技能是 AgentSkills 兼容的文件夹，包含 SKILL.md 文件。

加载优先级（高到低）：

  1. 工作区技能：<workspace>/skills
  2. 管理/本地技能：~/.openclaw/skills
  3. 捆绑技能：随安装包提供

技能格式示例：

---
name: weather
description: Get current weather and forecasts
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["curl"], "env": ["OPENWEATHER_API_KEY"] },
        "emoji": "🌤️",
      },
  }
---

Use the weather tool to fetch current conditions...

技能门控（Gating）：

  • requires.bins：必需的二进制文件
  • requires.env：必需的环境变量
  • requires.config：必需的配置路径
  • os：限制平台（darwin/linux/win32）

3.3 插件系统（Plugins）

插件是 TypeScript 模块，在 Gateway 进程中通过 jiti 加载。

插件能力：

  • 注册 Gateway RPC 方法
  • 注册 HTTP 路由
  • 注册 Agent 工具
  • 注册 CLI 命令
  • 注册后台服务
  • 注册上下文引擎
  • 提供技能

插件生命周期：

  1. 发现：从配置路径、工作区根目录、全局扩展根目录读取 openclaw.plugin.json
  2. 启用/验证：根据配置决定是否启用
  3. 运行时加载：通过 jiti 加载模块
  4. 注册：调用 register(api) 收集注册信息

官方插件示例：

  • @openclaw/voice-call：语音通话
  • @openclaw/msteams：Microsoft Teams 集成
  • @openclaw/matrix：Matrix 协议
  • @openclaw/nostr：Nostr 协议

3.4 工具安全与沙箱

工具策略配置：

{
  tools: {
    allow: ["read", "exec", "sessions_list"],
    deny: ["write", "edit", "browser"],
  },
}

沙箱模式：

  • off：无沙箱（默认主会话）
  • non-main：非主会话在 Docker 容器中运行
  • all：所有会话都沙箱化

作用域：

  • session：每个会话一个容器
  • agent：每个 Agent 一个容器
  • shared：所有会话共享容器

4. 内存管理系统

4.1 内存文件架构

OpenClaw 使用纯 Markdown 文件作为内存，文件是事实的来源。

默认工作区布局：

~/.openclaw/workspace/
├── MEMORY.md              # 长期记忆（仅在主会话加载）
├── memory/
│   ├── 2026-03-14.md     # 每日记录
│   └── 2026-03-13.md     # 昨日记录
├── AGENTS.md             # 操作指令
├── SOUL.md               # 人格/语气
├── USER.md               # 用户信息
├── IDENTITY.md           # Agent 身份
└── TOOLS.md              # 工具使用说明

4.2 内存工具

  • memory_search：语义搜索索引片段
  • memory_get：读取特定 Markdown 文件/行范围

4.3 向量内存搜索

混合搜索（BM25 + 向量）：

  • 向量相似度：语义匹配，处理同义词
  • BM25 关键词：精确匹配，适合 ID、代码符号

配置示例：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        query: {
          hybrid: {
            enabled: true,
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

后处理流水线：

向量 + 关键词 → 加权合并 → 时间衰减 → 排序 → MMR → Top-K 结果

4.4 自动内存刷新

当会话接近自动压缩时，OpenClaw 触发静默内存刷新：

{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
        },
      },
    },
  },
}

4.5 会话历史管理

存储位置：

  • 会话存储：~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 会话记录：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

维护策略：

  • pruneAfter：删除超过 N 天的条目（默认 30 天）
  • maxEntries：最大条目数（默认 500）
  • rotateBytes：sessions.json 轮转大小（默认 10MB）
  • maxDiskBytes：磁盘预算上限

5. 模块化架构与灵活扩展性

5.1 扩展机制概览

┌────────────────────────────────────────────────────────────┐
│                    OpenClaw Gateway                        │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│   Channels  │   Plugins   │   Skills    │    Providers     │
│ （消息渠道）  │  （功能扩展） │  （工具技能） │   （模型提供商)    │
├─────────────┼─────────────┼─────────────┼──────────────────┤
│ • WhatsApp  │ • Voice Call│ • Weather   │ • OpenAI         │
│ • Telegram  │ • MS Teams  │ • Browser   │ • Anthropic      │
│ • Discord   │ • Matrix    │ • Code Exec │ • Google         │
│ • Slack     │ • Nostr     │ • ...       │ • Mistral        │
│ • Signal    │ • ...       │             │ • Ollama         │
│ • ...       │             │             │ • ...            │
└─────────────┴─────────────┴─────────────┴──────────────────┘

5.2 渠道扩展架构

统一渠道接口：
所有渠道实现统一的入站/出站消息接口，Gateway 通过渠道抽象层统一管理。

支持的渠道（25+）：

  • 即时通讯：WhatsApp, Telegram, Signal, iMessage, BlueBubbles
  • 企业通讯：Slack, Discord, Microsoft Teams, Google Chat, Feishu, Mattermost
  • 开源/去中心化：Matrix, Nostr, IRC, Tlon
  • 其他：LINE, Zalo, Nextcloud Talk, Synology Chat, WebChat

渠道配置示例：

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123"],
    },
    telegram: {
      enabled: true,
      botToken: "123456:ABC...",
      dmPolicy: "pairing",
    },
    discord: {
      enabled: true,
      token: "DISCORD_BOT_TOKEN",
      dmPolicy: "pairing",
    },
  },
}

5.3 模型提供商扩展

支持的提供商：

  • OpenAI (GPT-4, GPT-5, Codex)
  • Anthropic (Claude 系列)
  • Google (Gemini)
  • Mistral
  • Ollama (本地模型)
  • OpenRouter (聚合服务)

模型配置：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

6. 任务处理流程和性能优化

6.1 命令队列系统

队列模式：

  • steer：立即注入当前运行（取消待处理的工具调用）
  • followup：当前运行结束后排队处理
  • collect：合并所有排队消息为单个后续运行（默认）
  • steer-backlog：立即引导并保留消息用于后续运行

队列配置：

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",  // old | new | summarize
    },
  },
}

6.2 流式处理与分块

块流式（Block Streaming）：

  • 将助手输出分块发送，而不是等待完整消息
  • 配置：agents.defaults.blockStreamingDefault: "on"
  • 边界：text_end（文本结束时）或 message_end（消息结束时）

预览流式（Preview Streaming）：

  • Telegram/Discord/Slack 支持实时预览更新
  • 模式：off, partial, block, progress

分块算法：

  • 低边界：缓冲区 >= minChars 才发送
  • 高边界：优先在 maxChars 前分割
  • 分割偏好：段落 → 换行 → 句子 → 空白 → 强制分割

6.3 上下文压缩

自动压缩：
当会话接近模型上下文窗口限制时，OpenClaw 自动压缩旧历史：

  • 保留最近消息
  • 将旧消息总结为压缩条目
  • 压缩摘要持久化到 JSONL 记录

手动压缩：

/compact Focus on decisions and open questions

压缩配置：

{
  agents: {
    defaults: {
      compaction: {
        model: "anthropic/claude-sonnet-4-5",  // 专用压缩模型
        reserveTokensFloor: 20000,
      },
    },
  },
}

6.4 会话修剪（Pruning）

在每次 LLM 调用前，OpenClaw 从内存中修剪旧的工具结果（不修改 JSONL 历史）：

  • 减少上下文窗口占用
  • 保留工具调用的摘要
  • 可配置 agents.defaults.sessionPruning

6.5 性能优化策略

并发控制：

  • 每个会话键序列化运行（保证一致性）
  • 全局并发限制：agents.defaults.maxConcurrent
  • 子 Agent 独立队列，避免阻塞主会话

技能快照：

  • 会话启动时快照符合条件的技能
  • 同一会话的后续运行复用技能列表
  • 配置更改在下次新会话生效

嵌入缓存：

  • 块嵌入缓存到 SQLite
  • 避免重复嵌入未更改的文本
  • 配置：agents.defaults.memorySearch.cache.enabled

批处理索引：

  • OpenAI/Gemini/Voyage 支持批量嵌入 API
  • 大语料库索引时启用：remote.batch.enabled: true

7. 安全架构

7.1 DM 访问控制

配对策略（dmPolicy）：

  • pairing（默认）：未知发送者收到一次性配对码
  • allowlist：仅允许列表中的发送者
  • open：允许所有入站 DM（需配合 allowFrom: ["*"]）
  • disabled：忽略所有 DM

安全 DM 模式：

{
  session: {
    dmScope: "per-channel-peer",  // 按渠道+发送者隔离会话
  },
}

7.2 执行审批

审批模式：

  • deny：拒绝所有提升执行
  • allowlist：需要显式批准
  • full：允许所有提升执行

审批命令：

openclaw pairing approve <channel> <code>

7.3 沙箱隔离

Docker 沙箱：

  • 非主会话可在隔离容器中运行
  • 限制文件系统访问
  • 网络 egress 控制

8. 代码示例

8.1 创建子 Agent 任务

// 使用 sessions_spawn 创建子 Agent
const result = await sessions_spawn({
  task: "Analyze the codebase and summarize the architecture",
  label: "code-analysis",
  thinking: "high",
  runTimeoutSeconds: 300,
  sandbox: "inherit",  // inherit | require
});

// 返回结果
// {
//   status: "accepted",
//   runId: "run-xxx",
//   childSessionKey: "agent:main:subagent:uuid"
// }

8.2 跨会话消息

// 发送消息到另一个会话
await sessions_send({
  sessionKey: "agent:main:discord:group:123456",
  message: "Please check the server logs",
  timeoutSeconds: 60,
});

// 列出活跃会话
const sessions = await sessions_list({
  kinds: ["main", "group"],
  activeMinutes: 30,
  messageLimit: 5,
});

8.3 内存搜索

// 搜索内存
const results = await memory_search({
  query: "what was the decision about database migration",
  limit: 5,
});

// 读取特定内存文件
const memory = await memory_get({
  file_path: "memory/2026-03-14.md",
  offset: 1,
  limit: 50,
});

8.4 配置多 Agent 路由

// ~/.openclaw/openclaw.json
{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        model: "anthropic/claude-sonnet-4-5",
        default: true,
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: "openai/gpt-5.2",
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: ["read", "exec"],
          deny: ["write", "edit", "browser"],
        },
      },
    ],
  },
  bindings: [
    // 工作 WhatsApp 账号路由到 work Agent
    {
      agentId: "work",
      match: { channel: "whatsapp", accountId: "work-number" },
    },
    // 个人 WhatsApp 账号路由到 personal Agent
    {
      agentId: "personal",
      match: { channel: "whatsapp", accountId: "personal-number" },
    },
    // Discord 特定频道路由到 work Agent
    {
      agentId: "work",
      match: {
        channel: "discord",
        peer: { kind: "channel", id: "123456789" },
      },
    },
  ],
}

9. 总结

OpenClaw 采用模块化、分层架构，通过以下设计实现灵活扩展：

  1. Gateway 控制平面：统一的 WebSocket 控制平面，管理所有渠道、会话和工具
  2. Agent 运行时：嵌入式 pi-mono 运行时 + OpenClaw 自有的会话管理和工具连接
  3. 技能系统：AgentSkills 兼容的技能文件夹，支持工作区/本地/捆绑三级覆盖
  4. 插件系统：TypeScript 模块，可扩展渠道、工具、CLI 命令和后台服务
  5. 内存管理：纯 Markdown 文件 + 向量搜索（BM25 + 语义），支持混合搜索和时间衰减
  6. 多 Agent 路由：基于绑定的灵活路由，支持按渠道、账户、对等体隔离
  7. 安全架构：配对码、允许列表、沙箱隔离、执行审批多层防护
  8. 性能优化：队列序列化、流式分块、上下文压缩、嵌入缓存、批处理索引

这种架构使 OpenClaw 能够作为个人 AI 助手运行，同时支持多用户、多 Agent、多渠道的复杂场景。

参考文档

# 架构 # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

ChatGPT多模态技术拆解：GPT-4o端到端架构与实测

avatar AtomGit开源社区
cover

gemini-3.1-pro-preview-thinking-medium思考版模型，告别“快了不准，准了太慢”！才是真正能用的AI王炸

avatar AtomGit开源社区
cover

Redis—分布式缓存

avatar AtomGit开源社区