OpenClaw目录结构详解：从引擎到技能的可插拔设计

拿到一份OpenClaw的源码仓库，我一般不会先刷README，而是直接敲tree。目录结构就是一篇文章的目录，透过它你才能真正看懂这个项目想干什么、能干什么、扩展点在哪里。很多朋友私信问我OpenClaw怎么部署、怎么接Ollama、怎么写skill，我通常都会先让他们把目录结构过一遍，因为八成的问题其实都出在对目录的理解上。这篇我就把OpenClaw的目录结构从头到尾拆一遍：每个顶层目录的职责、关键文件的作用、哪些能改哪些不能乱动，以及在不同部署场景下目录会发生什么变化。

1. OpenClaw目录结构的设计哲学：分层与可插拔

1.1 从单体脚本到模块化框架

早期很多类似的个人智能体项目，都是一个main.py从头写到尾，里面塞满了模型调用、Prompt模板、各种工具函数。功能少了还能跑，一旦要加第二个技能、换一个底模、接一个机器人仿真环境，代码就开始互相纠缠，改一行能蹦出一串问题。OpenClaw从一开始就把自己定位成一个可扩展的智能体运行框架，所以它的目录结构也是围绕扩展性来设计的。

你可以把这套结构想象成一家餐厅：core是后厨的灶台和出餐流程，skills是厨师手里的菜谱，providers是给后厨送食材的供应商，storage则是冰箱和冷藏室。菜谱可以随时换，食材供应商也可以换，只要灶台本身稳定，餐厅就能正常运转。这种分层的好处在于，模块之间只通过约定好的接口通信。比如providers目录里每一种模型服务都要实现同一个chat接口，上层业务根本不需要知道当前用的到底是本地Ollama，还是某个云服务商的API。目录在这里不只是为了好看，它本质上就是把架构设计直接落在文件系统里了。

1.2 一句话记住核心目录

OpenClaw的根目录并不复杂，顶层就是五个：

openclaw/ ├── app/ # 主程序：引擎、Agent、技能、模型适配、存储 ├── config/ # 所有配置文件 ├── data/ # 运行时数据：数据库文件、日志、临时文件 ├── scripts/ # 安装、部署、维护脚本 └── tests/ # 自动化测试

先记住这五个，就不会走偏。app是你日常开发的主战场，config是你调参的地方，data这个目录建议永远不要手动改，scripts里提供的是日常操作的入口，而tests属于保命用的，每次改动之后跑一遍就知道有没有把已有功能搞坏。后面提到的所有子目录，几乎都落在app下面。先有顶层鸟瞰图，再钻进具体细节，读代码的效率会高很多，排查问题也不再像无头苍蝇一样到处翻。

2. 根目录：入口、依赖与配置的解耦

2.1 main.py 与 pyproject.toml

在OpenClaw根目录里，两个最重要的文件是main.py和pyproject.toml。main.py是整个进程的唯一入口，它做的事情很少：加载config目录下的配置，初始化core引擎，然后启动事件循环。很多新手喜欢在main.py里写自己的业务逻辑，这是第一个要避开的坑。main.py必须保持“薄”，一旦它变厚，后面调试、跑测试、切换部署环境都会非常难受。如果你是从FastAPI项目转过来的，会发现这个思路很熟悉：入口只负责创建application对象并暴露给启动命令，真正的逻辑都放在app包里。

pyproject.toml负责管理项目依赖和打包元数据。建议无论多小的项目都不要用requirements.txt硬顶着，因为OpenClaw的安装和部署脚本会优先读取pyproject.toml，只有一些历史兼容场景才会看requirements.txt。另外，pyproject里的依赖分组也值得关注，比如src、dev、ros、mobile这些extra，按需安装比全量安装省心得多。安装时用pip install -e .[ros]只装ROS2扩展，目录会干净很多。

2.2 config/ 下那些yaml文件

config目录是OpenClaw整个项目里改动最频繁的地方。主配置在config/config.yaml，里面定义系统级参数，比如日志级别、HTTP端口、Agent默认角色、技能调用超时时间。其他文件按领域拆分，我通常见到的布局是这样：

config/ ├── config.yaml # 系统主配置 ├── skills.yaml # 技能开关与默认参数 ├── providers.yaml # 模型供应商配置 └── logging.yaml # 日志格式与输出目标

拆文件不是随意的。主配置只管那些跟业务无关的稳定性参数，比如监听端口、工作线程数；providers.yaml只存放模型服务地址和密钥；skills.yaml控制哪些技能启用、哪些默认禁用。这样拆的核心原因和12-Factor应用的理念一样：配置与代码分离。你换一个部署环境时，不需要改动app/下的任何Python文件，只需要调整yaml里的参数即可。

2.3 .env 与环境变量注入

根目录下的.env.example不是摆设，它列出了所有适合在部署时手动注入的环境变量，比如数据库连接串、Ollama服务地址、云服务API Key的变量名。OpenClaw加载配置的优先级是：真实环境变量优先于.env文件，.env文件优先于config下的yaml。这种设计在服务器部署时特别有用，你不需要把密钥写在会被提交到Git仓库的yaml文件里。

我在实际部署中踩过坑：改了config.yaml里的模型名，但进程没重启，OpenClaw启动时才会一次性读取配置，所以一直走的是旧配置。部分新版本支持openclaw config reload热加载，但大多数场景下最稳妥的流程还是“改配置、保存、重启”。另外，.env文件不要提交进Git，.env.example才应该提交。很多开源项目把这项写进.gitignore，OpenClaw也是这样，一旦你把真实.env推上去了，密钥泄露只是时间问题。

3. app/core：智能体引擎的心脏

3.1 引擎、事件总线与任务队列

进入app目录之后，第一眼要看的不是skills，而是core。core里保存着整个框架最核心的机制，目录大致如下：

app/core/ ├── engine.py # 引擎生命周期管理 ├── events.py # 事件类型定义 ├── bus.py # 事件总线 ├── task_queue.py # 异步任务队列 ├── scheduler.py # 定时任务调度 └── plugin_loader.py # 技能扫描与注册

engine.py负责启动、停止、崩溃恢复这些生命周期动作。bus.py是事件总线，它是OpenClaw能够“让所有模块都有机会响应消息”的关键。你给智能体发一句话，总线把消息广播出去，所有订阅了这个事件的Agent都会收到，Agent再决定要不要调用某个skill。task_queue是异步任务池，耗时的技能调用会被丢进队列里去跑，不阻塞主线程。如果你要做一个“每天定时抓取电商价格并推送”的功能，大概率就要同时研究scheduler和task_queue。

3.2 插件加载器如何扫描skills

plugin_loader是整套可插拔架构的功臣。它启动时会扫描app/skills目录下的每一个子目录，读取技能描述文件，然后把可用的技能登记到内存注册表里。这个扫描动作并不是简单遍历一下目录，它还会做依赖检查和冲突检测：如果某个技能声明了需要requests，而当前环境没安装，这个技能会被标记为禁用，并在启动日志里给出一行警告。

我见过不少人把自定义技能放错位置，放在app根目录或者其他临时目录，结果加载器永远扫不到。技能目录必须直接放在app/skills/下面，每个技能一个子目录，目录名就是技能ID。这一步看着简单，但搭错了整个技能体系都起不来，属于“目录结构直接决定功能是否可用”的典型例子。另外，技能目录内部不要嵌套太深，plugin_loader默认只扫描一层，如果你在技能目录下又套了一层，加载器会认为那是一个后续需要手动加载的子模块。

3.3 核心引擎的修改边界

core是改动成本最高的地方，不建议常规业务去碰它。OpenClaw社区早期有人为了加一个“特殊前缀触发某技能”的功能，直接在bus.py里写了硬编码，结果后续升级时跟官方补丁冲突，整个分支都废掉了。正确做法是把这类触发逻辑放到Agent层，或者写成一个新的skill去监听事件。如果确实觉得某个引擎行为不合理，优先去官方仓库的issue里确认一下新版本是否已经支持，而不是自己动手魔改。

我自己的习惯是：core目录只读，除非在做二次开发级别的定制。日常加功能、调行为，都在skills、agents、providers这三个目录里完成。这样升级OpenClaw版本时，只需要处理config和skills的兼容问题，几乎不用担心core冲突。把这个边界守住，你手头的分支就能长期跟上游同步，不会越改越累。

4. app/skills：技能插件的标准姿势

4.1 一个skill的标准目录结构

skill是OpenClaw可扩展性的灵魂，也是大家最关心的目录。每个技能独立成子目录，推荐结构如下：

app/skills/web_search/ ├── manifest.yaml # 技能元信息：名称、入口、权限 ├── __init__.py # Python包标识 ├── handler.py # 核心处理函数 ├── requirements.txt # 技能独立依赖 └── assets/ # 静态资源：模板、词典、小工具脚本

manifest.yaml是加载器判断技能是否合法的关键。里面至少要有name、version、author、description、entry这五个字段，entry指向处理函数的完整模块路径。很多新手在entry里写成相对路径“handler.run”，加载器是不认的，正确写法是“skills.web_search.handler.run”。这个细节在官方文档里有，但特别容易被忽略，而且一旦写错，日志里只会出现一句“skill ignored”，不会明确告诉你是entry写错了。

4.2 技能注册与依赖隔离

技能的启用状态在config/skills.yaml里管理。你可以把配置文件理解成技能总开关：manifest只是把技能接入了系统，到底通没通电，还得看当前环境的enable列表。这样设计的好处是，仓库里可以保留大量默认不启用的技能，部署时按需打开，不浪费一点资源。

依赖隔离同样重要。每个skill的requirements.txt不会在OpenClaw主安装时自动安装，你需要运行openclaw skill install <名字>，或者直接执行scripts/install_skill.py。安装脚本会把该技能声明的依赖合并进虚拟环境，并检查版本冲突。如果不走这个流程，直接全局pip install，很容易把系统环境搞乱，多个skill互相覆盖包版本。我在维护一个多技能实例时，就踩过A技能升级了requests、把B技能搞挂的坑。从那时起，我坚持每个skill尽量少引第三方库，能用标准库解决就别偷懒。

4.3 电商类skill的实战拆解

热搜词里出现“openclaw电商”，可见不少人拿它做比价、订单跟踪、店铺数据这类自动化场景。电商类skill的目录通常会比通用技能多两个模块：一个是适配电商平台API的client，一个是把不同平台返回结构统一成内部标准的normalizer。目录长这样：

app/skills/ecommerce/ ├── manifest.yaml ├── handler.py # 对外入口 ├── platforms/ │ ├── _base.py # 平台适配基类 │ ├── shop_a.py │ └── shop_b.py ├── normalizer.py # 结果统一结构 └── requirements.txt

为什么要单列platforms目录？因为各电商平台的API参数、签名方式、返回字段差异很大，但OpenClaw内部只需要一种“商品信息对象”。把适配和标准化分开后，新增一个平台就只需要在platforms下新增一个文件，handler完全不用动。这也是目录结构引导你写出可维护代码的典型例子。如果你做的电商技能涉及登录状态，不要把Cookie写进代码里，放进config或环境变量，这是另一个层面的安全问题，但目录结构可以帮你天然隔离掉这种隐患。

5. app/providers：模型接入层，绕不开的Ollama

5.1 providers目录要解决的问题

OpenClaw本身不内置大模型，它把模型服务统一收敛到providers目录。这样设计是为了回答一个核心问题：你的Agent底层到底用本地模型还是远程API，这件事不能影响上层业务。providers目录通常包含这些文件：

app/providers/ ├── base.py # 统一接口定义 ├── ollama.py # Ollama本地推理接入 ├── openai_compatible.py # 兼容OpenAI的API ├── web_api.py # 其他HTTP API封装 └── registry.py # 供应商注册与回退逻辑

base.py里会定义chat、embed、tools_list这类基础方法，所有具体provider都要继承并实现。registry.py负责根据config里设置的active_provider值返回对应的实例。这样你在agents和skills里拿到的是一个统一的provider对象，根本不用关心当前跑的是Ollama还是云端API，切换底模对业务代码完全无感。如果你要新增一个本地推理引擎，比如vLLM，直接在providers目录下新增一个适配文件并注册进来就行。

5.2 Ollama本地模型与配置位置

用Ollama部署OpenClaw是当前很主流的一种玩法。配置上，先在providers.yaml里指定默认供应商：

providers: active: ollama ollama: base_url: http://127.0.0.1:11434 model: qwen2.5:7b temperature: 0.7 num_ctx: 8192

base_url是Ollama服务地址，默认端口11434。如果你在本机同时跑OpenClaw和Ollama，用127.0.0.1就够了；如果Ollama跑在另一台机器或Docker容器里，这里要改成实际可达的IP或域名。num_ctx是上下文窗口长度，直接影响长对话下的显存占用，新手很容易忽略这个参数，导致Ollama在高并发时OOM。这些参数都在providers目录之外，通过配置文件控制，正好体现目录分层的价值：改模型参数不用改代码，改代码不用碰模型参数。

5.3 “只能用API算力吗”的答案

很多人在搜索“OpenClaw只能用接入API的方式使用算力吗”，答案是否定的。OpenClaw的providers目录同时支持本地推理和远程API两类接入。本地推理的代表就是ollama.py，它通过Ollama推理引擎直接调用本机的CPU或GPU算力，不需要任何云端服务；远程API则走openai_compatible.py或web_api.py。这个双轨制恰恰是OpenClaw目录结构里最值得琢磨的地方，它把“算力来源”彻底抽象成了可替换的组件。

从实践看，我的建议是：追求隐私、离线可用、不想按量付费，就用Ollama；追求当前最强大模型能力、不在乎按量付费，就接云端API。甚至可以在同一个实例里配置多个provider，通过config切换，或根据任务类型调用不同供应商。只要providers目录不坏，切换模型的成本几乎为零。

6. agents与storage：角色状态和记忆

6.1 agents目录怎么组织

agents目录存放Agent角色与行为策略。Agent可以理解为“带着人设和决策逻辑的大脑”，它决定在什么时机调用哪个skill。典型结构如下：

app/agents/ ├── base.py # Agent公共基类 ├── state_machine.py # 对话状态机 ├── registry.py # 角色注册表 └── builtin/ ├── assistant/ # 通用助手 ├── translator/ # 翻译角色 └── robot_operator/ # 机器人控制角色

每个Agent目录里通常有一个描述文件，比如agent.yaml，定义角色预置、系统提示词和默认策略，另有一个策略文件决定它是直接触发skill还是带条件判断。state_machine是复杂对话场景的核心，比如“先收集参数再调用电商查询技能”这一步骤，就是一个状态流转。如果只需要普通聊天助手，用builtin里的assistant就够了；要自定义人设，千万别改builtin，直接在app/agents/下新建角色目录，升级时不用担心冲突。

6.2 memory和db存储分层

记忆系统决定了OpenClaw能不能记住上下文。在目录层面，记忆相关代码集中放在app/storage/：

app/storage/ ├── memory/ │ ├── session.py # 短期会话记忆 │ └── vector.py # 向量存储接口 ├── db.py # 数据库读写封装 └── cache.py # 缓存接口

session.py管理一次对话里的历史记录，vector.py负责把长期记忆向量化，比如存入本地向量数据库。db.py是关系型数据的统一入口，OpenClaw默认使用SQLite，配置成PostgreSQL也不会太难。任务状态、技能调用日志这类业务数据，都会走db.py，所以data目录里会出现类似openclaw.db的文件。记忆策略要在配置里统一指定，而不是每个skill各搞一套存储。统一接口的好处是，以后从SQLite换到PostgreSQL，skills层完全不感知。

6.3 data/目录的坑

data/是运行时生成的数据目录，里面除了数据库文件，还有日志、临时上传文件、向量索引。这个目录最需要注意两点：一是别提交进Git，二是别手动往里乱放东西。正确做法是在.gitignore里加上data/，让每个部署环境自己初始化数据。我见过有人把模型权重下载到data目录里，导致仓库体积迅速膨胀，每次克隆都要拉下来一堆根本不该进版本库的二进制文件。

还有一个很容易被忽略的点：data/目录的读写权限。在Linux服务器上跑OpenClaw时，如果进程用户对data没有写权限，启动时会报数据库初始化的错误。这个错误和代码没关系，纯粹是目录权限问题，但排查起来很费时间。所以我把chmod和data目录检查直接写进部署脚本，确认可写了再启动主程序。目录权限这类小事，往往比逻辑bug更能消耗人的耐心。

7. 跨平台部署：ROS2与Termux目录差异

7.1 ros/机器人集成目录

OpenClaw不只是一个跑在服务器上的聊天程序，在ROS2场景里它还能担任机器人的决策节点。为了不把机器人桥接代码污染进主程序，仓库里专门保留了ros/目录：

ros/ ├── bridge/ # Topic/Service 桥接层 ├── actions/ # ROS2 Action 定义与客户端 ├── launch/ # 启动文件 └── models/ # 自定义消息类型

bridge的作用是把OpenClaw的事件转换成ROS2消息，再发布到/cmd_vel这类Topic上。在Gazebo仿真环境中，先用roslaunch启动仿真世界，再启动OpenClaw的桥接节点，Agent就能读仿真里的传感器消息，并输出控制指令。这套流程听起来复杂，但目录把职责切得很清楚：app里不直接import rclpy，而是通过ros/bridge做适配。以后升级ROS2版本，只需要动ros目录，核心智能体逻辑可以原样保留。搜索里的“rosclaw openclaw ros2 humble gazebo”指的就是这套组合玩法。

7.2 mobile/与Termux部署

Termux能在安卓上提供Linux环境，于是很多人在手机上头安装OpenClaw，这就是mobile/目录存在的意义。它在仓库里的位置大致是：

mobile/ ├── termux/ │ ├── install.sh # 一键安装脚本 │ ├── run.sh # 启动脚本 │ └── storage_path.env # 安卓存储路径映射

安卓上的文件目录和服务器完全不一样，不能把data/直接放在App私有目录里，否则系统清理缓存时数据可能就没了。install.sh通常会在Termux的存储权限目录下建立openclaw_data，然后通过storage_path.env把data目录映射过去。这个流程不是改Python代码，而是改环境变量和软链接。所以你在手机安装OpenClaw时，不要按PC路径死记硬背，先跑一下install.sh，确认它把data放到了哪里，再做后续配置。

7.3 不同部署形态对目录结构的影响

服务器部署时，完整的app、config、data、scripts是最佳形态；Termux部署时，tests和ros目录完全可以裁剪掉以节省空间，mobile/termux/install.sh会自动处理；机器人部署时，需要额外保留ros目录并安装对应的ROS2依赖；电商应用部署时，重点配置skills/ecommerce和providers.yaml。目录的选择性组合能力，是OpenClaw比较舒服的地方：它不是“一套代码跑天下”，而是“一套框架，按场景裁剪目录”。

从传统项目迁移过来的朋友可能会问，这跟SpringBoot或FastAPI的目录结构有什么本质区别？我的理解是：FastAPI项目通常按“接口层-服务层-存储层”纵向切，OpenClaw按“引擎-技能-模型-记忆”横向切，核心不是请求处理，而是能力编排。你不需要把OpenClaw硬套Web项目的MVC结构，它的目录就是为Agent场景设计的。下表可以快速看出不同场景下的目录取舍：

8. 常见问题与排查技巧实录

8.1 skill不加载，先查这三处

我遇到最多的问题是自定义skill明明写了，但OpenClaw就像没看见一样。这时先依次排查三处：第一，skill目录是否直接放在app/skills/下面，目录名是否和manifest里的name保持一致；第二，manifest.yaml里的entry字段是否写成了带完整包路径的方式；第三，config/skills.yaml的enable列表是否包含这个技能。这三处只要错一个，插件加载器就会跳过。用openclaw skill list命令能看到当前被识别的技能列表，比靠猜快很多。

下面这张小表是我常用的排查定位表，遇到症状直接对号入座：

8.2 配置改了没生效？缓存与权限

配置没生效多半不是缓存诡异，而是改错了文件，或者权限不对。前面提过加载优先级，环境变量会覆盖yaml，所以先检查系统里是否设置了同名环境变量。另一个常见问题是YAML缩进。YAML对缩进极其敏感，特别是providers.yaml里嵌套多层配置时，少两个空格就会解析失败。OpenClaw启动时会打印配置解析错误，这类日志很容易被忽略，看到“ConfigParseError”别慌，去检查缩进即可。

还要注意config目录的权限。如果配置目录被改成只读，OpenClaw启动时也许成功，但写缓存文件会失败，表现为配置看起来没有被加载。Linux下用ls -l config/看权限，必要时用chmod修正。这些都是五分钟能解决的排查路径，但我见过有人花了一下午去改Python代码，最后发现只是yaml文件里多了一个Tab。YAML规范里禁止用Tab缩进，这也是一个老生常谈但要反复强调的坑。

8.3 目录速查命令与维护技巧

最后分享一套实用的目录速查命令。在OpenClaw根目录执行：

tree -L 3 -I '__pycache__|*.pyc|.git|data'

这条命令能快速看到三层以内的完整目录结构，同时过滤掉缓存和运行时目录。维护上，我建议每次大版本升级之后，用tree导出一份结构，和官方文档里的参考结构做diff，能及时发现目录里多出来的模块或丢失的文件。尤其在多分支并行开发时，目录结构diff比代码diff更能暴露架构漂移。目录整洁不是洁癖，它是降低长期维护成本最实惠的手段。

我个人实际操作的体会是，目录结构这个东西，第一眼感觉只是文件夹排列，用久了才发现它一直在默默约束着你的设计。我在OpenClaw上踩过几次坑之后，现在每接手一个新环境，会先把config和providers两个目录读完，再看skills开关，最后才去跑功能。如果你也是刚接触OpenClaw，建议不要想着“等需求来了再研究目录”，先花半小时把顶层结构过一遍，然后在data下建一个sandbox目录去试第一个skill。目录顺了，后面的部署和调优大概率也顺，希望这篇拆解能帮你少走一段弯路。