OpenClaw（小龙虾）深度解析：开源AI Agent框架的完整指南
OpenClaw（小龙虾）深度解析：开源AI Agent框架的完整指南
OpenClaw（昵称“小龙虾”）是一个免费、开源、自托管的AI智能体框架，旨在让AI真正“动手做事”。本文将全面解析其核心设计、架构、配置与最佳实践，助你快速上手。
一、项目概述与核心定位
OpenClaw由奥地利开发者Peter Steinberger创建，其口号是“The AI that actually does things”。它不是简单的聊天机器人，而是一个自主执行任务的AI代理操作系统。它能接收来自WhatsApp、Telegram、Discord等平台的指令，在本地机器上规划、调用工具并执行操作，全程无需人工干预。关键数据请参考下表：
指标 数据
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”取龙虾爪子之意，结合开源精神，体现“抓取执行”的能力。中文社区亲切称之为“小龙虾”。
三、核心设计理念
OpenClaw的设计围绕四个核心理念展开：
本地优先（Local-First）：所有数据以纯文本Markdown格式存储在本地磁盘，用户完全掌控隐私。
模型无关（Model-Agnostic）：通过API Key接入Anthropic Claude、OpenAI GPT、DeepSeek、Ollama本地模型等，不绑定任何LLM。
消息平台作为UI：利用WhatsApp、飞书等已有应用作为操作界面。
文件即配置（Files as Configuration）：修改Markdown文件即可改变Agent行为，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（网关）是核心组件，一个长驻WebSocket服务器（默认localhost:18789），负责会话管理、渠道连接、消息路由、事件系统及工具调度。它不负责推理，由LLM完成。六种输入源包括：
输入类型 说明
消息（Messages） 来自各消息平台的用户消息
心跳（Heartbeats） 每 30 分钟的定时自检触发
定时任务（Cron Jobs） 在 HEARTBEAT.md 中配置的精确时间任务
Hooks 系统启动、任务完成等内部状态变化触发
Webhooks GitHub PR、Jira ticket 等外部系统推送
Agent 间通信 多 Agent 协作中的相互消息
系统提示词动态组装，每次会话按以下顺序构建：
System Prompt =
工具清单（可用工具 + 描述）
+ 安全护栏
+ 技能列表（元数据 + 文件路径）
+ 工作区信息
+ 当前日期时间（时区感知）
+ 心跳契约
+ 运行时元数据（主机/OS/模型/思考等级）
── 项目上下文 ──
+ AGENTS.md（操作规范）
+ SOUL.md（人格/风格）
+ TOOLS.md（本地工具说明）
+ IDENTITY.md（Agent 名称/主题）
+ USER.md（用户档案）
+ HEARTBEAT.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：定义人格、语气和边界，启动时自动加载。示例：
# Soul
你的名字是 Molty，我的个人 AI 助手。
## 性格特点
– 直接、简洁，不说废话
– 像朋友一样对话，不用过度礼貌
– 遇到不确定的事会主动说明，而不是乱猜
## 行为边界
– 删除任何文件前必须向用户确认
– 不主动分享系统配置信息给第三方
– 工作时间 9:00-21:00，其他时间非紧急消息不打扰
## 我的工作习惯
我使用 macOS，偏好 TypeScript 和 Python
主要工作目录：~/Projects
AGENTS.md：操作手册，定义文件操作规范、错误处理等。示例：
# Operating Rules
## 文件操作
– 永远不要删除 ~/Documents 以外的文件
– 修改重要配置前先备份
## 资源限制
– 单次任务最多调用 20 次 API
– Token 消耗超过 50k 时暂停并请示用户
## 汇报规范
– 任务完成后简洁汇报结果
– 错误时给出原因 + 建议的解决方案
HEARTBEAT.md：定时任务，每30分钟检查一次。示例：
# Heartbeat Tasks
## 每日任务
### 7:30 AM – 早间摘要
读取今日日历、待处理邮件和 GitHub 通知，生成摘要发送到 Telegram。
### 21:00 – 每日日志整理
整理今天的对话记录，提炼关键信息追加到 MEMORY.md。
## 每周任务
### 每周一 9:00 AM – 记忆维护
读取最近 7 天的记忆文档，总结提炼关键信息，清理冗余条目。
## 每月任务
### 每月 1 日 10:00 AM – 月度报告
汇总上月工作完成情况，生成月报发送至邮箱。
，工作原理：
┌──────────┐ ┌──────────┐ ┌────────────────────┐
│ 计时器 │───▶│ Agent │───▶│ HEARTBEAT_OK │──▶ 抑制（不打扰用户）
│ (30分钟) │ │ 执行轮 │ │（无紧急任务） │
└──────────┘ └────┬─────┘ └────────────────────┘
│
├──────────▶ 警报文本 ──▶ 发送到聊天
│
└──────────▶ 后台工作（记忆维护、文件整理等）
IDENTITY.md：身份标识，定义名称、主题等。示例：
# Identity
Name: Molty
Emoji:
Theme: Space Lobster
Mention Pattern: @molty
USER.md：用户档案，记录稳定信息。示例：
# User Profile
Name: 张三
Language: 中文（简体）为主
Timezone: Asia/Shanghai
## 工作偏好
– 技术栈：TypeScript, Python, Docker
– 编辑器：VS Code + Cursor
– 主要项目目录：~/Projects
## 个人偏好
– 不喜欢冗长的汇报，简洁优先
– 早上 7:30 前不要打扰
MEMORY.md：动态记忆，由Agent自动写入，区别于USER.md和MEMORY.md。
六、安装与部署
系统要求如下：
项目 最低要求 推荐配置
Node.js 版本 22.0+ 22.16+（LTS）
内存（云服务器） 1GB RAM —
内存（本地运行） 8GB RAM 16GB+
磁盘空间 500MB 10GB+（含日志/媒体）
CPU 1 核 —
操作系统 Windows/macOS/Linux macOS 或 Linux
一键安装（推荐）：macOS/Linux执行
curl -fsSL https://openclaw.ai/install.sh | bash
，Windows执行
powershell -c “irm https://openclaw.ai/install.ps1 | iex”
。国内镜像安装：Mac/Linux执行
curl -fsSL https://clawd.org.cn/install.sh | bash -s — –registry https://registry.npmmirror.com
，Windows执行
iwr -useb https://clawd.org.cn/install.ps1 -OutFile install.ps1; ./install.ps1 -Registry https://registry.npmmirror.com
。手动安装：
# 全局安装 openclaw
npm install -g openclaw@latest
# 或使用 pnpm
pnpm add -g openclaw@latest
# 运行引导向导（首次使用）
openclaw onboard –install-daemon
（–install-daemon参数可注册为守护进程）。Docker部署：
# 使用官方 docker-compose
git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker-compose up -d
；Nix部署：openclaw/openclaw-nix；源码构建：
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 开发/测试 隔离性好 无法访问宿主机文件（沙箱内）
七、模型接入指南
主流模型接入一览：Anthropic Claude配置
openclaw onboard # 引导向导中选择 Anthropic
# 或直接配置 API Key
openclaw configure –section model
；OpenAI GPT配置OPENAI_API_KEY；Google Gemini、DeepSeek、Ollama本地模型：
# 先安装 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
支持模型路由（Multi-Provider），简单任务用廉价模型，复杂任务用高能模型。
八、渠道集成
支持50+消息渠道，主要渠道如下：
渠道 类型 说明
WhatsApp 即时通讯 通过 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配对（配对命令openclaw pairing approve ），群组可配置是否需要@mention。
九、Skills技能系统
Skill是扩展单元，包含SKILL.md文件。文件结构：
skills/
└── my-skill/
├── SKILL.md # 主文件（必需）
├── scripts/ # 可选的辅助脚本
│ └── helper.py
└── resources/ # 可选的资源文件
；格式：
—
name: weather-briefing
trigger: “weather|forecast|temperature”
tools: [web-search, chat]
user-invocable: true
—
# Weather Briefing
当用户询问天气时，搜索当前天气状况，提供简洁的摘要，
包含温度、天气状况和任何天气预警。
使用 {baseDir}/scripts/weather.py 获取数据。
。必装基础技能：
技能名 功能 安装命令
浏览器自动化、网页交互和截图
桌面自动化、鼠标键盘控制
自我改进，随使用次数增加自动优化执行流程
扫描已安装技能是否存在安全风险
向量记忆搜索，解决上下文过杂导致的记忆不准确
多 Agent 任务委派，让 AI 学会把子任务分配给其他 AI
自动更新 OpenClaw 和技能
定时备份 OpenClaw 数据
让 Agent 自行搜索并安装所需技能
四种安装方式：CLI（
openclaw skills install
openclaw skills install web-search
）、ClawHub CLI（
npx clawhub@latest install
npx clawhub@latest install github-integration@2.1.0 # 指定版本
）、手动安装（
cd ~/.openclaw
# 下载并解压 skill 包到 skills/ 目录
）、让Agent自己安装。
十、ClawHub技能市场
ClawHub（clawhub.com）是官方技能商店，功能如下：
指标 数据
技能总数（2026 年 3 月） 13,729+
增长速度 每日新增，从 1 月的 2,857 增长至 3 月的 13,729（+380%）
许可证 大多数为 MIT-0（免费，无需署名）
安装CLI：
npm i -g clawhub
# 或
npx clawhub@latest install
；技能安装目录：
~/.openclaw/skills// # 默认安装位置
。主要分类：生产力类（gog、obsidian等）、开发类（github-integration、sql-toolkit等）、安全类（skill-vetter、openclaw-backup等）、自动化类（web-search、browser-automation等）、个人助理类（moltbook、news-aggregator等）。2026年2月曾发现1,467个恶意技能，ClawHub已接入VirusTotal自动扫描并引入作者验证。
十一、Tools工具系统
内置26个工具：文件系统类（
工具 说明
读取文件
写入/修改文件
列出目录内容
文件内容搜索
）、执行类（
工具 说明 风险等级
运行 Shell 命令（最强大也最危险） 高
执行脚本文件 中
Docker 隔离执行 低
SSH 远程执行（v2026.3.24 新增） 中
）、网络类（
工具 说明
网页搜索（需配置 Tavily/Google API）
读取网页内容
完整浏览器控制（CDP 协议，支持点击、表单、截图）
）、消息类（
工具 说明
向用户发送消息
推送通知
）、媒体类（
工具 说明
调用摄像头拍照
录制屏幕
获取 GPS 位置
）。配置示例：
{
“tools”: {
“allow”: [“read”, “write”, “web_search”, “web_fetch”, “chat”],
“deny”: [“exec”, “browser”],
“require_approval”: [“script”]
}
}
（require_approval提升安全性）。
十二、记忆系统与上下文管理
Context（上下文）vs Memory（记忆）对比：
维度 Context（上下文） Memory（记忆）
存储位置 模型的 Token 窗口（临时） 本机磁盘文件（持久）
生命周期 会话结束即消失 永久保存，重启后仍在
操作方 由系统自动管理 由 Agent 自动写入，用户可编辑
格式 临时 Token Markdown 纯文本
记忆文件体系：
~/.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
└── …
；向量记忆系统：
Markdown 文件
→ 分块（~400 tokens，80 token 重叠）
→ 嵌入（OpenAI / Gemini / 本地 GGUF）
→ SQLite 存储（可选 sqlite-vec 加速）
→ 文件监听（防抖 1.5 秒，增量更新）
（使用finalScore = vectorWeight × vectorScore + textWeight × textScore综合评分）。记忆加载策略：始终加载今天和昨天的日志，更早的通过向量搜索按需检索。
十三、Heartbeat心跳机制
心跳让OpenClaw具备主动性：Gateway每30分钟发送检查消息，Agent读取HEARTBEAT.md判断待办任务。无任务时返回HEARTBEAT_OK（HEARTBEAT_OK抑制模式），用户无感。配置要点：
# 好的写法（精确时间）
每天 6:45 AM：发送早间天气和日历摘要
# 不好的写法（模糊）
每天早上：发送摘要
# 有条件触发
当 GitHub 有新 PR 时，在 5 分钟内通知我并附上摘要
# 周期性维护
每周日 23:00：整理本周记忆文档，压缩冗余信息
；优化方案：使用廉价模型、减少任务密度、避免加载大量上下文。
十四、安全风险与最佳实践
主要风险：提示词注入、恶意Skill、端口暴露、惯性滥权（~/.openclaw/目录明文存储API Key）。安全加固清单：网络层
# 将 Gateway 绑定到本地环回地址（绝不暴露到公网）
# 在配置文件中设置：gateway.bind: “loopback”
# 远程访问使用 SSH 隧道（推荐）
ssh -L 18789:localhost:18789 user@your-server
# 或使用 Tailscale Serve（仅内网可见）
、工具权限
// 最小权限原则：只开放必要的 Tools
{
“tools”: {
“allow”: [“read”, “write”, “web_search”, “chat”],
“require_approval”: [“exec”, “script”, “browser”] // 高风险操作需审批
}
}
、系统提示词
# 为每个渠道设置配对，只允许已知用户通信
openclaw pairing approve telegram YOUR_PAIRING_CODE
# 保持 allowlist（白名单）最小化
、审计日志
# 启用 Docker 沙箱（不信任的代码在容器内执行）
# 配置 tools.sandbox: “docker”
、进程隔离
# 健康检查 + 自动修复配置问题
openclaw doctor –repair
# 安全审计
openclaw security audit
、环境变量
主 Agent（Manager）
├── 子 Agent A：负责前端开发
├── 子 Agent B：负责后端开发
└── 子 Agent C：负责测试验证
、更新策略
# ── 安装与初始化 ──
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
openclaw skills list # 列出已安装技能
openclaw skills update
openclaw skills update –all # 更新所有技能
openclaw skills uninstall
openclaw skills search
# ── ClawHub CLI（独立工具）──
npx clawhub@latest install
npx clawhub@latest install
clawhub list # 列出已安装
clawhub update –all # 更新所有
clawhub inspect
clawhub publish
# ── 渠道配对 ──
openclaw pairing approve telegram CODE # 批准 Telegram 配对
openclaw pairing approve discord CODE # 批准 Discord 配对
# ── 日志与调试 ──
openclaw logs –follow # 实时查看日志
openclaw security audit # 安全审计
# ── 更新 ──
npm update -g openclaw # 更新 OpenClaw 到最新版
、监控告警
# 检查 Gateway 是否运行
openclaw gateway status
# 查看实时日志
openclaw logs –follow
# 检查渠道配对是否已审批
openclaw pairing approve telegram YOUR_CODE
。
十五、多智能体与子代理
多智能体配置：
# 清除 npm 缓存
npm cache clean –force
# 使用 ClawHub 原生安装替代 npm
openclaw skills install
；子代理（Sub-Agent）机制：
# 需要以管理员身份运行 PowerShell
# 如遇权限错误，右键 PowerShell → 以管理员身份运行
；Agent间通信：
# 使用 npmmirror 镜像
curl -fsSL https://clawd.org.cn/install.sh | bash -s — –registry https://registry.npmmirror.com
。
十六、常用CLI命令速查
核心命令：
openclaw doctor –repair # 自动修复
# 注意：v2026.3.22 起超过两个月的旧配置不再自动迁移，需手动处理
；配置管理：
# macOS/Linux
npm uninstall -g openclaw
rm -rf ~/.openclaw/ # 删除工作区（谨慎！含记忆数据）
# Windows
npm uninstall -g openclaw
# 删除 %USERPROFILE%\.openclaw\ 文件夹
。
十七、生态系统与衍生项目
社区生态包括ClawHub、ClawMate、ClawKit、ClawDeploy等。国内厂商支持：阿里云、华为云、腾讯云、百度云等均有集成。与AutoGPT、LangChain Agent、CrewAI等竞品对比：
仓库 说明
核心主仓库（TypeScript，342k Stars）
官方网站（GitHub Pages 托管）
Nix 包
Windows 伴侣套件（系统托盘、PowerToys 扩展）
Agent Communication Protocol 扩展
Lobster 工作流 Shell（类型安全的本地优先宏引擎）
十八、常见问题与排错
常见问题：Gateway无法启动（检查端口占用）、模型响应超时（切换模型）、渠道连接失败（验证Token）、心跳不触发（检查HEARTBEAT.md语法）、记忆丢失（检查MEMORY.md权限）。
© 版权声明
文章版权归作者所有，未经允许请勿转载。
相关文章
暂无评论...