精通 OpenClaw 系统架构-文章专栏-方倍工作室

本文梳理了 OpenClaw 中 Gateway、Agent、Workspace、Session、Session Key、Memory、Context、AgentDir 和 Delivery Route 等核心概念之间的关系。

Agent 是最顶层的“大脑”单元，Workspace 是这个大脑的文件系统家目录，Session 是这个大脑内部的一条对话线，Context 是每次推理时模型实际看到的内容快照。

一、总体层级结构

Gateway（网关守护进程） │ └── Agent（智能体）× N                     ← --agent      │      ├── Workspace（工作区 · 文件系统层）      │    ├── 人设 / 指令文件      │    ├── Memory（跨 session 持久记忆）      │    └── Skills（技能包）      │      ├── Session（会话层）× N              ← --session      │    ├── 对话历史（transcript .jsonl）      │    ├── Context（上下文快照 · 每次推理）      │    ├── Session Key（会话键）      │    └── Delivery Route（消息交付路由）      │      └── AgentDir（运行时状态目录）           └── ~/.openclaw/agents//

如果用一句话概括三者的包含关系：

Agent（智能体） ├── Workspace（工作区）：agent 的文件系统主目录 ├── Session（会话）：agent 的对话历史单元 │    └── Session Key（会话键）：标识具体某条对话线 └── AgentDir（状态目录）：agent 的运行时私有状态

二、核心概念详解

1. Gateway（网关）

Gateway 是整个系统的统一入口和调度中枢。

所有消息渠道（微信、飞书、钉钉、QQ、企业微信、Telegram、WhatsApp、Slack 等）和所有客户端（CLI、macOS App、WebChat 等）都通过 WebSocket 连接到 Gateway。Gateway 负责接收消息、识别路由规则、分发给对应 Agent，并把结果送回相应渠道。

通常每台主机只运行一个 Gateway 实例。

2. Agent（智能体）`--agent`

Agent 是 Gateway 下的最顶层逻辑单元，代表一个完整且独立的“大脑”。

每个 Agent 拥有完全隔离的：

• 自己的 Workspace：文件、记忆、技能和人设。 • 自己的 AgentDir：认证信息、模型配置和运行时状态。 • 自己的 Session Store：该 Agent 的所有对话历史。

默认只有一个 Agent，id 为 main，对应状态目录：

~/.openclaw/agents/main/

常见命令：

openclaw agent --agent main --message "..."openclaw agents add workopenclaw agents list --bindings

其中：

openclaw agent --agent main --message "..."

表示：使用 main 这个 Agent 的大脑，即它自己的 workspace、记忆、配置和默认 session，来处理这次消息。

多 Agent 典型场景：

• main：处理私人事务。 • work：处理工作事务。 • family：处理家庭群组。

这些 Agent 的 workspace、状态、认证、session 和记忆相互隔离。

3. Workspace（工作区）

Workspace 是 Agent 的文件系统家目录，也是工具执行时的默认工作目录（cwd），并且是注入 system prompt 的关键文件来源。

默认路径：

~/.openclaw/workspace/

一个典型 Workspace 结构如下：

workspace/ ├── AGENTS.md        # 操作指令 / 行为规范 ├── SOUL.md          # 人设 / 性格 / 边界 ├── USER.md          # 用户信息 / 称呼偏好 ├── IDENTITY.md      # agent 名字 / Emoji ├── TOOLS.md         # 工具使用约定 ├── HEARTBEAT.md     # 定时心跳检查清单 ├── BOOT.md          # 启动检查清单 ├── BOOTSTRAP.md     # 首次运行仪式（完成后删除） ├── MEMORY.md        # 长期记忆（精华层） ├── memory/ │    └── YYYY-MM-DD.md   # 每日工作笔记 ├── DREAMS.md        # 梦境日志（可选，dreaming 功能） └── skills/          # 工作区技能包

可以把 Workspace 理解为 Agent 的“硬盘”：它保存人设、操作准则、用户信息、长期记忆、日常记忆和技能包。

4. AgentDir（运行时状态目录）

AgentDir 是 Agent 的运行时私有状态目录，不在 Workspace 里，也不应纳入版本控制。

路径：

~/.openclaw/agents//

典型结构：

~/.openclaw/agents// ├── agent/ │    ├── auth-profiles.json    # 模型 API Key / OAuth Token │    └── codex-home/           # Codex 运行时状态 └── sessions/      ├── sessions.json         # 所有 session 元数据索引      └── .jsonl     # 各 session 对话记录

Workspace 与 AgentDir 的区别：

对比项	Workspace	AgentDir
内容	人设、记忆、技能、工作文件	Auth、Sessions、运行时状态
是否建议版本控制	可纳入私有 Git	不建议提交
默认路径	`~/.openclaw/workspace/`	`~/.openclaw/agents//`
角色	Agent 的文件系统家目录	Agent 的运行时状态目录

5. Session（会话）`--session`

Session 是 Agent 内部的一条对话线。一个 Agent 可以有多条 Session，比如按渠道、联系人、群组、任务或定时任务隔离。

Session 存储在：

~/.openclaw/agents//sessions/.jsonl

Session 不跨 Agent。main Agent 的 session 和 work Agent 的 session 是两套完全独立的对话历史。

Session Key 格式：

agent::

常用 --session 值：

值	含义
`main`	默认私信共用会话，也是默认值
`isolated`	每次运行创建全新对话，常用于 cron / webhook
`session:`	指定某条具体会话
`current`	当前活跃会话

常见 Session 重置规则：

• 每日重置：默认在 Gateway 主机时间凌晨 4:00 自动开新 session。 • 空闲重置：可通过 session.reset.idleMinutes 配置。 • 手动重置：在对话中输入 /new 或 /reset。

可以把 Session 理解为 Agent 的“RAM”：它保存当前对话过程中的上下文历史，但可以按规则重置。

6. Memory（记忆）

Memory 是独立于 Session 的持久记忆层，存放在 Workspace 文件中。Session 重置后，对话历史会清空，但 Memory 仍然存在，并可在新 session 启动时重新注入 system prompt。

Memory 的常见三层结构：

层	存储位置	生命周期	作用
`MEMORY.md`	Workspace 根目录	长期保存，手动管理	长期事实、偏好、精华记忆
`memory/YYYY-MM-DD.md`	Workspace 的 `memory/` 目录	永久保存，按日归档	每日工作笔记
`DREAMS.md`	Workspace 根目录	可选	Dreaming 功能的人工审查日志

Memory 与 Session 的区别：

对比项	Session	Memory
比喻	RAM（运行时内存）	硬盘（持久存储）
存储位置	`.jsonl` 对话文件	Workspace 中的 `.md` 文件
生命周期	按天 / 按空闲 / 手动重置	长期保存
重置后	对话历史清空	内容仍在
主要作用	保存对话过程	保存跨 session 的知识和偏好

常见 Memory 工具：

• memory_search：语义搜索历史记忆。 • memory_get：读取指定记忆文件。

7. Context（上下文）

Context 是每次调用模型时实际传入的内容快照。它来自 Session，但不等于完整 Session 历史。

Context 通常由以下内容组成：

Context（传给模型的全部内容） ├── System Prompt（OpenClaw 自动构建） │    ├── 工具列表 + 描述 │    ├── Skills 列表（名称 + 描述） │    ├── 时间 / 运行时元数据 │    └── Workspace 文件注入（Project Context） │         └── AGENTS.md / SOUL.md / MEMORY.md / USER.md 等 ├── 对话历史（Session transcript 中的近期消息） ├── 工具调用 + 工具结果 └── 附件（图片 / 音频 / 文件）

关键点：

• Session 可以很长，保存在磁盘中。 • Context 受模型 token 窗口限制，只是每次推理时送入模型的一部分内容。 • 当历史超出上下文窗口时，会通过 Compaction（压缩归纳）把旧对话总结成摘要，释放 token 空间。

常用检查命令：

/status          # 快速查看 token 窗口占用/context list    # 查看各文件注入大小/context detail  # 查看详细上下文分解/context map     # 查看可视化 treemap/compact         # 手动触发压缩

8. Delivery Route 与 Channel Docking

Session 的对话内容和消息交付目标是分离的。

• Session：保存对话历史，绑定的是一条对话线。 • Delivery Route：决定回复消息发往哪个渠道，可以动态切换。

Channel Docking（渠道停靠）指的是：在不重置 Session 的情况下，把后续回复路由切换到另一个渠道。

示例：

场景：在 Telegram 开始任务，然后切换到 Discord 接收后续回复。Telegram 发送：/dock_discord结果：  - Session 历史不变。  - 后续回复发往 Discord。  - 通常需要配置 session.identityLinks，把两个账号关联到同一身份。

这意味着 OpenClaw 的“对话上下文”和“消息发往哪里”可以解耦。用户可以在一个渠道开始任务，在另一个渠道继续接收结果，而不丢失原有上下文。

三、多 Agent 配置方式

OpenClaw 的多 Agent 配置在：

~/.openclaw/openclaw.json

1. 单 Agent 模式（默认）

{  agents: {    defaults: {      workspace: "~/.openclaw/workspace"    }  }}

默认 Agent id 为 main，使用默认 workspace。

2. 多 Agent 模式

可以为每个 Agent 指定独立 workspace：

{  agents: {    defaults: {      workspace: "~/.openclaw/workspace"    },    list: [      {        id: "main",        workspace: "~/.openclaw/workspace"      },      {        id: "work",        workspace: "~/.openclaw/workspace-work"      },      {        id: "family",        workspace: "~/.openclaw/workspace-family"      }    ]  }}

三条关键规则：

1. 最简单的创建方式是使用向导：

openclaw agents add work

它会自动创建 workspace，并初始化 AGENTS.md、SOUL.md、USER.md 等 bootstrap 文件。

1. 每个 Agent 的 workspace 必须独立，不能复用同一个目录，否则可能导致人设、记忆、auth 或 session 边界混乱。
1. agents.list 中具体 Agent 的 workspace 优先级高于 agents.defaults.workspace。

四、完整概念地图

Gateway │ ├── Channel Plugins（WeChat / Telegram / WhatsApp / Slack ...） │    └── 入站消息 → Bindings 路由规则 → 分发给对应 Agent │ ├── CLI / macOS App / WebChat │    └── 通过 WebSocket 连接 Gateway │ └── Agent: main      │      ├── Workspace（持久文件系统）      │    ├── AGENTS.md / SOUL.md / USER.md / IDENTITY.md      │    │    └── 每次 session 启动时注入 system prompt      │    ├── MEMORY.md      │    │    └── 跨 session 的长期记忆      │    ├── memory/YYYY-MM-DD.md      │    │    └── 每日工作笔记      │    └── skills/      │         └── 工作区技能包      │      ├── Session A: agent:main:main（默认私信）      │    ├── Transcript: .jsonl      │    ├── Context（本次推理快照）      │    │    = System Prompt + Workspace 注入 + 对话历史 + 工具结果      │    └── Delivery Route → WeChat / Telegram / Discord / ...      │      ├── Session B: agent:main:wechat-xxx（某个联系人）      │    └── ...      │      ├── Session C: agent:main:group-xxx（某个群组）      │    └── ...      │      ├── Session D: agent:main:cron-xxx（cron 独立会话）      │    └── ...      │      └── AgentDir（运行时状态）           ├── auth-profiles.json           └── sessions/

多 Agent 场景：

Gateway ├── Agent: main │    ├── Workspace: ~/.openclaw/workspace/ │    └── Sessions: │         ├── agent:main:main │         ├── agent:main:wechat-xxx │         └── agent:main:cron-xxx │ ├── Agent: work │    ├── Workspace: ~/.openclaw/workspace-work/ │    └── Sessions: │         ├── agent:work:main │         └── agent:work:project-xxx │ └── Agent: family      ├── Workspace: ~/.openclaw/workspace-family/      └── Sessions:           ├── agent:family:main           └── agent:family:group-xxx

五、各层职责速查表

层	职责	生命周期
Gateway	统一入口，连接渠道、客户端和 Agent	持续运行
Agent	独立大脑，拥有完整的人设、记忆、配置和会话	持久存在
Workspace	Agent 的文件系统家目录，人设和记忆的载体	持久存在
AgentDir	Agent 的运行时状态目录，保存 auth 和 sessions	持久存在
Memory	跨 Session 的知识积累层	长期保存
Session	单条对话线，保存完整对话历史	按天、空闲或手动重置
Session Key	标识具体对话线	随 Session 存在
Context	每次推理时传给模型的内容快照	单次推理有效
Delivery Route	决定回复消息发往哪个渠道	可随时 dock 切换

六、总结

• Gateway 是入口 • Agent 是大脑 • Workspace 是大脑的硬盘 • AgentDir 是运行时状态目录 • Session 是对话容器 • Session Key 是对话线标识 • Memory 是跨 session 的长期记忆 • Context 是每次推理时模型实际看到的快照 • Delivery Route 是消息发往哪里的路由