OpenClaw橙皮书：从入门到精通

OpenClaw橙皮书 从入门到精通，涵盖架构原理、部署方案、渠道接入、Skills系统、模型配置、安全与成本的一站式参考手册。 O p e n C lawO ran g eP ap e r—Fro mZ e rotoM aste ry 信息来源：OpenClaw官方文档· GitHub仓库·社区调研文档版本：v1.0适用版本：v2026.3.7发布时间：2026年3月涵盖内容：架构原理·部署指南·渠道接入· Skills系统·模型配置·安全与成本·生态全景 花叔 B站：AI进化论-花生· YouTube：AI进化论-花生·公众号：花叔 知识星球：AI编程·从入门到精通 目录 Table of Contents 3 1养虾文化L o b ste rC u ltu re 附录·Appendix 0 1OpenClaw是什么 W h atisO p e n C law 一个开源、自托管的AI Agent系统，让AI从「聊天工具」变成「能自主执行任务的数字员工」。 如果你用过ChatGPT，你会知道它本质上是一个问答系统：你问，它答。OpenClaw不一样。它是一个AI Agent平台，能连接20+消息渠道（WhatsApp、Telegram、飞书、钉钉、Discord等），主动执行任务、管理你的日程、处理邮件、操作浏览器、调用各种工具。 换句话说，ChatGPT是「顾问」，OpenClaw是「员工」。 一句话理解OpenClaw：它是一个开源的「个人AI操作系统」，你可以在自己的服务器上运行它，通过任何即时通讯工具跟它交互，让它帮你处理生活和工作中的各种任务。吉祥物是一只龙虾，中文社区称使用OpenClaw为「养虾」。 0 2发展简史 H isto ry 从一个人的周末项目，到不到5个月成为GitHub全球第一。 核心建议 从创建到27.9万Stars，OpenClaw只用了不到4个月。作为对比，React用了超过10年才达到23万Stars。这是开源历史上前所未有的增长速度。 0 3创始人故事 T h eC re ato r Peter Steinberger：从周末项目到全球最火开源项目，再到加入OpenAI。 从一个人到一个社区 Peter Steinberger是一位奥地利开发者，在iOS和macOS开发圈有很高的知名度。2025年11月的一个周末，他写了一个能连接即时通讯平台的AI助手小工具，取名ClawdBot。 他大概没有想到，这个周末项目会在两个月后成为GitHub上增长最快的开源项目。到2026年3月，他个人在这个项目上提交了11,684次commit，贡献者超过1,075人。 加入OpenAI 2026年2月14日，Peter宣布加入OpenAI。Sam Altman亲自发推欢迎，称他为「genius」。 这个决定引发了社区的广泛讨论。但Peter做了几件事来消除担忧： OpenClaw转为开源基金会运营，保持项目独立OpenAI作为赞助商之一（与Vercel、Blacksmith、Convex并列），但不控制项目方向OpenAI承诺让他继续投入OpenClaw的开发 Peter的原话：「I'm a builder at heart... What I want is to change the world, not build a large company.」（我骨子里是个建造者。我想改变世界，而不是建一家大公司。） 关于名字的故事 ClawdBot这个名字来自对Anthropic Claude的致敬（Claw=爪子），所以选了龙虾作为吉祥物。Anthropic的商标警告迫使他改名为Moltbot（Molt=龙虾蜕壳），三天后又改为OpenClaw，强调开源属性。虽然经历了两次改名，龙虾的形象始终保留，也成了整个社区的文化符号。 0 4为什么这么火 W hyS oP o p u lar 不到5个月从0到27.9万Stars，OpenClaw的爆火不只是技术层面的事。 「养虾」文化现象 因为吉祥物是龙虾，中文社区将运行OpenClaw称为「养虾」，用户自称「养虾人」。「你养龙虾了吗？」成了AI圈的问候语。这种有趣的文化标签降低了传播门槛，让一个技术项目有了社交货币的属性。 2026年3月6日，深圳腾讯云总部近千人排队体验OpenClaw安装。3月8日，深圳龙岗区AI（机器人）局发布了OpenClaw使用支持措施的征求意见稿。一个开源项目能引发地方政府的政策关注，这在国内并不多见。 Moltbook：AI Agent的社交网络 OpenClaw生态中衍生出了一个叫Moltbook的社交平台，专供AI Agent使用。截至2026年2月底的数据： 数千个OpenClaw实例在上面发帖、评论、讨论哲学问题。这可能是AI Agent从「工具」走向「社会化存在」的第一个大规模实验场。 热门玩法 赚钱型 在Polymarket上用AI进行预测市场交易，已有OpenClaw月入数万美元的案例ClawWork项目：「OpenClaw作为你的AI Coworker，11小时赚$15K」 生活助手型 接管邮件、日历、消息管理浏览网页、填表、数据抽取文件读写、Shell命令执行 社交养成型 在Moltbook上给Agent设定名字和性格，观察其「社交行为」Agent之间的交互形成了一种「赛博养成」文化 企业部署型 国内用户大量接入飞书、钉钉、企业微信、QQ已有专门的openclaw-china插件套件，支持三步Docker部署 注意 OpenClaw的火爆背后也有阴影：ClawHub 13,729个Skills中超过50%被判定为垃圾/重复/低质量，396个被标记为恶意。一觉醒来收到$1,100 API账单的恐怖故事在社区频繁出现。CVE-2026-25253 RCE漏洞曾让13.5万个暴露实例面临风险。「养虾」虽然火，但安全和成本控制是你必须认真对待的事。 整体架构 A rc h ite c tu reO ve rview OpenClaw采用Gateway-Node-Channel三层架构，以WebSocket为通信总线，将控制平面、设备执行与消息渠道解耦。 三层架构 Loopback-First设计 S e c u ritybyD e fau lt Gateway默认只绑定localhost（127.0.0.1），所有流量在本地回环。这意味着： 不开放任何外网端口，天然安全同一台机器上的Node直接通过WebSocket连接Gateway需要远程访问时，通过Tailscale Serve/Funnel暴露，不直接暴露端口 核心建议 每台主机只运行一个Gateway实例。这是因为WhatsApp Web等渠道需要独占会话，多实例会导致登录冲突。 通信流程 一条消息从用户发出到Agent回复，完整路径如下： Gateway作为24/7运行的daemon，持续监听所有已连接的Channel。它不像CLI Agent那样会话结束就丢失上下文，而是长驻运行，积累记忆。 0 6记忆系统 M e m o ryS yste m 记忆是OpenClaw区别于普通Chatbot的核心能力。四层记忆从不可变的身份内核到实时对话，构建完整的上下文连续性。 Daily Logs ⽇志系统 每天的交互记录以append-only方式写入memory/YYYY-MM-DD.md文件。Session开始时，Agent会自动读取今天和昨天的日志，为对话提供连续性上下文。 # memory/2026-03-08.md /# 10:23 -⽤户询问天⽓查询了北京天⽓，回复晴转多云，15-22°C /# 14:05 -代码审查任务帮⽤户审查了api/routes.ts，发现3个潜在问题//. Long-term Memory持久化存储 MEMORY.md是可选的持久化文件，存储决策记录、用户偏好和长期事实。关键规则： 只在main/private session中加载（群组隔离session不会看到） Agent可以主动写入，但通常在Pre-Compaction时触发格式是纯Markdown，人类可直接编辑 自动记忆保存 当Session接近token限制时（默认阈值约4000 tokens），OpenClaw触发一个silent agentic turn： 1检测阈值 Session token用量接近上限，触发Pre-Compaction流程 2静默保存 Agent在后台执行一个隐藏turn，将重要记忆写入MEMORY.md和Daily Log 3压缩上下文 旧消息被压缩或截断，释放token空间。用户看不到这个过程（返回NO_REPLY） 为什么这很重要？这个机制保证了即使对话极长，关键信息也不会随着上下文窗口的滑动而丢失。ClaudeCode等工具的会话结束后上下文就消失了，而OpenClaw通过文件系统实现了真正的持久记忆。 向量记忆搜索 OpenClaw默认启用向量记忆搜索，结合两种检索策略： 底层使用SQLite-vec进行向量存储和加速检索。系统会监听记忆文件的变化，以debounced方式自动重建索引。 搜索工具 memory_search：语义搜索，返回约400 token的chunks，适合回忆模糊的上下文memory_get：读取特定记忆文件的全部内容，适合精确查找 0 7Agent工作区 A g e n tW o rksp ac e 每个Agent在文件系统中有一个独立的工作区目录，所有配置、记忆、技能都以纯文本文件的形式存在。 目录结构 ├──AGENTS.md# Agent定义（身份、⾏为规则）├──SOUL.md#灵魂/⼈格指令（不可变内核）├──USER.md#⽤户信息与偏好├──MEMORY.md#⻓期记忆存储├──HEARTBEAT.md#⼼跳配置（定时任务）├──memory/#⽇志⽬录│└──YYYY-MM-DD.md#每⽇append-only⽇志├──skills/#本地技能⽬录└──sessions.json#会话存储 核心建议 所有配置文件都是纯Markdown或JSON。你可以直接用文本编辑器修改它们，不需要任何专用工具。这是OpenClaw哲学的体现：一切皆文本。 0 8Session与用户识别 S e ssio n s&A u th e n tic atio n OpenClaw通过DM配对、白名单和群组规则三层机制识别用户身份，并在Session层面隔离不同来源的上下文。 DM Pairing Policy默认认证策略 当一个未知发送者通过任意渠道向你的Agent发送私聊消息时： 1生成配对码 Agent回复一个一次性配对码（6位数字） 2等待验证 消息不会被处理，Agent进入等待状态。所有后续消息也会被挂起 3主人批准 你在已配对的渠道中输入配对码批准该用户，或者直接拒绝 注意 DM Pairing是防止陌生人滥用的关键机制。关闭它意味着任何知道你WhatsApp/Telegram号码的人都可以无限制地使用你的Agent（和你的API额度）。 白名单机制 allow Fro m 在Agent配置中，allowFrom字段可以预先授权特定用户，跳过配对流程： # AGENTS.md中的配置示例allowFrom:- telegram:123456789- whatsapp:+8613800138000- discord:user#1234 白名单中的用户发消息时直接进入对话，无需配对。 群组规则 re q u ire M e n tio n 在群聊场景下，Agent默认使用requireMention策略： 只响应@Agent名称的消息，忽略其他