OpenClaw 入门指南：从原理到实战

引言

从上周起就萌生了写一篇关于 OpenClaw（Clawdbot）文章的想法，但一直拖到现在才动笔。拖延的原因有二：其一，对于一个可能是昙花一现的现象级产品，我不太愿意投入过多精力做深入研究------事实上，直到写完这篇文章，我都还在纠结标题用"入门指南"还是"浅析"更为恰当；其二，放假后事情比较多，实在抽不出整块时间来完成（主要指做饭、打炉石和匡扶汉室）。

不过拖延归拖延，该聊的还是得聊。在正式介绍 OpenClaw 之前，有一个问题值得先回答：市面上的 AI 工具已经如此丰富，为什么Openclaw会成为一个现象级的产品？它的独到之处在哪里？

结合官方文档和个人体验，我梳理出以下几个核心差异点：

它不是"一个聊天框"，而是"一个网关化的 Agent 操作系统"。 单一 Gateway 作为会话、路由、渠道连接的事实源，统一对接 WhatsApp、Telegram、Discord、iMessage、QQ、飞书等消息平台。它的设计哲学不是把用户拉到一个新 App 里，而是把 Agent 放进用户已有的消息入口。

它把"个性与长期上下文"工程化了。 MEMORY.md 这类文件被注入系统上下文，记忆以落盘 Markdown 的形式存在，而非黑盒式的"隐式记忆"。对多数 AI 产品来说，这是从"prompt"到"workspace"的范式转变。

它把"可执行能力"做成了强约束工具层。 工具是类型化 Schema + 策略控制（allow/deny/profile），支持沙箱、会话工具、子智能体并在本地运行。很多产品只强调"会回答"，OpenClaw 强调的是**"会执行且可控"**。

它在可靠性上做了生产化设计。 每会话串行队列、agent.wait 生命周期事件、模型故障转移（先 Profile 轮换，再 Model Fallback）------这些特性让它更像一个"可运维系统"，而非又一个 demo agent。

至于它短期内爆火的原因，我的推断是多方面的：

分发优势：天然进入高频聊天场景，获客成本极低
价值闭环：从聊天直接走向自动化执行（browser/nodes/cron/session tools）
开源扩散：插件/Skills + 社区 showcase + 高频 release（最近两周多次版本发布）
灵活性：多模型提供商、可本地/远程部署，降低了平台锁定感

那么OpenClaw适合来做些什么？

一句话来说：你需要把它跑在自己的电脑或服务器上，然后用 QQ、飞书、WhatsApp、Telegram 这类即时通信软件给它发消息，它能在本地（你的电脑或者服务器）干的事，大致是这几类：帮你回邮件、文件管理、运行脚本、自动化、实际监控等。

当然，代价也很明确：学习与运维门槛比同类产品更高（网关、策略、插件治理都需要上手成本），官方文档也坦诚地指出------系统提示里的安全措施是"建议性"的，硬约束需要靠工具策略、审批和沙箱来实现；插件是进程内受信代码，治理不好会带来安全风险（这也是最主要的问题）。

带着这些认知，我们来逐层拆解 OpenClaw 的架构与设计。

一、架构设计

1.1 整体架构

先看官方架构图，对 OpenClaw 的全局建立一个直观印象：

从架构图可以看出，OpenClaw 的设计围绕几个核心层次展开。

最上层是接入层，包含三类入口：消息渠道（WhatsApp/Telegram/Slack/Discord/Signal/iMessage）、控制平面客户端（macOS App/CLI/Web UI/自动化，通过 WebSocket 连接）以及节点客户端（macOS/iOS/Android/无头设备，提供 camera/screen/canvas/location 等能力）。所有这些入口最终都汇聚到同一个 Gateway。

中间是 Gateway 网关，这是整个系统的核心枢纽。它是一个单实例守门人，负责会话与路由事实源、类型化 WS API 事件流、connect 握手、认证配对和 Schema 校验。可以把它理解为 Agent 的"耳朵"和"嘴巴"------所有外部信号都经过它进来，所有响应也通过它投递出去。

Gateway 之下分出三条支线：

路由与会话层：通过 bindings 选择 agentId，会话键支持 main/dm/group/channel 四种类型
嵌入式 Agent Runtime：Agent 的"大脑"，基于 Node.js 的执行环境。其 Agent Loop 的核心流程是：接收 → 组装上下文 → 模型推理 → 工具执行 → 流式输出 → 持久化
插件与 Hook ：插件可以扩展命令、工具甚至 Gateway RPC，Hook 支持 before_agent_start 和 tool_call 等生命周期拦截点

再往下是三个核心支撑模块：

上下文组装：系统提示 + Skills + 注入文件 + 历史消息 + 工具结果/附件
工作区与记忆：AGENTS/SOUL/USER/TOOLS 等配置文件 + memory/YYYY-MM-DD.md + MEMORY.md
模型与工具层：多模型提供商（OpenAI/Anthropic 等）+ 内置工具 + session tools

最终，响应经过 accepted → stream → final 的投递流程，由 Gateway 分发到对应的渠道或客户端。

这套架构中，Gateway 与 Agent Runtime 的关系是理解 OpenClaw 的关键。Gateway 负责"通信"------它不关心 Agent 在想什么，只负责把消息送进来、把回复投出去；Agent Runtime 负责"思考"------它不关心消息从哪来，只负责理解上下文、调用模型、执行工具。这种职责分离使得同一个 Agent 可以同时服务于多个渠道，也让渠道扩展变得非常轻量。

1.2 目录结构

了解了整体架构，再来看看 OpenClaw 在文件系统层面是如何组织的。

首先是 .openclaw 安装目录：

这是 OpenClaw 的"系统根目录"，包含 agents（智能体配置）、credentials（凭证）、devices（设备管理）、extensions（扩展插件）、cron（定时任务）以及核心配置文件 openclaw.json 等。

然后是 workspace 工作目录------Agent 真正"生活"的地方：

工作目录中的文件各司其职：

文件/目录	作用
`AGENTS.md`	Agent 的行为准则和工作流程定义
`SOUL.md`	Agent 的人格定义------"你是谁"
`USER.md`	用户画像------"你在帮助谁"
`TOOLS.md`	工具使用的本地配置说明
`MEMORY.md`	长期精选记忆
`HEARTBEAT.md`	心跳检查清单和提醒事项
`BOOTSTRAP.md`	首次运行的"出生证明"
`memory/`	每日记忆日志目录
`skills/`	技能文件目录

Gateway 默认监听 18789 端口，进程名为 openclaw-gateway，可通过 lsof 或 ps 命令确认。

1.3 记忆系统设计

OpenClaw 的记忆体系是它区别于多数 AI 产品的核心亮点之一。它没有采用向量数据库或隐式嵌入式记忆，而是用可读、可编辑的 Markdown 文件来承载整个记忆系统。

记忆分为两个层次：

Daily Logs（每日日志） ------ memory/YYYY-MM-DD.md

每日的原始流水账记录，存储在 workspace 的 memory/ 目录下。它采用混合模式：既包含原始交互日志，也包含 Memory Flush 产生的自动摘要。文件是 Append-only（只追加），系统在每次会话时自动加载"今天 + 昨天"的内容。用户可以直接打开查看和编辑。

Curated Memory（精选记忆） ------ MEMORY.md

类比人类的长期记忆------经过筛选和提炼的精华。它仅在主会话（与用户一对一聊天）时加载，不会在群聊或共享会话中暴露。这是一个深思熟虑的安全设计，因为 MEMORY.md 中可能包含用户的个人偏好、隐私信息等内容。Agent 可以在主会话期间自由查看和更新，记录重要的决策、教训和心得。

这种设计带来一个显著的好处：记忆是完全透明的。用户可以直接打开 Markdown 文件查看 Agent 到底"记住"了什么，觉得不对就直接改，觉得多余就直接删。不存在"黑盒"，也不需要逆向工程去理解 Agent 的认知状态。

从"prompt"到"workspace"的转变，本质上是把 Agent 的认知状态从一个不可见的 prompt 外化成了一个可版本化、可审查、可协作的文件系统。

二、提示词设计与 Agent 设计原则

架构决定了 OpenClaw "能做什么"，而提示词和配置文件则决定了它"该怎么做"。这一节我们聚焦 Agent 的行为设计层。

2.1 Agent 执行流程

先看 Agent 的策略驱动执行流：

当一个输入事件到达（可能是首次运行、用户消息或心跳轮询），Agent 首先进行会话类型判定，这决定了后续加载哪些上下文：

主会话（与用户直接对话）：加载 SOUL + USER + memory（今天/昨天）+ MEMORY.md ------ 完整上下文
共享会话 （Discord、群聊等）：加载 SOUL + USER + memory（今天/昨天），不加载 MEMORY ------ 安全裁剪

这个区分至关重要。MEMORY.md 中可能包含用户的私人信息，在群聊场景下自动屏蔽，是一种"默认安全"的设计选择。

进入 Agent 核心后，三个子系统协同工作：

策略引擎：负责安全边界控制、群聊场景的发言门控、对外动作的审批流
记忆系统：Daily Logs + MEMORY.md（仅主会话），维持 Agent 的跨会话认知连续性
执行层：Skills（SKILL.md）调用、工具执行、心跳检查等实际动作

最终输出有三种形态：用户回复、HEARTBEAT_OK（心跳静默，表示无需主动沟通）、或记忆更新（将本次会话中的重要信息写入文件）。

2.2 AGENTS.md 深度解析

AGENTS.md 是整个 Agent 行为定义的核心文件。如果说 SOUL.md 定义的是"你是谁"，那么 AGENTS.md 定义的就是"你应该怎么做"。OpenClaw 官方提供了一份设计精良的默认模板，其中的设计思路值得细品。

会话初始化------四步走

AGENTS.md 开篇就规定了每次会话前的加载顺序：

复制代码

1. SOUL.md --- 弄清楚你是谁
2. USER.md --- 弄清楚你需要帮助的是谁
3. memory/YYYY-MM-DD.md（今天 + 昨天）--- 了解近期上下文
4. 如果处于主会话：还要读取 MEMORY.md

紧跟着一句简短有力的指令："直接做就行不需要询问权限。"这表明 OpenClaw 的 Agent 不是一个被动的助手------它被明确授权可以自主读取文件、整理信息、执行预设任务，是一个主动的 Agent。

记忆管理------"写下来，别靠心里记着"

AGENTS.md 中有一条非常直白的原则：

📝 Write It Down - No "Mental Notes"!

记忆会消失------想记住什么必须写进文件。"心里记"熬不过重启，文件可以永久保存。

这句话的背景是：Agent 每次会话都会重新启动（stateless），所有"想记住"的内容必须显式写入文件。这种设计把记忆管理从隐式行为变成了显式操作：

有人说"记住这个" → 写入 memory/YYYY-MM-DD.md
获得心得 → 更新 AGENTS.md 或相关技能文件
出了差错 → 记录下来，避免未来重蹈覆辙

文档记录大于脑海记忆------这条规则既是给 Agent 看的，对做工程的人来说同样受用。

群聊行为准则------"参与对话，别抢风头"

AGENTS.md 对群聊场景的行为规范出乎意料地具体。它详细列举了什么时候该说话：

有人直接 @你或问你问题
你能贡献真正有用的内容
有恰到好处的俏皮话可以插入

以及什么时候该保持沉默：

只是普通的闲聊扯淡
问题已经有人回答了
你的回复就是"对"或"挺好"这种

甚至包括"别连发三条"这种接地气的指导------一条有思想的回复强过三条碎片式的。核心原则浓缩成一句话：Participate, don't dominate。

这些规则读起来像是一位有社交经验的前辈在教新人如何在群里得体地说话。而它之所以需要这么具体，是因为 LLM 天然有"话痨"倾向------不加约束的话，它会对每一条消息都做出回应。

心跳机制------Agent 的"生物钟"

OpenClaw 的心跳（Heartbeat）机制是它实现"主动 Agent"的关键设计。Agent 不是被动等待用户消息才做事，而是会定期收到心跳轮询。在心跳时段，Agent 可以自主完成一系列后台工作：

检查邮件、日历、社交通知（轮流检查，每天 2-4 次）
整理记忆文件，将日常笔记中的精华提炼到 MEMORY.md
检查项目状态（如 git status）
更新和维护文档

AGENTS.md 甚至给出了"主动沟通 vs 保持静默"的判断准则：

✅ 应主动联系：重要邮件到达、日程即将开始（2 小时内）、沉默超过 8 小时

❌ 应保持静默：深夜时间（23:00-08:00）非紧急、用户明显在忙、距上次检查无新变化

这套设计的精妙之处在于：它不是用代码逻辑来硬编码 Agent 行为，而是用自然语言的"行为准则"来引导 LLM。AGENTS.md 本质上就是一份 Agent 的"员工手册"，把"怎么做一个靠谱的 AI 助理"写成了可读的文档。

2.3 一个实际踩坑：记忆"消失"了

在我的实际测试中遇到了一个有趣的情况：Agent 声称自己会自主维护记忆，但查看 workspace 时却发现 memory/ 目录下空空如也------预期中的记忆文件一个都没有。

排查后发现原因是：memory 文件夹和记忆文件只有在 Agent 首次写入记忆时才会创建。如果交互量不足，没有触发 Memory Flush 的压缩阈值，Agent 并不会主动创建文件结构。

解决方案其实很简单------直接告诉 Agent"帮我创建 memory 目录和今天的记忆文件"即可。

三、实战部分

3.1 安装部署

OpenClaw 的安装过程并不复杂，按官方文档操作即可。推荐两个参考资源：

官方安装文档 ：https://docs.openclaw.ai/zh-CN/start/getting-started
腾讯云部署指南 ：https://cloud.tencent.com/developer/article/2624003

安装本身按图索骥即可，没有太多出乎意料的地方。值得注意的是部署环境的选择：本地部署适合开发调试和日常使用，云端部署则适合需要 7×24 小时在线的场景。

3.2 安全性考量

安全性是 Agent 类产品绕不开的话题。OpenClaw 官方文档中有明确的风险说明（详见 GitHub 安全文档），并提供了一套分层防护方案：

沙箱隔离（推荐） ------ 两种互补的方式：

容器边界：在 Docker 中运行完整的 Gateway
工具沙箱：宿主机 Gateway + Docker 隔离的工具执行环境

沙箱作用域配置：

配置	说明
`scope: "agent"`（默认）	每个 Agent 独立沙箱，防止跨 Agent 访问
`scope: "session"`	更严格的单会话隔离
`scope: "shared"`	共享容器/工作区，安全性最低

工作区访问控制：

配置	说明
`workspaceAccess: "none"`（默认）	Agent 工作区不可访问，工具针对沙箱工作区运行
`workspaceAccess: "ro"`	只读挂载 Agent 工作区
`workspaceAccess: "rw"`	读写挂载 Agent 工作区

官方还特别提醒：tools.elevated 是在宿主机上运行命令的全局逃逸舱口，其 allowFrom 配置必须严格控制，不能为不受信的智能体启用。

这套安全体系的设计思路是纵深防御：系统提示是第一层（建议性约束），工具策略是第二层（强制性控制），沙箱是第三层（物理隔离）。三层配合，才能构建出可靠的安全边界。

3.3 实际体验：接入 QQ 与飞书

纸上得来终觉浅。作为实战验证，我分别将 OpenClaw 接入了 QQ 和飞书进行测试。

QQ 接入效果：

飞书接入效果：

从实际体验来看，飞书的对接效果要优于 QQ------消息格式渲染更完整，列表和加粗等 Markdown 格式都能正常显示，交互体验也更流畅。

不过坦率地说，云端部署的实际效果有限。OpenClaw 的核心定位是个人 AI 助理，把它部署到企业级 IM 系统上总有一种"定位错位"的感觉。飞书本身已经有丰富的自动化能力和机器人生态，OpenClaw 在其中的差异化价值并不突出；QQ 的使用场景倒是更贴合"个人助手"的定位，但受限于 QQ 开放平台的能力边界，很多功能无法完全发挥。而且，更为重要的是，我是在云端而不是本地部署，本身可使用的实用功能就很有限。

总体来说------新鲜感有余，实用性还不够。

3.4 现阶段还缺什么

基于实际体验，OpenClaw 目前仍有一些值得改进的方向：

安全性监控：虽然提供了沙箱和策略控制机制，但缺少一个统一的安全监控面板，无法直观地查看 Agent 的所有操作记录和潜在风险告警
执行审计：Agent 的每一步操作------特别是涉及外部工具调用和文件操作时------应当有完整的审计日志，而不仅仅是 Daily Logs 中的简略记录

这些能力对于将 OpenClaw 从"个人玩具"推向"生产级工具"至关重要。

如果你对 OpenClaw 感兴趣并想深入了解，强烈推荐直接阅读其官方中文文档：https://github.com/openclaw/openclaw/tree/main/docs/zh-CN。写得清晰详尽，是目前最好的学习资料。

结语

本文从架构设计、Agent 行为准则和实际体验三个维度，对 OpenClaw 进行了一次全面的入门梳理。

回顾全文，OpenClaw 最打动我的设计理念有两个：一是将记忆外化为可读写的 Markdown 文件系统 ，让 Agent 的认知状态完全透明，可审查、可编辑、可协作；二是将 Agent 放进用户已有的消息入口而非强制用户迁移到新平台，这种"润物无声"的接入方式在分发上具有天然优势。

当然，它也远非完美。较高的学习门槛、尚不完善的安全审计能力，以及在国内 IM 生态中略显水土不服的实际体验，都是需要后续迭代解决的问题。

但无论如何，OpenClaw 代表了一种值得关注的 Agent 设计范式------不是黑盒魔法，而是结构化的、可运维的、把控制权交还给用户的 Agent 系统。它的很多设计思路，比如记忆工程化、行为准则化、安全纵深化，即便你不直接使用 OpenClaw，也值得在自己的 Agent 实践中加以借鉴。

最后，祝大家新年快乐，马到成功！