OpenClaw源码解析(一)开篇:项目定位与愿景

源文件：VISION.md, README.md, package.json

开篇虽然不是“函数级源码解析”，但也不只是泛泛概览。

正确读法是：

• 先读 VISION.md，看项目明确写下来的产品边界

• 再读 README.md，看对外呈现的主叙事和核心卖点

• 最后读 package.json，看包的真实发布形态和扩展边界

第一步：从 VISION.md 抓产品定义

VISION.md 开头两句其实已经给了整个项目的核心定位：

OpenClaw is the AI that actually does things.

It runs on your devices, in your channels, with your rules.

这两句拆开看：

• does things：不是纯聊天机器人，而是任务执行型助手

• your devices：强调本地设备、控制权和执行环境

• your channels：消息入口不是自建 App，而是现有聊天通道

• your rules：安全策略、访问策略、路由策略都应由操作者控制

这会直接影响后面所有架构判断：

• 为什么有这么重的 channel 抽象层

• 为什么强调 gateway / routing / allowlist

• 为什么工具、插件、memory 都倾向可配置和可替换

第二步：从 README.md 抓对外叙事

README.md 的开头主叙事比 VISION.md 更“产品化”：

• personal AI assistant

• run on your own devices

• answers you on the channels you already use

• single-user assistant that feels local, fast, and always-on

这里有两个很重要的架构暗示。

暗示 1：Gateway 不是产品本体

README 明确写了：

The Gateway is just the control plane — the product is the assistant.

这句话非常重要，因为很多人看目录会误以为 src/gateway/ 是绝对中心。

更准确的理解是：

• gateway 提供控制平面和连接面

• 真正的用户体验中心是 assistant runtime

• 所以后面要重点读 src/agents/、src/routing/、src/channels/

暗示 2：单用户是核心假设

README 里明确把它描述成：

• personal

• single-user

• local / always-on

这会解释很多设计决策：

• 安全模型强调 operator-controlled，而不是 SaaS 多租户

• session、workspace、agent isolation 更像“一个人的多个工作区”

• 权限系统更偏设备与消息源信任，而不是 RBAC

第三步：从 package.json 看真实发布边界

package.json 里最重要的三块不是 scripts，而是：

• description

• bin

• exports

1. description

"description": "Multi-channel AI gateway with extensible messaging integrations"

这说明 npm 包对外暴露时，强调的是：

• multi-channel

• gateway

• extensible integrations

也就是发布形态偏“平台底座”，而不仅是“一个聊天机器人”。

2. bin

"bin": {  "openclaw": "openclaw.mjs"}

这说明 CLI 是第一入口，后面读 src/entry.ts 就不是偶然，而是主线。

3. exports

exports 里不只有主入口，还有大量 ./plugin-sdk/* 子入口。

这说明：

• 插件不是附属能力，而是包级公开边界

• 不同通道和扩展能力被当成正式 SDK surface 对待

• OpenClaw 的 core 从一开始就在为“外部集成”设计

一句话定位

把上面三份文件合起来，比较准确的定位应该是：

OpenClaw 是一个以 CLI 和 Gateway 为入口、以消息通道为交互面、以插件和工具为扩展面的个人 AI assistant runtime。

核心价值主张

OpenClaw is the AI that actually does things.It runs on your devices, in your channels, with your rules.

三个关键词：

• your devices → 本地运行，不依赖云服务

• your channels → 在你已有的聊天平台上使用

• your rules → 你控制安全策略和访问权限

VISION.md 里最值得注意的 4 个架构信号

1. Terminal-first

VISION.md 写得很明确：

OpenClaw is currently terminal-first by design.

这不只是交互偏好，而是安全和初始化策略的一部分：

• 首次配置要显式

• 用户需要看见权限、认证和安全姿态

• 便利性不能压过可控性

所以后面你会看到 CLI 和 onboarding 被设计得非常重。

2. Core stays lean

Core stays lean; optional capability should usually ship as plugins.

这句话几乎能解释整个仓库为什么有：

• src/plugins/

• src/plugin-sdk/

• extensions/*

• slot 机制

也解释了为什么 memory、context engine 这类关键能力都开始被抽成可替换边界。

3. MCP 走桥接层，不进 core  ？

VISION.md 对 MCP 的表述非常直接：

• 通过 mcporter 集成

• 不把 first-class MCP runtime 内建到 core

这背后的架构态度是：

• 用桥接层隔离高波动协议

• 保持 core 工具面和上下文面精简

• 减少外部生态变动对主运行时的冲击

4. 明确写出“不合并什么”

What We Will Not Merge 这一段很值得细读，因为它比“要做什么”更能暴露系统边界。

比如：

• 不要重型 orchestration layer

• 不要 manager-of-managers

• 不要把可插件化能力直接塞进 core

这意味着 OpenClaw 追求的是：

• 强执行力

• 边界清晰

• 少做抽象叠抽象

设计哲学

1. Terminal-first（终端优先）

OpenClaw is currently terminal-first by design.This keeps setup explicit: users see docs, auth, permissions, and security posture up front.

→ 刻意让用户感知安全风险，不隐藏在 GUI 背后

2. Core stays lean（内核保持精简）

Core stays lean; optional capability should usually ship as plugins.

→ 核心只做必要的事，扩展能力通过插件发布

3. 为什么选 TypeScript？

OpenClaw is primarily an orchestration system: prompts, tools, protocols, and integrations.TypeScript was chosen to keep OpenClaw hackable by default.

→ 本质是编排系统，不是数值计算，TypeScript 最适合这类场景

4. MCP 集成策略（值得学习的架构决策）

不把 MCP 内置到 core，而是通过 mcporter 桥接：

• 不重启 gateway 就能添加/修改 MCP server

• 保持 core 工具/上下文面精简

• 减少 MCP 版本变动对 core 稳定性的影响

→ 架构启示：用桥接层隔离不稳定的外部协议

明确不合并的内容（学习边界意识）

这个列表揭示了项目的边界决策思维：

• 新 core skills（当它们可以在 ClawHub 上发布时）

• 全量文档翻译集

• 商业服务集成（不属于模型提供商类别）

• 嵌套 agent 框架（manager-of-manager

• 大型编排层（重复现有 agent/tool 基础设施）
  

→ 架构启示：清晰的边界比”什么都支持”更有价值

下一篇预告：OpenClaw整体架构全景