最近在给团队搭一个自主的 AI 助理，研究了一圈 Agent 框架之后，OpenClaw 成为我最终拆源码的那一个。它不是市面上名气最大的，但胜在结构干净：从消息接入到工具执行，再到模型调度，所有链路都能在几个核心模块里对齐，二次开发的时候很少需要“钻牛角尖”。

这篇博文我打算直接用实战视角，把 OpenClaw 的源码架构从外到内拆一遍。会聊它为什么要设计成事件驱动、路由器和工具注册表是怎么工作的、多模型适配层如何做到“换 provider 不换业务逻辑”，还会附带我在 Ubuntu 和阿里云上部署时遇到的几个真实报错。适合那种不想只跑通 demo、想真正掌握这个框架的开发者。

1. 项目概述与核心设计思路

1.1 一个“消息进来，动作出去”的中枢系统

OpenClaw 本质上是一个消息驱动的 AI 自动化框架。你可以把它想象成公司前台：所有外部来的请求，不管是来自 Teams 聊天、Obsidian 笔记，还是通过 HTTP 接口提交的任务，都会先被前台先生收集，然后递给背后的“大脑”，也就是大语言模型（LLM）。大脑分析后决定是直接回复，还是调用一个工具去执行某个动作，比如发邮件、写文件、查数据库。

我第一次跑通的时候最大的感受是：它的“爪子”真的能伸到各种平台。源码里把这类外部接入统称为Connector，每个连接器只需要负责两件事：接收消息、发送消息。正是这个极简接口，让整个框架能轻易覆盖 IM、知识库、Webhook 甚至本地目录。

1.2 源码里最值得看的三条设计主线

拆完源码，我认为有三条主线决定了 OpenClaw 的可扩展性。

第一是事件驱动。所有消息、定时任务、内部通知都被封装成事件，流入一个统一的事件循环。这样不同来源的消息之间不会互相干扰，处理逻辑也容易热插拔。

第二是“连接器-路由-工具-模型”四层解耦。消息经连接器进入，路由模块负责判断该交给哪个处理器，工具层管理可执行动作，模型层负责生成决策。每一层都能单独替换。

第三是配置与代码分离。框架本身的默认行为全部由配置驱动，你不需要改一行代码就能把默认模型换成 Qwen2.5-3b，或者把 Teams 换成 Obsidian。源码里到处能见到这种“先查配置，再走逻辑”的思路，对后人维护特别友好。

1.3 这篇拆解能帮你省下什么

我见过不少人把 OpenClaw 下载下来跑了一个欢迎对话，然后就丢到一边了。等到真正要接入自己的平台、写第一个自定义工具时，又无从下手。读源码的价值就在这里：当你理解了它的消息流转路径，就不会再去追问“这个功能应该改哪个文件”，而是能直接定位到对应的类和函数。

接下来我把整个架构拆成几个核心模块，每一块都会结合源码级别的细节和实际部署经验来讲。

2. 整体架构分层解析

2.1 三层架构：Core、Extensions、Channels

从目录结构上，OpenClaw 的源码非常直白地分成三大层：

• Core 核心层：负责事件循环、状态管理、配置合并、上下文保存。这是框架的心脏，目录通常是src/core/，里面按模块拆得很细。
• Extensions 扩展层：负责工具、技能、记忆、定时任务等。所有会被模型调用的“能力”都塞在这一层，目录通常是src/extensions/。
• Channels 通道层：负责和各种外部系统对接，比如 Teams、Obsidian、Websocket、HTTP API。目录通常是src/channels/。

下面的表格可以帮你快速建立起“哪个功能对应哪个模块”的直觉。

这种分层最大的好处是：你想换一个聊天平台，只需要写一个新的 Connector，完全不碰核心逻辑；你想给模型加一个新能力，只需要在 Extensions 里注册一个工具。我在接入内部系统时，就是照着这种结构，只花一个下午就把自定义 HTTP 连接器挂了上去。

2.2 事件循环与异步模型

OpenClaw 的事件循环基于 Python 的asyncio。它没有给每个连接器开独立线程，而是所有连接器把输入封装成Event，然后投递到一个全局队列里。这个设计很像一个餐厅服务员：一个人同时照顾多桌客人，但点菜、传菜都用异步方式，不用每桌客人占用一个员工。

源码里的事件对象通常长这样：

class Event: def __init__(self, type: str, payload: dict, source: str): self.type = type # message, command, cron, hook self.payload = payload self.source = source # 来自哪个 connector

主循环会从队列里取出事件，根据type调用对应的分发器。因为整个过程是异步的，即使某个工具执行较慢，比如等待某台服务器的响应，也不会阻塞其他消息的接收。这个特性在做多平台接入时非常重要：Teams 里的提问和 Obsidian 里的笔记更新得同时处理，而不是互相等待。

2.3 配置管理如何做到“零散但不混乱”

OpenClaw 的配置入口支持多种来源：YAML 文件、环境变量、命令行参数。这三者按优先级从低到高合并，和环境变量有关的内容在后级会覆盖前级。源码里有个resolve_config函数，专门处理这些层次。

一个典型的配置文件会包含这些块：

model: provider: "openai-compatible" base_url: "http://localhost:8000/v1" name: "qwen2.5-3b-instruct" channels: teams: enabled: true app_id: "xxxx" obsidian: enabled: true vault_path: "/home/user/obsidian" extensions: tools: - file_reader - web_search

为什么要把配置从代码里抠出来？我自己的体会是，当你要在多个环境部署时，比如本地、阿里云服务器、公司的测试机，同一套代码只需要改配置文件就能适配。这比在代码里改一堆常量再打包要靠谱得多。源码里很多模块都会先查询配置中心，再决定自己是否启用，这就是“配置驱动”模式。

3. 核心模块源码拆解

3.1 MessageRouter：消息到意图的第一站

路由器是消息进来后的第一个关卡。它接收来自不同连接器的Event，然后决定这个消息应该由哪个 handler 处理。OpenClaw 的默认路由逻辑设计得非常宽容：既支持精确匹配，也支持模糊匹配。

我打开src/core/router.py这个文件，半天就能理清它的核心逻辑。简单来说，注册一个 handler 时，你需要告诉路由器“我关心哪些消息”。路由规则可以是"command:status"，也可以是正则表达式，还可以是一个自定义函数。

下面是一个简化的路由示意：

class MessageRouter: def __init__(self): self.rules = [] def add_rule(self, pattern, handler, priority=100): self.rules.append((pattern, handler, priority)) self.rules.sort(key=lambda x: x[2]) async def route(self, event): for pattern, handler, _ in self.rules: if pattern.match(event.payload.get("text", "")): return await handler(event) return None

真实源码比这个复杂，但核心思路一致。需要注意的是，路由规则的顺序很重要。如果你同时注册了/help和/help@bot，前缀匹配会把@bot也当成普通文本。我建议在写自定义 handler 时，最好用正则而不是简单startswith，避免误匹配。框架源码里也是优先用正则编译后的 pattern 对象，这样性能更好，规则也更精确。

3.2 ToolRegistry：技能库的管理员

模型输出一个“我想调用工具”的决定之后，OpenClaw 需要找到对应的函数来执行，这就是ToolRegistry的职责。它相当于一个技能库：工具可以有input_schema，让模型知道需要传哪些参数；工具执行后的结果也会被封装成规范结构，方便模型继续决策。

工具注册的源码通常这么写：

@tool_registry.register(name="read_file", description="读取本地文件内容") def read_file(path: str) -> str: with open(path, "r", encoding="utf-8") as f: return f.read()

这里的关键点在于description和类型注解。它们不是给人类看的注释，而是会被拼进发给模型的 prompt 里。也就是说，模型是靠这一段段描述来决定“这个任务该调用哪个工具、应该传什么参数”的。我踩过的坑是：如果工具描述写得含糊，模型就会频繁地不敢点下去，或者错误传参。所以写工具时，描述一定要比函数名详细得多。

ToolRegistry 内部还会做参数校验，防止模型生成缺参或类型错误的调用。源码里用jsonschema做校验，这一点非常值得学习。你的自定义工具如果对参数要求比较严格，就可以参考它的校验层设计，而不是在每个函数里自己写 if。

3.3 LLMProvider 适配层：换模型不改业务

OpenClaw 没有把某个模型厂商的 SDK 直接铺满整个项目，而是抽象出一个LLMProvider接口。所有模型接入都是实现这个接口的chat或complete方法。好处非常明显：你在代码里永远只面对这个接口，而不用关心底层调 GPT、Claude 还是本地 Qwen。

class LLMProvider: async def chat(self, messages, tools=None, temperature=0.7): raise NotImplementedError()

如果你想把 OpenClaw 关联到本地的 Qwen2.5-3b，只需要实现一个OpenAICompatibleProvider，因为绝大多数本地模型都提供 OpenAI 兼容的/v1/chat/completions接口。我在阿里云服务器上就起了一个vllm服务，然后在配置里填上base_url和model_name，OpenClaw 就能直接调用。源码里这种“兼容层”的思路，让接入一个新模型通常只需要改配置，而不是改代码。

4. 部署与扩展实践

4.1 Ubuntu 环境下从零到跑通

OpenClaw 的部署并没有那么复杂，官方文档推荐用 Python 3.10 以上。我在 Ubuntu 22.04 上的实际操作步骤大致如下：

1. 安装 Python 和uv工具。
2. 克隆仓库并创建虚拟环境。
3. 安装依赖并完成初始化。
4. 复制示例配置，填入模型和通道信息。
5. 启动服务并验证。

具体命令可以这样：

sudo apt update sudo apt install -y python3.10 python3.10-venv git curl curl -LsSf https://astral.sh/uv/install.sh | sh source $HOME/.local/bin/env git clone https://github.com/openclaw/openclaw.git cd openclaw uv sync cp config.example.yaml config.yaml # 编辑 config.yaml，填入模型和通道配置 uv run openclaw server

只要config.yaml里的模型端点可达，终端会输出类似openclaw started on port 8080的日志。这个时候你可以直接用 HTTP 连接器或你配置的聊天平台测试消息。这里我特别建议第一次部署的同学先用最简单的 HTTP 通道做测试，不要去同时开 Teams 和 Obsidian，先把主链路跑通，再加通道。

4.2 把 Teams 接进来

Teams 接入需要先到微软的 Azure 门户注册一个 Bot，拿到App ID和Client Secret。然后在 OpenClaw 的channels.teams配置块里填进去。源码里对应的连接器会创建 Bot 服务，接收来自 Teams 的实时交互消息。

我之前踩过的一个坑是：连接器在本地测试时，需要把外网回调地址填到 Teams 的配置里。如果你只是在局域网里跑，Teams 平台没法访问到你的回调接口。解决方法有两个，要么用官方隧道工具，要么部署到公网服务器上。我后来直接放到阿里云服务器，把安全组开放对应端口，才算解决。

4.3 Obsidian 作为知识库输入源

OpenClaw 的 Obsidian 连接器会监听某个 Vault 目录，当 Markdown 文件发生变化时，自动生成一个document_update事件。这个能力在个人助理场景太有用了：你随时在 Obsidian 里写笔记，OpenClaw 会感知到变化并把它纳入上下文。

配置也很简单，只需要指定vault_path。源码里会用一个文件系统监听器来触发事件，而不是轮询。这里有一个细节：连接器默认只监听.md文件，其他类型的附件会被忽略。如果你需要处理 PDF 或图片，得改一下连接器的扩展名白名单。

4.4 阿里云服务器部署的配置建议

如果你打算把 OpenClaw 部署到阿里云上，我建议先关闭一些不必要的安全组端口，只保留实际使用的端口。比如只运行 HTTP 连接器，就只放行 8080。同时用一个独立的非 root 用户运行服务。虽然这些是通用运维知识，但我在实际部署中发现，很多人是因为把 root 暴露出去，导致后面日志里一堆扫描攻击的记录。

服务器的规格方面，如果只跑openclaw本身加一个轻量模型，2 核 4G 内存足够起步；如果还要在本地跑 Qwen2.5-3b，建议至少 4 核 8G，因为模型推理的显存和内存占用都比较高。我在测试环境里只有 CPU，跑 3B 模型虽然慢，但能撑得住并发很小的场景。

5. 常见问题与排查实录

5.1 WSL2 环境异常导致启动失败

不少 Windows 用户不是直接部署在 Linux 机器上，而是用 WSL2 来跑 OpenClaw。这时最常见的报错就是类似“openclaw 无法安全验证 WSL2 环境，请在 powershell 中运行 wsl --status”。这其实是 OpenClaw 启动时的环境自检没有通过，并不是 OpenClaw 本身的问题。

我第一次遇到时也有点晕，后来从源码里看到check_wsl_status这个函数，它会读取wsl --status的输出来判断 WSL2 是否正常运行。如果输出显示内核版本落后或者分发版处于 stopped 状态，就会抛这个提示。排查方法很简单：

1. 打开 PowerShell，运行wsl --status，看看里面是否显示“默认版本: 2”。
2. 如果显示 WSL 版本为 1，运行wsl --set-default-version 2。
3. 如果内核提示过期，运行wsl --update。
4. 确保 Windows 的“虚拟机平台”功能已经开启，否则 WSL2 根本起不来。

完成之后，重启终端再进入 WSL 环境，重新启动 OpenClaw 就正常了。这里强烈建议不要在 WSL1 下强行跑，因为部分文件事件监听功能对文件系统事件的支持在 WSL1 下很不稳定。

5.2 本地模型端口不响应

如果你在服务器上单独用 vllm 或 Ollama 起模型，然后让 OpenClaw 连接，经常遇到“模型未就绪”或连接超时的问题。常见原因是模型服务并没有监听 OpenClaw 期望的那个地址。我记得有一次明明curl localhost:8000/v1/models能通，但 OpenClaw 里一直报错，最后发现配置里写的是http://localhost:8000/v1，而实际服务是在另一个容器里，需要用网络别名。

排查时先确认模型服务的监听地址，再确认防火墙是否开了对应端口，最后用curl手动模拟一次请求，看看返回格式是否真的是 OpenAI 兼容结构。OpenClaw 的适配层对返回格式比较严格，如果某个字段缺失，它可能直接抛异常。

5.3 常见报错速查表

这张表是我在部署不同环境后整理出来的，能覆盖大多数新手的启动和接入问题。

6. 二次开发：定制自己的扩展

6.1 找扩展点：从源码里发现 Hook

OpenClaw 预留的扩展点不在少数。核心层的BaseConnector、BaseTool、BaseSkill都是很好的入口。如果你想给框架加一个“定时任务”，只需要在 Extensions 里实现一个Schedulable接口，注册后就能被主循环定时触发。

读源码找 Hook 有个技巧：搜索interface或者base.py。这些文件里几乎所有类名都以Base开头，方法大多只有接口定义，没有具体逻辑。你会发现，框架作者把扩展接口写得特别薄，尽量不限定你的实现方式。

6.2 写一个“定时发送日报”的工具

我实际写过一个DailyReportTool，思路很简单：在工具层注册一个函数，它负责从数据库读取当天数据，拼成文本；再用一个定时任务每天下午六点调用这个函数，把结果通过某个通道发出去。

工具注册的代码类似这样：

from openclaw.extensions import tool_registry @tool_registry.register( name="daily_report", description="生成当天业务数据日报，并发送到指定通道", input_schema={ "type": "object", "properties": { "target": {"type": "string", "description": "接收日报的通道名称"} }, "required": ["target"] } ) def daily_report(target: str) -> str: data = pull_data_from_db() text = render_report(data) send_to_channel(target, text) return "日报已发送"

这里的关键点是input_schema要完整。模型是靠这个 schema 来决定参数的，如果你写得太模糊，模型可能会漏掉必填字段。写完后，在配置里启用这个工具，重启服务就能在对话中触发它。

6.3 源码阅读路径与避坑建议

我的建议是不要从main.py开始往后硬读，而是先读docs/architecture.md，再按“事件流”的顺序读：router.py→tool_registry.py→llm_provider.py→connector.py。你会发现，整个框架的流转路径非常线性，读完一遍心里就有底了。

避坑方面，我有三条经验：

• 不要直接跟踪main分支的源码，尽量用 release tag 或稳定分支，因为开发版可能整天在变。
• 修改源码前，先跑一遍现有的测试用例，确认环境正常，否则你改了半天分不清是自己的问题还是上游的问题。
• 配置里log_level一定要调成debug，否则排查问题时会漏掉很多关键上下文。

我个人在二次开发中受益最大的一点，是它的工具注册机制：我不需要理解太多复杂概念，只要把函数写好，挂上@tool_registry.register，就能让模型学会使用新能力。这种“去框架化”的体验，让开发者能把大部分精力放在业务逻辑上，而不是被框架本身捆住手脚。

如果你正在考虑用 OpenClaw 做自己的自动化中心，我建议你先从它的源码架构图出发，弄清楚自己需要扩展的是哪一层。是模型层、工具层，还是通道层？定位清楚以后，剩下的每一步都会非常顺。