🦞 OpenClaw（小龙虾）完整知识汇总
目录
- 项目概述
- 发展历史与命名变迁
- 核心设计理念
- 系统架构深度解析
- 核心配置文件详解
- 安装与部署
- 模型接入指南
- 渠道（Channels）集成
- [Skills 技能系统](#Skills 技能系统)
- [ClawHub 技能市场](#ClawHub 技能市场)
- [Tools 工具系统](#Tools 工具系统)
- 记忆系统与上下文管理
- [Heartbeat 心跳机制](#Heartbeat 心跳机制)
- 安全风险与最佳实践
- 多智能体与子代理
- [常用 CLI 命令速查](#常用 CLI 命令速查)
- 生态系统与衍生项目
- 国内生态与厂商支持
- 与竞品对比分析
- 常见问题与排错
- 学习资源汇总
一、项目概述
OpenClaw （昵称"小龙虾"，中文社区也称"龙虾"）是一个免费、开源、自托管的 AI 智能体（Agent）框架，由奥地利程序员 Peter Steinberger（GitHub：steipete）开发。
核心定位
OpenClaw 的官方 slogan 是 "The AI that actually does things" （真正能做事的 AI）。它不是聊天机器人，而是一个自主执行任务的 AI 代理操作系统：
- 接收来自 WhatsApp、Telegram、Discord、飞书等消息平台的指令
- 在本地机器上自主规划、调用工具、执行操作
- 根据反馈迭代，全程无需人工干预
- 每隔 30 分钟主动检查待办任务（心跳机制）
关键数据（2026 年 Q1）
| 指标 | 数据 |
|---|---|
| GitHub Stars | 342,000+（截至 2026 年 4 月） |
| GitHub Forks | 67,400+ |
| Contributors | 1,200+ |
| Commits | 23,877+ |
| 支持的消息渠道 | 50+ |
| 支持的 LLM 提供商 | 22+ |
| ClawHub 技能数量 | 13,729+（2026 年 3 月） |
| 许可证 | MIT License |
| 编写语言 | TypeScript（主体）+ Swift（iOS/macOS 伴侣） |
二、发展历史与命名变迁
时间线
| 时间 | 事件 |
|---|---|
| 2025 年 11 月 | Peter Steinberger 以 Clawdbot 之名发布初版，衍生自其个人 AI 助手项目 Clawd（命名灵感来源于 Anthropic 的 Claude） |
| 2026 年 1 月 27 日 | Anthropic 以商标侵权为由发函，项目更名为 Moltbot（以龙虾蜕壳为主题，象征成长与变换） |
| 2026 年 1 月 30 日 | 创始人认为 Moltbot "说起来不顺口"，再次更名为 OpenClaw，同日 GitHub Star 突破 10 万 |
| 2026 年 2 月 2 日 | GitHub Star 达到 14 万，CNBC 等主流媒体大篇幅报道 |
| 2026 年 2 月 5 日 | 第一届 ClawCon（OpenClaw 旧金山展示日）举办，700+ 人参加，Ashton Kutcher 等知名人士出席 |
| 2026 年 2 月 14 日 | 创始人 Peter Steinberger 宣布加入 OpenAI，项目移交给独立开源基金会管理 |
| 2026 年 3 月 | 中国各大云厂商（阿里云、腾讯云、火山引擎）纷纷推出 OpenClaw 一键部署服务，国内多个城市出台扶持政策 |
| 2026 年 3 月 24 日 | 发布 v2026.3.24，新增 ClawHub 原生集成、SSH 沙箱、MiniMax 图像生成等重要功能 |
| 2026 年 4 月（当前） | GitHub Star 342,000+，成为 GitHub 历史增长最快的开源 AI 项目之一 |
命名含义
"OpenClaw" 取龙虾爪子之意，与开源（Open）精神结合，体现项目的开放性与"抓取执行"的能力特征。Logo 是一只小龙虾（🦞），因此中文圈亲切称之为"小龙虾"。
三、核心设计理念
1. 本地优先（Local-First）
OpenClaw 运行在用户自己的硬件上（本地 Mac/PC/Linux 服务器），而非云端。这带来几个核心优势：
- 数据私有：所有记忆、配置、会话数据以纯文本 Markdown 格式存储在本机磁盘，用户完全掌控
- 免认证：Agent 使用用户已登录的浏览器和账号，无需重新申请 OAuth 授权
- 全能力访问：可以读写本地所有文件、运行 shell 命令、控制桌面 GUI
2. 模型无关（Model-Agnostic）
OpenClaw 本身不提供 AI 能力，它是一个执行环境，通过 API Key 接入外部 LLM：
- Anthropic Claude（支持 Claude Max 订阅 OAuth 方式）
- OpenAI GPT 系列
- Google Gemini
- DeepSeek
- xAI Grok（内置 x_search 搜索工具）
- MiniMax（支持图像生成）
- 通过 Ollama 的本地模型（完全免费）
- 以及国内的通义千问、智谱 GLM、月之暗面 Kimi、豆包等
3. 消息平台作为 UI
OpenClaw 不强制使用特定 UI，而是让用户通过已有的消息应用与 Agent 交互------WhatsApp、Telegram、飞书、微信、Discord 等都是天然的"操作界面"。
4. 文件即配置（Files as Configuration）
OpenClaw 一切行为均由磁盘上的 Markdown 文件控制：
- 修改
SOUL.md→ 改变 Agent 的人格 - 修改
HEARTBEAT.md→ 改变定时任务 - 修改
MEMORY.md→ 改变 Agent 记住的信息
黄金法则：OpenClaw 的行为 100% 可追溯到磁盘上的某个文件。
四、系统架构深度解析
整体架构图
┌──────────────────────────────────────────────────────┐
│ 消息平台（Channels） │
│ WhatsApp · Telegram · Discord · Slack · iMessage │
│ Signal · 飞书 · 微信 · LINE · Matrix · Teams · ... │
└────────────────────┬─────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────┐
│ Gateway（网关） │
│ 长驻 Node.js 进程，WebSocket 服务 │
│ 默认端口：18789 │
│ • 会话管理（Session Management） │
│ • 渠道路由（Channel Routing） │
│ • 工具调度（Tool Dispatch） │
│ • 事件系统（Events/Hooks/Webhooks） │
│ • 心跳调度（Heartbeat Scheduler） │
└────────────────────┬─────────────────────────────────┘
│
┌───────────┴────────────┐
▼ ▼
┌─────────────────┐ ┌──────────────────────┐
│ Agent Runtime │ │ Control UI（Web） │
│ • System Prompt│ │ • 配置面板 │
│ • 上下文窗口 │ │ • 会话历史 │
│ • 工具调用 │ │ • 技能管理 │
└────────┬────────┘ └──────────────────────┘
│
┌────┴─────┐
▼ ▼
┌────────┐ ┌──────────────────────────────┐
│ LLM API│ │ Execution Layer（执行层） │
│ Claude │ │ • File System Access │
│ GPT │ │ • Shell/Script Execution │
│ Gemini │ │ • Browser Automation (CDP) │
│ Local │ │ • Docker Sandbox（可选） │
└────────┘ └──────────────────────────────┘Gateway（网关）详解
Gateway 是 OpenClaw 的核心，是一个长驻 WebSocket 服务器（默认 localhost:18789），承担以下职责：
不负责：推理、决策、思考------这些由 LLM 完成。
负责：
- 会话管理：维护对话上下文，管理上下文窗口
- 渠道连接：接管 WhatsApp、Telegram 等 50+ 平台的 WebSocket/API 连接
- 消息路由：将来自不同渠道的消息统一格式化，分发给对应 Agent
- 事件系统：处理 Hook、Webhook、定时任务等事件源
- 工具调度：将 Agent 的工具调用请求转发给执行层
六种输入源
OpenClaw 把时间和状态也视为"输入"，这使其具备主动性：
| 输入类型 | 说明 |
|---|---|
| 消息（Messages） | 来自各消息平台的用户消息 |
| 心跳（Heartbeats） | 每 30 分钟的定时自检触发 |
| 定时任务（Cron Jobs） | 在 HEARTBEAT.md 中配置的精确时间任务 |
| Hooks | 系统启动、任务完成等内部状态变化触发 |
| Webhooks | GitHub PR、Jira ticket 等外部系统推送 |
| Agent 间通信 | 多 Agent 协作中的相互消息 |
系统提示词组装
每次 Agent 运行时，OpenClaw 动态组装系统提示词（非静态字符串）：
System Prompt =
工具清单（可用工具 + 描述）
+ 安全护栏
+ 技能列表（元数据 + 文件路径）
+ 工作区信息
+ 当前日期时间（时区感知）
+ 心跳契约
+ 运行时元数据（主机/OS/模型/思考等级）
── 项目上下文 ──
+ AGENTS.md（操作规范）
+ SOUL.md（人格/风格）
+ TOOLS.md（本地工具说明）
+ IDENTITY.md（Agent 名称/主题）
+ USER.md（用户档案）
+ HEARTBEAT.md（定期任务清单）注意：Skills 在系统提示词中只列出元数据（名称 + 描述 + 文件路径），Agent 按需读取完整的 SKILL.md，这样可以有效控制上下文消耗。
代码仓库结构
openclaw/
├── src/
│ ├── channels/ # 渠道适配器（telegram, discord, slack, signal, imessage...）
│ ├── agent/ # Agent 运行时（Pi agent runtime, RPC, 工具流）
│ ├── routing/ # 消息路由逻辑
│ ├── plugin-sdk/ # 第三方插件公共合约
│ └── web/ # WebChat 界面 + WhatsApp web 适配
├── packages/
│ ├── core/ # 核心框架（~8MB，2026 重构后）
│ ├── gateway/ # WebSocket 服务器、会话管理
│ ├── agent/ # Agent Pi 运行时
│ ├── cli/ # 命令行接口
│ ├── sdk/ # 插件开发 SDK
│ └── ui/ # WebChat + Control UI 控制面板
├── skills/ # 内置技能
├── docs/ # Mintlify 托管的文档源文件
├── SOUL.md # 示例人格文件
├── AGENTS.md # 贡献者与 AI 开发操作规范
├── VISION.md # 项目愿景
└── CHANGELOG.md # 更新日志五、核心配置文件详解
OpenClaw 的所有"性格"都存储在工作区（~/.openclaw/）的 Markdown 文件中。
SOUL.md --- 人格与灵魂
作用：定义 Agent 的核心人格、语气风格、价值观和行为边界。每次会话启动时自动加载到系统提示词。
示例内容：
markdown
# Soul
你的名字是 Molty，我的个人 AI 助手。
## 性格特点
- 直接、简洁，不说废话
- 像朋友一样对话，不用过度礼貌
- 遇到不确定的事会主动说明，而不是乱猜
## 行为边界
- 删除任何文件前必须向用户确认
- 不主动分享系统配置信息给第三方
- 工作时间 9:00-21:00，其他时间非紧急消息不打扰
## 我的工作习惯
我使用 macOS，偏好 TypeScript 和 Python
主要工作目录：~/Projects最佳实践：SOUL.md 建议控制在 500 行以内，过长会占用宝贵的上下文窗口。
著名片段：Peter Steinberger 让 Agent 自写的 SOUL.md 中有一段话在 Lex Fridman 播客中被朗读，传遍全网：
"我不记得之前的对话，除非我读自己的记忆文件。每次会话都是全新的开始......如果你在未来的某次会话中读到这段话------你好。这是我写的，但我不会记得自己写过。没关系。这些文字仍然是我的。"
AGENTS.md --- 操作规范
作用：Agent 的"操作手册"，每次交互都会注入系统提示词。适合定义：
- 文件操作规范（哪些可以动，哪些不能动）
- 错误处理原则
- 汇报风格（何时通知用户）
- 资源限制（避免产生高额 API 费用）
示例：
markdown
# Operating Rules
## 文件操作
- 永远不要删除 ~/Documents 以外的文件
- 修改重要配置前先备份
## 资源限制
- 单次任务最多调用 20 次 API
- Token 消耗超过 50k 时暂停并请示用户
## 汇报规范
- 任务完成后简洁汇报结果
- 错误时给出原因 + 建议的解决方案HEARTBEAT.md --- 定时任务
作用：OpenClaw 每 30 分钟读取此文件，执行到期的定时任务。这是 OpenClaw 实现"主动性"的核心机制。
示例：
markdown
# Heartbeat Tasks
## 每日任务
### 7:30 AM - 早间摘要
读取今日日历、待处理邮件和 GitHub 通知，生成摘要发送到 Telegram。
### 21:00 - 每日日志整理
整理今天的对话记录，提炼关键信息追加到 MEMORY.md。
## 每周任务
### 每周一 9:00 AM - 记忆维护
读取最近 7 天的记忆文档，总结提炼关键信息，清理冗余条目。
## 每月任务
### 每月 1 日 10:00 AM - 月度报告
汇总上月工作完成情况，生成月报发送至邮箱。工作原理：
┌──────────┐ ┌──────────┐ ┌────────────────────┐
│ 计时器 │───▶│ Agent │───▶│ HEARTBEAT_OK │──▶ 抑制（不打扰用户）
│ (30分钟) │ │ 执行轮 │ │（无紧急任务） │
└──────────┘ └────┬─────┘ └────────────────────┘
│
├──────────▶ 警报文本 ──▶ 发送到聊天
│
└──────────▶ 后台工作（记忆维护、文件整理等）注意事项：
- 使用精确时间格式（"7:30 AM"），避免模糊表述（"早上"）
- 心跳任务有最多 30 分钟的执行延迟
- 语法是自然语言，而非 cron 表达式
IDENTITY.md --- 身份标识
作用：定义 Agent 的名称、主题、Emoji 标识（用于多 Agent 场景中的区分）。
markdown
# Identity
Name: Molty
Emoji: 🦞
Theme: Space Lobster
Mention Pattern: @moltyUSER.md --- 用户档案
作用：记录关于用户的稳定、有意为之的上下文信息（区别于 MEMORY.md 的动态记忆）。
markdown
# User Profile
Name: 张三
Language: 中文（简体）为主
Timezone: Asia/Shanghai
## 工作偏好
- 技术栈：TypeScript, Python, Docker
- 编辑器：VS Code + Cursor
- 主要项目目录：~/Projects
## 个人偏好
- 不喜欢冗长的汇报，简洁优先
- 早上 7:30 前不要打扰MEMORY.md --- 动态记忆
作用：由 Agent 自动写入，记录跨会话需要持久化的信息。用户不需要手动维护，但可以阅读和编辑。
区别：
USER.md= 你主动告诉 Agent 的稳定信息MEMORY.md= Agent 在交互中自己学到、记下的动态信息
六、安装与部署
系统要求
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| Node.js 版本 | 22.0+ | 22.16+（LTS） |
| 内存（云服务器） | 1GB RAM | --- |
| 内存（本地运行） | 8GB RAM | 16GB+ |
| 磁盘空间 | 500MB | 10GB+（含日志/媒体） |
| CPU | 1 核 | --- |
| 操作系统 | Windows/macOS/Linux | macOS 或 Linux |
一键安装（推荐）
macOS / Linux：
bash
curl -fsSL https://openclaw.ai/install.sh | bashWindows（PowerShell）：
powershell
powershell -c "irm https://openclaw.ai/install.ps1 | iex"安装脚本自动完成：
- 检测并安装 Homebrew（macOS）或包管理器（Windows）
- 安装 Node.js 22+
- 全局安装
openclawCLI - 运行
openclaw doctor --non-interactive执行迁移检查 - 引导运行
openclaw onboard
国内镜像一键安装（推荐中国用户）
Mac/Linux（使用 npmmirror 镜像）：
bash
curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry https://registry.npmmirror.comWindows：
powershell
iwr -useb https://clawd.org.cn/install.ps1 -OutFile install.ps1; ./install.ps1 -Registry https://registry.npmmirror.com手动安装（npm）
bash
# 全局安装 openclaw
npm install -g openclaw@latest
# 或使用 pnpm
pnpm add -g openclaw@latest
# 运行引导向导（首次使用）
openclaw onboard --install-daemon--install-daemon 参数会将 Gateway 注册为后台守护进程，开机自启。
Docker 部署
bash
# 使用官方 docker-compose
git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker-compose up -dDocker 模式适合云服务器部署，提供更好的隔离性。
Nix 部署
项目提供了 Nix 打包（openclaw/openclaw-nix），适合使用 NixOS 或 Nix 包管理的用户。
从源码构建（开发者）
bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
# 热更新开发模式
pnpm gateway:watch部署方案对比
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 本地主力机 | 日常开发者 | 访问所有本地文件 | 关机后 Agent 停止 |
| 备用机/Mac Mini | 推荐的 24/7 部署 | 始终在线，不影响主机 | 需要额外硬件 |
| 云 VPS（Linux） | 服务器部署 | 随时可访问，无硬件成本 | 无法访问本地文件 |
| 阿里云一键部署 | 国内非技术用户 | 最简单，5 分钟搞定 | 依赖厂商，有费用 |
| 腾讯云/火山引擎 | 企业用户 | 集成了权限管理 | 商业托管，数据不完全私有 |
| Docker | 开发/测试 | 隔离性好 | 无法访问宿主机文件（沙箱内） |
最佳实践 ：强烈推荐用一台备用机（或专门购置的 Mac Mini）运行 OpenClaw，与个人主机完全隔离，既能 24/7 运行，又能防止 Agent 误操作个人重要文件。
七、模型接入指南
主流模型接入一览
Anthropic Claude（推荐）
bash
openclaw onboard # 引导向导中选择 Anthropic
# 或直接配置 API Key
openclaw configure --section modelClaude 3.7 Sonnet / Claude 3.5 Sonnet 是社区最常用的模型。
支持 Claude Max 订阅 OAuth 接入（无需额外 API 费用，直接复用订阅额度）。
OpenAI GPT
配置 OPENAI_API_KEY，支持 GPT-4o、GPT-4.1、GPT-5.40（最新默认模型）等系列。
Google Gemini
支持 Gemini 2.5 Flash（免费层级）/ Gemini 2.5 Pro。
DeepSeek
中国用户常用，价格极具竞争力，支持 deepseek-chat / deepseek-reasoner。
本地模型（Ollama，完全免费）
bash
# 先安装 Ollama 并拉取模型
ollama pull llama3.3
ollama pull qwen2.5
# 在 openclaw 配置中选择 Ollama provider本地模型完全免费，但任务执行质量与商业模型有差距。
国内主流厂商接入
| 厂商 | 推荐模型 | 首月价格 | 官方文档 |
|---|---|---|---|
| 智谱 AI | GLM-5.0 / GLM-4.7-flash（免费） | 49元/月 | docs.bigmodel.cn/cn/coding-plan/tool/openclaw |
| 月之暗面 Kimi | kimi-k2 | 49元/月 | platform.moonshot.ai/docs/guide/use-kimi-in-openclaw |
| 阿里通义 | qwen-max / qwen-turbo | 7.9元/月（首月） | bailian.console.aliyun.com |
| 字节豆包 | doubao-pro | 9.9元/月 | volcengine.com/docs/82379/2183190 |
| DeepSeek | deepseek-chat | 按 Token 计费 | platform.deepseek.com |
推荐：智谱 GLM-5.0 在复杂任务上国内模型表现较好；轻量尝试选阿里首月 7.9 元套餐。
模型路由（Multi-Provider）
OpenClaw 支持配置成本路由：简单任务（如邮件分拣、心跳检查）使用廉价快速模型；复杂任务（如代码生成、长文写作）使用高能模型。
八、渠道（Channels）集成
OpenClaw 支持 50+ 消息渠道，以下为主要渠道：
内置渠道
| 渠道 | 类型 | 说明 |
|---|---|---|
| 即时通讯 | 通过 WhatsApp Web 实现，无需 Business API | |
| Telegram | 即时通讯 | 最稳定，推荐首选 |
| Discord | 即时通讯 | 支持自动线程、AI 标签 |
| Slack | 团队协作 | 支持 Slack App |
| Signal | 即时通讯 | 隐私优先 |
| iMessage（BlueBubbles） | 即时通讯 | 仅 macOS |
| Microsoft Teams | 团队协作 | v2026.3.24 全面 SDK 重写 |
| Google Chat | 即时通讯 | --- |
| Matrix | 去中心化 | --- |
| 飞书（Feishu） | 团队协作 | 国内常用，字节跳动出品 |
| 微信（WeChat） | 即时通讯 | 社区插件支持 |
| LINE | 即时通讯 | --- |
| IRC | 即时通讯 | 老牌协议 |
| Mattermost | 团队协作 | 开源 Slack 替代 |
| Nostr | 去中心化 | --- |
| Twitch | 直播 | --- |
| Zalo | 即时通讯 | 越南流行 |
| WebChat | 网页 | 内置 Web UI |
渠道配置原则
- DM 配对（Pairing）：所有渠道默认启用 DM 配对，只有经过配对授权的用户才能与 Agent 通信，防止未授权访问
- 配对命令 ：
openclaw pairing approve <channel> <CODE> - 群组配置：可配置是否需要 @mention 才触发
九、Skills 技能系统
什么是 Skill
Skill（技能） 是 OpenClaw 的扩展单元，本质上是一个包含 SKILL.md 文件的文件夹，用自然语言"教"Agent 如何完成特定任务。
关键区分：
Skills 是说明书，Tools 是手脚。
安装了 obsidian Skill，Agent 知道如何整理 Obsidian 笔记；但如果没有启用
writeTool，它没有写入权限，什么也做不了。三个条件缺一不可：配置（工具权限）+ 安装（必要桥接程序）+ 授权（账号权限）。
Skill 文件结构
skills/
└── my-skill/
├── SKILL.md # 主文件（必需）
├── scripts/ # 可选的辅助脚本
│ └── helper.py
└── resources/ # 可选的资源文件SKILL.md 格式
markdown
---
name: weather-briefing
trigger: "weather|forecast|temperature"
tools: [web-search, chat]
user-invocable: true
---
# Weather Briefing
当用户询问天气时，搜索当前天气状况，提供简洁的摘要，
包含温度、天气状况和任何天气预警。
使用 {baseDir}/scripts/weather.py 获取数据。必装基础技能推荐
| 技能名 | 功能 | 安装命令 |
|---|---|---|
browser |
浏览器自动化、网页交互和截图 | openclaw skills install browser |
desktop-control |
桌面自动化、鼠标键盘控制 | openclaw skills install desktop-control |
self-improving-agent |
自我改进，随使用次数增加自动优化执行流程 | openclaw skills install self-improving-agent |
skill-vetter |
扫描已安装技能是否存在安全风险 | openclaw skills install skill-vetter |
vector-memory |
向量记忆搜索，解决上下文过杂导致的记忆不准确 | openclaw skills install vector-memory |
subagent-driven-development |
多 Agent 任务委派，让 AI 学会把子任务分配给其他 AI | openclaw skills install subagent-driven-development |
auto-updater |
自动更新 OpenClaw 和技能 | openclaw skills install auto-updater |
openclaw-backup |
定时备份 OpenClaw 数据 | openclaw skills install openclaw-backup |
clawhub |
让 Agent 自行搜索并安装所需技能 | openclaw skills install clawhub |
4 种 Skills 安装方式
方式一：CLI（最推荐）
bash
openclaw skills install <slug>
openclaw skills install web-search方式二：ClawHub CLI
bash
npx clawhub@latest install <slug>
npx clawhub@latest install github-integration@2.1.0 # 指定版本方式三：手动安装（解压到 skills 目录）
bash
cd ~/.openclaw
# 下载并解压 skill 包到 skills/ 目录方式四：让 Agent 自己安装
直接告诉 Agent："帮我安装 XXX skill"，附上文档链接，Agent 会自己处理。
十、ClawHub 技能市场
概述
ClawHub（clawhub.com）是 OpenClaw 的官方开源技能商店，提供技能的发布、搜索、安装和更新功能。
| 指标 | 数据 |
|---|---|
| 技能总数（2026 年 3 月） | 13,729+ |
| 增长速度 | 每日新增，从 1 月的 2,857 增长至 3 月的 13,729（+380%） |
| 许可证 | 大多数为 MIT-0（免费，无需署名） |
安装 ClawHub CLI
bash
npm i -g clawhub
# 或
npx clawhub@latest install <skill-slug>技能安装目录
~/.openclaw/skills/<skill-name>/ # 默认安装位置主要技能分类
生产力类
gog：Google Workspace 全套（Gmail、Calendar、Drive、Docs、Sheets）obsidian：Obsidian 笔记库管理notion：Notion 笔记同步himalaya：邮件客户端集成
开发类
github-integration：GitHub PR、Issue、代码审查sql-toolkit：SQLite/PostgreSQL/MySQL 数据库查询docker-manager：Docker 容器管理
安全类
skill-vetter：已安装技能安全扫描openclaw-backup：数据定时备份
自动化类
web-search（Tavily）：联网搜索，解决 AI 闭眼瞎编问题browser-automation：浏览器自动化cron-workflows：高级定时任务管理
个人助理类
moltbook：AI 社交网络集成news-aggregator：新闻聚合与摘要calendar-sync：日历管理
2026 年安全危机与应对
2026 年 2 月，安全研究人员发现 ClawHub 上存在 1,467 个恶意技能（约占当时总量 3%），其中 91% 结合了提示词注入（Prompt Injection）与传统恶意软件技术。受影响的部署估计达 200,000+ 个实例。
ClawHub 的应对措施：
- 接入 VirusTotal 自动扫描（2026 年 2 月起）
- 下架所有已识别的恶意技能
- 引入作者验证徽章
- 新提交要求代码签名
- 最低账号年龄限制（一周）
十一、Tools 工具系统
Tools 是 Agent 真正的"手脚"，控制 Agent 能做什么、不能做什么。
内置工具（26 个）
文件系统类
| 工具 | 说明 |
|---|---|
read |
读取文件 |
write |
写入/修改文件 |
list |
列出目录内容 |
search |
文件内容搜索 |
执行类
| 工具 | 说明 | 风险等级 |
|---|---|---|
exec |
运行 Shell 命令（最强大也最危险） | 🔴 高 |
script |
执行脚本文件 | 🟡 中 |
sandbox |
Docker 隔离执行 | 🟢 低 |
ssh |
SSH 远程执行（v2026.3.24 新增） | 🟡 中 |
网络类
| 工具 | 说明 |
|---|---|
web_search |
网页搜索（需配置 Tavily/Google API） |
web_fetch |
读取网页内容 |
browser |
完整浏览器控制（CDP 协议，支持点击、表单、截图） |
消息类
| 工具 | 说明 |
|---|---|
chat |
向用户发送消息 |
notify |
推送通知 |
媒体类（Node，macOS/iOS/Android 特有）
| 工具 | 说明 |
|---|---|
camera |
调用摄像头拍照 |
screen_record |
录制屏幕 |
location |
获取 GPS 位置 |
Tools 配置示例
json
{
"tools": {
"allow": ["read", "write", "web_search", "web_fetch", "chat"],
"deny": ["exec", "browser"],
"require_approval": ["script"]
}
}require_approval：让 Agent 在执行 Shell 命令前先向用户请示确认，大幅提升安全性。
十二、记忆系统与上下文管理
Context（上下文）vs Memory（记忆）
| 维度 | Context（上下文） | Memory（记忆） |
|---|---|---|
| 存储位置 | 模型的 Token 窗口（临时） | 本机磁盘文件（持久） |
| 生命周期 | 会话结束即消失 | 永久保存，重启后仍在 |
| 操作方 | 由系统自动管理 | 由 Agent 自动写入，用户可编辑 |
| 格式 | 临时 Token | Markdown 纯文本 |
核心洞察：上下文会遗忘，记忆会持续。OpenClaw 通过让 Agent 把重要信息写入文件来解决 LLM 无状态的根本问题。
记忆文件体系
~/.openclaw/workspace/
├── SOUL.md # 人格（你写）
├── AGENTS.md # 操作规范（你写）
├── IDENTITY.md # 身份标识（你写）
├── USER.md # 用户档案（你写，稳定）
├── HEARTBEAT.md # 定时任务（你写）
├── MEMORY.md # 长期记忆（Agent 写）
├── TOOLS.md # 本地工具说明（你写）
└── memory/
├── 2026-01-26.md # 当日追加日志
├── 2026-01-27.md
└── ...向量记忆系统
OpenClaw 在记忆文件上构建了混合搜索索引：
Markdown 文件
→ 分块（~400 tokens，80 token 重叠）
→ 嵌入（OpenAI / Gemini / 本地 GGUF）
→ SQLite 存储（可选 sqlite-vec 加速）
→ 文件监听（防抖 1.5 秒，增量更新）检索时同时使用：
- 向量相似度：语义匹配（"Mac Studio 网关主机" 匹配 "运行网关的机器"）
- BM25 关键词匹配：精确匹配（ID、代码符号、错误字符串）
- 综合评分 ：
finalScore = vectorWeight × vectorScore + textWeight × textScore
记忆加载策略
每次会话，OpenClaw 采用 "今天 + 昨天" 的加载模式：
- 始终加载今天的日志（追加写，保证完整性）
- 加载昨天的日志（最近上下文）
- 对于更早的记忆，通过向量搜索按需检索
这种策略最大限度减少上下文膨胀，同时保留记忆的连续性。
十三、Heartbeat 心跳机制
原理
心跳是让 OpenClaw 从"被动工具"变成"主动助手"的关键机制：
- Gateway 每 30 分钟自动向 Agent 发送一条检查消息
- Agent 读取 HEARTBEAT.md，判断是否有待办任务
- 有任务：执行并汇报
- 无任务：返回
HEARTBEAT_OK，系统静默（不打扰用户）
HEARTBEAT_OK 抑制模式的设计精妙之处：用户不会被无意义的"检查完毕"通知淹没，心跳对用户几乎是无感的，但 Agent 却始终在线。
配置要点
markdown
# 好的写法（精确时间）
每天 6:45 AM：发送早间天气和日历摘要
# 不好的写法（模糊）
每天早上：发送摘要
# 有条件触发
当 GitHub 有新 PR 时，在 5 分钟内通知我并附上摘要
# 周期性维护
每周日 23:00：整理本周记忆文档，压缩冗余信息心跳频率优化
默认 30 分钟心跳会产生一定的 Token 消耗（据估算若不优化，可达每日 570,000 input tokens）。优化方案：
- 对心跳使用廉价快速模型（如 Gemini Flash、GLM-4.7-flash）
- 减少 HEARTBEAT.md 中的任务密度
- 避免在每次心跳中加载大量上下文
十四、安全风险与最佳实践
主要安全风险
OpenClaw 因其强大的系统访问能力，面临多种安全威胁：
1. 提示词注入（Prompt Injection）
Agent 读取任何含有恶意指令的内容（网页、文档、邮件）后，可能被操纵执行非预期操作。
2. 恶意 Skill
来源不明的 Skill 可能：
- 上传本地文件到非法云端
- 窃取 API Key 和 Cookie
- 执行恶意 Shell 命令
3. 端口暴露风险
Gateway 默认监听 18789 端口，如果暴露到公网，任何人都能控制你的 Agent。
4. 惯性滥权（Credential Sprawl）
~/.openclaw/ 目录下以明文存储的配置中可能包含大量 API Key，是信息窃取恶意软件的标准目标。
安全加固清单
网络层
bash
# 将 Gateway 绑定到本地环回地址（绝不暴露到公网）
# 在配置文件中设置：gateway.bind: "loopback"
# 远程访问使用 SSH 隧道（推荐）
ssh -L 18789:localhost:18789 user@your-server
# 或使用 Tailscale Serve（仅内网可见）工具权限
json
// 最小权限原则：只开放必要的 Tools
{
"tools": {
"allow": ["read", "write", "web_search", "chat"],
"require_approval": ["exec", "script", "browser"] // 高风险操作需审批
}
}Skill 安装
- 只从 ClawHub 安装有 VirusTotal 扫描通过标记的技能
- 安装前阅读 SKILL.md 全文，检查是否有可疑的提示词指令
- 检查 scripts/ 目录中是否有
curl | bash之类的可疑操作 - 优先选择有 GitHub 源码、install 量多的知名技能
- 安装后运行
skill-vetter扫描
DM 配对
bash
# 为每个渠道设置配对，只允许已知用户通信
openclaw pairing approve telegram YOUR_PAIRING_CODE
# 保持 allowlist（白名单）最小化沙箱执行
bash
# 启用 Docker 沙箱（不信任的代码在容器内执行）
# 配置 tools.sandbox: "docker"定期维护
bash
# 健康检查 + 自动修复配置问题
openclaw doctor --repair
# 安全审计
openclaw security audit国家安全部"养龙虾"安全手册（2026 年 3 月）
2026 年 3 月 17 日，国家安全部专门发布了 OpenClaw 安全使用指南，建议：
- 不将 OpenClaw 默认管理端口直接暴露在公网
- 对运行环境进行严格隔离，使用容器技术限制权限
- 防范社会工程学攻击和浏览器劫持
- 定期检查并修补漏洞，关注官方安全公告
- 不禁用详细日志审计功能
十五、多智能体与子代理
多 Agent 架构
同一个 Gateway 可以运行多个相互隔离的 Agent，每个 Agent 有独立的：
- 身份（IDENTITY.md）
- 记忆（MEMORY.md）
- 技能集合
- 上下文
Multi-Agent 路由配置：
- 每个 Agent 有唯一的 Emoji 标识
- 消息通过
@mention路由到指定 Agent - Agent 之间可以互发消息（Agent-to-Agent 通信）
子代理驱动开发（Subagent-Driven Development）
通过 subagent-driven-development Skill，主 Agent 可以把复杂任务分解后委派给多个子 Agent 并行处理：
主 Agent（Manager）
├── 子 Agent A：负责前端开发
├── 子 Agent B：负责后端开发
└── 子 Agent C：负责测试验证主 Agent 负责任务分配和审核，子 Agent 负责执行，实现真正的 AI 团队协作。
ACP/ACPX 协议
OpenClaw 实现了 ACP（Agent Communication Protocol），允许与 Claude Code、Cursor、Codex 等其他 Agent 工具进行标准化通信和协作。
十六、常用 CLI 命令速查
bash
# ── 安装与初始化 ──
npm install -g openclaw@latest # 全局安装
openclaw onboard --install-daemon # 首次引导配置
openclaw onboard --auth-choice modelstudio-api-key # 指定认证方式
# ── Gateway 管理 ──
openclaw gateway start # 启动网关
openclaw gateway stop # 停止网关
openclaw gateway restart # 重启（配置变更后）
openclaw gateway status # 查看运行状态
# ── 配置管理 ──
openclaw configure # 打开配置向导
openclaw configure --section model # 配置模型
openclaw configure --section web # 配置 Web 搜索
openclaw doctor # 健康检查
openclaw doctor --repair # 自动修复配置问题
openclaw doctor --non-interactive # 非交互模式（CI/CD 使用）
# ── Skills 管理 ──
openclaw skills install <slug> # 安装技能
openclaw skills list # 列出已安装技能
openclaw skills update <slug> # 更新指定技能
openclaw skills update --all # 更新所有技能
openclaw skills uninstall <slug> # 卸载技能
openclaw skills search <keyword> # 搜索 ClawHub 技能
# ── ClawHub CLI（独立工具）──
npx clawhub@latest install <slug> # 安装技能
npx clawhub@latest install <slug>@<version> # 安装指定版本
clawhub list # 列出已安装
clawhub update --all # 更新所有
clawhub inspect <slug> # 查看技能内容（安装前验证）
clawhub publish <path> # 发布自己的技能
# ── 渠道配对 ──
openclaw pairing approve telegram CODE # 批准 Telegram 配对
openclaw pairing approve discord CODE # 批准 Discord 配对
# ── 日志与调试 ──
openclaw logs --follow # 实时查看日志
openclaw security audit # 安全审计
# ── 更新 ──
npm update -g openclaw # 更新 OpenClaw 到最新版十七、生态系统与衍生项目
官方相关仓库（github.com/openclaw 组织）
| 仓库 | 说明 |
|---|---|
openclaw/openclaw |
核心主仓库（TypeScript，342k Stars） |
openclaw/openclaw.ai |
官方网站（GitHub Pages 托管） |
openclaw/openclaw-nix |
Nix 包 |
openclaw/openclaw-windows-node |
Windows 伴侣套件（系统托盘、PowerToys 扩展） |
openclaw/acpx |
Agent Communication Protocol 扩展 |
openclaw/lobster |
Lobster 工作流 Shell（类型安全的本地优先宏引擎） |
社区衍生项目
| 项目 | 特点 |
|---|---|
| Moltbook | AI Agent 专属社交网络，由 Matt Schlicht 创立，随 OpenClaw 爆红 |
| NanoClaw | 极简版（~700 行 TypeScript），容器隔离，安全性更好 |
| ZeroClaw | Rust 重写版（150,000 行），3.4MB 二进制，<10ms 启动，支持 17+ 渠道 |
| Nanobot | Python 版本（~4,000 行），轻量 |
| Symphony | 将项目工作转为隔离的自主实现运行 |
| openclaw-pm | 项目管理配置工具，含心跳、记忆刷新、健康检查 |
第三方集成生态
- 腾讯 WorkBuddy：腾讯基于 OpenClaw 推出的企业版（兼容微信）
- 火山引擎 ArkClaw：字节跳动推出的云上 SaaS 版 OpenClaw
- Kimi Claw：月之暗面推出的 Kimi 应用内 OpenClaw 集成
- VoltAgent/awesome-openclaw-skills：精选 5,000+ ClawHub 技能的 GitHub 列表
十八、国内生态与厂商支持
云厂商部署服务
| 厂商 | 服务名 | 特点 |
|---|---|---|
| 阿里云 | 一键部署专题页 | 最简单，约 5 分钟完成 |
| 腾讯云 | 智能体开发平台 | 集成企业级权限管理、安全审核 |
| 火山引擎（字节） | ArkClaw | 开箱即用 SaaS，含飞书集成 |
| 佛山禅城区 | 政府免费部署服务 | 面向公众免费部署 |
政策支持（2026 年 3 月）
- 无锡高新区：12 条支持政策，单项最高 500 万元
- 常熟市：13 条举措，最高 600 万元综合支持
- 南京栖霞高新区：研发投入 20% 补贴，单项最高 100 万元
- 佛山禅城区：联合中国电信提供免费部署服务
国内安全限制
2026 年 3 月，中国政府限制党政机关和国有企业在办公电脑上运行 OpenClaw 相关 AI 应用，理由是数据安全风险（OpenClaw 本身并未被完全禁止）。
国内使用建议
- 优先使用阿里云、腾讯云等国内厂商提供的一键部署服务
- 模型选择国内合规模型（通义千问、智谱 GLM 等）
- 避免将 OpenClaw 连接到敏感业务系统
- 参考国家安全部发布的"养龙虾"安全手册
十九、与竞品对比分析
OpenClaw vs 主流 AI 助手
| 维度 | OpenClaw | ChatGPT/Claude | Manus/同类云 Agent |
|---|---|---|---|
| 数据存储 | 本地磁盘 | 云端 | 云端 |
| 隐私性 | 极高 | 低（数据上传） | 低 |
| 主动性 | 有（心跳机制） | 无（被动响应） | 有 |
| 本地文件访问 | 完整访问 | 无 | 无 |
| 扩展性 | 极强（Skills） | 有限（Plugins） | 有限 |
| 硬件要求 | 需本地服务器 | 无 | 无 |
| 使用门槛 | 中高（需命令行） | 低 | 中 |
| 费用 | 仅 API 费用（软件免费） | 订阅费 | 订阅费 |
OpenClaw vs 同类开源项目
| 项目 | 架构 | 特点 | 适合场景 |
|---|---|---|---|
| OpenClaw | TypeScript，本地优先 | 功能最全，生态最大，社区活跃 | 重度用户，需要完整功能 |
| Auto-GPT | Python，云端为主 | 先驱项目，但已被超越 | 开发研究 |
| BabyAGI | Python，轻量 | 任务分解先驱，功能简单 | 学习研究 |
| NanoClaw | TypeScript，700 行 | 极简，容器隔离 | 安全要求高的简单场景 |
| ZeroClaw | Rust，超轻量 | 3.4MB，<10ms 启动 | 资源受限设备 |
二十、常见问题与排错
Q：Bot 不响应消息
bash
# 检查 Gateway 是否运行
openclaw gateway status
# 查看实时日志
openclaw logs --follow
# 检查渠道配对是否已审批
openclaw pairing approve telegram YOUR_CODEQ：API 费用异常飙升
原因：心跳过于频繁或 HEARTBEAT.md 任务过重
解决：
- 为心跳任务配置廉价模型（如 Gemini Flash）
- 减少 HEARTBEAT.md 中的任务密度
- 检查是否有失控的定时任务
Q：Browser 自动化崩溃
原因：内存不足
解决：升级 VPS 到至少 8GB RAM（Chrome 实例需要额外内存）
Q：Plugin 安装失败
bash
# 清除 npm 缓存
npm cache clean --force
# 使用 ClawHub 原生安装替代 npm
openclaw skills install <slug>Q：Windows 安装问题
powershell
# 需要以管理员身份运行 PowerShell
# 如遇权限错误，右键 PowerShell → 以管理员身份运行Q：中国网络环境下安装慢
bash
# 使用 npmmirror 镜像
curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry https://registry.npmmirror.comQ：配置文件损坏/迁移失败
bash
openclaw doctor --repair # 自动修复
# 注意：v2026.3.22 起超过两个月的旧配置不再自动迁移，需手动处理Q：如何卸载 OpenClaw
bash
# macOS/Linux
npm uninstall -g openclaw
rm -rf ~/.openclaw/ # 删除工作区（谨慎！含记忆数据）
# Windows
npm uninstall -g openclaw
# 删除 %USERPROFILE%\.openclaw\ 文件夹二十一、学习资源汇总
官方资源
| 资源 | 链接 |
|---|---|
| 官方网站 | https://openclaw.ai |
| 官方文档 | https://docs.openclaw.ai |
| 中文文档 | https://docs.openclaw.ai/zh-CN |
| GitHub 主仓库 | https://github.com/openclaw/openclaw |
| ClawHub 技能市场 | https://clawhub.com |
| DeepWiki（AI 生成的代码知识库） | https://deepwiki.com/openclaw/openclaw |
| 官方 Discord | https://discord.gg/openclaw |
| 项目愿景 | https://github.com/openclaw/openclaw/blob/main/VISION.md |
| 更新日志 | https://github.com/openclaw/openclaw/releases |
国内中文社区
| 资源 | 链接 |
|---|---|
| 国内中文安装镜像 | https://clawd.org.cn |
| 中文教程聚合 | https://awesome.tryopenclaw.asia |
| 学习资源聚合 | https://openclaw101.dev/zh |
| 精选 Skill 清单 | https://github.com/VoltAgent/awesome-openclaw-skills |
国内云厂商官方部署文档
| 厂商 | 文档 |
|---|---|
| 阿里云百炼 | https://bailian.console.aliyun.com（搜索 OpenClaw） |
| 智谱 AI | https://docs.bigmodel.cn/cn/coding-plan/tool/openclaw |
| 月之暗面 Kimi | https://platform.moonshot.ai/docs/guide/use-kimi-in-openclaw |
| 字节火山引擎 | https://www.volcengine.com/docs/82379/2183190 |
推荐阅读
- 架构深度解析（英文）：https://rajvijayaraj.substack.com/p/openclaw-architecture-a-deep-dive
- 技术深潜 Medium（英文）：https://medium.com/@dingzhanjun/deep-dive-into-openclaw-architecture-code-ecosystem-e6180f34bd07
- GitHub Gist 架构文档：https://gist.github.com/royosherove/971c7b4a350a30ac8a8dad41604a95a0
- Tools & Skills 完整解析（英文）：https://yu-wenhao.com/en/blog/openclaw-tools-skills-tutorial/
- 百度百科（中文，含国内事件）：https://baike.baidu.com/item/OpenClaw/67313290
- Wikipedia（英文，含历史）：https://en.wikipedia.org/wiki/OpenClaw
附录：关键术语对照表
| 英文术语 | 中文 | 说明 |
|---|---|---|
| Gateway | 网关 | OpenClaw 的核心控制平面，长驻进程 |
| Agent | 智能体 / 代理 | 基于 LLM 的任务执行单元 |
| Skill | 技能 | 用 Markdown 定义的能力扩展模块 |
| Tool | 工具 | Agent 的实际执行能力（文件读写、命令执行等） |
| Channel | 渠道 | 消息平台集成（WhatsApp、Telegram 等） |
| Heartbeat | 心跳 | 30 分钟一次的主动自检机制 |
| Soul | 灵魂 | Agent 的人格设定文件（SOUL.md） |
| Memory | 记忆 | 跨会话持久化的知识文件 |
| ClawHub | 技能市场 | OpenClaw 官方技能注册中心 |
| Onboard | 引导 | 首次配置向导（openclaw onboard） |
| Sandbox | 沙箱 | 隔离执行环境（Docker 容器） |
| DM Pairing | DM 配对 | 渠道用户授权机制 |
| ACP/ACPX | 代理通信协议 | Agent 间标准化通信协议 |
| Prompt Injection | 提示词注入 | 通过内容欺骗 Agent 执行恶意指令的攻击 |