深入OpenClaw我学到了什么?

• steering message：用于在工具运行期间对Agent进行中断与干预，具体来说，在工具执行完成后的下一个turn中会立刻填充steering message，以此来中断或干预执行过程；
• follow-up message：在Agent所有trun运行完成后，开启一个新的turn继续执行follow-up message。

• 本质上其初衷实现的是一个开箱即用的coding agent CLI应用，类似claude code；
• 同时也可以作为一个Agent框架通过SDK或RPC的方式快速集成进其他应用。

• 不内置MCP，因为实现方式不止一种，且浪费上下文tokens。
• 不内置sub-agents，实现方式有很多。
• 没有权限确认（permission confirm），可通过扩展实现符合你环境和安全需求的自定义确认流程。
• 没有计划模式（plan mode），你可以将计划写入文件，或通过扩展，或安装现成的包实现。
• 没有内置todo list，因为这类机制容易干扰模型，你可通过扩展自行实现。
• … …

{"type":"session","version":3,"id":"uuid","timestamp":"2025-12-03T14:00:00.000Z","cwd":"/path/to/project"}

• SessionMessageEntry：对应conversation history中的每一条message记录；
• ModelChangeEntry：用于记录session运行过程中的模型切换操作；
• ThinkingLevelChangeEntry：用于记录session运行过程中的thinking/reasoning level切换操作；
• CompactionEntry：上下文压缩时创建，用于记录压缩后的上下文summary摘要信息；
• BranchSummaryEntry：当通过/tree操作进行分支切换时生成，该条目包含由LLM自动生成的摘要，概括左侧分支从当前节点回溯至公共祖先的内容，用于保留被中断路径中的上下文。

{"type":"message","id":"id1","parentId":"id0","timestamp":"2025-12-03T14:00:01.000Z","message":{"role":"user","content":"Hi."}}{"type":"message","id":"id2","parentId":"id1","timestamp":"2025-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"provider":"deepseek","model":"deepseek-v3.2","usage":{...},"stopReason":"stop"}}{"type":"message","id":"id3","parentId":"id2","timestamp":"2025-12-03T14:00:03.000Z","message":{"role":"toolResult","toolCallId":"too_call_id","toolName":"bash","content":[{"type":"text","text":"output"}],"isError":false}}

• compaction：当上下文context超过设定阈值时或用户手动执行 /compact操作时触发；
• branch summarization：当用户执行 /tree 操作进行分支切换时触发。

• 查找fisrtKeptEntryId：从最新消息开始向上遍历，估算累计token数量，直到达到keepRecentTokens（配置定义，默认20k），通常fisrtKeptEntryId会在turn边界，而不会split turns；

• 寻找cut point：从firstKeptEntryId向上遍历，直到前一个保留边界（compaction entry或root entry）；

• 生成summary：使用LLM进行结构化摘要生成；

• 追加compact entry：保存包含summary和firstKeptEntryId的compact entry；

• 加载context：重新reload加载上下文context。

{"type":"compaction","id":"id","parentId":"id_parent","timestamp":"2025-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"idxxx","tokensBefore":50000}

{"type":"branch_summary","id":"id","parentId":"id_parent","timestamp":"2025-12-03T14:15:00.000Z","fromId":"idxxx","summary":"Branch explored approach A..."}

1. 如果是ChangeModelEntry或ChangeThinkingLevelEntry，对provider/model和thinking level进行设置；
2. 如果是CompactionEntry：
1. 需要先提取summary信息；
1. 然后提取从firstKeptEntryId到CompactionEntry之间的消息；
3. 如果是BranchSummaryEntry或CustomMessageEntry，提取并按需转化成LLM Mesage；

• 管理所有接入Chat Apps或Channel Surface，这类Client统称为Channel；
• 管理所有Control Plane like WebUI、TUI、以及Mac APP，这类Client统称为Operator；
• 管理所有外部物理设备工具 like Phone、Computer or Headless等，这类Client统称为Node；
• 提供统一的WebSocket API。

{ "type": "req", "id": "...", "method": "...", "params": {} }

{ "type": "res", "id": "...", "ok": true, "payload": {} }

{ "type": "event", "event": "agent", "payload": {} }

• connect：client交互前必须经过connext建立连接，未建立连接的消息会直接丢弃；
• auth：支持包括token/password、tailscale、trusted proxy等多种接入认证；
• pairing：所有client connect后都会生成device identify，新client接入连接需要进行配对审批，Approve通过后颁发device token；
• nonce：支持防重放和安全绑定，请求的签名必须匹配设备信息。

• Agent在哪个目录运行，文件存储在哪里？
• Agent会话如何管理、如何隔离？
• Agent Context如何构造？包括system prompt、memory等；
• Agent能用哪些工具和技能？
• Agent任务如何表示、调度、和执行？
• Agent的结果如何输出？

• 工作输出：Agent执行任务生成内容文件，如代码实现文件等；
• 人格约束：Agent行为定义配置文件，如：SOUL.md、USER.md、AGENTS.md等；
• 记忆空间，Agent长期记忆文件，如MEMORY.md和memory/*.md等；

💡 注意：session对应任务的执行的日志，并不属于特定Agent的记忆，所以其存储并不在workspace中 。

• 各个Channel的消息隶属于哪个Session，如何进行路由？
• 不同的Session会话如何隔离和存储？
• Session何时、如何自动重置？
• Session如何压缩？

• main：默认配置，所有dm共享一个session；
• per-peer：每个用户一个session；
• per-channel-peer：每个channel + 用户一个session，官方推荐配置；
• per-account-channel-peer：最细粒度。

• 默认每天凌晨4点会对session进行reset，意味这一个session的声明周期最长是一天；
• 同时可选的通过配置idleMinutes字段，这样session在idleMinutes分钟不活跃后会立刻reset；
• 同样我们可以手动执行/new或/reset操作来重置session。

1. Compact后自动触发重试，这个过程对用户无感。
2. 增加identifier policy对标识符进行特殊处理，避免compact后将关键ID修改或漏掉；
3. 在压缩前，需要先做一个隐式操作，将需要长期记住的内容写入memory daily文件，防止重要的信息被summary吃掉，这个过程称为memory flush。

• System prompt系统提示词；
• Conversation History对话历史，也就是session中message信息；
• Tool Calls + Results工具调用和结果，同样存储在session中；
• Attachments：图片、音频、文件等多模态信息；
• Compaction Summaries 上下文压缩后的摘要文本信息；
• Provider Hidden Wrappers针对特定LLM Provider隐含注入的信息等。

• Injected workspace files into System Prompt；
• Conversation history from Session；
• Tool Definitions；
• 如果memory设计的不合理的话，同样会挤占context空间；

• Ingest：空操作，消息持久化直接由session manager处理；
• Assemble：直接透传，委托给底层embeddedPiAgent assemble pipeline处理：

• Compact：同样委托给底层embeddedPiAgent实现处理；
• AfterTurn：空操作，不做任何处理。

• Tools：有哪些工具，怎么使用工具，工具执行约束等；
• Skills：渐进式披露机制（强制执行）；
• Memory Recall：在需要时获取memory，使用memory_search/get工具；
• Workspace：工作目录说明；
• Current Date & Time：时区、日期和时间说明；
• Safety：安全约束，注意只是软约束（Advisory）；
• CLI Reference：OpenClaw命令执行规范；
• Document：OpenClaw文档本地存储路径及使用说明；
• Project Context（editable）：
• AGENTS.md：维护Agent长期记忆和行为规范；
• SOUL.md：制定Agent的人格/风格/边界；
• IDENTITY.md：设置Agent的名字/vibe/emoji，即你是谁？
• USER.md：用户画像，即你在帮助谁？
• TOOLS.md：工具使用说明；
• MEMORY.md：长期记忆存储，OpenClaw默认memory engine基于文件构建；
• HEARTBEAT.md：定义一些简短的定期清单或提醒；
• BOOTSTRAP.md：首次运行时，如果BOOTSTRAP.md存在，那就是你的出生证明。遵循它，弄清楚你是谁，然后删除它。你不会再需要它了。
• Group Chats：群聊约束说明；
• Runtime信息：OS、Node、当前模型、repo路径等；

• 软裁剪：在pruning过程中保留工具输出的开头和结尾，中间用…替代；
• 硬清理：在pruning过程中将工具输出全部替换为占位符；

• 短期/日志记忆Memory：用于记录当天发生的重要事情、临时上下文以及观察记录等，写入workspace/memory/YYYY-mm-dd*.md文件进行存储，每天一个文件，默认保留最近两天；
• 长期记忆Memory：用来存储用户偏好、重要决策以及稳定事实等信息，每次session开始时都会加载，存储在workspace/MEMORY.md文件；
• 梦境Dreaming Memory：用来记录自动总结、记忆筛选后的结果，可供人类审核，存储在workspace/DREAMS.md文件中。

• 用户触发：比如在会话中用户明确提示：需要记住…等内容，这时Agent会触发写入MEMROY.md；
• 自动触发：一般的，在compaction上下文压缩之前，OpenClaw会自动触发一个隐藏步骤，提醒Agent把重要的信息写入memory文件；
• Dreaming记忆整理机制：memory不是无脑存储，而是会经过收集、筛选、打分等过程后写入MEMORY.md，这部分会在下一节单独介绍。

• memory_search：memory检索，支持关键词匹配和语义理解；
• memory_get：精确的读取某个memory文件或片段；

• Built-in：默认实现，基于SQLite + Embedding本地检索系统；
• QMD：本地增强检索系统，https://github.com/tobi/qmd
• Honcho：基于用户建模的跨session记忆服务，https://github.com/plastic-labs/honcho

• 关键词检索（传统搜索）：基于SQLite FTS5 + BM25算法实现；
• 向量搜索（语义搜索）：基于Embedding向量化检索实现；
• Hybrid Search（混合搜索）：同时支持关键词检索+语义搜索。

• 自动更新：当memory记忆文件被修改后会自动重建索引；
• 配置变更：当embedding provider或索引chunk配置修改后，索引也会自动全量重建；
• 手动重建：用户主动执行openclaw memory index –force也会进行索引重建。

• Light（浅睡阶段）：收集 /去重 / 暂存；

• REM（快速眼动阶段）：寻找模式 / 主题 / 潜在关联；

• Deep（深度睡眠阶段）：最终裁决，哪些记忆值得长期记住；

• Live dreaming：配置自动运行执行，自动筛选记忆；
• Grounded backfill：手动重放历史，openclaw memory rem-backfill –path ./memory。

• Memory recall不稳定，有时查，有时不查，同时其行为调试起来困难，不可控；
• 另外主System Prompt很复杂，memory recall多轮浪费tokens。

• Agent：计算资源，最终的任务需要分配到某个具体的agent上执行；
• Context：临时上下文信息，agent执行时动态生成；
• Memory：记忆资源，与agent一一对应，即多个Agent之间的memory是相互隔离的；
• Tool：工具资源，agent执行时可调用的工具，用于与外部世界交互；
• Config：配置资源，OpenClaw全局配置信息，默认存储~/.openclaw/openclaw.json；
• Session：会话资源，OpenClaw自行管理session的lifecycle，其内部执行任务会共享底层session文件。

• Session调度队列：session内多个任务串行执行，一个session同一时刻只能有一个agent run在执行，后面的消息必须排队，以此解决上下文context一致性的问题；
• 全局调度队列：用于全局并发控制（限流），即整个系统中最多可以同时运行多少个agent run，所以所有的输入消息同时必须进入全局队列，默认main agent并发限制4，其他sub-agent并发限制8。

1. collect（默认配置）：后续的消息统一收集起来，合并成一个任务agent run进行处理；
2. follow-up：消息排队，然后逐条处理，即每条消息会触发一个agent run；
3. steer：在下一个turn开始时插入，会在下一个tools call边界生效，可以中断或改变当前流程。对于大部分的coding agent的默认策略，从这个角度来看，不同场景的Agent实现确实差别很大；
4. steer-backlog：既插入下一个turn，又保留一份follow-up，不常用；
5. interrupt：直接打断当前run，抢占式调度策略，不常用。

• 消息去重（Dedupe）：基于channel + account + peer + messageId维度构建一个缓存，来防止消息在短时间内由于网络抖动的重复发送；
• 防抖动（Debounce）：针对IM用户习惯，会将连续的输入合并为一次消息，本质上是把用户行为转成合理的agent调度粒度，这个在上面已经提到过。

• Block Streaming：LLM token streaming -> block -> message -> Channel，OpenClaw返回时需要将token streaming组装成一个一个block，然后作为IM的Message进行返回即block1 -> block2 -> block3…
• Chunking（切块算法）：block切分算法，需要综合考虑不同的channel限制（如：字符限制、行数限制、block大小限制等等）以及交互体验问题，同时避免一次发送大量消息影响用户体验或造成客户端崩溃等问题。

• 定义缓存buffer，当buffer < minChars时，token持续缓存，不发送；
• 当buffer >= maxChars时需要进行切分block，切分优先级：原子单元 > 段落 > 换行 > 句子 > 空格；
• Human Delay & 合并发送：模拟人类节奏 block1 → pause → block2 → pause → block3…

• 远程执行：这是OpenClaw实现“远程操控设备”的核心能力；
• 感知输入：截图、拍照、录屏、录像、GPS等多模态输入，相当于给Agent加上了“眼睛和传感器”；
• UI/Canvas控制：打开网页、执行js、推送UI内容等，当然这部分可基于browser-use或compute-use tool实现；
• 设备&个人数据访问（Android）：让Agent可以像人一样使用手机，可能权限很难绕过；
• 通知能力：主动推送notification、alert等。

• Agent类比于计算单元，Context、Memory类别于存储资源；
• Agent Session类比于进程，Agent Run类比于线程；
• 基于多进程单线程的任务调度模型；
• 外部物理设备统一抽象定义为工具Tool，除了Function Tools以外，还增加了Node Tools；
• Skills就是未来AgentOS上运行的APP，即未来APP的用户是Agent而不是人类；突然想起来前段时间北京金谷园饺子馆上架了Skill技能，所以大家也快行动起来吧；
• 最后一点，未来AgentOS的主要入口可能就集中在生活社交或办公协同的IM软件中，毕竟我们现在的大部分沟通都发生在这里。

1. Not ChatBot，is an Open-source Autonomous AI Agent that DOSE THINES；
2. OpenClaw真动手，从其System Prompt设计可以去看看，很有意思；
3. 数据不出域，完全自托管，A Pensonal Assistan；
4. 最主要爆火的核心原因可能是Agent落地感，Local first本地部署，这样所有人都有尝试的冲动，这也是为什么那么多人排队装龙虾。