把 OpenClaw 的源码从入口到插件体系整体过一遍感受和读文档完全不一样。第一篇文章里我重点写了项目定位和整体能力边界这篇“II”就直接扎进代码层面事件循环是怎么设计的、Skill 是怎么注册和加载的、模型接入层凭什么能同时兼容本地 Ollama 和云端 API。别担心这不是那种通篇名词堆砌的源码论文而是我带着你一段一段读代码的真实记录。以我自己的经验源码里真正有价值的往往不是那些大而全的抽象而是几个关键模块之间的协作方式。读完这篇之后你应该能搞清楚 OpenClaw 的启动链路、技能扩展机制、模型切换逻辑以及在 Windows 和安卓 Termux 上部署时到底动了哪些源码层面的东西。1. 项目骨架从目录结构和入口文件看系统设计思路1.1 目录结构本身就是一张架构图拿到一个开源项目的源码我习惯先不看 README而是直接打开目录结构。因为目录布局往往比文档更诚实它能告诉你作者把系统边界画在了哪里。OpenClaw 的源码目录大概是这个形态openclaw/ ├── app.py # 主入口 ├── config.yaml # 默认配置 ├── core/ │ ├── __init__.py │ ├── agent.py # 智能体核心逻辑 │ ├── events.py # 事件定义与分发 │ ├── registry.py # Skill 注册表 │ └── context.py # 上下文管理 ├── connectors/ │ ├── llm/ │ │ ├── ollama_connector.py │ │ ├── api_connector.py │ │ └── base.py │ └── platform/ │ ├── windows.py │ └── terminal.py ├── skills/ │ ├── builtin/ │ │ ├── web_search/ │ │ └── file_tools/ │ └── custom/ # 用户自定义技能目录 ├── utils/ │ ├── logger.py │ └── config_loader.py └── tests/这个结构传达了几个关键信息。第一core目录和connectors目录是严格分离的。核心逻辑不知道消息具体来自微信、终端还是 Windows 桌面端它只处理抽象后的事件。比如events.py里定义的可能是一个个数据类agent.py只关心这些事件类型不关心它们怎么来的。这就是典型的依赖倒置上层策略依赖抽象接口不依赖具体实现。第二skills/builtin和skills/custom分开暗示了技能系统是“内置优先、自定义靠后加载”的模式。这种设计能让项目保持开箱即用的体验同时又给二次开发留了足够空间。很多项目因为技能散落在一堆模块里最终难以维护OpenClaw 这种“一个技能一个文件夹”的做法是值得学习的。第三connectors/platform下面能看到windows.py和terminal.py说明这个项目确实考虑了桌面端的集成问题。热词里频繁出现的“Windows Companion”配置对应的源码应该就在这个平台连接层里。1.2 入口文件里的初始化顺序启动时到底发生了什么打开app.py我第一个关注的永远是初始化顺序因为它直接决定了部署时遇到报错该怎么排查。app.py的逻辑大致是按照“配置加载 → 日志初始化 → 模型连接 → 技能注册 → 事件循环”的顺序执行的def main(): config load_config(config.yaml) init_logger(config.get(logging)) llm create_connector(config.get(model)) llm.connect() registry SkillRegistry() registry.load_builtin(skills/builtin) registry.load_custom(skills/custom) agent OpenClawAgent(llmllm, registryregistry) agent.run()如果启动时经常在某个环节卡住参照这个顺序去查问题会快很多配置错了先报错日志配置不对会静默失败模型连接失败会直接抛异常技能加载失败一般只警告不退出。这个设计其实暗示了一个很重要的机制——即使某个技能挂了主进程也不应该崩掉这与后面要讲的 Skill 隔离机制有关。还有一个细节配置文件是通过load_config统一加载的。源码里通常会实现“默认配置 用户配置”的合并逻辑用户写的config.yaml会覆盖默认值。这种分层配置的设计很有必要因为 OpenClaw 的部署场景差异极大本地跑和服务器跑的模型参数完全不同不搞配置分层会让用户被迫复制一整个配置目录。我建议二次开发时也沿用这个思路不要把用户配置和代码默认配置混在一个文件里。2. 核心事件循环智能体每一轮“感知—思考—行动”背后的调度细节2.1 为什么选择事件驱动而不是简单的 while 循环智能体框架和普通脚本最大的区别在于普通脚本是线性执行的而智能体需要同时处理多个来源的输入并且要随时响应中断和插话。有的开发者会直接写一个while True循环不断调用大模型接口等结果返回后处理输出。这种实现的问题在于当大模型推理耗时超过几秒时整个系统会被一个请求阻塞别的输入全都进不来。想象一下用户已经在说“停下来”系统却还在等上一次模型调用返回——这就是没有事件驱动导致的体验崩溃。OpenClaw 在core/events.py里使用的是一种基于asyncio的事件调度模型。核心逻辑并不复杂可以理解为一张事件表系统把不同来源的输入统一包装成事件对象放进队列再由主循环按优先级分发async def run(self): while self._running: event await self.event_queue.get() if event.type EventType.USER_INPUT: response await self.handle_user_input(event) elif event.type EventType.SKILL_RESULT: response await self.handle_skill_result(event) elif event.type EventType.INTERRUPT: self.interrupt_current_task() await self.output(response)这个模式的精髓在于所有外部输入都被“事件化”了系统的其他部分不需要知道输入来自键盘、文件还是某个平台的消息推送只要往队列里塞一个事件对象就行。这也就解释了为什么 OpenClaw 能实现跨平台Windows Companion、安卓终端、Linux 桌面本质上都是“不同的事件生产者”而已。2.2 一条用户消息从进入到响应的完整链路我在读源码时把事件流转路径整理成了下面这条链路套用到任何输入来源上都适用输入捕获连接层比如终端监听、Windows Companion 的窗口事件拿到原始输入封装事件把原始输入包装成UserInputEvent附带上来源 ID 和时间戳进入队列事件被放入主循环的事件队列等待调度上下文组装agent.py从context.py里读取当前会话的上下文把事件和上下文一起打包模型推理把组装好的 prompt 发送给当前模型中等待返回响应分发模型返回后agent.py判断是否要触发某个 Skill。如果需要就进入 Skill 执行流程否则直接把文本输出回来源设备在第 6 步里藏着一个非常关键的设计模型返回内容中如果包含 Skill 调用标记OpenClaw 并不会直接执行而是把请求转发给 SkillRegistry由注册表来解析并调用对应的技能。这种“模型只负责决策、系统负责执行”的分离是智能体安全性的基础。试想一下如果模型能直接执行任意系统命令那和多让 AI 掌握了终端 root 权限没什么区别。所以源码里一定有一层白名单校验确保只有注册过的 Skill 才能被执行。2.3 异步调度里最常见的坑共享状态与取消机制这块属于经验之谈。源码里asyncio用得再好二次开发时还是会踩两类坑。第一类是共享状态的并发修改。因为在事件循环里多个协程共享同一个上下文对象是很常见的。如果某个 Skill 在阻塞执行时另一个输入事件到达并尝试修改上下文就可能出现上下文错乱。翻源码时我注意到 OpenClaw 给context.py加了锁机制但锁用多了又会拖慢整体响应速度。实际开发时我的建议是上下文对象尽量设计成不可变的快照结构每次更新生成新版本而不是就地修改这样能从根本上避免并发竞争。第二类是任务取消。当用户发出中断指令时系统需要能取消正在进行的模型调用。我们知道大模型接口一旦发出 HTTP 请求客户端主动断开连接并不等于服务器端停止计算但至少可以让框架快速恢复响应。如果你在二次开发时加了长耗时的自定义 Skill一定要记得监听取消事件把asyncio.CancelledError处理干净否则会出现“主循环已经跳走了后台任务还在偷偷执行”的诡异情况。3. Skill 注册表整个项目扩展性最强也最容易写飞的部分3.1 Skill 到底长什么样不仅是一段函数而是一套元数据描述在 OpenClaw 源码里Skill 不是简单的一个 Python 函数而是一个自带“描述文件”的模块。每个 Skill 文件夹下通常包含一个manifest.json或同名 YAML 文件里面声明了名称、描述、参数约束、权限级别。这样设计的原因很实际为了让模型能够“知道”这个技能存在并且知道什么时候该调用它。Skill 的元数据描述会被拼到系统提示词里所以描述写得越清楚模型的调用准确率就越高。这一点极其重要。源码里registry.load_custom()加载技能时实际上做的是“扫描目录 → 读取 manifest → 动态 import 模块 → 把技能信息注册到技能表”如果 manifest 缺失或格式错误这个技能会被静默跳过。Skill 描述文件里我觉得最关键的是parameter_schemas字段它直接决定了模型是否能正确生成调用参数。举个例子如果有一个查询天气的 Skill它的参数 schema 定义不好模型可能传成字符串而你的函数需要浮点数调用就会失败。3.2 注册、发现、加载三个阶段的源码行为深度解析我在阅读core/registry.py时发现它的工作流程可以分为三个阶段。阶段一发现Discovery。注册表会遍历技能目录查找所有包含 manifest 文件的子文件夹。这里有一个值得注意的细节内置技能和自定义技能是分开扫描的内置技能在启动时就装载自定义技能可以配置为启动时装载或按需动态装载。阶段二解析Parse。每个 manifest 里的信息会被提取出来转换成统一的SkillDescriptor数据结构。源码中这一步做得比较好的地方是校验逻辑不仅检查字段是否齐全还会检查参数 schema 的合法性。阶段三动态装载Dynamic Loading。通过importlib把技能模块的run(**)方法注册到一张字典表里。在源码里技能名是键执行函数是值。后续调用时直接查表执行完成后再把结果作为SkillResultEvent返回给主循环。对于二次开发者来说最容易漏掉的一点是技能没有独立的异常隔离。如果你写的 Skill 内部抛出了未捕获的异常OpenClaw 默认会捕获并记录错误日志但如果你在技能里直接用sys.exit()或者写了死循环就可能导致整个系统崩溃。所以技能开发的底线是永远把核心逻辑包在try/except里保证异常被框架捕获而不是炸穿主流程。3.3 手写一个最小 Skill从零开始的完整示例下面是我自己写的一个最简 Skill 的结构可以直接放到skills/custom/datetime_skill里datetime_skill/ ├── manifest.json └── main.pymanifest.json的内容{ name: get_current_time, description: 获取当前日期和时间在没有其他时间信息时使用, version: 1.0.0, permissions: [basic], parameters: { type: object, properties: {}, required: [] } }main.py的内容from datetime import datetime def run(**kwargs): now datetime.now() return f当前时间是 {now.strftime(%Y-%m-%d %H:%M:%S)}注意这里run函数必须通过**kwargs接收参数因为框架在调用时会把模型生成的参数解析成字典再传进去。如果你写的是普通函数签名参数列表不匹配就会报错。源码正是通过这样的“约定优于配置”让 Skill 的编写成本降到最低——你不需要理解事件循环也不需要了解内部调度只需要实现一个能被安全调用的纯函数。4. 模型接入层Ollama 本地部署和云端 API 是怎样被统一成一套接口的4.1 连接器模式为什么不能直接写 HTTP 调用很多人问过我一个问题接入大模型不就是拼一个 API 地址然后发请求吗为什么要单独搞一层connectors/llm把这个问题想明白你才算真正看懂了这层设计。核心原因是模型供应商的接口差异远比你想象的大。Ollama 返回的格式遵循它自己的规范OpenAI 兼容接口又有一套字段更别提还有各种自托管网关。如果你在业务代码里直接写死某个模型的 HTTP 请求方式后期想换个模型几乎要重构所有调用点。OpenClaw 的做法是在base.py中定义一个抽象连接器接口所有具体的模型接入方式都实现这个接口。这个接口通常包含四个方法connect()建立连接或检查可用性chat()发送对话请求返回文本stream_chat()流式对话close()释放连接这样一来上层agent.py只依赖base.py里定义的接口完全不知道你底层用的是 Ollama 还是其他 API。我在实际使用中觉得这个模式的收益在切模型时体现得最明显——不用动任何业务代码只改配置文件和连接器类型系统就换了个脑子。4.2 Ollama 接入路径本地推理到底走了哪些源码步骤从热词来看很多人都在问“Ollama 部署 OpenClaw”。Ollama 的接入逻辑在connectors/llm/ollama_connector.py里实现思路可以概括为从配置读取 Ollama 服务地址默认为http://localhost:11434调用本地接口检查目标模型是否存在如果模型不存在记录一个明确提示错误而不是直接发请求后报错发送请求时使用流式模式逐块接收 token避免长回复导致响应超时源码里有个容易被忽略的优化点Ollama 连接器首次启动时会先发送一个空请求来预热模型把模型加载进显存或内存。这么做的原因很实际——本地模型第一次推理时往往需要加载权重耗时可能长达几十秒如果没有预热机制用户会以为系统已经卡死了。4.3 参数细节中的隐藏问题上下文长度、超时与温度设置这部分内容不写清楚部署时真的会被坑。源码在创建连接器时会读取配置文件里的模型参数比如model: provider: ollama name: qwen2.5:7b temperature: 0.7 max_tokens: 4096 context_window: 8192 timeout_secs: 120context_window这个参数很关键。本地模型能够接受的上下文长度是有限的如果你设置的context_window大于模型本身的上限连接器不会报错但生成质量会严重下降——因为系统发送给模型的提示词已经超出了模型的有效处理范围模型会“遗忘”前面的内容。源码里并没有自动截断上下文的逻辑所以这就要求使用者在配置时老老实实查一下所选模型的上下文长度。timeout_secs同样值得重视。本地模型在 CPU 机器上跑时一个长回复的生成时间可能很夸张。如果你不给足超时时间流式请求会一直在等待状态看起来像没接上模型。5. 多端部署的源码适配Windows Companion 怎么工作安卓 Termux 上跑需要动什么5.1 Windows Companion它解决的其实是一个系统集成问题很多从热词里搜“OpenClaw Windows Companion”的人来说第一反应是“这不就是个快捷键启动器吗”但如果你读过connectors/platform/windows.py的源码就会明白它做的事情远不止启动程序。Windows Companion 本质上是一个系统感知层。它要做的事情包括监听全局快捷键、监控窗口状态、获取当前活动窗口标题、把能力暴露成可以被智能体调用的一组系统接口。这里的核心点在于“感知”和“操作”分离感知的部分通过 Windows API 或者辅助功能接口拿到系统状态操作的部分则通过封装好的函数来模拟按键、写入文本或触发动作。源码实现上无非是通过ctypes调用 Windows API但这层封装解决了前面事件循环设计里的关键问题它让 Windows 系统变成了一个事件源。用户在任意窗口里输入的内容能通过系统级监听被包装成UserInputEvent送进 OpenClaw 的事件队列。这样智能体才能做到“全局唤起”和“上下文感知”。5.2 安卓 Termux 上跑的难点不是代码逻辑而是环境适配Termux 部署 OpenClaw 是社区里讨论不少的一个方向。手机跑服务端本质上是把安卓系统当作一个轻量 Linux 环境来用。从源码层面看OpenClaw 的核心代码基本能直接跑因为用到的库都是纯 Python 的不依赖桌面环境。真正的坑在环境依赖和权限上。我实际部署时踩过的几个问题可以归纳为下表问题点原因解决方式缺少编译工具链部分依赖需要编译安装在 Termux 里安装clang、python相关包端口监听受限安卓系统对本地服务有限制确认使用的是非特权端口路径差异安卓的文件系统结构与 Linux 不同修改配置里的日志文件和技能目录路径长时间后台运行被杀死系统进程管理机制导致使用 Termux 的唤醒锁或设置前台服务这些问题的共同特点就是源码逻辑没问题但环境适配不处理就会感觉全是毛病。如果你准备在手机上玩 OpenClaw我建议配置时把日志级别开到debug观察具体是哪个依赖加载失败再对症处理。5.3 跨平台代码里反复出现的那几行路径、编码、进程隔离通读 OpenClaw 的跨平台代码后我觉得最值得二次开发者借鉴的就是它对“环境差异”的封装方式。首先是路径处理。源码中所有涉及文件路径的地方都用了Path或os.path.join而不是手写/分隔符。这看似基础但在 Windows 上跑的时候一个手写的/路径能把整个配置加载搞挂。我自己曾经因为在配置里写死绝对路径导致 Windows 和安卓两端行为不一致排查了半天才发现是分隔符问题。其次是编码处理。Windows 的终端默认编码和 Linux 不一样OpenClaw 在utils/logger.py里做了兼容处理对所有输出强制使用 UTF-8。如果你二次开发时在 Windows 下看到乱码日志第一反应就该检查是不是输出编码被系统默认代码页覆盖了。最后是进程隔离。Windows 上调用系统操作往往需要创建子进程而子进程的环境继承问题会导致环境变量不一致。源码里封装了一个统一的环境变量注入接口保证子进程能拿到正确的配置。读到这里你会明白所谓“跨平台支持”不是写一份代码到处跑而是把每一个环境的差异点都封装到边界处让核心代码始终保持平台无关。6. 给二次开发者如何高效读懂代码、调试技巧和避免把自己绕进去6.1 我的调试链路从日志到单步追踪再到替换实现OpenClaw 的日志系统分得比较细调试时我通常按这样的顺序来先看启动日志确认配置加载和模型连接是否正常再开事件日志确认消息是否进入了事件队列接着看模型调用日志确认 prompt 组装是否符合预期最后看技能执行日志确认 Skill 是否被正确找到并成功执行这个链路每层都是独立的任何一个环节断掉日志都能明确告诉你是在哪一层。源码里这样的日志埋点意识非常强几乎每个关键入口都有logger.debug。这也是我建议所有开源项目都学的一点日志不是给你自己看的是给成千上万个部署者看的埋点位置决定了用户体验的下限。6.2 源码阅读路线图先读什么后读什么如果你第一次打开 OpenClaw 的源码我建议按照下面的顺序阅读不要从头到尾啃完第一站config.yaml—— 知道有哪些配置项对应哪些能力第二站core/events.py—— 知道事件类型有哪些理解系统边界第三站core/registry.py—— 知道技能如何注册这是扩展的钥匙第四站connectors/llm/base.py—— 知道模型接入的抽象第五站app.py—— 把前面几个模块串起来看整体流程这个路线的逻辑是“从配置到抽象从抽象到流程”避免像无头苍蝇一样在几千个文件里乱转。大概需要半天时间就能建立一个完整的心理模型之后再做二次开发就能直接定位到具体模块。6.3 实战中反复踩到的那几个坑提前帮你排掉最后分享几个我实际过程中整理的容易踩坑的位置。配置文件的缩进问题。在 YAML 配置里一个缩进错误不会直接报错而是会导致启动时配置加载成空值模型连接器拿不到参数报出一些奇怪的错误。遇到这种问题别急着怀疑代码先检查配置文件是不是合法 YAML。技能目录命名不一致。自定义 Skill 的目录名和 manifest 里的name字段如果不一致会出现“明明文件在却调用不到”的现象。源码里通过目录名发现技能但通过name字段来注册调用两条线的值不一致就会产生断连。使用模型接口但不兼容流式响应。如果你换了一个不流式返回的模型连接器可能会一直等待流结束才输出。源码默认开启了流式模式所以非流式服务必须在配置里显式关闭流式否则响应延迟会显得特别大。我可以说OpenClaw 的源码设计整体上非常克制它没有堆叠夸张的抽象层每个模块的定义都很清晰核心与扩展的边界划得很干净。这也是为什么它能在不同平台、不同模型之间保持一致的体验。如果你正在做一些智能体相关的项目哪怕是完全不使用 OpenClaw把它的模块划分思路和事件驱动模型抄一遍也足够你少走很多弯路了。这篇分析报告没有覆盖到所有细节但把主干链路走了一遍之后再回到文档看任何一项功能你都会觉得代码里的答案是明摆着的。