OpenClaw 核心架构、记忆机制与多 Agent 部署实践

OpenClaw 可以理解成一套面向个人和小团队的 Agent 运行框架。它把大语言模型、即时通信工具、本地工作区、工具权限、长期记忆、会话历史和多 Agent 协作串到一起，让一个 Agent 不只停留在聊天窗口里，而是能长期运行、接收消息、调用工具、读写文件，并把一部分知识沉淀到自己的 workspace 中。

它的工程复杂度并不来自某个非常神秘的算法，而是来自一套清晰的约定：每个 Agent 有独立身份、独立 workspace、独立记忆、独立技能列表；多个 Agent 之间可以互相发消息，也可以临时派生子任务。掌握这些约定以后，OpenClaw 就不再是一个黑盒工具，而是一套可以被改造和精细化管理的 Agent 基础设施。

OpenClaw 解决的核心问题

单纯把一个大语言模型接到聊天软件里，只能解决“问答入口”的问题。真正做个人 Agent 时，还会遇到一堆更具体的工程问题：

整体结构可以抽象成下面这样：

flowchart LR
    U[用户 / IM 群聊] --> IM[IM Bot]
    IM --> G[OpenClaw Gateway]
    G --> R[Agent Runner]

    R --> W[Agent Workspace]
    W --> C[配置文件<br/>AGENTS / SOUL / TOOLS]
    W --> M[Memory<br/>MEMORY.md / daily memory]
    W --> S[Sessions<br/>JSONL 会话记录]
    W --> SK[Skills<br/>按需加载]

    R --> LLM[LLM 大语言模型]
    R --> T[本地工具 / API / 文件系统]

OpenClaw 的价值不在于“替代模型”，而在于把模型外部的工程能力组织起来。模型越强，Agent 的执行质量通常越高；但角色定义、长期记忆、技能沉淀、多 Agent 分工这些资产，可以随着底层模型升级继续复用。

部署方式：云机与自部署

使用 OpenClaw 通常有两种方式：云机部署和本地自部署。

本地部署时，macOS 环境通常更省事，很多工具链和脚本对 Mac 更友好。Windows 也可以部署，但调环境的成本会更高。

如果只是运行 OpenClaw、调用各种 API（应用程序编程接口），机器性能压力并不大；真正吃配置的是本地文生图、文生视频、TTS（文本转语音）等模型。硬件选择可以按下面的思路判断：

LLM（Large Language Model，大语言模型）的选择会直接影响 Agent 的稳定性。低能力模型经常会把工具参数写错、忘记角色边界、错误调用 skill，最后表现为“Agent 不可靠”。如果预算允许，优先使用 SOTA（State of the Art，当前领先水平）模型，更容易判断问题到底来自框架配置，还是来自模型能力不足。

安全边界必须提前设计

OpenClaw 一旦接入 IM（Instant Messaging，即时通信）工具，就相当于把一个能调用工具、能读写文件、能访问本地资源的机器人暴露给聊天入口。安全风险不能靠“我会小心使用”来兜底，而要靠权限隔离和最小授权来控制。

需要特别注意几件事：

OpenClaw 的配置应按“某些数据可能会被 IM、LLM、工具链同时接触”来设计。只要这个前提成立，很多权限决策就会变得更谨慎。

快速安装与初始化

安装前准备两类信息：

1. IM 平台的 Bot API 配置；
2. LLM 模型的 API Key、Base URL、模型名称等信息。

本机安装命令如下：

curl -fsSL https://openclaw.ai/install.sh | bash

安装完成后会进入 onboarding 流程，用来配置主 Agent、IM Bot、LLM 模型等基础信息。skills 配置可以先跳过，等主流程跑通后再做精细化管理。

不建议让代码助手在不了解 OpenClaw 项目结构的情况下直接改配置。更稳的方式是：

flowchart LR
    A[下载 OpenClaw 源码] --> B[让代码助手理解源码结构]
    B --> C[描述本地配置问题]
    C --> D[辅助定位和 Debug]
    D --> E[人工确认配置变更]

代码助手适合辅助排错，但 OpenClaw 的 Agent 配置、workspace、sessions、skills 之间有关联，盲改很容易出现“短期能跑，后续难维护”的状态。

Agent workspace 的核心文件

OpenClaw 的每个 Agent 都有自己的 workspace。Agent 的人格、权限、长期记忆、用户偏好和启动引导，主要由一组 Markdown 文件描述。

这些文件会在 Agent 运行时被加载，并参与构造 system prompt。源码层面可以抽象成类似下面的逻辑：

export async function loadWorkspaceBootstrapFiles(dir: string) {
  const entries = [
    { name: "AGENTS.md", filePath: path.join(dir, "AGENTS.md") },
    { name: "SOUL.md", filePath: path.join(dir, "SOUL.md") },
    { name: "TOOLS.md", filePath: path.join(dir, "TOOLS.md") },
    { name: "IDENTITY.md", filePath: path.join(dir, "IDENTITY.md") },
    { name: "USER.md", filePath: path.join(dir, "USER.md") },
    { name: "HEARTBEAT.md", filePath: path.join(dir, "HEARTBEAT.md") },
    { name: "BOOTSTRAP.md", filePath: path.join(dir, "BOOTSTRAP.md") },
  ];

  // 还会动态检测 MEMORY.md / memory.md
  // 读取时需要做路径和文件边界校验，避免路径穿越

  for (const entry of entries) {
    await readWorkspaceFileWithGuards(entry);
  }
}

AGENTS.md 通常最重要，因为它定义了 Agent 的职责、工作边界、记忆管理方式、工具调用原则和与其他 Agent 的协作规则。想让 Agent 长期稳定执行某类任务，不要只在聊天窗口里口头提醒，而要把规则写进 AGENTS.md。

Agent 的启动流程

OpenClaw 的 Agent 不是一个永远不销毁的常驻大脑。更准确的理解是：每次会话触发运行时，OpenClaw 会加载 workspace、恢复 session、构造 system prompt、创建 Agent Session、执行任务，然后把结果和状态写回文件系统。

flowchart TD
    A[IM 消息到达 Gateway] --> B[解析 Agent 和 sessionKey]
    B --> C[读取 workspace bootstrap 文件]
    C --> D[准备 SessionManager]
    D --> E[构造 system prompt]
    E --> F[加载 Skills 列表]
    F --> G[创建 Agent Session]
    G --> H[调用 LLM 与工具]
    H --> I[写回 session / memory / 文件]
    I --> J[返回 IM 消息]

可以用一段伪代码表示这个过程：

import { createAgentSession } from "@mariozechner/pi-coding-agent";

// 1. 加载 workspace 上下文
const bootstrap = await resolveBootstrapContextForRun({
  workspaceDir,
  agentId,
});

// 2. 准备 session 管理器
const sessionManager = await prepareSessionManagerForRun({
  sessionKey,
  workspaceDir,
});

// 3. 构造 system prompt
const systemPrompt = buildEmbeddedSystemPrompt({
  bootstrapFiles: bootstrap.files,
  skills,
});

// 4. 创建 Agent Session
const agentSession = await createAgentSession({
  model,
  systemPrompt,
  sessionManager,
  tools: createOpenClawCodingTools({ workspaceDir }),
});

这里有一个很关键的点：system prompt 是动态构造的。也就是说，AGENTS.md、SOUL.md、TOOLS.md 等文件的修改，会在新的运行过程中被重新读取。某些 session 级快照除外，例如 skills 快照，后面会单独讲。

Session 与 Memory：OpenClaw 如何处理记忆

OpenClaw 的记忆不是单一文件，而是由会话历史、按天记录的 memory、精炼后的 MEMORY.md 一起组成。

典型路径如下：

# 会话历史，JSON Lines 格式
.openclaw/agents/ceo/sessions/xxxx.jsonl

# 按天记录的 memory
.openclaw/workspace-ceo/memory/YYYY-MM-DD.md

# 精炼后的长期记忆
.openclaw/workspace-ceo/MEMORY.md

三者的分工可以这样理解：

Session Header

每个 JSONL 会话文件的第一行是 session 元数据，通常包含 sessionId、工作目录、时间戳等信息。

{
  "type": "session",
  "version": 3,
  "id": "fd292408-168e-4c7b-9f2a-ff7ec0a7c492",
  "timestamp": "2026-03-04T16:11:50.567Z",
  "cwd": "/Users/example/.openclaw/workspace-ceo"
}

消息到达后，OpenClaw 会根据 sessionKey 找到对应的 sessionId，再加载对应 JSONL 文件。这个过程是按需发生的，不是把所有历史都提前塞进模型。

sequenceDiagram
    participant IM as IM Bot
    participant G as Gateway
    participant SM as SessionManager
    participant F as JSONL 文件
    participant L as LLM

    IM->>G: 新消息
    G->>SM: 根据 sessionKey 找 sessionId
    SM->>F: 加载对应 session JSONL
    F-->>SM: 返回历史记录
    SM->>SM: 过滤 / 压缩 / 裁剪
    SM->>L: 发送可用上下文
    L-->>G: 返回回复或工具调用
    G-->>IM: 回复用户

长会话不会全部塞进 Context

Transformer 架构的 LLM 受到 context 窗口限制。会话越来越长时，如果把所有用户消息、助手回复、工具结果都塞进去，成本会升高，速度会变慢，还会挤掉真正重要的上下文。

OpenClaw 主要靠三类策略控制上下文长度。

Compaction 的效果大致如下：

压缩前：
[user1, assistant1, user2, assistant2, ..., user100, assistant100]

压缩后：
[compaction_summary, user80, assistant80, ..., user100, assistant100]

Session Pruning 更像临时清理：

JSONL 文件中仍然保存：
[user1, assistant1, toolResult1(10KB), user2, assistant2, toolResult2(5KB)]

实际发送给 LLM：
[user1, assistant1, "[Old tool result cleared]", user2, assistant2, toolResult2(5KB)]

压缩会改变后续会话看到的历史，修剪只影响本次送入模型的上下文。

Agent 如何写入 MEMORY.md

当 session 接近 context 上限时，OpenClaw 会提示 Agent 把重要信息写入 Memory，再进行 session 压缩。Agent 本质上是通过文件系统工具更新 MEMORY.md 或按天 memory 文件，例如 fsWrite、fsAppend。

一个合理的记忆流转可以画成这样：

flowchart TD
    A[用户对话和工具结果] --> B[Session JSONL]
    B --> C{上下文是否过长}
    C -- 否 --> D[继续使用近期 session]
    C -- 是 --> E[提炼关键信息]
    E --> F[memory/YYYY-MM-DD.md]
    F --> G[更新 MEMORY.md]
    E --> H[Compaction Summary]
    H --> B

    G --> I{后续任务是否需要长期背景}
    I -- 需要 --> J[检索 / 注入相关 Memory]
    I -- 不需要 --> K[只使用当前 Session]

长期记忆的质量很依赖 Agent 的规则设计。如果 AGENTS.md 没有明确“什么信息值得写入长期记忆、什么信息只是临时上下文”，Agent 就容易把无关内容写进去，后续检索时造成污染。

为什么需要多 Agent

单 Agent 最大的问题不是“不能做事”，而是容易把不同领域的上下文混在一起。

假设一个 Agent 原本负责 Flutter 学习辅导，中途又频繁讨论 C++、部署脚本、家庭事务、论文摘要。由于 session 和 memory 会保留这些内容，后续再让它生成 Flutter 示例时，它可能错误地联想到 C++ 示例。这不是模型完全不会 Flutter，而是上下文被污染了。

flowchart LR
    A[单 Agent] --> B[Flutter 学习]
    A --> C[C++ 讨论]
    A --> D[家庭提醒]
    A --> E[论文摘要]
    B --> F[Memory 混杂]
    C --> F
    D --> F
    E --> F
    F --> G[检索偏移 / 示例跑题 / Context 浪费]

更稳的方式是让 Agent 专事专做：

多 Agent 的核心不是“数量越多越好”，而是降低 context 污染，让每个 Agent 的 memory、skills、工具权限都围绕固定职责设计。

新增 Agent

新增 Agent 可以使用 OpenClaw CLI：

openclaw agents add iostutor

新增过程中会进入 onboarding，按提示填入 IM Bot API 和 LLM API 即可。完成后，通常会生成新的 agent 配置目录和 workspace，例如：

.openclaw/
  agents/
    ceo/
    iostutor/
  workspace-ceo/
  workspace-iostutor/

多 Agent 建好后，还需要配置它们之间的通信方式，否则它们只是多个互不认识的独立 Agent。

多 Agent 通信：sessions_send 与 sessions_spawn

OpenClaw 中 Agent 之间常见的协作方式有两种：sessions_send 和 sessions_spawn。

可以用“同事沟通”和“临时外包任务”来理解：

flowchart TD
    A[ceo Agent] --> B{需要 iostutor 做什么}

    B -- 延续某个讨论<br/>需要写入对方 session --> C[sessions_send]
    C --> D[iostutor 既有 session]
    D --> E[双方后续可继续基于上下文沟通]

    B -- 一次性明确任务<br/>完成后返回结果 --> F[sessions_spawn]
    F --> G[iostutor 子任务环境]
    G --> H[返回交付物]

配置 sessions_send

sessions_send 依赖 agentToAgent 能力和 session 可见性配置。需要在 openclaw.json 中打开 Agent 间通信，并允许相关 Agent 互相可见。

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["ceo", "iostutor"]
    },
    "sessions": {
      "visibility": "all"
    }
  }
}

visibility: "all" 很容易漏掉。没有这个配置时，Agent 可能知道有通信工具，但找不到目标 session。

如果有多个核心 Agent，并且希望它们像一个扁平团队一样互相沟通，可以把核心 Agent 都加入 allow 列表：

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["ceo", "iostutor", "paper", "family"]
    },
    "sessions": {
      "visibility": "all"
    }
  }
}

配置 sessions_spawn

sessions_spawn 需要配置 subagents。比如希望 ceo 可以把任务派给 iostutor：

{
  "id": "ceo",
  "name": "ceo",
  "workspace": "/Users/example/.openclaw/workspace-ceo",
  "agentDir": "/Users/example/.openclaw/agents/ceo/agent",
  "model": "openai-codex/gpt-5.3-codex",
  "subagents": {
    "allowAgents": ["iostutor"]
  }
}

如果两个 Agent 可以互相派任务，就需要在两个 Agent 的配置里分别加入对方：

[
  {
    "id": "iostutor",
    "name": "iOSTutor",
    "workspace": "/Users/example/.openclaw/workspace-iostutor",
    "agentDir": "/Users/example/.openclaw/agents/iostutor/agent",
    "model": "openai-codex/gpt-5.3-codex",
    "subagents": {
      "allowAgents": ["ceo"]
    }
  },
  {
    "id": "ceo",
    "name": "ceo",
    "workspace": "/Users/example/.openclaw/workspace-ceo",
    "agentDir": "/Users/example/.openclaw/agents/ceo/agent",
    "model": "openai-codex/gpt-5.3-codex",
    "subagents": {
      "allowAgents": ["iostutor"]
    }
  }
]

但不是所有 Agent 都应该互为 subagent。像 Markdown formatter、图片生成器、TTS 播报器这类工具型 Agent，通常只需要被上层 Agent 调用，不一定需要主动联系其他 Agent。

LLM 如何选择 send 还是 spawn

当 sessions_send 和 sessions_spawn 都可用时，具体调用哪个工具取决于 LLM 对任务的判断。

为了让 Agent 稳定选择正确工具，不能只靠聊天窗口里的临时说明。应该把 Agent 路由规则写进 AGENTS.md。

例如在 workspace-ceo/AGENTS.md 中加入：

## AgentToAgent 通信规则

当任务需要其他角色参与时，按下面的规则选择：

- iOS、Swift、Flutter 学习和代码示例：联系 `iostutor`
- 每日论文、模型动态、技术趋势：联系 `paper`
- 家庭日程、天气、提醒：联系 `family`
- Markdown 排版和格式清理：调用 `formatter`

如果任务需要延续对方已有上下文，使用 sessions_send。
如果任务是一次性明确交付，使用 sessions_spawn。

AGENTS.md 会进入 system prompt，比在聊天窗口里说一次更可靠。否则几天后 session 被压缩，Agent 可能会忘记怎样联系其他 Agent。

sessions_send 会复用旧 session

sessions_send 不会因为时间间隔自动创建新 session。只要目标 session 还存在，它会继续向已有 session 发消息。

例如 6 小时前 ceo 和 iostutor 已经通过内部 session 通信：

agent:ceo:internal:main
agent:iostutor:internal:main

6 小时后继续使用 sessions_send，仍然会复用这些 session。好处是上下文连续，代价是旧上下文可能污染后续讨论。对于完全无关的新任务，可以考虑用 sessions_spawn。

IM 调用额度：多 Agent 容易踩的坑

多 Agent 部署后，IM 平台调用额度会明显增长。OpenClaw gateway 里存在定时健康快照逻辑，类似下面这样：

const healthInterval = setInterval(() => {
  void params.refreshGatewayHealthSanpshot({ probe: true });
}, 60_000);

如果每个 Agent 都需要定期 ping IM，Agent 数量一多，额度消耗会很快放大。

多 Agent 不是越多越强。更推荐保留少量核心 Agent，再把格式化、TTS、文生图这类能力设计成工具型 subagent。

Skills 的加载机制

Skills 是 OpenClaw 扩展能力的重要方式，但它不是把所有 skill 文档完整塞进 system prompt。更合理的做法是：system prompt 只注入 skill 列表，Agent 判断需要时，再用 read 工具读取完整的 SKILL.md。

flowchart TD
    A[扫描 Skills 目录] --> B[按优先级合并]
    B --> C[检查 requires 条件]
    C --> D[生成 available_skills 列表]
    D --> E[注入 system prompt]
    E --> F{Agent 是否需要某个 skill}
    F -- 需要 --> G[read SKILL.md]
    F -- 不需要 --> H[不加载完整内容]

Skills 来源有优先级：

每个 skill 还可以声明运行条件，例如依赖命令、环境变量、配置项。以 weather skill 为例：

name: weather
description: "Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed."
homepage: https://wttr.in/:help
metadata:
  openclaw:
    emoji: "🌤️"
    requires:
      bins:
        - curl

如果当前环境没有 curl，这个 skill 就应该被过滤掉，避免 Agent 看到一个无法执行的能力。

注入到 system prompt 的通常是类似这样的列表：

<available_skills>
  <skill>
    <name>healthcheck</name>
    <description>Check whether the configured gateway and services are healthy.</description>
    <location>~/.openclaw/skills/healthcheck/SKILL.md</location>
  </skill>
  <skill>
    <name>weather</name>
    <description>Get current weather and forecasts.</description>
    <location>~/.openclaw/skills/weather/SKILL.md</location>
  </skill>
</available_skills>

Skills 应该按 Agent 职责精细化配置

Skills 过多会带来两个问题：

1. skill 列表本身占用 context；
2. Agent 更容易错误调用不相关 skill。

更稳的设计是“通用基础 skills + Agent 专属 skills”。

例如 brave-search 属于通用联网检索能力，可以共享；weather 如果只服务家庭提醒，就不应该暴露给所有 Agent。

Skills 更新后为什么没有立刻生效

OpenClaw 在 session 启动时会创建 skills 快照，并在当前 session 生命周期内复用。修改 skills 目录后，旧 session 可能仍然看到旧列表。

处理方式通常是：

# 思路示例：找到对应 agent 的旧 session
ls ~/.openclaw/agents/ceo/sessions

# 删除不再需要的旧 session 文件，或新建 session
rm ~/.openclaw/agents/ceo/sessions/<old-session>.jsonl

# 重启 gateway
openclaw restart

实际操作前要确认 session 文件是否还有保留价值。删除 session 会丢失对应会话历史；如果里面有重要信息，先提炼到 MEMORY.md。

用 Clawhub 管理 Skills

Clawhub 可以理解为 OpenClaw 的 Skills Market，常用命令如下：

# 语义搜索 Skills
clawhub search "calendar management"

# 安装指定 Skill
clawhub install <skill-slug>

# 列出已安装的 Skills
clawhub list

# 更新所有已安装的 Skills
clawhub update --all

# 同步并备份本地 Skills
clawhub sync

可关注的 skill 类型包括：

Skills 安装太容易，反而需要定期治理。可以周期性让高阶模型扫描本地 skills，清理低质量、重复、冲突或长期不用的 skill。

OpenClaw 配置的版本控制

OpenClaw 会沉淀大量本地数据：Agent 配置、workspace、skills、memory、session、密钥。直接把整个 .openclaw 目录提交到 Git 风险很高。

比较合理的策略是：版本化框架配置和可复用规则，不版本化敏感数据和私人会话。

.gitignore 可以按下面的方向设计：

# 会话历史，通常包含私人对话和工具结果
.openclaw/agents/*/sessions/

# 按天记忆，可能包含隐私
.openclaw/workspace-*/memory/

# 精炼长期记忆，也可能包含隐私
.openclaw/workspace-*/MEMORY.md

# 本地密钥和环境变量
.env
.env.local

# 临时缓存
.openclaw/**/cache/
.openclaw/**/tmp/

可以纳入版本管理的内容：

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
HEARTBEAT.md
BOOTSTRAP.md
skills 中自己编写且不含密钥的部分
openclaw.json 的脱敏模板

openclaw.json 如果同时包含核心配置和密钥，不要直接提交。可以拆成模板加环境变量注入：

{
  "model": "openai-codex/gpt-5.3-codex",
  "apiKeyEnv": "OPENAI_API_KEY",
  "baseUrlEnv": "OPENAI_BASE_URL"
}

然后在本机 .env.local 中保存真实密钥：

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://example.com/v1

可落地的 Agent 场景

OpenClaw 的玩法很多，关键是把任务拆成稳定输入、稳定工具、稳定输出。

例如 RAG Tutor 可以把资料放到专属 workspace 中：

.openclaw/workspace-iostutor/
  AGENTS.md
  MEMORY.md
  materials/
    swift-concurrency.md
    flutter-state-management.md
    ios-networking.md

AGENTS.md 中写清楚它的角色：

## 角色

你是 iOS / Swift / Flutter 学习辅导 Agent。

## 工作方式

- 回答技术问题时，优先检索 workspace 中的 materials 目录。
- 示例代码默认使用 Swift 或 Dart，除非用户明确要求其他语言。
- 如果问题超出 iOS / Swift / Flutter 范围，说明边界，并建议联系更合适的 Agent。
- 重要学习偏好可以写入 MEMORY.md，临时讨论不要写入长期记忆。

这样可以减少“明明是 Flutter Tutor，却突然输出 C++ 示例”的概率。

多 Agent 设计建议

多 Agent 架构不是组织层级越复杂越好。更推荐从少量清晰角色开始，等边界稳定后再拆分。

一个相对稳的结构可以是：

flowchart TD
    CEO[ceo<br/>任务拆解与调度]

    CEO <--> IOS[iostutor<br/>iOS / Flutter 学习]
    CEO <--> PAPER[paper<br/>论文与技术动态]
    CEO <--> FAMILY[family<br/>家庭提醒与日程]

    CEO --> FORMAT[formatter<br/>Markdown 排版]
    CEO --> IMAGE[image<br/>ComfyUI 生成]
    CEO --> VOICE[voice<br/>TTS 播报]

    IOS --> FORMAT
    PAPER --> FORMAT
    FAMILY --> VOICE

双向箭头表示可以用 sessions_send 延续沟通；单向箭头表示更适合用 sessions_spawn 做一次性任务。

一份部署检查清单

OpenClaw 跑起来不难，长期稳定使用更依赖配置治理。可以按这份清单检查：

OpenClaw 的核心思路可以概括成一句话：用文件系统和配置约定，把 Agent 的身份、工具、记忆、技能和协作关系固定下来，再让 LLM 在这些边界内执行任务。真正把它用稳，不是多装几个 skill 或多建几个 Agent，而是持续维护好每个 Agent 的职责边界、上下文质量和安全权限。