概念
适用于任何操作系统的 AI 智能体 Gateway 网关,支持 WhatsApp、Telegram、Discord、iMessage 等。 发送消息,随时随地获取智能体响应。通过插件可添加 Mattermost 等更多渠道。
源码目录
openclaw/
├── AGENTS.md # 🤖 AI代理/系统说明(类似设计文档)
├── CLAUDE.md -> AGENTS.md # 👉 软链接(给 Claude/AI 用的说明)
├── VISION.md # 🧭 项目愿景(了解架构思想用)
├── CHANGELOG.md # 📜 更新记录
├── CONTRIBUTING.md # 👨💻 贡献指南
├── LICENSE # 📄 开源协议
├── SECURITY.md # 🔐 安全策略
├── README.md # 📘 入口文档(建议精读)
├── docs/ # 📚 详细文档
├── docs.acp.md # 🧠 ACP(Agent Control Protocol?)说明
├── apps/ # 🚀 【核心】应用层(入口!!!)
│ # 👉 前端 / 后端 / 网关 都在这里
│ # 👉 等你 ls apps 后重点分析
├── packages/ # 📦 公共库(类似 framework 层)
│ # 👉 各个 app 共享代码
│ # 👉 比如 API 封装 / utils
├── ui/ # 🎨 UI组件库(React组件)
│ # 👉 Button / Chat UI / Layout
│ # 👉 Panel 的“外观”
├── src/ # 🧠 核心逻辑(可能是服务端 or SDK)
│ # 👉 有时是核心 runtime / agent逻辑
├── extensions/ # 🔌 插件系统(扩展能力)
│ # 👉 类似 ChatGPT plugin
├── skills/ # 🧠 AI技能(Agent能力定义)
│ # 👉 很关键(AI行为逻辑)
├── vendor/ # 📦 第三方代码(内置依赖)
├── assets/ # 🖼️ 静态资源(图片 / 图标)
├── test/ # 🧪 测试代码
├── test-fixtures/ # 🧪 测试数据
├── scripts/ # ⚙️ 脚本(构建/部署辅助)
├── git-hooks/ # 🔧 git hook(代码提交检查)
├── patches/ # 🩹 依赖补丁(patch-package)
├── Swabble/ # ❓(可能是内部模块/实验功能)
├── openclaw.mjs # 🚀 启动入口(Node 脚本,很重要)
# 👉 可能是 CLI / 主程序入口
├── package.json # 📦 Node 主配置
├── pnpm-lock.yaml # 🔒 依赖锁
├── pnpm-workspace.yaml # 🧠 workspace定义(关键!)
# 👉 决定 apps/packages 关系
├── tsconfig.json # 🟦 TypeScript配置
├── tsconfig.plugin-sdk.dts.json # 插件SDK类型定义
├── tsdown.config.ts # ⚙️ 构建配置(可能是打包工具)
├── knip.config.ts # 🧹 检查未使用依赖
├── vitest*.ts # 🧪 单元测试配置(很多)
# 👉 说明项目很工程化
├── docker-compose.yml # 🐳 一键部署(包含多个服务)
├── Dockerfile # 🐳 主镜像
├── Dockerfile.sandbox* # 🧪 沙箱环境(执行代码用)
├── docker-setup.sh # ⚙️ Docker初始化脚本
├── setup-podman.sh # 🐳 Podman支持(替代docker)
├── openclaw.podman.env # 环境变量(podman)
├── fly.toml # ☁️ Fly.io部署配置
├── fly.private.toml # ☁️ 私有部署配置
├── render.yaml # ☁️ Render部署配置
├── pyproject.toml # 🐍 Python环境(很重要!)
# 👉 说明有 Python AI 后端
├── zizmor.yml # 🔍 CI / 安全扫描
架构
┌───────────────┐
│ apps │ ← 🚀 应用入口(前端/后端)
└──────┬────────┘
│
┌──────▼────────┐
│ packages │ ← 📦 公共逻辑(类似framework)
└──────┬────────┘
│
┌───────────▼───────────┐
│ skills / extensions │ ← 🧠 AI能力层
└───────────┬───────────┘
│
┌──────▼──────┐
│ 模型/API │ ← 🔌 推理层(外部 or 内置)
└─────────────┘
package.json
┌──────────────┐
│ CLI / UI │
└──────┬───────┘
│
┌──────▼───────┐
│ Gateway │ ← 核心
└──────┬───────┘
│
┌──────────────▼──────────────┐
│ Plugin SDK │
│ (agent / provider / tools) │
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ 多渠道 (Telegram/Slack…) │
└──────────────┬──────────────┘
│
┌──────▼──────┐
│ LLM层 │
└─────────────┘
CLI 入口
openclaw.mjs = 整个系统的“启动入口”
"bin": {
"openclaw": "openclaw.mjs"
}
openclaw.mjs 是一个 JavaScript 脚本文件,采用了 ES Modules (ESM) 标准
模块导出(🔥 架构核心)
"main": "dist/index.js",
"exports": {
".": "./dist/index.js",
"./plugin-sdk": {
"types": "./dist/plugin-sdk/index.d.ts",
"default": "./dist/plugin-sdk/index.js"
},
"./plugin-sdk/telegram": {
"types": "./dist/plugin-sdk/telegram.d.ts",
"default": "./dist/plugin-sdk/telegram.js"
},
"./plugin-sdk/telegram-core": {
"types": "./dist/plugin-sdk/telegram-core.d.ts",
"default": "./dist/plugin-sdk/telegram-core.js"
},
"./cli-entry": "./openclaw.mjs"
},
在 package.json 里,所有 plugin-sdk 的路径都指向了 dist/plugin-sdk/。
- dist/ 是编译后的产物:这意味着 plugin-sdk 的原始 TypeScript 代码分散在 src/ 目录下的各个核心模块中。
- 真正的源码目录通常是: src/plugin-sdk/ 或者分布在 src/core/、src/runtime/ 之中。
- 构建逻辑:当你运行 pnpm build 或 pnpm build:plugin-sdk:dts 时,构建脚本会提取 src 中的接口定义,并按照 package.json 里的映射关系,把它们重组到 dist/plugin-sdk/ 目录下。
plugin-sdk = OpenClaw 的“操作系统 API”
OpenClaw 的核心设计
它不是一个应用, 而是一个“平台 + SDK”
plugin-sdk 是什么?
plugin-sdk = 插件开发框架
在 OpenClaw 的工程结构中,找不到 plugin-sdk 目录是非常正常的,因为 plugin-sdk 不是一个源码目录,而是一个“发布别名(Alias)”或“虚拟映射”。
AI 核心运行时
"./plugin-sdk/agent-runtime"
"./plugin-sdk/llm-task"
"./plugin-sdk/text-runtime"
"./plugin-sdk/conversation-runtime"
多渠道支持
"./plugin-sdk/telegram"
"./plugin-sdk/discord"
"./plugin-sdk/slack"
"./plugin-sdk/whatsapp"
"./plugin-sdk/matrix"
"./plugin-sdk/msteams"
Provider(模型层)
"./plugin-sdk/provider-models"
"./plugin-sdk/provider-stream"
"./plugin-sdk/provider-auth"
"./plugin-sdk/provider-web-search"
Memory(记忆系统)
"./plugin-sdk/memory-lancedb"
支持向量数据库(AI 记忆)
安全
"./plugin-sdk/security-runtime"
网关
"./plugin-sdk/gateway-runtime"
scripts(🔥 启动方式)
"dev": "node scripts/run-node.mjs",
"start": "node scripts/run-node.mjs"
真正入口不是 openclaw.mjs 而是 scripts/run-node.mjs
网关启动(重点)
"gateway:dev": "node scripts/run-node.mjs --dev gateway"
gateway 是核心服务, gateway = AI 请求入口(类似 API Server)
dependencies(看架构)
Web 框架
既支持传统 API(express),也支持轻量网关(hono)
"express": "^5.2.1",
"hono": "4.12.8"
网络通信
WebSocket(实时通信)
"ws": "^8.19.0"
AI 相关
MCP / ACP(AI协议)
"@modelcontextprotocol/sdk"
"@agentclientprotocol/sdk"
AI agent 系列(重点)
OpenClaw 直接基于“现成 Agent 框架”
"@mariozechner/pi-agent-core"
"@mariozechner/pi-ai"
"@mariozechner/pi-coding-agent"
向量数据库
本地 embedding + memory
"sqlite-vec"
多媒体能力
❗支持多模态 AI
"sharp" // 图像处理
"pdfjs-dist" // PDF解析
"node-edge-tts" // 语音
peerDependencies
本地模型支持
"node-llama-cpp": "3.16.2"
OpenClaw 如何启动“整个 AI 系统”
node openclaw.mjs
→ 初始化 runtime
→ 启动 gateway(核心调度)
→ 加载 skills(AI能力)
→ 启动 sandbox(执行环境)
→ 对外提供 API/UI
指令执行流程
用户输入
↓
Gateway
↓
任务拆解(可能用 LLM)
↓
选择 Skill
↓
执行(sandbox)
↓
返回结果
openclaw.mjs