OpenClaw多Agent架构与上下文管理笔记

对话背景：围绕 OpenClaw 多 Agent 架构的上下文隔离、Sub-agent 机制、Skill 隔离、并发调度、记忆压缩等核心机制进行系统性问答。

核心需求：理解 OpenClaw 的上下文管理、Sub-agent 创建与隔离、Skill 权限控制、并发与路由机制，并能够配置实现。

一、架构设计理念：从职能划分到上下文隔离

1.1 核心观点

多 Agent 架构不应按"角色"（规划者/执行者/审查者）划分，而应转向上下文隔离 + 工具模块化。

• Anthropic：通过 Harness 实现模型-工具-环境解耦
• OpenAI：通过 Managed Agents 实现元调度
• Google：通过 Session 化重构 实现上下文隔离

1.2 关键收益

• 上下文连续性可控
• Token 消耗可隔离（Sub-agent 做脏活，主流程保持清爽）
• 工具与能力按需加载，而非按角色绑定

二、核心概念速查（按首次出现顺序排列）

三、上下文（Context）与压缩机制

3.1 Context 的组成

Context 不是"对话框"，而是 Agent 单次推理时的完整信息栈：

1. System Prompt（SOUL.md + MEMORY.md + CLAUDE.md）
2. 历史对话消息（用户输入 + Agent 输出 + 工具调用结果）
3. 加载的 Skill 文件（SKILL.md）
4. 当前工具返回的实时结果

规格与限制：

• 硬上限：受模型上下文窗口限制（Claude 200K、GPT-4o 128K 等）
• 软上限：Bootstrap（系统提示词）单文件默认 20K 字符，总计约 150K
• 压缩触发线：对话 Token 逼近上限时（默认提前 4000 tokens）触发 Auto-Compaction

3.2 五级上下文压缩（由轻到重依次触发）

触发方式：

• 自动：当前 Token > 窗口大小 - 预留缓冲（如 200K 窗口预留 20K，超过 180K 触发）
• 手动：用户输入 /compact
• 强制溢出：LLM 返回"上下文太长"错误时，以 trigger: "overflow" 强制执行

3.3 切片（Chunking）的自适应算法

核心参数：

• BASE_CHUNK_RATIO = 0.4：默认每块占上下文窗口的 40%
• MIN_CHUNK_RATIO = 0.15：单条消息平均占窗口 10% 以上时，自动缩小到 15%
• SAFETY_MARGIN = 1.2：给摘要指令和输出预留 20% 安全缓冲

计算示例（200K 窗口）：

场景 A：普通聊天（消息短而多）

• 历史 30 条共 150K，平均每条 5K（占窗口 2.5% < 10%）
• 触发 BASE_CHUNK_RATIO = 0.4
• 每块额定大小 = 200K × 0.4 = 80K
• 实际可装历史 = 80K ÷ 1.2 ≈ 66.7K
• 150K 历史 ÷ 66.7K ≈ 3 块
• 每块装约 13 条消息（按 Token 累积，非固定条数）

场景 B：长文档分析（消息长而少）

• 历史 5 条共 150K，平均每条 30K（占窗口 15% > 10%）
• 触发 MIN_CHUNK_RATIO = 0.15
• 每块额定大小 = 200K × 0.15 = 30K
• 实际可装历史 = 30K ÷ 1.2 = 25K
• 150K 历史 ÷ 25K = 6 块
• 每块装约 1 条长消息

为什么自适应？

• 消息短：大块切，一次多装几条，减少 API 调用次数
• 消息长：小块切，一次少装几条，防止 LLM 超载、摘要遗漏细节

3.4 压缩时的标识符保全

压缩过程中禁止模型改写：

• UUID、API Key、Hash、Hostnames
• 确保"风景可以被遗忘，但执行锚点依旧精准"

3.5 Silent Turn（静默固化）

当 Token 逼近红线（默认提前 4000 tokens），系统抛出用户看不见的静默提示，让模型在"被洗脑前"把重要线索写入当天日志，再输出 NO_REPLY。

四、Session 机制

4.1 Session 的本质

Session 是交互实例，Agent 是处理大脑。一个 Agent 可服务多个 Session，但 Session 之间上下文完全隔离。

Session Key 格式：

agent:<agent-name>:<channel>:<mode>:<user-id>

示例：

• agent:main:feishu:direct:ou_123（飞书私聊）
• agent:main:discord:thread:thread_789（Discord 线程）

4.2 存储位置

每个 Session 的聊天记录独立存储在：

~/.openclaw/agents/<agentId>/sessions/

4.3 并发调度配置

多个 Session 同时向同一个 Agent 发消息时，Gateway 通过两层队列管理：

配置示例：

{
  "agents": {
    "defaults": {
      "maxConcurrent": 4
    }
  },
  "messages": {
    "queue": {
      "mode": "collect",
      "debounceMs": 1000,
      "cap": 20,
      "drop": "summarize"
    }
  }
}

队列模式：

• followup：每条消息单独触发 Agent run
• collect：快速连续消息先收集，等安静期后合并处理
• steer-backlog：高级模式，可手动干预队列

溢出策略：

• old：丢弃最旧消息
• new：丢弃最新消息
• summarize：默认，把被丢弃消息合成摘要注入上下文

五、Harness（调度核心）

5.1 定义

Harness 是维持循环、拼装 Prompt、路由工具调用到对应基础设施的控制层。Anthropic 将 Agent 拆解为四层：

5.2 在 OpenClaw 中的实现

• Gateway：维护长连接、消息路由、协议转换、安全验证
• Agent Loop（基于 pi-mono 的 ReAct 循环）：调用模型 → 解析工具请求 → 分发执行 → 收集结果 → 继续循环

5.3 工具调用与输出格式

1. 组装 System Prompt + 历史消息
2. 调用 LLM API
3. 模型返回内容（包含 <thinking> 和 <tool> 标签）
4. Agent Loop 解析输出：
   • 普通文本 → 直接返回用户
   • 工具调用 → 提取参数 → 路由到 Tool Handler → 执行 → 收集结果 → 格式化为 Observation → 追加到上下文 → 再次调用 LLM（ReAct 循环）

输出格式控制：

• Tool 定义采用 JSON Schema 约束，模型必须按 Schema 输出参数
• 在 Skill 的 SKILL.md 中可定义输出模板（Markdown 表格、JSON、YAML）

六、Sub-agent 机制

6.1 核心作用

用隔离的 Context Window 消耗 Token、做搜索/分析，然后把结果压缩成 1000–2000 Token 的摘要合并回主流程。

6.2 创建方式

Sub-agent 是 Main Agent 动态创建的，不是用户在 JSON 中预定义的独立 Agent。

创建流程：

1. Main Agent 调用内置工具 sessions_spawn
2. Gateway 立即返回 childSessionKey 和 runId，不阻塞
3. 后台创建独立 Session（如 agent:main:subagent:<uuid>）
4. Sub-agent 在独立 Context Window 中异步执行任务
5. 完成后通过 announce 把结果推回父 Agent 的聊天上下文

调用示例（LLM 自动生成）：

{
  "tool": "sessions_spawn",
  "parameters": {
    "agent": "code-reviewer",
    "task": "审查 PR #123 的安全性",
    "mode": "run"
  }
}

模式区别：

• mode: "run"：一次性跑完返回结果
• mode: "session"：持久化，可后续交互

6.3 独立 Agent vs Sub-agent

6.4 配置控制

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "anthropic/claude-haiku-4-5",
        "thinking": "low",
        "maxConcurrent": 4,
        "runTimeoutSeconds": 300,
        "archiveAfterMinutes": 30
      }
    },
    "list": [
      {
        "id": "main",
        "subagents": {
          "allowAgents": ["code-reviewer", "doc-writer"],
          "maxSpawnDepth": 1,
          "maxChildrenPerAgent": 5
        }
      }
    ]
  }
}

配置项解释：

嵌套深度限制：

• maxSpawnDepth: 1：Main → Sub（Sub 不能再 spawn）
• 优点：防止 Token 成本爆炸、调度混乱、架构扁平化、安全隔离（深度 ≥ 2 时 Sub-agent 默认被剥夺 sessions_spawn）

并行任务启用：
由 Main Agent 的 LLM 自行判断。当用户提出可拆分的复杂任务时，LLM 会连续调用多次 sessions_spawn。真正的并行受限于 maxConcurrent。

6.5 成本对比

• 5 个并行 Haiku Sub-agent 的 Token 成本 ≈ 1 个 Opus 主 Agent 的 Token 成本
• Sub-agent 把 10 万 Token 的调研过程压缩成 1000 Token 摘要传回，父 Agent 只需处理摘要

七、记忆系统

7.1 记忆生成时机

7.2 存储结构

• MEMORY.md：长期核心事实
• memory/YYYY-MM-DD.md：每日日志
• AGENTS.md：能力反思

7.3 混合检索机制

对 memory/*.md 日志采用 向量搜索（语义匹配）+ BM25（关键词搜索），权重 7:3，互补召回。

时间半衰期：默认 30 天，过时记忆自然衰减淘汰。

7.4 分块写入与检索优化

问题：默认按 400 Token/块 硬切，不识别语义边界，可能切断句子。

补偿策略：

Markdown 标题分块示例：

# Session: 2026-04-24
## Summary
用户决定使用 Next.js。

## Key Points
- 用户偏好 Telegram 通知

## Action Items
- [ ] 调研 Next.js 14

分块后：

• Chunk 0：# Session... 到 ## Key Points 之前
• Chunk 1：- 用户偏好... 到结尾

为什么有效：底层算法遇到 Markdown 标题会优先断开，保证每个块内部语义自洽。

八、Skill 管理与隔离

8.1 Skill 加载优先级（从高到低）

1. <workspace>/skills/                    ← Agent 私有（最高）
2. <workspace>/.agents/skills/             ← 项目级私有
3. ~/.agents/skills/                       ← 个人级共享
4. ~/.openclaw/skills/                    ← 机器级共享
5. 内置 skills（随安装包提供）            ← 全局
6. skills.load.extraDirs                  ← 额外配置目录（最低）

8.2 隔离手段

8.3 关键配置项

{
  "skills": {
    "load": {
      "extraDirs": ["/company/shared-skills"]
    },
    "allowBundled": ["filesystem", "exec", "git"]
  }
}

• extraDirs：额外加载 Skill 的目录路径数组，优先级最低
• allowBundled：允许使用的内置工具白名单

8.4 两个 Agent 隔离 Skill 的最佳实践

• 敏感 Skill（如 kubectl、db-admin）放在特定 Agent 的私有目录
• 通用 Skill（如 git、search）放在 ~/.openclaw/skills/ 共享
• 同名 Skill 冲突时，工作区私有版本优先

九、路由与过滤

9.1 Bindings 频道级路由（最硬）

{
  "bindings": [
    { "agentId": "writer", "match": { "channel": "telegram", "accountId": "writing-group" } },
    { "agentId": "coder",  "match": { "channel": "telegram", "accountId": "code-group" } }
  ]
}

• 零 LLM 消耗，按频道/群组固定路由

9.2 SOUL.md / AGENTS.md 路由规则（软引导）

在 Agent 的 AGENTS.md 中写入委派规则，LLM 根据用户输入自行判断 spawn 哪个 Sub-agent：

## Agent 委派规则
- 用户提到"代码"、"PR"、"审查" → 派给 code-reviewer
- 用户提到"文档"、"README" → 派给 doc-writer
- 简单问答 → 自己处理，不要 spawn

9.3 Lobster 工作流编排（确定性流程）

Lobster 是 OpenClaw 原生工作流引擎，通过 YAML 定义确定性执行流程。

启用方式：

1. 安装：pnpm install -g lobster
2. 在 openclaw.json 中启用工具："tools": { "alsoAllow": ["lobster"] }
3. 在 workspace 创建 .lobster 文件

示例：

name: blog-pipeline
steps:
  - id: research
    pipeline: openclaw.invoke --tool llm-task --action json ...
  - id: write
    stdin: $research.json
  - id: review
    approval: "Review before publishing?"

注意：Lobster 是工作流编排，不是"前置关键词过滤层"。

9.4 前置关键词路由（当前限制）

OpenClaw 原生不支持精确的关键词 → Sub-agent 映射表。如需 100% 确定性关键词路由，需在外部自建 Gateway 插件或前置分类器。

十、文件系统与 Sandbox

10.1 Sandbox 配置

{
  "agents": {
    "list": [{
      "id": "main",
      "sandbox": {
        "mode": "all",
        "workspaceAccess": "rw"
      }
    }]
  }
}

10.2 路径限制

• tools.fs.workspaceOnly: true 时，read/write/edit 只能操作工作区目录内文件
• 沙箱阻止 ../ 路径逃逸

十一、关键配置参数汇总表

十二、最佳实践与避坑指南

1. Sub-agent 用便宜模型："model": "anthropic/claude-haiku-4-5"，降低成本
2. 敏感 Skill 不放共享层：放在 Agent 私有目录，防止越权访问
3. Sandbox 生产环境必开："mode": "all"，防止文件系统逃逸
4. 记忆按主题分文件：memory-frontend.md、memory-backend.md，检索时先文件名过滤
5. 两个飞书机器人绑定同一 Agent 的风险：共享 MEMORY.md，不同群体（对外客户/对内员工）绝对不要绑定同一 Agent，防止信息泄露
6. 不要依赖 LLM 做精确关键词路由：如需 100% 确定性，用 Bindings 频道隔离或外部分类器
7. Compaction 前利用 Silent Turn：系统自动把关键线索写入日志，防止压缩丢失上下文锚点
8. 验证 Skill 隔离：使用 openclaw skills list --agent <id> --show-source 检查实际加载来源