第 7 期 · 2026-11-07
openclaw/openclaw — 跑在自己电脑上、住进聊天软件里的 AI 助手网关
第 7 期看点:不到一年拿下 39.4 万 Star 的 AI 助手——不跑在别人的云上,跑在你自己的电脑里,再住进 Telegram、WhatsApp、Discord 这些你本来就在用的聊天软件。
一句话定位
openclaw/openclaw 是一个开源的个人 AI 助手网关:它在你自己的电脑上跑一个 Gateway(网关),把大模型接进来,再把助手投放到 20 多个聊天软件里——你在 Telegram 里发一句话,它就能在你的电脑上真的去执行任务、读写文件、跑命令、定时做事。它的口号是“The AI that really does things”,前身是 Peter Steinberger 的个人项目 Clawdbot,历经 Warelay、Clawdbot、Moltbot 三次改名才定为 OpenClaw,如今由独立非营利组织 OpenClaw Foundation(501(c)(3))管理,没有付费层、没有托管服务、没有代币。仓库创建于 2025-11-24,到今天不到一年,Star 已达 394,067,是 Atlas 榜上增长最快的 AI 智能体项目。
源码结构
克隆下来实测(git clone --depth 1,工作区 1.1GB、检出 65,091 个文件;GitHub 标注的仓库体积约 13GB,那是含完整历史的数字)。TypeScript 文件 50,655 个、TSX 1,579 个、Markdown 文档 2,400 个;按目录汇总的非测试 TypeScript 约 163 万行。体量最大的几块:
src/(16,738 个非测试 TS 文件,约 38.6 万行):核心源码,顶层 70 多个子目录。最大的是src/gateway/(1,114 个文件,网关控制面:会话、审批、cron、审计)与src/agents/(1,010 个文件,智能体运行时),其次是src/channels/(渠道接入框架:注册表、allowlist、配对、会话绑定)与src/cli/、src/config/、src/state/、src/security/、src/cron/、src/memory/、src/mcp/、src/skills/等。ui/(2,653 个文件,约 42.8 万行):Control UI,SolidJS 2.0 + Vite 8 写的 Web 控制台,用来在浏览器里配网关、看会话。extensions/(194 个扩展,181 个带独立 package.json,约 20.1 万行):模型、渠道、工具全部以扩展形态存在,包括 anthropic、openai、deepseek、google、ollama、openrouter、xai、kimi、moonshot 等模型扩展,以及 telegram、whatsapp、discord、slack、signal、imessage、teams、matrix 等渠道扩展。packages/(24 个包,991 个文件,约 13.6 万行):可复用的核心包,如agent-core(智能体循环)、plugin-sdk(插件契约)、llm-core、gateway-protocol、model-catalog-core、net-policy(网络策略)、memory-host-sdk。skills/(51 个内置技能):1password、apple-notes、github、notion、obsidian、spotify-player、trello、weather 等,都是 Markdown + 脚本形式的技能包。scripts/(1,142 个文件,约 37.8 万行):其中很大一部分是scripts/perf/下的性能度量脚本——这也是仓库文件数膨胀的原因之一。crates/(3 个 Rust 包):openclaw-gateway-client、openclaw-iroh-node、openclaw-node-host,节点间通信用了 iroh(P2P)。apps/:android、ios、linux、macos(含 macos-mlx-tts)等原生应用与节点;docs/有 1,428 篇 Markdown 文档;test/另有 639 个文件。- 根目录:
README.md331 行、package.json(版本 2026.11.1,bin 为openclaw,入口openclaw.mjs)、pnpm-workspace.yaml(pnpm monorepo,明确不支持根目录npm install)、Dockerfile、docker-compose.yml、fly.toml、render.yaml。
一个值得注意的数字是测试规模:全库 *.test.ts 文件 21,582 个,几乎与源码文件数量相当。CHANGELOG 也印证了这种工程强度:版本号按日期排(2026.11.1、2026.10.10、2026.10.9……),2026 年 10 月几乎每天发一版。
架构图
flowchart TD
A[用户入口 聊天软件与控制台] --> B[渠道层 20多个消息渠道]
A --> C[控制面 Control UI 与 CLI 与 TUI]
B --> D[网关层 Gateway 本地控制面]
C --> D
D --> E[智能体层 Agent Runtime 任务循环]
E --> F[模型层 可插拔模型与 Harness]
E --> G[能力层 Tools Skills 与 MCP]
D --> H[数据层 SQLite 与 Postgres]
D --> I[安全层 配对 审批 审计]
F --> J[生态层 194 个扩展与 ClawHub]
G --> J
H --> K[记忆层 会话与长期记忆]
E --> K
分层设计说明
按实际代码可以分成七层,每层各有明确的 owner:
- 用户入口层:两类入口。一类是聊天软件(Telegram、WhatsApp、Discord、Slack、Signal、iMessage、Teams、Google Chat、LINE、Matrix、飞书、Zalo 等,内置渠道 ID 39 个,含别名,真实渠道 20 多个);另一类是 Control UI(浏览器控制台)、CLI 与 TUI,直接连网关。
- 渠道层(
src/channels/):渠道只负责消息的收发与路由。注册表(registry.ts)、会话绑定(thread-bindings-*.ts)、allowlist、提及过滤(mention-gating.ts)、防抖(inbound-debounce-policy.ts)等机制都在这一层,渠道本身不碰模型逻辑。 - 网关层(
src/gateway/):本地控制面,管会话、事件、工具调用与渠道连接。package.json的openclaw字段声明了数据库引擎支持 sqlite 与 postgres,状态 schema 已演进到 39 版、agent schema 40 版。网关支持单人自用与多人共享两种形态,配置不同而已(README 称之为 personal claw 与 multiplayer claw)。 - 智能体层(
src/agents/+packages/agent-core/):内置运行时在src/agents/embedded-agent-runner/,负责 attempt loop(尝试循环)、模型选择、compaction(上下文压缩)、transcript 与会话接线;可复用的循环逻辑抽在@openclaw/agent-core包里。src/agents/harness/管 harness 的注册与选择:内置运行时 id 是openclaw,OpenAI 官方路由可隐式选用codexharness,其余走插件注册的 harness。 - 模型层(
src/llm/+ 各模型扩展):模型与 provider 是插件,可替换而不动其他部分。src/model-catalog/与packages/model-catalog-core/维护模型目录;网关启动时为每个 agent 生成一份“模型运行时 generation”——auth 模板、模型注册表与模型目录的原子快照,执行中途 pin 住该 generation,换 owner 不会混进另一套回调。 - 数据与记忆层(
src/state/、src/storage/、src/memory/、src/sessions/):状态与缓存用 SQLite(也可配 Postgres),而不是各处散落 JSON 文件——这是 AGENTS.md 明文规定的工程纪律。记忆以文件形式存在用户本地,root-memory-files.ts管根记忆文件。 - 安全层(
src/pairing/、src/security/、src/secrets/):配对(join-code + challenge + allowlist)、审批(agent-runtime-approval-authority.ts)、审计(audit-*.ts近 20 个模块,覆盖 secrets、插件信任、开放入站、文件系统)与网络策略包(net-policy:URL 协议检查、敏感 URL 脱敏)。README 的安全节开宗明义:把入站消息当作不可信输入。 - 生态层(
extensions/、skills/、ClawHub):新能力一律走扩展与技能,不进核心。扩展通过openclaw/plugin-sdk/*的公开契约与核心交互,不得 import 核心内部文件;资源清单用package.json的openclaw字段声明(extensions、skills、prompts、themes),未声明的按约定目录兜底发现。
技术亮点
亮点一:网关与运行时分离,模型与 harness 都可插拔。 证据在 docs/agent-runtime-architecture.md 的“Runtime Selection”与“Model Runtime Generations”两节:内置运行时与插件 harness 共存,agentRuntime.id 按模型条目优先于 provider 条目解析,未配置时 auto 选择;OpenAI 只有在“精确的官方 HTTPS Platform/ChatGPT Responses 路由且无自定义请求覆盖”时才隐式选用 codex harness,自定义端点与明文 HTTP 端点直接拒绝。每个 agent 的模型运行时以“原子快照”发布,失败或过期 generation 永不与新 generation 混着提供服务;执行开始后嵌套工作 pin 在已准入的 generation 上,插件 owner 中途变更不会把回调混到另一套实现里。代价是概念多:Gateway、Agent、Harness、Generation 四层抽象,新人要先读架构文档才能动手改模型逻辑。
亮点二:安全是运行时边界,不是文档口号。 证据有三处。第一,配对机制:src/pairing/ 下有 join-code、pairing-challenge、pairing-allowlist、pairing-store-sqlite 等完整实现,陌生人 DM 默认要配对批准,命令 openclaw pairing approve <channel> <code> 才能放行。第二,审批权威:src/gateway/agent-runtime-approval-authority.ts 与 src/agents/agent-tools.before-tool-call.approval*.ts 把工具执行前的审批做成运行时关卡,而不是事后日志。第三,审计面:src/security/ 下 audit-secrets、audit-plugins-trust、audit-open-inbound、audit-fs 等近 20 个审计模块,外加 packages/net-policy/ 的 URL 协议与 IP 检查。代价也很直接:默认偏严,第一次接渠道、第一次让助手执行高风险操作都要人工过一遍;想把网关暴露给多人或公网,必须先读安全指南与暴露 runbook。
亮点三:小核心、大生态的扩展纪律是写进仓库宪法的。 AGENTS.md 的设计优先级写明“小核心, capable 插件”:模型-facing 的核心新增要付出持续的上下文成本,可选能力一律放边缘;新能力必须先走 capability ladder 的第一步。docs/agent-runtime-architecture.md 的 Boundaries 一节规定:核心只通过 SDK barrels 对外,插件不得 import src/** 内部;新能力通常属于插件,经 ClawHub 分发。实测结果是 194 个扩展 + 51 个内置技能,而核心 src/ 保持为网关、智能体、渠道框架三条主线。代价是边界收紧后,贡献者想加能力得先过契约评审,不能直接往核心里塞代码。
值得参考的设计或实现
- 资源清单 manifest + 约定目录兜底:扩展在
package.json的openclaw字段里声明自己提供的 extensions、skills、prompts、themes;没声明的按约定目录自动发现。声明式与约定式各退一步,既不用写注册代码,也不会出现找不到资源的静默失败。 - 模型运行时 generation 快照:启动与配置变更时为每个 agent 生成一份完整的模型运行时快照(auth 模板 + 注册表 + 目录),旧快照失效前新快照必须完整发布,执行中途 pin 住 generation。这个模式值得抄给任何“配置热更新 + 长任务执行”的系统:快照隔离了配置变更与运行中任务的互相干扰。
- 稳定 prompt 前缀契约:会话内工具定义、系统提示与历史只依赖会话与配置事实,历史只追加不重写;任何触及 provider 请求的改动必须让
src/agents/agent-tools.prefix-stability.test.ts保持通过。背后是 prompt-caching 的复用收益:前缀稳定,缓存命中率才稳。这是把“性能优化”落成一条测试守护的做法。 - 生成物不手改:
.generated.*、.d.mts、node_modules 一律重新生成,AGENTS.md 明文禁止手改;配合同仓库的 pr-simplify、fresh review、落地检查等流程,大仓才扛得住每天一版的发布节奏。 - 日期版本号 + split changelog:版本即日期(2026.11.1),CHANGELOG 按版本拆文件存放,发布节奏与版本命名合二为一,查某天发了什么直接按日期翻。
适合谁
- 想在自己电脑上跑一个真正能干活的 AI 助手,而不是只在网页对话框里聊天的人;
- 想把助手接进 Telegram、WhatsApp、Discord、Slack 等聊天软件,随时随地使唤它的人;
- 做 AI agent、多渠道接入、插件化架构的工程师:网关、运行时、渠道三层分离与 194 个扩展是最现成的参考实现;
- 在意数据主权的人:状态、记忆、凭证默认都在自己硬件上,README 明确写着除每日版本检查外默认不向外打电话,匿名统计需主动 opt-in;
- 也适合想给助手加能力的人:模型、渠道、工具、技能全部走插件与 ClawHub,不用改核心。
怎么上手
需要 Node.js 24.16.0 以上(24.x)或 26.1.0 以上,官方强烈建议 24.22.1+ 或 26.12.1+(安全原因)。安装与启动:
# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash
# 或已有 Node 时
npm install -g openclaw@latest --allow-scripts=openclaw
# 首次向导(会验证模型访问、建工作区、配网关)
openclaw onboard --install-daemon
# 确认网关状态并打开控制台
openclaw gateway status
openclaw dashboard
向导完成后,在控制台里发一句话确认助手工作,再按文档接渠道(Telegram、WhatsApp 等各有自己的配对流程)。从源码跑则 git clone 后 pnpm install && pnpm build && pnpm ui:build。提醒两点:第一,把入站消息当不可信输入,DM 陌生人默认要配对批准;第二,工具默认在宿主机上执行,联网或接多人之前先读安全指南与沙箱指南。
数据卡
- 仓库:openclaw/openclaw · 官网 openclaw.ai · 文档 docs.openclaw.ai
- Star:394,067(2026-11-07 实测;Atlas 快照为 393,436,5 天涨约 600)
- Fork:82,812 · Watch:1,692 · Open Issue:7,634
- 主要语言:TypeScript
- 许可证:MIT
- Atlas 分类:AI智能体与大模型 · 领域:人工智能与机器学习
- 创建时间:2025-11-24 · 最近更新:2026-11-06 · 当前版本:2026.11.1
- 维护方:OpenClaw Foundation(独立 501(c)(3) 非营利组织);捐助方包括 Amazon、OpenAI、Red Hat 等