玩转 OpenClaw，你需要了解的：核心架构、运作原理、Agent 部署步骤

建议想深入了解 OpenClaw 的同学优先看源码和官方文档——该项目目前仍在高频迭代。本文聚焦核心框架与通信机制，让你看完能说清 OpenClaw 是怎么运作的、能力边界在哪里。尤其要注意安全风险：如果选择部署 OpenClaw，请按「数据全部公开」的最坏打算对待你机器上的数据。

OpenClaw 是最近半年爆火的个人 Agent 平台，底层基于 Pi coding agent（@mariozechner/pi-coding-agent）。在它出现之前，喜欢折腾 Agent 的人基本人手一个自建架构：Skills 管理、Agent 身份赋予、架构自进化、memory-search、Session 管理，每一样都得自己搭。跟朋友交流 Agent 前，还得先花半天互相介绍各自的架构，才能聊到具体 Case。

OpenClaw 真正的价值，是把这件事「标准化」了。

一、OpenClaw 到底有什么不同

技术框架并不复杂，优势在于共识的推广。 作为程序员可以做个粗略类比：OpenClaw 的框架难度，大概相当于 AI Coding 诞生前「一个带初级推荐算法的前后端通信 App」——做过几年开发的同学都知道，这并不难。所以技术框架不是 OpenClaw 的亮点。

它的亮点是：把 Agent 架构的「共识」推了出去。以前每个人搭的 Agent 架构都不同，交流成本极高；现在大家基于 OpenClaw 搭，就不用再解释架构是什么了，直接聊「怎么保活、怎么换 RAG 算法库、怎么部署多 Agent、怎么复用 good case」——沟通效率完全不同。

第二，多 Agent 的天然支持。 LLM 成也 transformer、卡脖子也在 transformer：Context 瓶颈严格约束了单 Agent 的发挥。传统的「Prompt 定义身份 + 堆 Skills」正在一步步蚕食 Context 窗口。专事专做，正在成为更好使用 LLM 的共识——而多 Agent 正是它的落点。

第三，做与 AI 能力正交的事。 选择不做什么和选择做什么一样重要。花时间打磨和迭代自己的 Agent，就是一件跟 AI 能力正交的事：模型越来越聪明，你只需要升级底层 LLM；而那些跟 AI 交互留下的长期数据，会变成未来更好驱动 AI 的私人资产。

二、部署前的三个现实问题

云机 vs 自部署。 买机器不是必须的。云机（如腾讯云已支持一键部署 OpenClaw）最省事，数据随时可下载；自部署则更可控，也是多数人关心的路线。

自部署优先选 Mac——OpenClaw 的部署与诸多工具对 Mac 环境天然友好，Windows 也能装但折腾一些。机器上推荐 Mac Mini（部署后就一直本地跑着），主要看三个指标：

• 芯片：至少要 M 系列；M1~M4 看诉求，不跑本地文生图/视频的话 M1 性价比最高（OpenClaw 运行时主要就是调 API，不太吃性能）。
• 内存：需要本地部署文生图/视频模型就上 24G，否则常规即可。
• 磁盘：本地跑 ComfyUI 模型动辄 30G 起步，建议 256G 起。

IM 工具怎么选。 这是容易踩坑的地方，三条原则：安全性、可用性、易用性。

• 安全性：从数据隔离出发，别把 OpenClaw 当「文件传输助手」，别因习惯而忽视风险——部署后你就等同于把机器人公开在网上。
• 可用性：单 Agent 时够用，但多 Agent 时 IM 调用额度会被飞速消耗。原因是网关里有一个每 60 秒一次的定时健康快照（healthInterval 会 ping IM），Agent 一多额度很快就见底。所以多 Agent 一定要选额度充裕（或无额度约束）的 IM。
• 易用性：国内 IM 的易用性普遍高于国外那几款。

配置麻烦吗？ 只跑通工程 + 配一个 IM 机器人，半小时足矣；但配多 Agent、任务分配、调试 Skills、定制身份、定时任务、自部署模型，按经验大概需要 2~3 天。

三、核心架构：八个文件定义一个 Agent

每个 Agent 对应一个 workspace，核心配置文件如下：

AGENTS.md     # Agent 职责声明，决定工具权限（最核心的 Prompt 文件）
SOUL.md       # 个性化提示词，注入 system prompt
TOOLS.md      # 工具白名单/黑名单，安全边界
IDENTITY.md   # 身份标识（name/avatar），通道展示
USER.md       # 用户偏好，上下文先验
HEARTBEAT.md  # 定时任务配置（可选）
BOOTSTRAP.md  # 首次 onboarding 引导（一次性消费）
MEMORY.md     # 用户记忆文档（RAG 源）

文件顺序即优先级：AGENTS 定义能力边界、SOUL 注入灵魂、TOOLS 划定禁区，这八个文件共同构成 Agent 的完整人格。其中 AGENTS.md 详细描述了 Agent 的启动与 memory 管理流程，堪称 OpenClaw 最核心的 Prompt 文件。

Agent 不是常驻进程，而是 per-session 的瞬态实例。 每次对话都是一次完整的「加载—执行—销毁」循环：加载 bootstrap 上下文 → 创建 SessionManager → 动态构建 system prompt（把 workspace 文件内容注入）→ 创建 agent session。也就是说 system prompt 是动态生成的，每次 run 都会重新读 workspace 文件，配置实时生效。

四、运作原理：记忆是怎么管理的

与记忆相关的配置有三处：

.openclaw/agents/ceo/sessions/xxxx.jsonl      # 会话信息
.openclaw/workspace-ceo/memory/YYYY-MM-DD.md  # 按天记录的 memory
.openclaw/workspace-ceo/MEMORY.md             # LLM 精炼后的 memory

Session 按需加载。 每个会话有独立的 .jsonl，第一行是 Session Header（type / session id / cwd / timestamp / parentSession）。消息路由到 SessionKey 后，OpenClaw 才把对应 SessionId 的 .jsonl 加载进 Agent——懒加载。

Session 太长怎么办？ 显然不会全量塞进 LLM。从加载到 LLM 感知之间有三层策略：

1. Compaction（压缩，持久化）：对话太长时，把旧消息总结成一个 summary 写回 JSONL，下次继续用压缩后的历史（firstKeptEntryId 控制压缩程度）。
2. Pruning（修剪，临时）：发送前把旧的 tool 结果临时替换成占位符，只改内存不改文件。
3. History Limit（历史限制，可选）：限制发送的消息数量。

Memory 怎么迭代。 Agent 通过文件系统工具（fsWrite/fsAppend）更新 MEMORY.md；当 Session 接近 Context 上限时，会自动提示 Agent 先写 Memory，再压缩 Session。这正是「越用越懂你」的底层机制。

五、从单 Agent 到多 Agent

单 Agent 的问题很实在：Context 被快速消耗，还容易「错误 search」导致交付质量下降。举一个真实案例——先构建一个 RAG tutor 强化 Flutter 技能，中途跟它聊过 C++ 后，因为 memory 机制，后续多轮对话它都会带着 C++ 的记忆，要 Demo 示例时给的是 C++ 而不是 Flutter。所以明确 Agent 的专属任务后，最好让它专事专做。

新增 Agent 很简单：

openclaw agents add iostutor

它会按 onboarding 流程引导配置，填上 IM bot API 和 LLM API 即可。

Agent 之间的调用有两种方式：sessions_send 和 sessions_spawn。

• sessions_send：向已存在的 session 发消息，通信会写入各自 memory。像给同事发消息，他在自己的上下文里处理。
• sessions_spawn：以 SubAgent 方式在独立环境跑任务，像雇临时工，完成后汇报。例如 ceo 说「让 iostutor 写一个 Swift 网络请求封装类」。

两者都在 openclaw.json 里配置。sessions_send 要注意 sessions.visibility 很容易漏配：

"tools": {
  "agentToAgent": { "enabled": true, "allow": ["ceo", "iostutor"] },
  "sessions": { "visibility": "all" }
}

sessions_spawn 则是在主 Agent 的配置里声明 subagents.allowAgents：

{
  "id": "ceo",
  "name": "ceo",
  "workspace": "/Users/.../.openclaw/workspace-ceo",
  "model": "openai-codex/gpt-5.3-codex",
  "subagents": { "allowAgents": ["iostutor"] }
}

用哪个由 LLM 自己判断。 如果你对 ceo 说「让 iostutor 生成一篇文章发给我」，LLM 理解为新任务 → 用 sessions_spawn；如果说「继续跟 iostutor 的那个文章讨论」，有明确上下文指向 → 用 sessions_send。

一个常见的坑：Agent 之间的通信会「遗忘」。 打通之后过几天，iostutor 可能就不知道怎么跟 ceo 通信了——因为上面的配置是「用 session 记忆」，短期记忆遗忘后就忘了。解决办法是把通信规则写进各自 workspace/agent_xx/AGENTS.md，明确告诉它别的 Agent 是谁、用 callAgent("iostutor") 直接通信（AGENTS.md 内容会被注入 system prompt）。

sessions_send 不新建 session，只向已存 session 发消息，所以间隔 6 小时仍会复用之前的 session 继续沟通。

实战经验三条：公司要扁平化（别部署太多 Agent、别搞多层汇报）、尽量保持双向沟通（同时配 send + spawn）、核心 Agent 设边界（纯工具型 Agent 只配 SubAgent，不记太多上下文）。

六、精细化管控：Skills 与版本控制

Skills 不是把每个文档完整注入，只注入列表（名称、描述、路径），Agent 需要时才用 read 工具读完整的 SKILL.md。来源按优先级分三级：workspace-xxx/skills/（最高，per-agent）→ ~/.openclaw/skills/（共享）→ bundled（内置）。还会按每个 skill 的 requires.bins/env/config 过滤掉不满足条件的。

Skills 太多会给 Agent 造成 Context 负担，甚至错误调用工具。推荐把每个 Agent 的 skills 配成「基础通用 Skills + 专属 Skills」：brave_search 这类联网检索属于基础通用，Weather 这类定时天气汇报只属于 Family Agent 专属。

一个坑：Skills 延迟加载。 改完 Skills 架构后，Agent 可能还在用旧配置——因为 OpenClaw 在 session 启动时创建 skills 快照并全程复用，重启 gateway 后旧 session 仍用旧快照。删掉对应 session 再重新咨询，新 skills 才会生效。

Clawhub 是 OpenClaw 的 Skills 市场：

clawhub search "calendar management"   # 语义搜索
clawhub install <skill-slug>           # 安装
clawhub list                           # 列出已安装
clawhub update --all                   # 更新全部（谨慎）
clawhub sync                           # 同步备份本地 skills

版本控制两点提醒：memory 里的对话信息不建议上云（在 .gitignore 里排除）；openclaw.json 同时存了密钥和核心 config，密钥部分建议走注入式管理，避免泄露。

七、Quick Start

curl -fsSL https://openclaw.ai/install.sh | bash

安装后会自动进入 openclaw onboarding，按导引完成 main Agent 的配对即可（config skills 可先跳过）。不建议用 Claude Code 来配置 OpenClaw——CC 目前对它的配置理解还有偏差，容易出现「it works, but it also broke」。更推荐的姿势是：先把 OpenClaw 源码 download 下来，让 CC 学习源码，再针对本地配置做 debug，交付水平会大幅提升。

说在后面

Model 的选择：预算允许就用 SOTA 模型——落后的 LLM 会影响你对「AI 到底行不行」的判断，别因一个不及格的交付就下了「AI 能力还不行」的结论。也别按年订阅某个专一模型，迭代太快，几个月可能就过时了。

OpenClaw 能玩的还很多：替换 memory-search 底层算法、重写 AGENTS.md 构建更复杂的 Agent 关系，都可以继续深挖。关于 Agent 运行时，我们此前也写过 DeepSeek Harness 的架构拆解，两者的「插件化/标准化」思路可以对照着看。