这期接着聊 openclaw。先解释标题里那句“文件即真理流程即文件”在 openclaw 这套 AI Agent 框架里agent 的记忆、任务状态、工具定义、配置参数全部都是磁盘上的文件而 agent 每一步的执行流程、思考过程、工具调用序列也全部以可读的文本文件形式存在。你打开它的工作目录就能看到这个 agent 当下在想什么、接下来打算干什么、每一步调了哪些工具。把 workspace 整个摊开就像把一个黑盒拆成了透明玻璃盒。这篇是系列第 4 篇面向两类人一类是已经部署过 openclaw、想深入源码搞清楚它内部怎么运转的另一类是还没上手、正在挑一个能完全掌控的 AI Agent 框架来落地自己业务的。我会从整体架构、核心模块、算法调度、代码实现、部署实操和踩坑记录这几个角度完整走一遍涉及到配置和代码的地方会尽量给出可以直接复制改用的版本。openclaw 的代码量不算大但它把一个 agent 该有的东西都装全了模型交互、任务规划、工具调用、记忆存储、文件系统抽象。把这些东西一层层拆开你会发现自己也能照着搭一套。1. openclaw 整体设计为什么“文件即真理流程即文件”1.1 传统 Agent 与 openclaw 的架构差异先说一个很多人对 AI Agent 的误解以为 agent 就是把大模型接上一个 API用户问一句模型答一句。真这么简单的话市面上就不会有那么多部署翻车的案例了。传统 Agent 框架通常把状态放在内存里任务进行到一半进程崩溃所有上下文全丢工具调用逻辑靠硬编码加一个工具就要改代码日志散落在控制台和数据库里想复盘一次完整的任务推进过程几乎不可能。openclaw 换了思路它的设计哲学非常朴素凡是值得记录的东西都写成文件。agent 的当前任务状态、历史记忆、工具描述、模型配置、执行日志全部以结构化文件的形式存在项目目录里。这样做带来三个直接收益第一进程崩了可以从文件恢复状态agent 重启之后还能接着干第二所有决策过程都可审计你可以翻文件看它为什么选这个工具、为什么拒绝那次调用第三二次开发门槛骤降改配置就等于改文本不用重新编译、不用热部署框架。我在拆源码的时候最大的感受是openclaw 更像一个“项目经理”而不是“聊天机器人”。项目经理手里永远有一份项目文档记录当前进度、待办事项、资源清单。openclaw 的工作目录就是这份项目文档每次决策都要先读文件、做完事再写回文件。相比之下很多 agent 框架像那种全凭脑子的临时工聊得挺好一断电全忘光。1.2 “文件即真理”的工程含义“文件即真理”这句话可以拆成三层来理解。第一层是状态持久化。openclaw 会把当前任务拆解成一个个 step每个 step 的执行状态pending、running、done、failed都记录在状态文件里。我一开始不理解为什么不用数据库后来用下来明白了对 agent 这种需要频繁读写小体量结构化数据的场景文件系统反而比数据库更合适。没有连接池、没有 schema 迁移、没有权限问题一个文本编辑器就能完成全部运维操作。任务中断后agent 会扫描这些状态文件知道自己做到哪一步然后从断点继续。第二层是配置即代码。模型参数、超时时间、重试次数、工具白名单这些全部以配置文件形式存在。我碰见过很多框架喜欢把配置塞进环境变量十几个变量名能记到你怀疑人生。openclaw 的做法是集中写到配置文件里字段一目了然改动直接生效不需要重启服务就能被 agent 感知到。它在启动时读一次配置然后在每次任务循环里也会周期性检查配置文件的更新时间发现变了就重新加载。第三层是日志即真相。openclaw 的每一次模型调用、每一次工具执行、每一次状态变更都会追加到结构化日志文件里。这不是普通意义上的运行日志而是包含完整上下文的操作记录。你可以像读剧本一样回放一次任务的完整执行过程这也给后来做性能分析和 bug 定位提供了极大便利。我后文讲代码阅读技巧时会再展开这里先记住一个结论遇到问题先翻文件不要急着打日志断点。1.3 “流程即文件”的执行模型再来看“流程即文件”。openclaw 的任务执行不是一个隐藏在二进制里的死循环而是把每一步“动作”都描述成文本再把文本按顺序执行。具体来说当用户给 agent 一个目标它会先把目标拆解成若干子任务每个子任务对应一个流程文件或者叫 task 文件。这个文件里记录了任务的描述、依赖关系、当前状态、需要调用的工具和参数。agent 拿到这个文件后读一遍执行其中的指令然后把结果写回文件再进入下一个文件。整个过程像工厂里的流水线工单工单是文件工人是 agent工单流转到哪里agent 就干到哪里。这种设计的妙处在于流程本身可以被修改。如果你发现 agent 对某个任务的拆解不合理可以直接编辑流程文件把不合适的步骤删掉或者调整顺序再让 agent 重新读取。我在调 openclaw 的时候经常这么干agent 偶尔会钻牛角尖把一个简单任务拆成七八步我就在文件里手动把它合并成两步效果立竿见影。传统框架里你要改流程逻辑得去改源码里的状态机改动代价完全不是一个量级。执行文件还有一个隐藏优势支持部分重放。某个步骤执行失败了你可以只重跑后续步骤不用整个任务从头再来。这背后依赖的还是“每一步都有文件记录”的设计这一步的输入输出来龙去脉全在文件里单独拎出来执行没有任何障碍。2. 核心结构与模块拆解openclaw 的骨架和血肉2.1 从入口到出口openclaw 的主循环现在进入代码层面。openclaw 的主循环说白了就是一个“感知-决策-行动”的循环跟强化学习里的 agent-environment loop 非常像。完整流程可以概括成六步接收输入、识别意图、规划任务、调用工具、归纳结果、更新状态。接收输入这一步没啥特别的支持终端、网页、聊天平台多个入口。重点是第二步意图识别它会先把用户输入和模型对话历史一起打包发送给底层大模型让模型判断当前请求的类型是一次普通问答还是一个需要拆解的多步骤任务。这个判断结果会直接影响后面的流程分支。第三步任务规划是关键中的关键。openclaw 会让大模型把复杂目标拆解成子任务每个子任务都明确标注需要的工具和预期输出。这个拆解结果会写到文件里形成上文说的流程文件。我当时读到这里就想明白了一件事为什么 openclaw 强调“流程即文件”因为规划的结果本来就应该是一个可持久化、可修改、可验证的东西而不是内存里一段随时可能丢失的临时数组。第四步调用工具时openclaw 会先在工作目录里扫描可用工具列表然后根据任务描述做匹配。工具匹配的算法细节我在第三章展开。调用结果会返回给大模型由第五步归纳成阶段性结论再决定是进入下一个子任务还是直接输出最终答案。最后一步更新状态把整个任务的完成情况写回文件整个循环结束。这个主循环的代码并不复杂复杂的是每一环都留了足够的扩展接口。比如工具层可以随时新增脚本模型层可以随时切换供应商文件层可以对接不同的存储后端。这也是 openclaw 能在这么短时间里出现大量衍生产品的原因骨架搭得足够干净。2.2 工具注册与调用层openclaw 里有一个统一的工具抽象层所有外部能力都以“工具”的形式存在。工具可以是本地命令行脚本可以是 HTTP API 调用也可以是 Python 函数。每个工具都有一个描述文件包括工具名称、功能说明、参数 schema、运行方式、超时设置。agent 在做任务规划时会读取这些描述文件把工具当作可调用的“函数”来使用。工具描述文件的存在让 openclaw 具备了动态扩展能力。你想给它加一个“查天气”的功能不需要改任何源码只要在工具目录下新建一个描述文件写清楚调用方式agent 下一次规划任务时就能发现它。我在实际使用中加过不少自定义工具比如查数据库、调内部 API、执行定时任务都是几分钟搞定。工具调用层还有一个值得关注的设计错误处理。openclaw 对工具调用失败有一套内置的降级策略。第一次调用失败它会读取错误信息交给大模型做判断让模型决定是修改参数重试、换一个工具还是直接放弃这个子任务并向上报告。这个机制我后文讲算法的时候会重点分析它本质上是一个带反馈的决策过程而不是简单的 try-catch。从目录结构看openclaw 的 tools 目录通常分两类内置工具和自定义工具。内置工具负责文件读写、命令执行、网络请求这些基础能力自定义工具则是用户根据业务场景添加的。两者在调用层面没有区别都走同一个描述-匹配-执行-返回的链路。2.3 模型接入与配置体系openclaw 本身不生产模型它只是一个调度框架所以模型接入层做得非常灵活。很多人问 openclaw 是不是只能用某些固定的大模型答案是否定的。它通过一个统一的 LLM Client 接口对接不同供应商只要实现这个接口就能接入任何模型。配置体系集中在模型配置文件里核心字段大致包括这几项模型供应商类型、接口地址、模型名称、API Key、温度参数、最大 token 数、超时时间。openclaw 在启动时会读取这些配置然后在每次模型调用时把配置项注入请求。最常用的场景是关联本地部署的开源模型比如 qwen2.5-3b。具体方法是先通过 Ollama 或者 vLLM 把模型挂到本地端口然后在 openclaw 的配置文件里把接口地址填成http://127.0.0.1:11434或对应端口把模型名称填成qwen2.5-3b即可完成关联。这里有个很实用的细节模型配置是可以配多个的。openclaw 支持主模型和辅助模型分离主模型负责复杂推理和任务规划辅助模型负责简单分类和摘要。因为简单任务用大模型纯属浪费算力拆分之后整体响应速度和成本都会有明显改善。我第一次看到这个设计觉得挺惊喜这已经不是玩具框架的思维了而是考虑生产环境成本优化的思路。配置文件的改动是热生效的。openclaw 会定期检查配置文件的修改时间戳一旦发现变化就重新加载配置不需要重启整个服务。实测下来这个机制很稳定我在调整模型温度参数的时候改完文件等几秒后续请求就自动用新参数了。3. 算法与代码机制解析从调度到底层实现3.1 工具选择的算法逻辑枚举、贪心与剪枝openclaw 的执行引擎里最值得研究的是工具选择的算法逻辑。虽然表面上看工具调用就是大模型给一个 JSON里面写着工具名和参数但框架在这背后做了一层算法决策而不是把选择权完全交给模型。先看最简单的情况候选工具集合很小。当系统里只有三四个工具时openclaw 会使用一种类似暴力枚举的思路把所有工具的描述文件都读出来构建一个候选列表让模型在这个小范围内做选择。这种做法的好处是信息无损每个工具的完整描述模型都能看到不会因为截断或遗漏导致误判。这就像你去一家只卖几种菜的小饭馆老板直接把所有菜单摊开你随便挑不用纠结。候选工具一多枚举就不行了。几十个工具的描述文件全部塞给模型既超 token 限制又会干扰模型注意力。这时候 openclaw 会启用贪心策略先根据任务描述做一次关键词提取再用关键词对工具描述进行相似度排序只把排名靠前的几个工具描述发给模型。这个贪心体现在“只看局部最优”不求全局最优但换来的是响应速度和成本的大幅下降。实测下来工具数量在 20 个以上的场景这种策略能把 token 消耗减少一半以上同时保持不错的工具命中率。还有一些场景会用到剪枝策略。比如任务附带明确约束条件时openclaw 会先做一轮硬性过滤不满足条件的工具直接剔除根本不进入模型的选择范围。这相当于下棋的时候先砍掉明显不合理的走法再让棋手在可行范围里思考。剪枝的依据通常包括权限限制、参数 schema 匹配、运行环境要求、资源配额。我在给 openclaw 接入内部 API 时专门加了权限标记让某些敏感工具只在特定任务上下文里出现避免模型误调用这就是剪枝思路的实际应用。3.2 主循环的代码级实现与 ReAct 范式openclaw 的任务执行主循环本质上就是这几年大模型 Agent 领域非常经典的 ReAct 范式Reason Act 交替进行。每一轮循环里模型先根据当前状态推理决定下一步动作然后执行动作观察结果再推理再行动。openclaw 把它工程化得很干净核心逻辑用伪代码可以表示如下def run_agent(task_file, workspace): state load_state(workspace) # 从文件加载当前状态 while not state.is_finished(): prompt build_prompt(state, task_file) # 组装模型输入 plan llm.reason(prompt) # 模型推理得到计划 if plan.is_final_answer(): # 模型认为任务完成 answer plan.get_final_answer() state.set_finished(True) save_state(workspace, state) return answer tool_name plan.get_tool_name() # 选择要调用的工具 tool_args plan.get_tool_args() result execute_tool(tool_name, tool_args, workspace) state.add_step(tool_name, tool_args, result) # 记录执行结果 save_state(workspace, state) # 状态落盘这段伪代码看起来简单但每个细节都有讲究。load_state和save_state对应“文件即真理”状态必须落盘才能断点续跑llm.reason是一次完整的模型调用上下文会包含历史步骤记录execute_tool是工具调度层负责在隔离环境里运行工具并捕获输出。值得展开的是状态维护这块。openclaw 的每一步执行都会追加到状态文件并且还会计算一个“执行摘要”把关键信息提取出来。这个摘要下次会一起发给模型避免上下文无限膨胀。这一步非常关键因为大模型的上下文窗口不是无限的几千步执行记录要是全塞进去后面的请求直接爆 token。openclaw 用的是滑动窗口加摘要压缩的策略保留最近 N 步完整记录更早的记录用摘要代替。主循环还有一个安全检查机制最大步数限制。如果任务执行超过预设步数仍然没有收敛agent 会强制终止并报告超时。这是防止模型陷入死循环的最后防线我建议部署的时候根据业务复杂度合理设置这个阈值太小的值会导致复杂任务频繁被打断太大的值又会让故障任务空转很久。3.3 文本匹配与强化学习的进阶视野代码里还有一个容易被忽略但很有意思的细节大量字符串匹配和路径解析的算法。openclaw 要在工作目录里定位记忆文件、匹配工具名称、检索日志关键词这些操作用到的基础算法就是字符串匹配那一套。比如在大量工具描述中扫描某个关键词如果描述文件体量很大朴素的逐字符匹配会有效率问题工程上通常会用类 KMP 式的预处理思路或者直接基于 Trie 树做前缀匹配。我读 openclaw 代码时看到它内置了好几种检索策略根据匹配场景的规模自动切换这给整个 agent 的响应速度帮了大忙。聊到强化学习算法很多人会问 openclaw 这种 agent 框架跟 DQN、PPO 有什么关系。直接回答是openclaw 本身不做模型训练它更多是调用已有模型来做推理决策核心是“用”模型而不是“训”模型。但这不代表强化学习完全无关。如果你想让 agent 的决策策略越用越聪明可以在 openclaw 的日志反馈之上叠一层策略优化每次工具调用是否成功、任务是否高效完成这些信息都是天然的奖励信号。可以把这些记录喂给一套 PPO 或 DQN 训练流程对底层的工具选择策略做微调。这不是 openclaw 的默认功能但框架留下的事件文件格式和数据接口完全支持这种扩展属于进阶玩法。对绝大多数使用者来说真正需要理解的还是那套“离线优化”思路。openclaw 把每一步决策都记录成文件你可以后期拿这些记录做统计、做分析、做策略迭代。这比在线训练模型要稳得多风险也可控。我自己的做法是每跑完一批任务就把日志导出来分析工具调用的成功率和平均步数找出频繁失败的工具然后针对性优化描述文件。这种基于文件数据的闭环迭代才是 openclaw 真正值钱的地方。4. 部署与实操从零跑通 openclaw4.1 Windows 上用 WSL2 搭建开发环境很多人在 openclaw 部署的第一步就卡住了尤其是 Windows 用户。openclaw 在 Windows 上跑得最稳的方式不是原生安装而是在 WSL2 里面跑 Ubuntu再装 Node.js 环境和相关依赖。这个方案踩坑最少。先确认 WSL2 环境本身是健康的。在 PowerShell 里运行wsl --status和wsl --list --verbose如果提示当前版本是 1或者显示“无法安全验证 WSL 2 环境”多半是 WSL 内核更新包没装或者默认版本没设置为 2。解决办法是先执行wsl --set-default-version 2然后去微软官网下载并安装 WSL2 Linux 内核更新包装完重启电脑再一次。这个步骤看着简单但我见过一半以上的人在初期部署失败都倒在这一关上。进入 Ubuntu 子系统之后下一步装 Node.js。openclaw 依赖 Node.js 环境直接apt install nodejs装出来的版本通常太老会有兼容性问题。我推荐用 nvm 安装管理三条命令搞定curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20装完验证一下node -v能看到 v20 以上的版本号就说明环境基础没问题。然后 clone openclaw 仓库进入项目目录执行依赖安装命令。安装过程如果遇到网络超时建议检查一下 apt 和 npm 的代理设置WSL2 的网络和 Windows 宿主不是一套经常出现代理配置不一致的问题这是很多安装失败案例的根源。4.2 关联本地模型与接入 Microsoft Teams环境跑通之后最重要的一步是配置模型。以关联本地部署的 qwen2.5-3b 为例过程非常简单。先用 Ollama 起本地模型服务执行ollama pull qwen2.5-3b拉取模型然后确认服务已经监听在本地端口。接着编辑 openclaw 的模型配置文件把类型改成 ollama接口地址填http://127.0.0.1:11434模型名填qwen2.5-3b。改完保存openclaw 会自动加载新配置。之后随便输入一个问题试试能正常返回就说明模型关联成功。如果要接入 Microsoft Teams走的是标准 Bot Framework 流程。先在 Azure 门户创建一个 Bot 资源拿到 Application ID 和 client secret然后在 Teams 后台把 Bot 添加为应用。openclaw 这边需要配置 Teams 频道相关参数填上刚才拿到的 ID 和密钥再设置好 Bot 的 endpoint 地址。这里有一个容易被坑的地方Teams 的 Bot 回调地址必须是公网可访问的 HTTPS 地址本地开发的场景下建议先用内网穿透工具把端口暴露出去填好临时域名调试通过后再切正式环境。整个接入过程走下来你会发现 openclaw 的配置体系是真的顺畅。所有配置都在文件里改几行文本就完成一个频道的接入不用碰任何业务代码。这正好呼应了“文件即真理”的主题配置本质上也是文件的一种。4.3 用 Obsidian 打造 openclaw 代码阅读与配置管理工作流最后说一个我自己的独门工作流用 Obsidian 来管理 openclaw 的配置和源码笔记。因为 openclaw 强调文件化它的工作目录天然适合交给 Obsidian 这样的本地知识库工具来打理。具体做法很简单把 openclaw 的 workspace 目录直接用 Obsidian 作为一个 Vault 打开。这样所有配置文件的变更、日志文件的更新、工具描述文件的新增都会实时出现在 Obsidian 的文件列表里。你可以用 Obsidian 的双链功能把某次任务的日志、相关工具的描述、对应的源码文件串起来形成一条完整的追踪链路。我通常在 Obsidian 里建两个笔记模板一个叫“任务复盘”用来记录每次复杂任务的执行情况和暴露的问题另一个叫“工具档案”给每个自定义工具写详细说明和调用注意事项。这两个模板里的链接直接指向 openclaw 目录里的具体文件这样 agent 下次执行类似任务时我能快速回查当时的决策上下文。这其实形成了一个很有意思的循环openclaw 用文件管理 agent 的工作我用 Obsidian 管理 openclaw 的工作。两层文件系统叠在一起所有信息都可见、可检索、可追溯这种完全透明的工作方式是我用过这么多 AI 工具之后觉得最踏实的。5. 常见问题与排查实录5.1 部署阶段高频报错速查这段时间帮几个朋友远程排查 openclaw 部署问题把最高频的几个坑整理成一个速查表基本覆盖了从零到跑通的全部节点。问题现象根本原因解决办法wsl 命令提示无法安全验证 WSL 2 环境WSL 内核更新包未安装或默认版本为 1安装 WSL2 内核更新包并执行wsl --set-default-version 2Node 版本过低导致依赖安装失败apt 默认源里的 Node 太老用 nvm 安装 Node 20 并切换默认版本npm install 超时或卡住代理设置不一致或镜像源不通检查 npm 镜像配置必要时换国内镜像源模型请求一直超时模型服务端口未启动或配置地址错误确认模型服务监听端口检查配置文件和实际端口一致工具调用报 permission denied工具目录权限不足给 workspace 目录添加写权限并确认用户属主agent 反复执行同一工具不收敛最大步数设置过大且工具描述不清晰调整最大步数阈值优化工具描述文件Teams 消息接收不到Bot 的 endpoint 未配置或不可公网访问配置公网 HTTPS 回调地址确认 Bot 密钥正确速查表能解决 80% 的问题剩下 20% 基本都在日志文件里有明确线索。记住 openclaw 的排查原则先看状态文件确认 agent 执行到哪一步再看日志文件找到最近的错误信息最后看配置文件核对参数是否有误。三步走完大多数问题都能定位到根因。5.2 源码阅读与二次开发的避坑心得最后一个部分分享我在读 openclaw 源码和动手改造时积累的经验。第一不要从头到尾顺序读代码。openclaw 的项目结构虽然清晰但顺序读源码很容易陷入细节无法自拔。我推荐的做法是先把一个最简单的任务跑通然后顺着日志文件往回找日志里每一条记录都能对应到代码的具体位置。这样你从任务入口到状态保存的整条链路跟着日志走一遍就全明白了。第二改配置之前先备份原文件。openclaw 的配置热加载虽然方便但也意味着你改坏一个字段服务不会立即报错而是带病运行很久。我自己吃过一次亏把温度参数从 0.7 改成 1.5结果 agent 连续几轮回答开始胡言乱语排查了半天才发现是配置问题。现在我的规矩是任何配置文件改动之前都先复制一份带日期的备份文件出问题秒回滚。第三自定义工具要写清楚描述文件。工具描述直接决定模型能不能正确调用它。描述写得含糊模型就可能填错参数或者干脆无视这个工具。我总结出一个技巧在描述文件里加一段“典型用法示例”用一句话把工具最常用的调用方式写清楚。比如查天气的工具就写“当用户问某个城市天气时使用此工具并传入城市名”。实测加了这段之后工具调用准确率提升非常明显。第四遇到诡异问题先怀疑并发。openclaw 允许并行执行多个任务但如果多个任务同时读写同一个状态文件可能产生文件锁冲突。这个问题在低负载下基本不会出现但一旦你提高并发数就要在代理层引入简单的时间戳或者任务 ID 隔离机制避免任务间互相踩踏。踩过这些坑之后再去回看 openclaw 的设计你会更理解“文件即真理流程即文件”这句话的含金量。文件化的状态让崩溃恢复变得简单文件化的流程让调试和修改变得轻松文件化的配置让扩展变得低成本。这套设计牺牲了一部分极致性能换来了极高的可维护性我觉得对大多数真实业务场景来说这个取舍是赚的。你在自己项目里如果也想搭一个可控的 agent 框架完全可以照搬这套文件优先的思路不必追求一开始就做得多炫先保证所有东西都看得见、摸得着、改得动后面再慢慢加复杂度。