拆解OpenClaw：三层架构、技能插件与任务调度底层逻辑

1. 从一次任务卡死说起OpenClaw 三层架构到底解决了什么问题如果你用过 OpenClaw社区里常叫它“龙虾”跑稍微复杂一点的任务大概率遇到过这种场景让它“把项目里的日志文件按日期归档再生成一份周报”结果它执行到一半停住了既没报错也没继续终端里只剩一个光标在闪。你以为是模型的问题换了个更大的模型还是卡在同一个地方。这类问题的根因往往不在模型本身而在 Agent 的运行时调度链路。OpenClaw 之所以在同类框架里比较能打靠的不是接了多少模型而是它把“意图 → 规划 → 调度 → 执行 → 回传”这条链路拆成了清晰的三层运行时层Runtime、能力层Capability、接口层Interface。三层各管一摊互不越界任务卡住时你能定位到具体是哪一层出的问题。这篇文章面向两类人一是正在用 OpenClaw 做自动化任务、想搞懂它内部怎么跑起来的开发者二是准备基于 OpenClaw 写自定义技能插件、但被注册流程和调度参数绕晕的人。我会按“三层架构拆解 → 技能插件注册 → 任务调度链路 → 可复制配置 → 一次完整任务验证 → 常见报错排查”的顺序讲每个环节都给能直接抄的配置片段和命令。先给一个整体印象运行时层是心脏管生命周期和调度能力层是技能库管工具注册和模型适配接口层是对外窗口管 CLI、API、Web UI 和 MCP 协议。任务从接口层进来运行时层解析调度能力层提供具体工具执行结果再沿原路回传。理解这条链路你就能在任务卡住时快速判断是调度器没派活、还是插件没注册上、还是模型适配器返回格式不对。下面逐层拆。每层我都会给出关键模块、可观测的状态、以及你能动手改的配置点。2. 运行时层拆解事件总线、状态机与调度器如何协作运行时层是 OpenClaw 的执行引擎它不关心你调的是哪个模型也不关心工具是内置还是插件只负责把任务从“收到”推到“完成”。这一层有四个核心模块事件总线、状态机、资源管理器、调度器。它们之间的协作方式决定了任务会不会卡死、能不能并行。事件总线Event Bus是内部通信中枢。所有模块之间不直接调用而是通过发布/订阅事件来传递消息。比如一个工具执行完成会往总线发一个tool.completed事件文件被创建发fs.created出错发task.error。订阅者各取所需。这种设计的好处是解耦你新增一个技能插件不需要改调度器代码只要订阅自己关心的事件即可。坏处是调试时链路变长一个任务卡住可能是某个事件没人消费。状态机State Machine管理 Agent 的完整状态转换状态包括 Idle、Planning、Executing、Waiting、Error、Terminated。关键点在于任何时刻 Agent 只能处于一个状态状态转换有明确触发条件。比如从 Planning 到 Executing必须收到规划完成事件从 Executing 到 Waiting必须有一个工具调用发出且未返回。如果你发现任务“卡住”第一步就是看当前状态——如果停在 Waiting说明有个工具调用没返回如果停在 Planning说明模型没吐出可解析的规划。资源管理器Resource Manager管控文件句柄、网络连接、子进程、显存等。当资源接近上限时触发限流或降级。这一层最容易被忽略但它是长任务稳定的关键。比如你同时跑 10 个插件每个都开子进程资源管理器会限制并发子进程数超出的排队。调度器Scheduler负责任务优先级排序和并发控制支持 FIFO、优先级队列、依赖图调度三种策略。依赖图调度是重点当多个工具可以并行调用时调度器分析依赖关系最大化并行度。比如“读取 A 文件”和“读取 B 文件”无依赖可并行“汇总 A 和 B”依赖前两者必须等。下面是一段运行时层的配置示例放在config/runtime.toml[runtime] max_concurrent_tasks 4 state_timeout_seconds 120 event_bus_buffer 1024 [runtime.scheduler] strategy dependency_graph # 可选 fifo / priority_queue / dependency_graph max_parallel_tools 6 priority_weights { user 0.5, wait 0.3, resource 0.2 } [runtime.resource] max_subprocesses 8 max_open_files 256 memory_limit_mb 2048state_timeout_seconds是我建议你重点关注的参数。它表示某个状态停留超过这个秒数就判定超时并触发错误处理。默认值偏大长任务容易“假死”。我一般设成 120配合日志能快速发现卡点。调度策略选dependency_graph时调度器会先构建任务 DAG入度为零的进就绪队列执行完一个就把后继任务入度减一直到全部完成。这就是拓扑排序的落地。你可以通过日志里的scheduler.ready_queue和scheduler.in_degree观察调度过程。3. 能力层与技能插件从 tool_schema.json 到沙箱执行能力层是 OpenClaw 的扩展核心通过插件化架构实现按需加载。它包含四块内置能力、技能插件、模型适配器、工具注册中心。对开发者来说最常打交道的是技能插件和工具注册中心。一个技能插件是自包含模块标准结构是三个文件skills/ my_skill/ skill.md # 自然语言描述供 LLM 理解用途 tool_schema.json # 工具的 JSON Schema 定义 handler.py # 实际执行逻辑skill.md是给模型看的写清楚这个插件能做什么、什么时候用。tool_schema.json是给注册中心和模型看的定义参数类型。handler.py是真正干活的。下面是一个可复制的tool_schema.json功能是“按日期归档日志文件”{ name: archive_logs_by_date, description: 将指定目录下的 .log 文件按修改日期归档到 YYYY-MM-DD 子目录, parameters: { type: object, properties: { source_dir: { type: string, description: 日志文件所在目录的绝对路径 }, target_dir: { type: string, description: 归档目标根目录 }, dry_run: { type: boolean, default: false, description: 为 true 时只打印计划不实际移动 } }, required: [source_dir, target_dir] }, timeout_seconds: 60, idempotent: true }对应的handler.py骨架import os, shutil, json, sys from datetime import datetime def main(): args json.loads(sys.stdin.read()) src args[source_dir] dst args[target_dir] dry args.get(dry_run, False) moved [] for f in os.listdir(src): if not f.endswith(.log): continue full os.path.join(src, f) day datetime.fromtimestamp(os.path.getmtime(full)).strftime(%Y-%m-%d) target os.path.join(dst, day) if not dry: os.makedirs(target, exist_okTrue) shutil.move(full, os.path.join(target, f)) moved.append({file: f, date: day}) print(json.dumps({moved: moved, count: len(moved)})) if __name__ __main__: main()插件加载流程是Agent 启动时扫描skills/目录解析每个插件的元信息注册到工具注册中心规划阶段 LLM 查询注册中心选工具执行时插件在独立沙箱进程中运行结果通过标准输出返回由 Agent 解析后纳入上下文。这里有个关键点插件在独立沙箱进程执行意味着它崩了不会拖垮主进程但也意味着它不能直接访问 Agent 的内存状态。所有输入通过 stdin 传 JSON输出通过 stdout 回 JSON。这个约定必须严格遵守否则解析会失败。模型适配器Model Adapter抽象了不同 LLM 提供商的接口差异。OpenClaw 支持 OpenAI、Anthropic 以及国内的通义千问、DeepSeek 等。统一接口屏蔽底层差异你切换模型时不用改插件代码。如果你通过 TaoToken 这类聚合入口接入模型适配器配置会更简单因为 Base URL 和 Key 统一了。工具注册中心维护所有工具的元信息名称、描述、参数 Schema、权限要求、性能特征。规划阶段模型就是靠这些元信息决定调哪个工具。所以description写得好不好直接决定模型选工具的准确率。我踩过的坑是描述写得太笼统模型在多个相似工具间反复横跳任务规划阶段就耗掉大量 token。4. 任务调度链路从触发到执行完成的完整参数示例这一节把前三层串起来走一遍完整链路。任务生命周期分八个阶段接收、解析、分解、调度、执行、监控、汇报、归档。我们重点看调度和执行。调度器的核心是依赖解析。它用拓扑排序处理任务依赖构建 DAG → 入度为零的进就绪队列 → 调度器选取执行 → 完成后后继入度减一 → 重复直到全部完成。无依赖任务根据资源可用性决定并行数。优先级由三个因素决定用户指定优先级、等待时间、资源需求。权重在runtime.toml的priority_weights里配。默认user0.5, wait0.3, resource0.2意思是用户标记的紧急程度占主导但等太久的任务也会被提上来资源需求小的优先调度以提高吞吐。下面是一个调度参数示例放在config/scheduler.toml[scheduler] strategy dependency_graph max_parallel_tools 6 retry_on_failure true max_retries 2 retry_backoff_seconds 5 [scheduler.priority] high 10 medium 5 low 1 [scheduler.timeout] planning_seconds 90 tool_execution_seconds 120 total_task_seconds 900retry_on_failure和max_retries是实用参数。插件执行失败时自动重试避免偶发网络问题导致整个任务失败。但要注意只有idempotent: true的插件才适合自动重试否则可能重复副作用。任务从触发到执行完成的验证步骤我建议这样操作第一步确认插件已注册。启动 Agent 后查看注册中心日志openclaw agent start --config config/runtime.toml --log-level debug # 观察输出中是否包含 # [registry] loaded skill: archive_logs_by_date第二步用 CLI 触发一个单次任务openclaw run 把 /var/log/app 下的日志按日期归档到 /data/archive先 dry-run第三步观察状态机流转。日志里应该依次出现[state] Idle - Planning [state] Planning - Executing [scheduler] ready_queue: [archive_logs_by_date] [tool] archive_logs_by_date started (pid 12345) [tool] archive_logs_by_date completed in 0.8s [state] Executing - Idle第四步检查 dry-run 输出确认归档计划正确再去掉 dry-run 实际执行。第五步验证结果ls /data/archive/ # 应看到 2025-01-15/ 2025-01-16/ 等日期目录如果这五步都通过说明三层链路是通的。任何一步断了对照下一节的报错排查。5. 常见报错排查401、local proxy failed 与 reading choices这一节列几个真实高频报错以及对应的定位方法。这些报错我在不同环境都遇到过按下面的顺序查基本能解决。报错一401 Unauthorized[model_adapter] request failed: 401 Unauthorized这是模型适配器调用 LLM 时鉴权失败。检查三件套Base URL、API Key、Model ID 是否匹配。如果你用 TaoToken 接入Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 填你实际要用的模型名。三者任一不对都会 401。常见错误是 Base URL 多写了/v1或少写了路径或者 Key 复制时带了空格。报错二local proxy failed[model_adapter] local proxy failed: connection refused这个报错通常出现在你配置了本地代理端口但代理没启动或者端口被占用。检查配置里的代理地址是否可达。如果你没主动配代理检查环境变量里是否有残留的代理设置。清理掉不需要的代理配置让请求直连。报错三reading choices[model_adapter] failed to parse response: reading choices of undefined这是响应格式解析失败。模型适配器期望 OpenAI 兼容的响应结构含choices数组但实际返回的不是这个格式。原因通常是 Base URL 指向了非兼容端点或者 Model ID 写错导致返回了错误页。检查 Base URL 是否是 OpenAI 兼容接口Model ID 是否在服务端存在。用 curl 直接测一下curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d {model:your-model-id,messages:[{role:user,content:hi}]} | head -c 500如果返回里没有choices就是端点或模型名的问题。报错四OAuth 相关[model_adapter] oauth token expired部分模型提供商走 OAuth 流程token 过期需要刷新。检查你的凭据文件如~/.openclaw/auth.json里的 refresh token 是否有效。如果是 Codex 类接入auth.json里要包含完整的凭据字段。刷新后重启 Agent。报错五插件未注册[tool_registry] tool not found: archive_logs_by_date说明插件没被扫描到。检查skills/目录路径是否在配置里声明tool_schema.json是否是合法 JSONname字段是否和调用时一致。JSON 里多一个逗号都会导致解析失败注册中心会静默跳过。排查时记住一个原则先看状态机停在哪再看对应层的日志。停在 Waiting 查工具执行停在 Planning 查模型适配器停在 Executing 查调度器。6. 把三层链路用起来接入配置与后续验证理解架构的最终目的是能自己搭起来跑通。如果你还没接入模型最快的路径是先把模型适配器配好再验证一次简单任务确认三层链路通畅然后再去写自定义插件。模型适配器的接入配置核心就是三件套。以 TaoToken 为例在config/model.toml里[model] provider openai_compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_id your-model-id timeout_seconds 60 max_retries 2把TAOTOKEN_API_KEY写进环境变量model_id换成你要用的模型。配好后用上一节的 curl 命令先验证端点通不通再启动 Agent。如果你要长期跑编码类或 Agent 类任务建议用 Coding Plan 这类按量方案避免单次调用成本失控。验证模型是否正常可以直接在模型对话里发一条测试消息确认返回结构里有choices。接入文档里有完整的参数说明和示例遇到配置项不确定时对照查一遍比在日志里猜快得多。最后给一个实用技巧把runtime.toml里的state_timeout_seconds调小配合--log-level debug启动任何任务卡住你都能在 2 分钟内从日志里定位到是哪个状态、哪个工具、哪个事件出的问题。这比反复换模型有效得多。Agent 的稳定性从来不取决于模型多大而取决于这条三层链路有没有被你看清楚。