编者按：本文整理并翻译自 Reddit 社区 r/AskClaw 的高赞硬核科普贴《OpenClaw has six parts. Most people only understand one》。作者深入浅出地拆解了 OpenClaw 的底层架构、记忆机制以及高级用法。

• **Gateway（网关）**是核心。所有进来的消息、出去的响应以及每一次工具调用，都要流经它。它负责维持与 Telegram、WhatsApp、Discord 和 Slack 的持久连接。当消息到达时，Gateway 决定由哪个 Agent（智能体）来处理，提取历史记录，组装上下文，并发送给大语言模型（LLM）。响应也会通过同样的路径返回。它还在端口 18789 上运行了一个 WebSocket API，供你连接自己的界面或外部集成。
• **Agent（智能体）**是大脑。它接收由 Gateway 组装好的上下文：聊天记录、记忆文件、可用的工具。它负责思考、决定调用哪个工具、构建响应。如果需要，它还会进行链式思考：调用工具 -> 获取结果 -> 进一步思考 -> 调用另一个工具，直到准备好最终答案。
• **Tools（工具）**是双手。执行 exec 在你的服务器上运行 Shell 命令；browser 打开网页、点击、截图；file 读写文件；message 发送消息到各个频道；memory 搜索长期笔记。每一个都是可以独立开启或关闭的能力。
• **Workspace（工作区）**是长期记忆。这是一个包含各种文件的文件夹，保存了 Agent 在会话之间所需的一切：你是谁、使用什么语气、你做过什么决定、昨天发生了什么。如果没有 Workspace，Agent 每次醒来都是一张白纸。
• **Sessions（会话）**是单次对话记忆。即特定对话的完整历史记录。每个会话都是独立的，除非你配置错误，否则它们不会相互干扰。
• **Nodes（节点）**是物理设备。你的 Mac、手机、远程服务器。它们连接到 Gateway，并扩展 Agent 的能力：拍张照片、截个图、获取地理位置。服务器上的 Gateway 是大脑，而你 Mac 上的 Node 就是它的眼睛和双手。

所有这些都是纯文本文件。没有数据库，没有二进制文件。全是普通的 .md 和 .json 文件，你可以用任何编辑器打开并手动修改。

Workspace：无人配置的超能力

如果没有工作区（Workspace），Agent 每次醒来大脑都是一片空白。它不记得你是谁，不记得你们上周讨论了什么，也不记得你们一起做过的决定。每次对话都要从零开始，每次你都在浪费 Token 来重新解释上下文。

Workspace 是一组 .md 文件，每个文件都有自己的角色：

• AGENTS.md：操作手册。Agent 应该如何思考，何时使用哪个工具，遵循什么安全规则，按什么顺序做事。
• SOUL.md：性格与灵魂。语气、边界、优先级。希望 Agent 简洁明了不给多余建议？写在这里。想要一个友好的助手？也写在这里。
• USER.md：你的用户画像。如何称呼你，你的职业，你的偏好。Agent 在每次回复前都会读取这个文件。
• MEMORY.md：长期记忆。绝不能丢失的事实。比如“我们只在 DEX 上交易，不用 CEX”、“主 RPC 是 Alchemy，备用是 Infura”。Agent 会自行写入，或者在你要求时写入。
• YYYY-MM-DD.md：每日日志。今天发生了什么，哪些任务正在进行，你们讨论了什么。到了明天，Agent 会打开昨天的日志并接续上下文。
• IDENTITY.md：身份与氛围。很短的文件，但它奠定了整体的基调。
• HEARTBEAT.md：定期检查清单。“检查邮件”、“看看监控是否在运行”。
• TOOLS.md：本地工具提示。脚本存放在哪里，哪些命令可用。这样 Agent 就不需要去猜，而是确切知道。

两层记忆：大多数人只用了一半

每次运行时，Gateway 都会抓取 AGENTS.md、SOUL.md、USER.md、IDENTITY.md 以及当天的每日日志，在 LLM 看到你的消息之前将它们注入到上下文中。

这就是第一层：Bootstrap（引导记忆）。Agent 每次都能看到这些文件的内容，没有例外。但它们会消耗 Token。你在 Bootstrap 文件里塞得越多，每次请求就越贵。

第二层：Semantic search（语义搜索）。当启用记忆插件时，Agent 会通过向量索引搜索 MEMORY.md 和其他笔记，通过“含义”而不是“关键词”来寻找相关的块。你问“我们在哪个 DEX 上交易？”，它能找到正确的答案，即使那是你两个月前写的。

区别在于：

• Bootstrap 是 Agent 每次必看的内容。
• 语义搜索 只在需要时提取当前相关的内容，不会持续消耗上下文，但它不能保证每次都能浮现出完全正确的事实。

💡最佳策略：将关键信息（语气、规则、你的身份）放入 Bootstrap。其他所有东西都放进 MEMORY.md 和每日日志，让语义搜索在需要时去提取。只用 Bootstrap 只发挥了一半的威力。两层都不用，就是每天在白白燃烧你的 Token。

⚠️ 长期使用的痛点：上下文膨胀与 Token 消耗

在实际使用中，Bootstrap 层的膨胀速度往往会被忽视。一旦 AGENTS.md、USER.md、每日日志和会话历史开始累积，Gateway 最终会为每一次调用组装非常庞大的上下文。这在早期很好用，但长期运行的 Agent 可能会消耗惊人的 Token。

这指出了目前许多 Agent 运行时面临的一个核心设计问题：有多少状态应该存在于 Prompt 上下文中，又有多少应该存在于运行时系统本身？ OpenClaw 严重依赖基于 Prompt 的状态，这保持了一切的透明度和可编辑性，但也意味着一旦 Agent 运行了几个星期或几个月，上下文管理就会变成一个真正的工程问题。因此，合理规划两层记忆的使用，不仅是为了成本，更是为了保证系统长期的可用性。

Gateway：一条消息如何变成响应

Gateway 是一个长期运行的守护进程。你启动一次，它就在那里待命。以下是你通过 Telegram 给你的机器人发消息时发生的事情：

1. Gateway 维护着与 Telegram API 的持久连接。
2. 一个事件进入。Gateway 检查配置：哪个 Agent 处理这个？它决定 SessionId：是旧对话的延续，还是新会话？
3. Gateway 组装上下文：从 .jsonl 文件读取会话历史；从 Workspace 拉取 Bootstrap 文件；加入可用的技能。
4. 打包好所有东西发送给 LLM。
5. LLM 返回文本或工具调用（Tool Call）。
6. 如果是工具调用，Gateway 会执行它，将结果反馈给上下文，然后 LLM 进一步思考，可能再调用另一个工具。这个循环会一直转动，直到得出最终答案。
7. 响应流式传回 Telegram。整个交流被写入 .jsonl，同时更新 sessions.json。

Gateway 的 WebSocket API 运行在 18789 端口。通过它你可以接入自己的 UI 或与外部系统集成。它甚至有一个兼容 OpenAI 的端点，任何能与 OpenAI API 对话的工具都能连上它。

⚠️ 注意：默认情况下 Gateway 只监听 localhost。如需远程访问，请使用 Tailscale 等 VPN 或 SSH 隧道。将 18789 端口暴露在公网上，意味着向全世界开放你所有的数据、会话和 Agent。

工具与 Cron：无需干预即可工作的 Agent

exec 是最强大的工具，它可以运行 Shell 命令。Agent 可以运行脚本、安装包、处理文件、部署代码。但它也是最危险的。exec 有三种模式：

• sandbox：在 Docker 容器内运行 Agent，与主系统隔离。
• gateway：直接在服务器上运行，但受限于你定义的白名单命令。
• full：无限制。适合用来做实验，但绝对不适合放了真实数据的生产服务器。

browser 工具控制浏览器。打开网页、点击元素、打字、截图、保存 PDF。

Cron 是将 Agent 从“聊天机器人”变成“数字员工”的关键。设置一次定时任务：

openclaw cron add --schedule "0 9 * * *" --agent personal --prompt "检查新邮件，发送摘要到 Telegram" --announce

每天早上 9:00，Agent 醒来，执行任务，并将结果发送到频道，完全不需要你插手。--announce 标志负责将结果发送到频道，--no-deliver 则会静默运行不发送结果。

**Heartbeat（心跳）**则是根据 HEARTBEAT.md 进行的更频繁的定期检查。监控在运行吗？磁盘空间还够吗？日志里有报错吗？如果出问题了，Agent 会主动给你发消息。

💡 综合运用：假设你想每天早上检查 Gmail 并将摘要发到 Telegram。启用 browser 工具，设置 9:00 的 cron，在 AGENTS.md 中写好指令。每天早上 Agent 都会打开带有已保存会话的浏览器，读取收件箱，过滤发件人，并把摘要发给你。你咖啡还没喝完，事情就已经处理妥当了。

多 Agent 架构：一个 Gateway，无限的 Agent

每个 Agent 都在 ~/.openclaw/agents/ 目录下有自己的独立文件夹。有自己的工作区、会话和记忆。工作 Agent 了解你的技术栈和项目；私人 Agent 了解你的习惯和日程，它们互不干扰。

频道映射在 config.json 中配置。向某个 Telegram 聊天发送消息，它会路由到工作 Agent；向另一个聊天发送，则路由到私人 Agent。同一个 Gateway，通过规则进行路由分发。

dmScope 控制着隔离级别。把它设置为 per-agent，每个 Agent 只能看到属于自己的对话。你可以扩展出一个通过心跳监控服务器的 Agent，一个解析信息源并将摘要存入专属 MEMORY.md 的研究 Agent，一个监控流动性池并随时提醒你机会的交易 Agent。所有的 Agent 都在同一个 Gateway 上运行。

🚨 核心规则：如果有多个人访问同一个 Agent，必须将 dmScope 设置为 per-channel-peer。否则，来自不同用户的会话会被折叠成一个。Agent 会用别人对话里的信息来回复你。这是个默认行为，你需要手动修改。

值得立刻检查的 5 个常见错误

1. **多用户场景下 dmScope 设置为 main。**默认情况下，所有私信都会被倒入同一个会话中。Telegram 上两个人给你发消息，Agent 会把它们当成一场对话。修复方法：设置为 per-channel-peer。
2. **在生产服务器上使用 full 模式的 exec 工具。**LLM 拥有不受限制的 Shell 访问权限。没有白名单，没有沙盒。修复方法：切换到 sandbox，或使用带有正确 exec-approvals.json 的 gateway 模式。
3. **没有 Workspace 或 Workspace 是空的。**每次对话都从零开始。你每次都在烧 Token 解释上下文。修复方法：配置好 AGENTS.md、SOUL.md 和 USER.md。花 15 分钟，回报从下一次对话就开始。
4. **没有压缩策略。**长对话会膨胀到数千个 Token。如果 Agent 在压缩前没有把重要决定写进 MEMORY.md，它们就永远丢失了。修复方法：在压缩前启用记忆刷新（memory flush）。
5. **将 18789 端口暴露在公网上。**任何发现它的人都能完全访问你所有的 Agent、会话和工作区文件。修复方法：使用 Tailscale 或 SSH 隧道，永远不要直接暴露该端口。

每个组件都是可以打开编辑的文本文件。每个会话都是可以读取解析的 JSONL。每个配置都是你控制的 JSON。整个系统是完全透明的。只是大多数人从来没有去深入看过。