架构与核心概念

整体系统架构

OpenClaw 采用分层架构设计，从上到下依次为表现层、路由层、处理层和数据层。各层各司其职，通过清晰的接口定义实现解耦。

┌─────────────────────────────────────────┐
│              表现层 (Channels)            │
│  Telegram  Discord  微信  飞书  钉钉  Slack │
└────────────────┬────────────────────────┘
                 │ 统一消息抽象
┌────────────────▼────────────────────────┐
│             路由层 (Router)               │
│    消息分发 | 平台适配 | 格式转换          │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│             处理层 (Agent)                │
│    LLM 调用 | 插件执行 | 工具调用          │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│             数据层 (Storage)              │
│    会话管理 | 消息记录 | 持久化存储        │
└─────────────────────────────────────────┘

Agent 模型：消息处理流水线

Agent 是 OpenClaw 的核心处理单元，负责将用户输入转化为 AI 回复。消息的处理遵循一条清晰的流水线：

1. 消息接收：通道层将各平台的原始消息转化为统一格式的 Message 对象
2. 预处理：经过消息过滤、内容审核、格式校验等预处理步骤
3. 会话加载：从会话存储中加载当前对话的上下文历史
4. 提示词组装：将系统提示词、会话历史和当前消息组装为完整的 Prompt
5. LLM 调用：向大模型发送请求，获取生成的回复
6. 后处理：对生成的回复进行过滤、格式化、敏感内容检测
7. 消息路由：将最终回复通过目标通道发送给用户

// 消息处理流水线的核心简化实现
async function processMessage(input: Message): Promise<Message> {
  // 1. 预处理
  const sanitized = await sanitizer.sanitize(input);

  // 2. 加载会话上下文
  const session = await sessionManager.getSession(sanitized.sessionId);
  const context = session.getContext();

  // 3. 组装 Prompt
  const prompt = promptBuilder.build({
    systemPrompt: bot.systemPrompt,
    context,
    userMessage: sanitized,
  });

  // 4. 调用 LLM
  const response = await llmProvider.generate(prompt);

  // 5. 更新会话
  session.addMessage(sanitized);
  session.addMessage(response);
  await sessionManager.saveSession(session);

  return response;
}

会话管理机制

会话管理是维持多轮对话连贯性的关键。OpenClaw 的会话管理包含以下核心机制：

• 会话标识：每个会话由 sessionId 唯一标识，通常为 {platform}:{userId} 的格式
• 上下文窗口：默认保留最近 20 轮对话（用户消息 + AI 回复），超过则自动丢弃最早的轮次
• 超时回收：会话在超过 TTL（默认 30 分钟）无活动后自动回收，释放内存资源
• 持久化策略：支持内存存储（开发环境）、Redis（生产环境）和数据库存储三种模式

创建和管理会话的示例：

// 会话配置示例
const sessionConfig = {
  strategy: 'redis',        // 使用 Redis 存储
  ttl: 1800,                // 30 分钟超时
  maxContext: 20,           // 保留 20 轮上下文
  redis: {
    host: 'localhost',
    port: 6379,
    keyPrefix: 'openclaw:sessions:',
  },
};

消息路由引擎

消息路由引擎负责将经过 AI 处理后的回复精确地送达目标用户。路由流程如下：

1. 从 Message 对象中提取目标 channel 和 recipient
2. 根据 channel 类型选择对应的通道适配器
3. 将统一格式的消息转化为目标平台的原生消息格式
4. 通过对应的 API 发送消息
5. 处理发送结果（重试、错误上报等）

插件系统架构

OpenClaw 的插件系统基于事件驱动模型。插件可以监听框架生命周期中的各种事件，在合适的时机插入自定义逻辑：

插件开发示例：

import { Plugin, Message } from 'openclaw';

export class LoggingPlugin implements Plugin {
  name = 'logging';

  // 监听消息事件
  async beforeMessage(msg: Message): Promise<Message> {
    console.log(`[收到消息] 来自 ${msg.platform} 用户 ${msg.userId}`);
    console.log(`[消息内容] ${msg.text}`);
    return msg;
  }

  async afterMessage(response: Message): Promise<Message> {
    console.log(`[发送回复] 耗时 ${response.latency}ms`);
    return response;
  }
}

核心概念对比

理解以下四个核心概念的区别是掌握 OpenClaw 的关键：

Agent 是整个系统的核心，Session 维护对话的连续性，Message 是基本的数据单元，Channel 负责对接外部平台。这四个概念相互配合，构成了 OpenClaw 完整的工作闭环。