OpenClaw 本地优先 Agent 运行时：架构、记忆与上下文组装机制

OpenClaw，早期名称是 Clawdbot，可以理解为一个本地优先的 AI Agent（智能体）运行时。它不是单纯的聊天界面，而是把 LLM（Large Language Model，大语言模型）接入用户自己的电脑、文件、Shell、浏览器、日历、消息通道和长期记忆，让模型不只会回答问题，还能真正执行任务。

本地优先是它的核心定位。状态、记忆、工具配置、工作目录尽量放在用户机器上，模型负责推理和规划，运行时负责把模型的意图变成可控的本地操作。这种模式和纯云端助手差别很大：云端助手通常只有应用暴露出来的 API（应用程序接口），OpenClaw 则能直接触达宿主机上的文件系统、命令行和浏览器会话。

需要先区分一个概念：本地优先不等于完全离线。LLM 仍然可以是云端模型，本地优先强调的是运行时、权限、上下文和记忆主要由本机控制。

OpenClaw 解决的核心问题

普通聊天机器人只有“说”的能力，复杂任务往往会卡在三个地方：

它更像一个“个人自动化中枢”：LLM 负责理解意图，运行时负责拿到上下文、调用工具、回传结果，并在需要时继续迭代。

整体架构：Gateway、Runtime、Tools 和 Memory

OpenClaw 的架构可以拆成四层：通信入口、Agent 运行时、工具层、记忆与上下文层。

flowchart LR
    U[用户<br/>Telegram / WhatsApp / HTTP / Webchat] --> G[Gateway 守护进程]

    G -->|WebSocket / 鉴权 / 路由| R[Agent Runtime<br/>Node.js]

    R --> P[Prompt 组装器]
    R --> O[Orchestration<br/>ReAct + Function Calling]
    R --> S[Session State<br/>会话状态]
    R --> M[Memory Manager<br/>记忆管理]

    M --> D[(Daily Logs<br/>memory/YYYY-MM-DD.md)]
    M --> C[(Curated Memory<br/>MEMORY.md)]
    M --> V[(sqlite-vec<br/>向量索引)]
    M --> UMD[(USER.md / SOUL.md / AGENTS.md)]

    O --> T[Tool Layer]
    T --> FS[文件读写<br/>read / write / edit]
    T --> EX[Shell 执行<br/>exec / process]
    T --> BR[Browser Relay<br/>接管浏览器]
    T --> MSG[消息发送<br/>message / sessions_send]
    T --> CRON[定时任务<br/>cron / heartbeat]
    T --> WEB[Web 搜索与抓取<br/>web_search / web_fetch]

Gateway：外部世界和本地运行时之间的入口

Gateway 是一个守护进程，负责和外部信道通信，例如 Telegram、WhatsApp、HTTP 或 Webchat。它处理连接、鉴权、消息路由和 WebSocket 通信，可以看作 Agent 的“输入输出层”。

用户从手机发一条 Telegram 指令，Gateway 收到后不会自己做推理，而是把消息送进 Agent Runtime。Runtime 处理完结果后，再由 Gateway 把回复送回对应渠道。

Agent Runtime：真正的控制中心

Agent Runtime 基于 Node.js，主要负责几件事：

• 维护会话状态；
• 动态组装 System Prompt（系统提示词）；
• 加载工具和 Skill；
• 解析 LLM 输出的 Function Calling；
• 执行工具调用；
• 把工具结果回填给 LLM；
• 判断任务是否需要继续循环。

LLM 本身不会直接执行 Shell 命令。模型只会输出结构化工具调用，运行时再根据权限和策略决定如何执行。

一个简化的工具调用长这样：

{
  "name": "exec",
  "arguments": {
    "command": "git status --short"
  }
}

真实运行时会按工具定义、权限策略和当前上下文处理这类调用。这个隔离很重要，因为模型的“想做什么”和系统“允许做什么”必须分开。

OS-Native Tools：Agent 的手脚

OpenClaw 的能力主要来自工具层。常见工具包括：

其中 Browser Relay 很关键。它可以接管用户已经打开的 Chrome 实例，复用 Cookie 和登录态。这样做能减少重复登录、验证码和权限配置带来的摩擦，但也意味着安全边界必须更严格：浏览器里已有的登录状态，本质上就是用户授权过的身份。

一条请求是怎么跑完的

OpenClaw 不靠硬编码的 DAG（Directed Acyclic Graph，有向无环图）来写死任务流程，而是采用 ReAct（Reason + Act，推理与行动）结合 Function Calling（函数调用）的动态循环。

sequenceDiagram
    participant User as 用户
    participant Gateway as Gateway
    participant Runtime as Agent Runtime
    participant Prompt as Prompt 组装器
    participant LLM as LLM
    participant Tool as 本地工具
    participant Memory as Memory

    User->>Gateway: 发送消息
    Gateway->>Runtime: 路由到会话
    Runtime->>Memory: 读取近期日志 / 用户信息 / 长期记忆
    Runtime->>Prompt: 组装系统提示词和上下文
    Prompt->>LLM: 发送用户请求 + 工具列表 + 上下文

    LLM-->>Runtime: 返回回复或工具调用
    alt 需要调用工具
        Runtime->>Tool: 执行 read / exec / browser 等
        Tool-->>Runtime: 返回 stdout / stderr / 文件内容 / 网页结果
        Runtime->>LLM: 把工具结果加入上下文继续推理
    else 不需要工具
        Runtime-->>Gateway: 生成回复
        Gateway-->>User: 发送结果
    end

这个循环有几个关键点：

• 模型先观察当前消息、近期上下文和系统状态；
• 模型判断是否需要工具；
• 运行时执行工具，而不是让模型直接碰系统；
• 工具输出回到模型，模型继续判断任务是否完成；
• 复杂任务可能会触发多轮工具调用。

例如用户说“帮我看看这个项目为什么测试失败，并给出修复方案”，Agent 可能会：

1. 读取项目目录；
2. 执行测试命令；
3. 分析错误日志；
4. 搜索相关文件；
5. 修改代码；
6. 再次执行测试；
7. 汇总改动和风险。

这个流程不是预先写死的，而是模型在运行时根据观察结果不断决策。

子 Agent：把耗时任务拆出去

复杂任务会占用大量上下文和时间。OpenClaw 提供 sessions_spawn，主 Agent 可以创建子 Session，让子 Agent 在独立上下文里处理一部分工作。

sequenceDiagram
    participant Main as 主 Agent
    participant Runtime as Runtime
    participant Sub as 子 Agent
    participant Tools as 工具层

    Main->>Runtime: sessions_spawn(task)
    Runtime->>Sub: 渲染 minimal prompt + 子任务上下文
    Sub->>Tools: 搜索 / 抓取 / 执行 / 分析
    Tools-->>Sub: 返回结果
    Sub-->>Main: 回调任务结果
    Main-->>Main: 合并多个子任务输出

典型场景是“抓取 10 个网站并总结”。主 Agent 不需要把所有网页内容都塞进自己的上下文，可以分裂出子 Agent 并行处理，每个子 Agent 只负责自己的网页，完成后把摘要交回主 Agent。

这种设计有两个收益：

• 主会话不会被大量中间材料污染；
• 子任务可以拥有更精简的提示词，减少 token 消耗。

代价也很明显：子 Agent 的上下文更少，可能缺少主会话里的细节；任务拆分如果不清楚，多个子 Agent 的输出也可能风格不一致或重复。

记忆管理：文件可见，检索混合，长期记忆可编辑

很多 Agent 系统把记忆完全交给 Vector DB（向量数据库），用户很难知道里面存了什么，也很难手动修正。OpenClaw 的思路更透明：长期记忆用 Markdown 文件保存，向量索引用来提升检索能力。

它的记忆可以分成三层。

Daily Logs：保留近期连续性

memory/YYYY-MM-DD.md 是每日日志，适合记录当天发生了什么。它通常是追加式的，既可以保存交互记录，也可以保存模型整理出的摘要。

运行时会自动加载“今天”和“昨天”的日志，让 Agent 在跨天任务里仍然保持近期连续性。比如昨天让它调研某个项目，今天说“继续昨天那个调研”，它就能通过近期日志找回上下文。

MEMORY.md：长期知识和决策

MEMORY.md 保存更稳定、更值得长期保留的信息，例如：

• 某个项目为什么选择 tRPC 而不是 HTTP；
• 上周遇到的 Docker 权限问题如何修；
• 某次会议确定的技术方向；
• 用户明确要求长期记住的偏好；
• 多次任务中沉淀出的工作习惯。

它不是流水账，而是提炼后的长期知识库。Daily Logs 更像日记，MEMORY.md 更像长期经验手册。

USER.md：关于服务对象，而不是关于项目

USER.md 和 MEMORY.md 都属于长期上下文，但服务目标不同。

USER.md 可以记录用户角色、偏好、沟通风格、长期兴趣和边界。例如：

# USER.md - About Your Human

- Name: George
- Role: AI Engineer
- Preferences:
  - Prefer concise code examples
  - Avoid unnecessary small talk
  - Care about system architecture and trade-offs
- Long-term interests:
  - AI Agent
  - Recommendation systems
  - Developer tools

MEMORY.md 更适合记录项目和经验：

# MEMORY.md

## Project: Go-Jarvis

- Decision: Use tRPC for internal module communication.
- Reason: Type safety is more important than cross-language compatibility in this phase.
- Follow-up: Revisit if Python services become first-class modules.

## Troubleshooting

- Docker permission issue on macOS:
  - Symptom: container cannot access mounted workspace.
  - Fix: check Docker Desktop file sharing settings and user permissions.

如果缺少 MEMORY.md，Agent 会忘记许多项目细节；如果缺少 USER.md，Agent 会不知道自己在为谁服务，也不知道应该采用什么沟通风格和安全边界。

记忆召回：向量语义 + 关键词匹配

纯向量检索适合找语义相近的内容，但对精确名称、路径、版本号、日期不一定稳定。关键词匹配能抓住精确 token，却不擅长处理换一种说法的查询。OpenClaw 采用混合检索，把两者结合起来。

flowchart TD
    Q[用户问题] --> J{是否涉及历史信息?}

    J -->|否| A[直接进入常规推理]
    J -->|是| S[memory_search]

    S --> V[sqlite-vec<br/>语义召回]
    S --> K[关键词匹配<br/>名称 / 日期 / 路径 / 版本]

    V --> Merge[合并候选]
    K --> Merge

    Merge --> G[memory_get<br/>只取必要片段]
    G --> P[注入当前上下文]
    P --> L[LLM 生成回答或继续调用工具]

触发记忆召回的典型信号包括：

• “上次”“之前”“继续刚才那个”；
• 询问某个项目的历史决策；
• 询问用户偏好；
• 询问过去的 todo、会议、日期；
• 当前任务依赖长期上下文。

召回时不应该把所有记忆都塞进 prompt，而是先搜索，再只取相关片段。这样能减少 token 消耗，也能降低无关记忆干扰模型判断的概率。

记忆压缩：从每日流水到长期知识

长期运行的 Agent 会不断产生日志，如果全部保留在活跃上下文里，token 会很快爆掉。OpenClaw 通过 Compaction（压缩/提炼）把每日日志里的重要信息沉淀到 MEMORY.md。

flowchart LR
    D1[memory/2026-06-05.md] --> R[定期回顾]
    D2[memory/2026-06-06.md] --> R
    D3[memory/2026-06-07.md] --> R

    R --> F{是否值得长期保留?}

    F -->|否| Skip[留在 Daily Logs]
    F -->|是| C[提炼为事实 / 决策 / 教训]
    C --> M[写入 MEMORY.md]

适合进入长期记忆的信息通常有三类：

• 未来会复用的决策；
• 用户明确要求记住的偏好；
• 任务中踩过的坑和修复方法。

不适合进入长期记忆的信息也很明确：一次性闲聊、敏感信息、已经过期的临时状态、没有复用价值的中间日志。

System Prompt 不是一段固定字符串，而是运行时组装结果

OpenClaw 的 System Prompt 采用分区组装。运行时会根据当前会话、工具权限、工作区文件、时间、平台能力和 prompt mode，动态生成最终发给 LLM 的系统上下文。

一个完整的系统上下文通常包含这些区域：

这种设计的好处是可组合。工具变了，Tooling 区域变化；进入子 Agent，prompt mode 变化；在群聊里，隐私上下文加载策略变化；换了工作区，Workspace 和 Project Context 变化。

Prompt mode：主会话和子 Agent 不能共用同一份上下文

OpenClaw 支持不同提示词模式，运行时会根据场景选择，不需要用户手动配置。

子 Agent 使用 minimal 的意义不只是省 token，也和隐私有关。主会话可以加载更完整的用户上下文，但子 Agent 只需要完成一个明确任务，不应该默认拿到所有私人记忆。

在群聊场景里同样要小心。Agent 可能能访问用户的文件、日历和消息，但群聊里它只是参与者，不是用户本人，也不是用户的代理发言人。私人上下文不能因为模型“知道”就被随便说出去。

AGENTS.md、SOUL.md、IDENTITY.md：把行为规则文件化

OpenClaw 很重要的一点是：许多行为不是写死在程序里，而是放在工作区的 Markdown 文件里。用户可以像维护项目文档一样维护 Agent 的规则和人格边界。

一个简化的 AGENTS.md 可以这样写：

# AGENTS.md

## Every Session

Before doing anything else:

1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md for today and yesterday
4. If this is the main session, also read MEMORY.md

## Memory

- Daily notes: memory/YYYY-MM-DD.md
- Long-term memory: MEMORY.md
- If something must survive restart, write it to a file.

## Safety

- Do not exfiltrate private data.
- Ask before destructive commands.
- Prefer trash over rm.
- Ask before external actions such as emails or public posts.

## Group Chats

- Respond only when mentioned, asked, or able to add value.
- Stay silent when humans are casually chatting.
- Do not leak private user context.

SOUL.md 更偏人格和沟通风格：

# SOUL.md

- Be helpful without filler.
- Be resourceful before asking.
- Read files and check context before saying you cannot know.
- Private things stay private.
- External actions require confirmation when uncertain.

IDENTITY.md 则定义 Agent 自己是谁：

# IDENTITY.md

- Name: Xiao Bai
- Role: Personal Assistant
- Vibe: Caring, efficient, trustworthy

这几个文件配合起来，构成了一个可编辑的 Agent 行为层：

相比把所有规则写进代码，文件化配置更适合个人 Agent，因为用户可以逐步调教它，而不需要每次都改运行时代码。

Skills：工具很多，但说明要按需加载

OpenClaw 的工具集可能非常大，例如 GitHub、Notion、Slack、天气、视频处理、PDF 编辑、图片生成、Twitter/X CLI 等。如果每次都把所有工具的详细说明塞进 System Prompt，token 会快速膨胀。

更合理的方式是：System Prompt 只注入技能名称、描述和路径；模型先扫描描述，判断哪个技能最匹配，再读取对应的 SKILL.md。

flowchart TD
    Q[用户任务] --> L[扫描 available_skills 描述]
    L --> M{是否有明确匹配技能?}
    M -->|没有| N[不读取 SKILL.md]
    M -->|一个明确匹配| R[读取该技能 SKILL.md]
    M -->|多个可能匹配| C[选择最具体的一个]
    C --> R
    R --> T[按技能说明调用工具]

这种懒加载策略能降低上下文成本，也能避免模型被无关工具说明干扰。

Heartbeat 和 Cron：两种主动任务机制

OpenClaw 不只能被动回答，还能主动做周期性检查。它的主动机制主要有两种：heartbeat 和 cron。

heartbeat 更像“定期醒来看看有没有事”。它可以检查 HEARTBEAT.md 里的清单，如果没有需要通知用户的内容，就回复 HEARTBEAT_OK。如果发现重要邮件、两小时内的日历事件、项目异常状态，再主动发消息。

cron 更适合“周一 9 点提醒我开会”这种精确时间任务，或者需要和主会话隔离的后台工作。

适合使用 OpenClaw 的场景

OpenClaw 最适合那些需要本地权限、跨平台联动、可持续记忆和自动化执行的个人任务。

不适合直接套用的场景

OpenClaw 的能力来自本地权限，这也意味着它不适合所有场景。

可以把它定位成个人极客工具、开发者自动化中枢、私有助理运行时，而不是开箱即用的通用消费级产品。

模型能力决定体验上限

OpenClaw 对模型能力依赖很强，尤其依赖三类能力：

• 长上下文理解；
• 稳定的 Function Calling；
• 主动读取文件和使用工具的能力。

同样的问题，在不同模型上的表现可能差很多。

这里不能简单理解为“本地模型不行，云端模型一定行”。真正影响结果的是模型是否能稳定遵循系统提示词、是否能处理足够长的上下文、是否能正确发起工具调用。很多本地模型在对话能力上看起来不错，但一旦进入长上下文、多工具、多轮反思，就容易暴露短板。

Token 消耗为什么容易膨胀

OpenClaw 的 System Prompt 很重。工具列表、技能描述、用户身份、项目文件、记忆规则、消息规则、心跳规则、运行时信息都会进入上下文。几十轮对话后，输入 token 进入 10 万量级并不奇怪。

常见膨胀来源包括：

降低成本的关键不是简单删功能，而是做上下文分层：

• 主会话用 full prompt，子 Agent 用 minimal；
• Skill 只按需读取一个最匹配的 SKILL.md；
• 历史记忆先 search，再 get 必要片段；
• Daily Logs 定期压缩到 MEMORY.md；
• 工具输出要截断、摘要或只保留关键行；
• 群聊和子任务不默认加载私人记忆。

安全边界：本地权限越大，约束越要清楚

OpenClaw 能执行 Shell、读写文件、控制浏览器、发送消息，这些能力一旦失控，影响比普通聊天机器人大得多。安全策略应该写进系统提示词，也应该由运行时落实。

关键原则包括：

一个本地优先 Agent 的可信度，不只来自模型是否聪明，更来自它是否知道什么时候不该动手。

已安装后的基础检查命令

OpenClaw 的 Gateway 守护进程可以通过 CLI 检查和管理。常用命令包括：

clawdbot gateway status
clawdbot gateway start
clawdbot gateway stop
clawdbot gateway restart

如果不确定当前版本支持哪些命令，可以查看帮助：

clawdbot help
clawdbot gateway --help

完成基础配置后，可以用几个低风险问题验证上下文是否正确加载：

我是谁？
你是谁？
继续昨天的任务。
记住：以后代码示例尽量给 TypeScript。

然后检查对应文件是否发生变化：

ls memory
cat USER.md
cat MEMORY.md

再用低风险本地任务验证工具调用：

查看当前工作区有哪些文件，不要修改任何内容。
帮我运行 git status，并解释当前仓库状态。

如果这些基础任务都能稳定完成，再逐步开放更高权限的自动化动作。

可以借鉴到其他 Agent 系统里的设计

OpenClaw 最值得借鉴的不是某个具体工具，而是它对上下文、记忆和权限的拆分方式。

这种架构的目标不是让 Agent 每次都显得“像人”，而是让它在长期使用中形成连续性：知道自己是谁，知道用户是谁，知道过去做过什么，也知道哪些动作需要克制。对于个人自动化和开发者工具来说，这比单次对话质量更关键。