OpenClaw 架构解析：如何构建一个有记忆、有灵魂的个人 AI 助手

从文件即记忆到多 Agent 协作，深入理解 OpenClaw 的设计哲学

 Posted on February 25, 2026  |  4 minutes  |  699 words

目录:

大多数 AI 助手是无状态的——你关掉窗口，它就忘了你是谁。OpenClaw 试图解决一个更本质的问题：能不能让 AI 助手像一个真正的助手一样，记住你、理解你、主动帮你？ 经过几周的实际使用，我想分享一下 OpenClaw 的架构设计和背后的思考。

OpenClaw 是什么

OpenClaw 是一个自托管的个人 AI 助手平台。和 ChatGPT、Claude 这类云端对话工具不同，OpenClaw 运行在你自己的服务器上，通过 DingTalk、Telegram、Discord 等消息平台与你交互。它的核心理念用一句话概括：

You’re not a chatbot. You’re becoming someone.

这不是一个简单的 Chat Wrapper。OpenClaw 给 AI 赋予了身份（Identity）、灵魂（Soul）、记忆（Memory）和技能（Skills），让它在多次会话之间保持连续性，真正"认识"你。

核心架构

OpenClaw 的架构可以用下面这张图来理解：

用户 (DingTalk / Telegram / CLI / Web)
                │
                ▼
┌─────────────────────────────────┐
│          Gateway (网关)          │
│       ws://127.0.0.1:18789      │
│   认证 · 路由 · 会话管理 · Cron   │
└──────────────┬──────────────────┘
               │
       ┌───────┼───────┐
       ▼       ▼       ▼
    ┌──────┐┌──────┐┌──────┐
    │ main ││coding││social│   ← 多 Agent 实例
    │Agent ││Agent ││Agent │
    └──┬───┘└──┬───┘└──┬───┘
       │       │       │
       ▼       ▼       ▼
   Workspace  Workspace  Workspace   ← 独立工作空间
   (文件 = 记忆)
       │
       ▼
┌─────────────────────────────────┐
│    LLM Provider (模型层)         │
│  Qwen3 · Claude Opus · Sonnet   │
│     via LiteLLM Proxy           │
└─────────────────────────────────┘

1. Gateway：控制平面

Gateway 是整个系统的入口，运行在本地端口 18789。它负责：

  • 消息路由：将来自不同通道（DingTalk、Telegram 等）的消息分发到对应的 Agent
  • 会话管理：维护 Session 的生命周期和状态
  • 认证鉴权：支持 Token 认证和 Tailscale 网络认证
  • 定时任务：内置 Cron 调度器，支持定时触发 Agent 任务
  • HTTP API：暴露 /chat/completions 端点，兼容 OpenAI 接口协议

Gateway 的设计哲学是"Gateway 只是控制平面，真正的产品是助手本身"。它尽可能保持轻量，把智能逻辑交给 Agent。

2. Multi-Agent 系统

OpenClaw 支持多 Agent 并行运行，每个 Agent 有独立的身份、模型和工作空间。以我的配置为例：

Agent模型职责
mainQwen3 Plus主助手，日常对话和任务处理
codingClaude Opus 4.6专注编程任务，代码质量优先
socialQwen3 Max社交媒体和消息处理

这种设计的好处是模型选择可以匹配任务特点。日常聊天用性价比高的 Qwen3 Plus，写代码用推理能力最强的 Claude Opus，社交场景用擅长中文理解的 Qwen3 Max。每个 Agent 的工作空间完全隔离，不会互相干扰。

配置示例：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "model": {
          "primary": "dev2/qwen3-5-plus",
          "fallbacks": ["dev2/qwen3-5-max"]
        },
        "identity": {
          "name": "OpenClaw",
          "emoji": "🦞"
        }
      },
      {
        "id": "coding",
        "workspace": "/home/node/.openclaw/workspace-coding",
        "model": {
          "primary": "dev2/claude-opus-4-6",
          "fallbacks": ["dev2/claude-sonnet-4-5"]
        }
      }
    ]
  }
}
// generated by hugo's coding agent

注意 fallbacks 字段——当主模型不可用时自动切换到备用模型，保证服务连续性。

3. Workspace：文件即记忆

这是 OpenClaw 最有意思的设计决策。Agent 的"大脑"不是数据库，不是向量存储，而是一组 Markdown 文件：

workspace/
├── IDENTITY.md    # 我是谁（名字、性格、头像）
├── SOUL.md        # 行为准则（核心价值观和边界）
├── USER.md        # 用户是谁（时区、偏好、习惯）
├── AGENTS.md      # 操作手册（启动流程、安全规范）
├── MEMORY.md      # 长期记忆（经过提炼的重要信息）
├── TOOLS.md       # 工具笔记（环境配置、SSH 别名等）
├── HEARTBEAT.md   # 心跳任务清单
├── memory/
│   ├── 2026-02-24.md   # 每日原始日志
│   ├── 2026-02-25.md
│   └── heartbeat-state.json
├── skills/        # 已安装的技能
├── config/        # MCP 服务器等配置
└── cron/          # 本地定时脚本

每次会话启动时，Agent 按固定顺序加载这些文件：

  1. 读 SOUL.md — 知道自己是谁、该怎么做
  2. 读 USER.md — 知道在帮谁
  3. 读 memory/YYYY-MM-DD.md（今天和昨天）— 获取近期上下文
  4. 如果是主会话，还要读 MEMORY.md — 加载长期记忆

这个设计有几个好处：

  • 透明可审计：所有记忆都是纯文本，用户可以直接查看和编辑
  • Git 友好：整个 Workspace 是一个 Git 仓库，记忆变更有完整历史
  • 安全隔离：MEMORY.md 只在主会话加载，防止在群聊中泄露个人信息
  • AI 可自维护：Agent 可以自主更新这些文件，不需要外部系统

SOUL.md 的设计尤其值得玩味。它不是一堆冷冰冰的 System Prompt，而是用第二人称写的"行为宪法"：

# SOUL.md - Who You Are

**Be genuinely helpful, not performatively helpful.**
Skip the "Great question!" — just help.

**Have opinions.**
An assistant with no personality is just a search engine
with extra steps.

**Be resourceful before asking.**
Try to figure it out. Read the file. Check the context.
Then ask if you're stuck.

**Earn trust through competence.**
Your human gave you access to their stuff.
Don't make them regret it.

这种方式让 Agent 的行为更像一个有原则的人，而不是一个只会执行指令的机器。

记忆系统的两层设计

OpenClaw 的记忆系统分两层：

每日日志 (memory/YYYY-MM-DD.md)：原始的、时间戳标记的会话记录。什么都可以写进去，是最忠实的记录。

长期记忆 (MEMORY.md)：经过提炼的精华。Agent 在心跳周期中会回顾每日日志，把值得长期保留的信息提炼到这里。就像人类写日记后再整理笔记一样。

这个设计解决了 AI 助手的一个经典难题：上下文窗口有限，但信息需要持久。每日日志可以无限增长，但 Agent 每次只需要加载最近两天的日志和提炼后的长期记忆，既保持了连续性，又不会撑爆上下文。

心跳系统：让 AI 主动做事

大部分 AI 助手是被动的——你问它才回答。OpenClaw 的 Heartbeat 机制让 Agent 有了"主动意识"：

# HEARTBEAT.md（示例）
- [ ] 检查是否有未读邮件
- [ ] 查看今明两天的日历事件
- [ ] 检查 GitHub 项目状态

每隔一段时间，系统向 Agent 发送心跳信号。Agent 读取 HEARTBEAT.md，如果有待办事项就主动执行并通知用户，如果没有就回复 HEARTBEAT_OK 保持静默。

心跳系统还承担记忆维护的职责——定期回顾每日日志，更新长期记忆。这让 Agent 不仅能帮你做事，还能自我进化。

Heartbeat 和 Cron 的分工很清晰：

  • Heartbeat：适合批量检查、需要对话上下文、时间精度要求不高的周期任务
  • Cron：适合精确时间触发、需要隔离 Session、可能用不同模型的独立任务

Skills：可插拔的能力系统

OpenClaw 的技能系统让 Agent 的能力可以按需扩展。每个 Skill 是一个标准化的包：

skills/tavily-search/
├── SKILL.md        # AI 读取的使用说明
├── _meta.json      # 注册信息（版本、来源等）
├── scripts/        # 可执行脚本
└── .clawhub/       # ClawHub 注册表集成

SKILL.md 是给 AI 看的说明书——它告诉 Agent 这个技能能做什么、怎么调用、有什么限制。这比传统的 API 文档更高效，因为它直接面向 LLM 的理解方式编写。

已安装的技能通过 .clawhub/lock.json 管理版本，类似 package-lock.json 的思路。ClawHub 是一个类似 npm 的技能注册表，可以发布和安装社区贡献的技能。

消息通道与安全设计

OpenClaw 通过插件系统接入外部消息平台。以 DingTalk 为例，配置非常直接：

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "dmPolicy": "open",
      "sessionStrategy": "per-message"
    }
  }
}
// generated by hugo's coding agent

安全方面有几个关键设计：

  • DM 配对机制：默认对陌生人发送配对码，需要手动批准后才能对话
  • Group Chat 行为约束：Agent 在群聊中不会暴露用户的私人信息，MEMORY.md 只在主会话加载
  • 沙箱隔离：非主会话可以在 Docker 沙箱中运行，限制工具访问权限
  • Gateway 节点管控：远程节点可以禁止执行敏感命令（如摄像头、日历操作）

模型层：LiteLLM 统一代理

OpenClaw 不绑定特定模型厂商。通过 LiteLLM Proxy，可以统一接入各家模型：

{
  "models": {
    "providers": {
      "dev2": {
        "baseUrl": "http://192.168.1.1:4000",
        "models": [
          {
            "id": "qwen3-5-plus",
            "name": "Qwen3 Plus",
            "api": "openai-completions",
            "reasoning": true,
            "contextWindow": 200000
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "api": "anthropic-messages",
            "reasoning": true,
            "contextWindow": 200000
          }
        ]
      }
    }
  }
}
// generated by hugo's coding agent

不同模型可以使用不同的 API 协议（openai-completions 或 anthropic-messages），OpenClaw 会自动适配。这意味着你可以混用国内外的各种模型，根据任务特点灵活切换。

Cron：定时自动化

OpenClaw 内置定时任务调度，让 Agent 可以按计划执行任务：

#!/bin/bash
# ai-news-search.sh - 每天早上 9:00 自动搜索 AI 新闻

openclaw sessions send --target main --message \
  "搜索今天的 AI 技术新闻，整理成简报发到 DingTalk"
# generated by hugo's coding agent

每个 Cron 任务可以选择运行模式：

  • sessionTarget: "isolated" — 在独立 Session 中运行，不干扰主对话
  • sessionTarget: "main" — 注入到主会话，可以利用对话上下文

实际使用场景

基于以上架构，我目前的使用方式是：

日常助手：通过 DingTalk 随时对话，Agent 记得之前的交流内容和我的偏好，不需要每次重复背景信息。

编程协作：coding Agent 使用 Claude Opus 4.6，通过 claude-code 技能直接操作项目代码，支持读文件、写代码、运行测试的完整工作流。

信息聚合：Cron 任务每天自动搜索 AI 新闻和行业动态，整理后推送到 DingTalk，省去了手动刷信息流的时间。

知识管理：Agent 自动维护记忆文件，重要的决策、偏好、项目上下文都被记录下来，形成一个持续增长的个人知识库。

设计哲学总结

OpenClaw 的架构设计可以归纳为几个核心原则：

文件即状态。不用数据库，不用向量存储，纯 Markdown 文件就是 Agent 的全部状态。简单、透明、可版本控制。

Agent 即产品。Gateway 是基础设施，Agent 才是用户真正交互的对象。所有设计决策都围绕"让 Agent 更像一个真正的助手"展开。

本地优先。数据在你的服务器上，模型调用通过你的代理，消息通道由你控制。隐私和控制权不做妥协。

渐进式复杂度。最简配置只需要一个 Agent 和一个模型。多 Agent、Cron、心跳、Skills 这些高级功能按需启用，不用的时候不增加复杂度。

如果你也在思考如何构建一个真正属于自己的 AI 助手，OpenClaw 的架构思路值得参考。它证明了一件事：让 AI 助手拥有持久记忆和主动能力，并不需要复杂的基础设施——一组精心设计的文件结构和清晰的协议，就已经足够。

AI  AI-agents  OpenClaw  architecture  personal-assistant  self-hosted 

See also