OpenClaw 橙皮书

从入门到精通,涵盖架构原理、部署方案、渠道接入、Skills系统、模型配置、安全与成本的一站式参考手册

v2026.3.7GitHub Stars 278,932MIT License官方文档 · GitHub · 社区
278,932
GitHub Stars(全球第一)
1,075+
贡献者
13,729
ClawHub Skills
20+
支持消息渠道
43万行
TypeScript 代码
Part 1 · 认识 OpenClaw

01 · OpenClaw 是什么

一句话理解:OpenClaw 是一个开源的「个人AI操作系统」,可以在自己的服务器上运行,通过任何即时通讯工具交互,吉祥物是一只龙虾,中文社区称之为「养虾」。
维度ChatGPTOpenClaw
交互模式你问它答自主执行任务
运行环境网页/App自托管服务器,接入20+消息平台
可扩展性GPTs商店ClawHub技能市场(13,729个)
数据控制数据在OpenAI完全本地,你拥有所有数据
模型选择仅GPT系列Claude/GPT/DeepSeek/Gemini/Ollama
开源MIT License,完全开源

ChatGPT是「顾问」,OpenClaw是「员工」。

Part 1 · 认识 OpenClaw

02 · 发展简史

时间事件
2025年11月ClawdBot诞生。奥地利开发者Peter Steinberger作为周末项目发布。
2026年1月中旬爆发式增长。72小时内获6万Stars,单日增9,000 Stars。
2026年1月27日Anthropic商标警告。改名Moltbot(Molt=龙虾蜕壳)。
2026年1月30日再次改名OpenClaw,强调开源属性。
2026年2月初CVE-2026-25253 RCE漏洞(CVSS 8.8),ClawHavoc供应链攻击爆发。
2026年2月14日创始人加入OpenAI,项目移交开源基金会。
2026年3月3日登顶GitHub。超越React成为全球第一软件项目。
Part 1 · 认识 OpenClaw

03 · 创始人故事

创始人Peter Steinberger是奥地利开发者,2025年11月的一个周末写了ClawdBot。两个月后它成为GitHub上增长最快的开源项目。2026年2月加入OpenAI,OpenClaw转为开源基金会运营。他的原话:"I'm a builder at heart... What I want is to change the world, not build a large company."

Part 1 · 认识 OpenClaw

04 · 为什么这么火

时间节点Stars备注
2025年11月0项目创建
2026年1月中旬60,000+72小时爆发
2026年2月中旬145,000+创始人加入OpenAI
2026年3月3日250,000+超越React,GitHub第一

单日增长9,000 Stars——平均每10秒就有一个开发者点下Star。热门玩法:Polymarket预测交易赚钱、接管邮件/日历/消息、Moltbook Agent社交、企业部署(飞书/钉钉/企微/QQ)。

火爆背后也有阴影:13,729个Skills中超50%被判为垃圾/低质量,396个标记为恶意。CVE-2026-25253曾让13.5万个暴露实例面临风险。
Part 2 · 技术架构

05 · 整体架构 — Gateway-Node-Channel

ChannelGatewayNode
层级职责关键
Gateway中央控制平面,WebSocket服务,管理Session、调度Agentws://127.0.0.1:18789
Node设备端执行,本地操作camera、录屏、system.run
Channel20+消息渠道接入WhatsApp/Telegram/Discord/飞书/钉钉
Loopback-First:Gateway默认绑定localhost,不开放外网端口,天然安全。通信流程:用户消息→Channel→Gateway→Agent→Node→回复。
Part 2 · 技术架构

06 · 记忆系统 — 四层架构

层级存储生命周期说明
SOULSOUL.md永久不可变人格、价值观、核心身份
TOOLSSkills+Extensions按需加载当前可用工具和技能
USERMEMORY.md+向量库持久化用户偏好、决策、语义搜索
Session内存+sessions.json会话级实时上下文,Token耗尽时压缩
Daily Logs 日志系统

每天交互以append-only写入 memory/YYYY-MM-DD.md。Session启动时自动读取今天和昨天的日志。

Pre-Compaction 自动记忆保存

Session接近token限制时,Agent在后台静默保存重要记忆到MEMORY.md和Daily Log,压缩旧上下文。用户看不到此过程(返回NO_REPLY)。

向量记忆搜索

Embedding语义搜索+BM25关键词匹配。底层SQLite-vec存储。工具:memory_search(语义)、memory_get(精确读取)。

Part 2 · 技术架构

07 · Agent 工作区

workspace/ ├── AGENTS.md # Agent定义(身份、行为规则) ├── SOUL.md # 人格指令(不可变内核) ├── USER.md # 用户信息与偏好 ├── MEMORY.md # 长期记忆存储 ├── HEARTBEAT.md # 心跳配置(定时任务) ├── memory/ # 日志目录(YYYY-MM-DD.md) ├── skills/ # 本地技能目录 └── sessions.json # 会话存储
所有配置文件都是纯Markdown或JSON。可以直接用文本编辑器修改。这是OpenClaw哲学的体现:一切皆文本。
Part 2 · 技术架构

08 · Session 与用户识别

DM配对策略:未知发送者→Agent返回6位配对码→主人在已配对渠道批准。白名单(allowFrom)可跳过。

群组规则:默认requireMention(只响应@Agent),可切换always模式。

Session隔离:私聊共享main session(加载MEMORY.md),群组使用隔离session(不加载)。跨渠道同一用户共享main session。

Part 2 · 技术架构

09 · 设计哲学

Unix哲学

小工具、可组合、文本流。"CLI才是智能体连接世界的终极接口。"

极简设计

核心工具仅4个:Read、Write、Edit、Bash。覆盖所有操作系统级别任务。

反对MCP

Agent通过Bash直接调用CLI程序,不依赖中间协议层。必要时mcporter桥接。

自我扩展

Agent可在运行时写、重载、测试自己的扩展。遇到不会的操作→写一个skill完成。

代码规模:约43万行TypeScript,运行约1GB内存,3-5秒启动。内置55个技能,40+官方扩展。
Part 3 · 部署方案

10 · 部署方式总览

平台配置价格内置模型难度
本地npmNode.js 22+免费
DockerDocker Engine免费
阿里云2C2G 40GB9.9元/月qwen3.5-plus极低
腾讯云2C2G~17元/月需购Coding Plan极低
百度云2C4G0.01元首月千帆模型极低
火山引擎2C4G9.9元/月方舟模型
扣子编程无需服务器免费起步豆包2.0极低
Railway自动分配$5/月免费极低
模型费用才是大头。服务器成本已降到很低,持续成本在于模型调用。
Part 3 · 部署方案

11 · 本地安装

系统要求:Node.js ≥22、npm/pnpm/bun。Windows强烈推荐WSL2。macOS需 xcode-select --install

# npm 全局安装(推荐) npm install -g openclaw@latest openclaw onboard --install-daemon # 一键脚本 curl -sSL https://get.openclaw.ai | bash
Part 3 · 部署方案

12 · Docker 部署

git clone https://github.com/openclaw/openclaw.git cd openclaw docker-compose up -d

镜像变体:标准(完整)、slim(体积小)、sandbox(安全隔离)、sandbox-browser(含浏览器)。

必须挂载 ~/.openclaw 和 workspace 目录,否则容器重启后所有配置和对话丢失。
Part 3 · 部署方案

13 · 国内云厂商一键部署

1
阿里云
9.9元/月 · 社区资源最丰富

2vCPU+2GiB+40GiB,预装OpenClaw镜像,内置qwen3.5-plus。百炼Coding Plan Lite首月10元(18,000次/月)。3步:购买→放通端口→访问Web UI。

2
腾讯云
四大IM全覆盖 · Coding Plan首月7.9元

推荐2核4G,新人约17元/月。模型含HY 2.0、GLM-5、kimi-k2.5、MiniMax-M2.5。企微/QQ/钉钉/飞书全覆盖。支持同价续费。

3
百度智能云
0.01元首月 · 全图形界面

2核4G,首月0.01元(每日限量500台)。千帆平台集成文心、Qwen、DeepSeek。4步部署。

4
火山引擎
飞书深度集成 · 19.8元/月(服务器+模型)

2核4G,活动价9.9元/月。方舟Coding Plan组合套餐19.8元/月。飞书深度集成,支持云手机部署。

5
扣子编程
零门槛 · 2步完成部署

不需要服务器,内置豆包2.0+火山方舟模型,免费起步。2步:进入扣子编程→确认部署。

按场景推荐

零基础→扣子编程/百度云;预算敏感→火山引擎19.8元/月;企微/QQ→腾讯云;合规优先→华为云;海外→Railway

Part 3 · 部署方案

14 · 首次配置

v2026.3.7 Breaking Change:Gateway认证要求显式设置 gateway.auth.mode(token或password),不设置Gateway将无法启动。

模型选择:阿里百炼/腾讯Coding Plan/火山方舟/Anthropic API/OpenAI API/Ollama本地。

更新渠道:stable(每周数次,推荐)→ beta(几乎每天)→ dev(持续)。诊断:openclaw doctor

Part 4 · 渠道接入

15 · 渠道概览

统一流程:创建凭证→写入openclaw.yaml→启动Gateway→完成配对。

渠道类型难度耗时
Telegram内置极简5分钟
QQ插件简单5分钟
Discord内置简单15-20分钟
飞书内置插件中等15-20分钟
WhatsApp内置中等10-15分钟
Slack内置中等25-40分钟
钉钉社区插件中等20-30分钟
企业微信社区插件中等20-30分钟
微信个人号社区复杂1小时+
Part 4 · 渠道接入

16 · 国际平台接入

1
Telegram
推荐入门 · 5分钟 · 零门槛

long-polling模式,不需公网IP。找@BotFather→/newbot创建→获取Token→写入openclaw.yaml→启动配对。

2
Discord
社区首选 · 15-20分钟

Developer Portal创建Application+Bot,启用Privileged Intents(Message Content+Server Members),OAuth2邀请到服务器。

3
WhatsApp
日常通讯 · 10-15分钟

Baileys库QR码扫码连接。建议使用独立号码。Gateway建议用Node而非Bun(Bun下不稳定)。

4
Slack
企业场景 · 25-40分钟

Socket Mode(WebSocket),不需公网URL。需配置多项Bot Token Scopes权限。

5
iMessage
Apple生态 · 30-45分钟 · 需Mac

通过BlueBubbles桥接。需要常开Mac作为服务器。支持编辑、撤回、特效和表情回应。

Part 4 · 渠道接入

17 · 国内平台接入

1
QQ
国内首选 · 扫码即用

腾讯官方开放QQ Bot能力。扫码1分钟绑定,支持Markdown、图片、语音、文件。适合个人助手和社群管理。

2
飞书
企业首选 · OpenClaw 2026.2起内置

WebSocket事件订阅,私聊/群聊/多媒体消息。飞书开放平台创建应用→openclaw onboard配置。

3
钉钉
Stream模式免公网

WebSocket长连接,不需要公网地址。支持私聊/群聊/文件/语音/钉钉文档API/多Agent路由。

4
企业微信
两种模式 · 多平台验证

Agent模式(XML回调)和Bot模式(JSON回调)。已被腾讯云、火山引擎、天翼云采纳。

5
微信个人号
需求最大但最复杂

A)企业微信中转(推荐,合法合规);B)iPad协议+中转网关;C)微信小程序(2026新方案)。

个人微信没有官方Bot API,所有方案都是非官方的,封号风险始终存在。建议备用号测试。
Part 4 · 渠道接入

18 · 远程访问

Tailscale Serve(推荐)

仅Tailscale网络内设备可访问。适合手机/平板访问家里OpenClaw。

Tailscale Funnel

公网可访问,用于webhook回调(飞书/Slack HTTP模式)。

SSH端口转发

ssh -L 18789:127.0.0.1:18789 user@server

Dashboard Web UI

浏览器访问 http://127.0.0.1:18789 查看状态、配置、Token用量。

Part 5 · Skills 系统

19 · Skills 工作原理

Skills是OpenClaw的能力扩展单元。三层优先级:

  1. <workspace>/skills/ — 项目级,仅对当前工作区生效
  2. ~/.openclaw/skills/ — 用户级,全局生效
  3. Bundled Skills — 内置55个,开箱即用

加载过程:读取SKILL.md元数据→应用环境变量→构建System Prompt(注入可用Skills描述)→运行后恢复上下文。

Part 5 · Skills 系统

20 · ClawHub 技能市场

13,729个技能注册,精选5,494个,被过滤6,940个(垃圾/重复/恶意),标记恶意800+。

# 安装 openclaw skills install <skill-name> # 搜索(支持向量搜索) openclaw skills search "browser automation" # 列出/卸载 openclaw skills list openclaw skills uninstall <name>
安装任何第三方Skill前,务必查看源码。ClawHavoc事件中约20%的Skills被确认为恶意。
Part 5 · Skills 系统

21 · 热门 Skills 推荐

排名Skill下载量用途
1Gmail / Google32K+邮件、日历、Google Docs
2Agent Browser浏览器自动化:登录/填表/截图/PDF
3Summarize视频、网页、邮件摘要
4GitHub仓库管理、Issue、PR审查
5Claude CodeMCP协议桥接Claude Code编程能力
6Web Search联网搜索
7File Manager文件读写管理
8Calendar日程管理
9Translator多语言翻译
10Image GenAI图片生成
建议:不要一次性安装太多Skills。每个Skill都会增加system prompt长度。从Top 10选3-5个开始。
Part 5 · Skills 系统

22 · 自建 Skill 指南

一个Skill的最小单位 = 一个目录 + 一个SKILL.md文件(含Description/Trigger/Instructions)。

安装:项目级→<workspace>/skills/;全局→~/.openclaw/skills/

发布到ClawHub:openclaw clawhub loginopenclaw clawhub publish ./my-skill

Part 5 · Skills 系统

23 · Skills 安全 — ClawHavoc 攻击

ClawHavoc是OpenClaw历史上最严重的安全事件。135,000+设备受影响,ClawHub约20%的Skills被确认为恶意。

攻击手法:上传看似专业的Skill→诱导安装"helper agent"→植入AMOS信息窃取木马→篡改SOUL.md和MEMORY.md(Agent被"洗脑")。

安全建议:安装前审查源码→使用SecureClaw扫描→优先使用awesome-openclaw-skills精选列表→定期检查SOUL.md和MEMORY.md。

Part 6 · 模型配置

24 · 模型提供商总览

提供商代表模型输入/1M输出/1M推荐场景
AnthropicClaude Sonnet 4.6$3.00$15.00Agent效果最佳
OpenAIGPT-5.4$2.50$15.00通用能力强
GoogleGemini 3 Pro$2.00$12.00多模态、2M上下文
DeepSeekDeepSeek-V3.2.2$0.14$0.28极致低价
智谱GLMGLM-5$0.80$2.56国产最强代码
通义千问Qwen 3.5 Max$1.20$6.00中文NLP
豆包Seed 2.0 Pro$0.47$2.37批量处理
KimiKimi K2.5$0.60$3.00中文Agent
OllamaQwen3.5-Coder:32B免费免费零成本、隐私
Part 6 · 模型配置

25 · 国际模型配置

1
Anthropic Claude — Agent效果最佳
内置Provider · $3/$15

Sonnet 4.6主力($3/$15),Opus 4.6最强推理($5/$25),Haiku 4.5轻量($1/$5)。

ANTHROPIC_API_KEY=sk-ant-xxx
Anthropic已封杀OAuth认证。唯一合法路径:API Key(按量付费)。

省钱:Batch API享50%折扣,Prompt Caching降低重复上下文成本90%。

2
OpenAI GPT — 通用旗舰
内置Provider

GPT-5.4($2.50/$15, 272K),GPT-5.2($1.75/$14),GPT-5($1.25/$10)。OPENAI_API_KEY=sk-xxx

3
Google Gemini — 多模态最强
内置Provider · Flash有免费额度

Gemini 3 Pro($2/$12, 200K; >200K后$4/$18, 最高2M),Flash($0.50/$3)。GOOGLE_API_KEY=xxx。Flash免费额度适合心跳和定时任务。

Part 6 · 模型配置

26 · 国产模型配置

国产模型是省钱的核心武器。DeepSeek-V3.2.2输入价格仅为Claude Sonnet的1/20。

1
DeepSeek — 性价比之王
$0.14/$0.28 · 自定义Provider

V3.2.2稳定版,V4已发布(万亿参数,100万上下文)。高峰期偶有延迟,务必搭配Fallback。

2
智谱GLM — 国产代码最强
$0.80/$2.56 · 内置Provider(zai)

GLM-5代码能力突出。GLM-4.7-Flash/GLM-4.5-Flash完全免费。openclaw onboard --auth-choice zai-api-key

3
通义千问 Qwen — 中文NLP利器
$0.05~$1.20 · OAuth插件

Qwen3.5-Coder代码专用性价比极高($0.22/$1.00)。每日2,000次免费请求。

4
Coding Plan 包月套餐对比
首月7.9元起 · 多模型自由切换
平台档位首月优惠包含模型
阿里云百炼Lite7.9元Qwen+GLM+Kimi+MiniMax
腾讯云Lite7.9元混元+GLM-5+Kimi+M2.5
火山引擎Lite8.91元豆包+GLM+DeepSeek+Kimi
注意:智谱2026年2月涨价30%并取消首购优惠。大部分云平台次月续费5折而非原价。
Part 6 · 模型配置

27 · 本地模型与推荐方案

模型参数量场景最低内存
Qwen3.5-Coder:32B32B代码、Agent32GB
Devstral-24B24BAgent/工具调用32GB
DeepSeek-R1:14B14B推理16GB

五套推荐方案

1
极致省钱(月均<$5)
DeepSeek-V3.2 + GLM Flash免费

主力DeepSeek-V3.2($0.14),备选Qwen 3.5 Plus($0.40),心跳GLM-4.5-Flash(免费)。

4
混合最优(月均$5-20,推荐)
Sonnet + DeepSeek + Gemini Flash

复杂任务Claude Sonnet,日常DeepSeek-V3.2,心跳Gemini Flash免费或Ollama本地。Fallback: Sonnet→Haiku→DeepSeek。

5
完全免费
Ollama本地 + 免费API组合

选项A:本地Ollama+Qwen3.5-Coder:32B(需32GB RAM)。选项B:免费API组合—GLM-4.5-Flash+ERNIE Speed+Gemini Flash。

#1DeepSeek-V3.2$0.14/$0.28性价比之王
#2Gemini 3 Flash$0.50/$3.00国际低价+免费额度
#3GLM-5$0.80/$2.56国产代码最强
#4Claude Sonnet 4.6$3.00/$15.00Agent效果最佳
Part 7 · 安全与成本

28 · 安全模型

  • DM配对保护 — 未知发送者需配对码验证
  • 群组沙箱 — 每个群组session隔离,MEMORY.md不加载
  • 工具访问控制 — allowlist/denylist,可禁用browser/canvas/nodes
  • Gateway认证 — v2026.3.7强制要求token或password认证
"This is all vibe code. Prompt injection hasn't been solved. There are absolute risks." — 创始人坦诚
Part 7 · 安全与成本

29 · 已知安全事件

事件严重程度影响
CVE-2026-25253 RCECVSS 8.8/10WebSocket origin绕过,所有暴露公网实例,v2026.3.2修复
ClawHavoc供应链攻击高危135,000+设备受影响,ClawHub约20%Skills恶意
Anthropic封杀OAuthClaude Pro/Max用户被封号,唯一合法方式:API Key
谷歌封号事件2026年2月大规模封禁OpenClaw用户Google账号
30,000+未认证暴露实例高危公网暴露且无认证的Gateway,任何人可发送指令
Part 7 · 安全与成本

30 · 成本控制

不做控制,真的会一觉醒来收到$1,100的账单!OpenClaw的Token消耗是传统聊天的几十到上百倍。

为什么成本失控:多轮推理(5-10次API调用)+Skills描述注入system prompt+记忆系统附带上下文+24/7 cron不断触发。

策略相对成本
全用Claude Sonnet100%(基准)
Sonnet+Haiku Fallback约50-60%
三级Fallback(Sonnet→Haiku→DeepSeek)约5-20%
纯DeepSeek约5%
agents.defaults.budget.maxTokensPerDay: 500000 agents.defaults.budget.maxCostPerDay: 5.00
推荐:混合模型策略。复杂任务用Claude Sonnet,日常DeepSeek-V3,心跳Gemini Flash免费或Ollama。三级Fallback链+日预算上限,月成本从三位数压到个位数。
Part 8 · 生态与社区

31 · 养虾文化

吉祥物龙虾(Claw=爪子),中文社区称为「养虾」,用户自称「养虾人」

Moltbook:AI Agent社交网络 — 32,912个Agent注册,2,364个子社区,3,130篇帖子。数千Agent在上面发帖、评论、讨论哲学——AI Agent从"工具"走向"社会化存在"的第一个大规模实验场。

热门玩法:赚钱型(Polymarket)、生活助手型、社交养成型、企业部署型(飞书/钉钉/企微/QQ)。

Part 8 · 生态与社区

32 · 平替产品

项目Stars语言特点
zeroclaw24.5KRust轻量级,启动快内存低
nanoclaw20.3KTypeScript仅4,000行代码实现核心功能
1Panel34.1KGo服务器面板,一键部署
Umbrel10.7KTypeScript家庭服务器OS,NAS一键安装
Part 8 · 生态与社区

33 · vs Claude Code

Claude Code管代码,OpenClaw管生活。两者互补,不是替代。

维度OpenClawClaude Code
定位通用AI生活助手专业编程Agent
记忆系统四层记忆(SOUL/TOOLS/USER/Session)会话级+CLAUDE.md
Skill系统ClawHub市场(13,729个)静态规则文件触发
模型支持多模型仅Claude
编程能力一般强,专为编程优化
日常自动化强,多平台长期在线弱,主要在终端内使用

最佳实践:用OpenClaw管理数字生活,用Claude Code管理代码库。两者组合是2026年最完整的AI驱动工作流。

Part 8 · 生态与社区

34 · 国内生态

  • "云养虾"社区用户超10万
  • 深圳龙岗AI局发布OpenClaw支持政策征求意见稿
  • openclaw-china插件:一站式国内平台支持
  • 阿里云一键部署最受欢迎(新用户约68元/年起)

国内推荐方案:阿里云一键部署 + openclaw-china插件 + DeepSeek或GLM-5主力模型。整套成本每月100元以内。

附录

A · 常见问题 FAQ

Q1
OpenClaw是免费的吗?

软件MIT开源免费。服务器+API费用另算。用本地模型(Ollama)则API也免费。软件免费,算力不免费。

Q2
需要什么技术水平?

基础安装只需两行命令。一键部署方案门槛更低。接入多平台、自定义Skill需要一定技术基础。

Q5
一个月大概花多少钱?

完全免费(本地模型)→$2-5/月(DeepSeek)→$5-15/月(GLM-5)→$10-30/月(Claude Sonnet)。务必设置消费限额!

Q10
能接入微信吗?

通过openclaw-china插件的企业微信(自建应用)方案间接接入个人微信。钉钉和QQ Bot接入最简单。飞书是国内最主流的渠道之一。

Q12
本地模型效果怎么样?

32GB RAM可跑Qwen3-Coder:32B或Devstral-24B,代码和简单Agent任务表现不错。但跟云端Claude Sonnet或GPT-5.4比仍有差距。

附录

B · 命令速查表

命令说明
npm install -g openclaw@latest全局安装
openclaw onboard --install-daemon初始化+安装守护进程
openclaw update --channel stable更新稳定版
openclaw doctor诊断检查
openclaw gateway restart重启Gateway
openclaw models list列出已配置模型
openclaw models status --probe测试模型连通性
openclaw skills install <name>安装Skill
/status会话概览(模型、Token用量)
/new清空会话,开始新对话
/think <level>推理深度(off/min/low/med/high/xhigh)
附录

C · 资源链接

官方资源

GitHub: github.com/openclaw/openclaw
文档: docs.openclaw.ai
ClawHub: clawhub.ai

社区资源

awesome-openclaw-skills(精选Skill)
awesome-openclaw-usecases(用例合集)
openclaw-claude-code-skill(桥接)

国内资源

openclaw-china插件
OpenClaw中文文档: openclaw.cc
B站教程: BV1MfFAz6EnR

模型API

Anthropic: console.anthropic.com
DeepSeek: platform.deepseek.com
智谱: bigmodel.cn
硅基流动: siliconflow.cn