1. 项目概述从Markdown菜谱到AI团队工作流如果你和我一样在尝试构建基于大语言模型的AI团队时被各种复杂的配置、状态管理和协作流程搞得焦头烂额那么ClawRecipes的出现可能就像在迷宫里找到了一张清晰的地图。这个项目本质上是一个OpenClaw插件但它解决的痛点非常具体如何将写在Markdown文件里的“菜谱”Recipes一键转化为可运行的AI智能体Agent、协作团队Team以及一套基于文件系统的、持久化的工作流。我最初接触这个概念时觉得它有点“反直觉”。现在很多AI Agent框架都追求极致的交互性和实时性把状态、记忆、任务都藏在内存或数据库里。但ClawRecipes走了另一条路文件优先File-First。所有的团队结构、角色定义、待办事项Ticket、工作流定义都以人类可读的Markdown、JSON或YAML文件形式实实在在地躺在你的磁盘上。这种设计哲学带来的好处是巨大的可追溯、可版本控制、可离线审查、可手动干预。你不再需要去猜一个AI助手“脑子里”在想什么所有的工作成果和过程记录都明明白白。简单来说ClawRecipes让你能用写文档的方式来定义和驱动一个AI团队。你写好一个“开发团队”的菜谱运行一条命令一个包含“技术负责人”、“开发”、“测试”等角色的团队目录结构就创建好了。然后你可以通过命令行“派发”任务任务会以Ticket文件的形式进入“待办”队列AI成员可以“领取”任务完成后“交接”给测试最终“完成”。整个过程就像在管理一个高度自动化的数字项目看板但背后的执行者是AI。2. 核心设计理念与架构解析2.1 为何选择“文件优先”架构在深入命令细节之前理解ClawRecipes的“文件优先”设计至关重要。这不仅仅是技术选型更是一种工程理念的体现。透明性与可调试性当工作流以文件形式存在时任何中间状态都是可见的。如果一个AI生成的内容不符合预期你可以直接打开对应的JSON或Markdown文件查看输入和输出甚至可以手动编辑修正然后让流程继续。这比在黑盒系统中猜测错误原因要高效得多。持久化与可移植性文件系统是操作系统提供的最基础、最可靠的持久化存储。基于文件的工作流状态不会因为服务重启而丢失。整个团队的工作空间一个目录可以轻松地打包、备份、迁移到另一台机器或者提交到Git仓库进行版本管理。这对于需要复现实验或审计工作流的场景是刚需。工具链友好性现有的开发者工具如文本编辑器、IDE、grep、sed、jq等可以无缝接入。你可以用自己熟悉的工具批量处理任务文件编写脚本自动化分析工作流日志或者用Git来对比不同版本工作流定义的差异。降低认知负荷对于开发者而言文件和目录是再熟悉不过的抽象。ClawRecipes用workspace-{team-id}/目录作为团队的根下面分门别类地存放roles/角色定义、work/任务票证、shared-context/共享知识库和工作流等。这种结构一目了然你不需要学习一套新的数据模型就能上手管理。注意“文件优先”并不意味着性能低下。ClawRecipes通过高效的文件监听和缓存机制来保证响应速度。它的设计目标不是处理每秒数千次的事务而是管理复杂、异步、长周期的AI协作任务在这方面文件系统的开销几乎可以忽略不计。2.2 核心概念拆解Recipe, Agent, Team, WorkflowClawRecipes建立在一套自洽的概念体系上理解它们的关系是高效使用的前提。菜谱Recipe这是一切的蓝图。一个Recipe就是一个Markdown文件它描述了一个智能体或一个团队应该如何被构建。里面定义了角色名称、系统提示词System Prompt、拥有的技能Skills、默认配置、甚至初始的待办事项模板。你可以把Recipe看作是一个“类”Class而通过它创建出来的Agent或Team就是“实例”Instance。项目自带了一些预置Recipe如development-team开发团队、project-manager项目经理等。智能体Agent一个具备特定角色和能力的大语言模型实例。它由Recipe定义拥有独立的配置、记忆和技能。在ClawRecipes中Agent通常是Team的一个成员。团队Team由多个Agent组成的协作单元。Team Recipe定义了团队的结构有哪些角色、协作规则如交接流程和共享的工作空间。创建团队时ClawRecipes会为每个角色实例化对应的Agent并搭建好整个文件目录结构和通信通道。工作流Workflow这是ClawRecipes将自动化提升到新高度的部分。一个Workflow是一个JSON文件定义了一系列的节点Node和边Edge描述了一个复杂的、多步骤的自动化过程。节点可以是“LLM调用”、“工具执行”、“条件判断”、“人工审批”等。工作流引擎会按定义执行这些节点并将每个步骤的输入输出持久化到文件。这使得创建定期的内容生成、审核发布流水线成为可能。票证Ticket代表一项具体的工作任务。它从创建到完成会经历backlog待办、in-progress进行中、testing测试中、done已完成等状态。每个Ticket也是一个文件包含了任务描述、分配信息、历史评论和最终产出物。这五个概念层层递进Recipe定义模板基于模板创建Agent和TeamTeam通过Ticket管理系统内的工作而复杂的周期性任务则由Workflow引擎驱动。整个体系逻辑清晰边界明确。3. 从零开始完整安装与初始化实战3.1 环境准备与插件安装ClawRecipes作为OpenClaw的插件运行因此前提是已经有一个正常运行的OpenClaw环境。假设你已经安装好了OpenClaw CLI并且openclaw命令可用。安装ClawRecipes插件官方推荐通过OpenClaw的插件管理器安装这是最简洁的方式。# 1. 使用OpenClaw插件命令安装 openclaw plugins install jiggai/recipes # 2. 启用插件将其加入允许列表 openclaw plugins enable recipes # 3. 重启OpenClaw网关以使插件生效 openclaw gateway restart # 4. 验证插件已成功安装并列出 openclaw plugins list运行openclaw plugins list后你应该能在列表中看到recipes插件并且状态是已启用。安装过程中可能遇到的“坑”及解决警告plugins.allow is empty如果看到此警告只需按上述步骤执行openclaw plugins enable recipes即可。这是OpenClaw的安全机制要求显式启用非捆绑插件。错误Plugin API版本不匹配如果安装失败并提示API版本问题说明你的OpenClaw核心版本与ClawRecipes插件要求的版本不兼容。此时可以尝试用npm直接安装特定版本或者升级/降级你的OpenClaw核心版本。警告suspicious code pattern(s)这是OpenClaw的安全扫描提示。因为ClawRecipes需要读取你的配置如API密钥来执行工作流例如调用DALL-E生成图片所以触发了模式匹配。对于ClawRecipes这个警告是预期的可以忽略。它只是在提醒你该插件会访问配置你需要信任插件的来源。备选安装方案如果插件安装器有问题或者你想安装特定版本可以使用npm直接安装到OpenClaw的插件目录# 指定安装路径到OpenClaw的插件目录 npm install jiggai/recipes --prefix ~/.openclaw/plugins openclaw gateway restart或者如果你需要从源码进行开发或调试可以使用--link参数进行本地链接安装git clone https://github.com/JIGGAI/ClawRecipes.git ~/ClawRecipes openclaw plugins install --link ~/ClawRecipes openclaw gateway restart3.2 初探系统查看与理解预置菜谱安装成功后首先应该探索系统里有什么可用的“菜谱”。# 列出所有可用的菜谱 openclaw recipes list这个命令会输出一个表格显示Recipe的名称、类型是Agent Recipe还是Team Recipe和简短描述。例如你可能会看到development-team、clinic-team、project-manager等。接下来可以查看某个具体Recipe的详细内容# 查看“开发团队”这个菜谱的详细定义 openclaw recipes show development-team这个命令会打印出该Recipe的Markdown源码。你可以看到它如何定义角色如lead,dev,test每个角色的系统提示词是什么以及团队初始的文件夹结构。花时间阅读一两个Recipe是理解ClawRecipes设计思想最快的方式。你还可以检查某个Recipe如果被实例化会创建哪些文件# 显示实例化“开发团队”菜谱将执行的操作模拟 openclaw recipes status development-team这个status命令非常有用它执行一次“预演”告诉你如果运行scaffold-team命令将会创建哪些目录和文件但并不会实际创建。这有助于你在执行前确认效果。3.3 创建你的第一个AI团队理解了Recipe之后就可以动手创建你的第一个团队了。我们以创建一个development-team为例。openclaw recipes scaffold-team development-team \ --team-id my-dev-team \ --apply-config \ --overwrite让我们拆解这个命令的每个部分scaffold-team development-team这是动作和模板。表示“使用development-team这个Recipe作为模板来搭建scaffold一个团队”。--team-id my-dev-team这是你为这个团队实例起的唯一标识符。后续所有针对这个团队的操作都需要用到这个ID。--apply-config这是一个关键参数。它告诉ClawRecipes在创建团队文件结构的同时自动向OpenClaw的配置文件通常是~/.openclaw/agents.json中添加这个新团队中所有Agent的配置项。如果不加这个参数你虽然创建了文件但OpenClaw核心并不知道这些Agent的存在它们就无法被调度和工作。--overwrite如果之前已经存在同team-id的团队或目录这个参数会强制覆盖。首次创建时可以不加如果遇到冲突再加。执行后系统会创建什么工作空间目录~/.openclaw/workspace-my-dev-team/。这是该团队所有活动的“大本营”。角色目录workspace-my-dev-team/roles/。里面会有lead/,dev/,test/等子目录每个目录包含对应Agent的详细配置、提示词和技能定义文件。工作流目录workspace-my-dev-team/shared-context/work/。里面初始会有backlog/,in-progress/,testing/,done/等子目录对应看板的不同列用于存放Ticket文件。共享上下文workspace-my-dev-team/shared-context/。用于存放团队共享的知识库、工作流定义文件等。OpenClaw配置更新如果使用了--apply-config你的OpenClaw配置中会新增几个Agent的配置块每个块都指向刚刚创建的角色目录。至此一个具备基础协作能力的AI团队就已经就绪等待接收任务了。4. 核心工作流实战任务派发与协作团队搭建好了接下来就是让它运转起来。ClawRecipes模拟了一个简化的敏捷开发流程核心是Ticket票证的流转。4.1 派发任务Dispatch向团队派发一个新任务就像在产品待办列表Product Backlog里添加一个新条目。openclaw recipes dispatch \ --team-id my-dev-team \ --owner lead \ --request 为我们的新产品‘智能笔记’编写一份用户欢迎邮件的初稿要求语气亲切突出核心功能。--team-id指定任务派发给哪个团队。--owner指定该任务的初始负责人。这里指定给lead团队负责人通常由TA进行任务拆解或初步分配。--request任务的详细描述。描述越清晰AI执行的效果越好。执行成功后系统会做几件事在workspace-my-dev-team/shared-context/work/backlog/目录下创建一个新的Markdown文件例如0001-welcome-email-draft.md。文件名包含了自动生成的序列号和任务描述的缩写。这个文件里记录了任务ID、创建时间、请求内容、状态初始为open、负责人等信息。命令行会输出新创建的Ticket ID例如0001。4.2 查看与认领任务Tickets Take团队负责人或任何成员可以查看当前所有任务的状态。# 查看my-dev-team团队的所有票证及其状态 openclaw recipes tickets --team-id my-dev-team输出是一个表格显示每个Ticket的ID、标题、状态、负责人等一目了然。假设lead角色评估后决定将0001号任务交给dev开发人员角色来执行。dev需要“认领”这个任务。openclaw recipes take --team-id my-dev-team --ticket 0001 --owner dev这个命令会将Ticket0001从backlog目录移动到in-progress目录并将负责人owner字段更新为dev。现在这个任务就正式进入执行阶段由dev负责。4.3 执行任务与协作那么dev这个AI角色如何实际工作呢这里就需要结合OpenClaw的核心能力。dev作为一个配置好的Agent可以通过OpenClaw的聊天接口、技能调用等方式来完成任务。一种常见的方式是你作为人类管理者直接与devAgent对话将Ticket内容作为上下文提供给它指导它完成。另一种更自动化的方式是结合技能Skills。你可以在Recipe中为dev角色预定义“写作”、“代码生成”等技能然后通过工作流Workflow自动触发。无论采用哪种方式dev在完成任务比如写好了欢迎邮件草稿后需要将产出物保存。最佳实践是将产出物以文件的形式保存在该Ticket的目录下或者直接更新Ticket文件的内容。ClawRecipes的文件系统使得这种操作非常自然。4.4 任务交接与完成Handoff Completedev完成初稿后按照流程可能需要交给test测试员角色进行审查或润色。openclaw recipes handoff --team-id my-dev-team --ticket 0001 --tester test这个命令会将Ticket0001从in-progress移动到testing目录并将负责人变更为test。同时它可能会在Ticket文件中添加一条交接记录。test角色进行审查后如果通过就可以将任务标记为完成。openclaw recipes complete --team-id my-dev-team --ticket 0001这个命令会将Ticket移动到done目录并将其状态标记为closed。一个任务的生命周期就此结束。整个流程的核心价值在于它将一个抽象的AI协作过程物化成了一个可视、可管、可追溯的文件操作流程。你不需要一个复杂的Web UI用命令行和文件浏览器就能清晰掌握整个团队的进度。5. 进阶能力工作流引擎深度解析如果说Ticket系统管理的是离散任务那么Workflow引擎则是为了处理复杂的、周期性的、多步骤的自动化流程。这是ClawRecipes真正强大的地方。5.1 工作流的概念与结构一个Workflow在ClawRecipes中是一个JSON文件通常存放在团队的shared-context/workflows/目录下。它定义了一个有向图其中节点Nodes代表一个操作步骤边Edges代表步骤之间的执行顺序和条件。节点类型丰富LLM节点调用大语言模型根据提示词生成内容。工具节点执行一个预定义的工具函数比如读取文件、调用外部API、运行脚本。条件节点根据上一步的结果判断流程走向IF/ELSE。审批节点暂停流程等待人工审批。这是实现“人在回路”Human-in-the-loop的关键。开始/结束节点定义流程的起点和终点。一个简单的营销内容生成工作流可能如下开始- 2.LLM节点生成博客主题- 3.条件节点主题是否通过- 若不通过回到2若通过- 4.LLM节点撰写博客草稿- 5.审批节点人工审核草稿- 若驳回回到4若批准- 6.工具节点发布到CMS- 7.结束。5.2 运行与管理工作流手动运行一次工作流openclaw recipes workflows run \ --team-id my-dev-team \ --workflow-file shared-context/workflows/weekly-blog.workflow.json这会让工作流引擎立即执行一次指定的工作流。执行过程、每个节点的输入输出都会被详细记录到shared-context/workflow-runs/目录下的一个独立运行记录文件中。自动化运行调度器Runner与执行器Worker对于周期性任务如每天早8点生成社交媒体内容需要调度器。# 设置一个定时任务Cron Job每10分钟触发一次调度器检查 # 在你的crontab中添加一行 */10 * * * * /usr/bin/openclaw recipes workflows runner-tick --team-id my-dev-team --concurrency 2runner-tick命令是调度器的“心跳”。它每次执行时会检查workflows/目录下所有已启用的工作流定义看看是否有需要触发的新运行实例比如根据cron表达式到了该运行的时间。如果有它会创建对应的“运行记录”文件并将其状态置为pending。创建了运行实例后需要执行器Worker来实际执行它。执行器通常以常驻进程或另一个定时任务的形式运行。# 在另一个终端或进程中运行执行器 openclaw recipes workflows worker-tick \ --team-id my-dev-team \ --agent-id my-dev-team-leadworker-tick命令会查找状态为pending或ready的运行实例锁定其中一个然后按照工作流定义一步步执行。--agent-id参数指定了以哪个Agent的身份来执行工作流中的LLM节点因为LLM调用需要关联到一个具体的Agent配置。这种Runner-Worker分离的架构非常经典它实现了调度与执行的解耦便于扩展和负载均衡。你可以运行多个Worker进程来提高并发处理能力。5.3 人工审批集成工作流中的审批节点是连接AI自动化与人类决策的桥梁。当流程执行到一个审批节点时状态会变为awaiting_approval并暂停。如何审批ClawRecipes提供了命令行工具来处理审批# 批准一个运行 openclaw recipes workflows approve \ --team-id my-dev-team \ --run-id abc123def456 \ --approved true # 驳回一个运行并附上意见 openclaw recipes workflows approve \ --team-id my-dev-team \ --run-id abc123def456 \ --approved false \ --note “文章基调需要更正式一些请重写第二段。”被驳回后工作流可以根据设计退回到之前的某个节点比如撰写节点重新执行。批准后工作流则继续向下执行。审批的实践心得通知机制单纯的命令行审批不够友好。你需要自己构建通知层。例如可以写一个简单的脚本当有任务进入awaiting_approval状态时发送邮件、Slack消息或钉钉通知给负责人。审批界面这就是ClawKitchen这类UI工具的价值所在。它提供了一个Web界面来集中查看、审批所有待办的工作流任务体验远好于命令行。超时处理在实际应用中一定要为审批节点设置超时策略。例如24小时内未审批则自动驳回或按默认策略处理避免流程永远卡住。5.4 关于“对外发布”的重要警告这是ClawRecipes文档中特别强调也是新手最容易踩坑的地方安装ClawRecipes并不意味着你的工作流会自动向外部世界如社交媒体、博客发布内容。默认是安全的ClawRecipes的发布版本出于安全考虑默认关闭了所有会产生实际外部影响如发帖、发邮件的“副作用”。一个工作流可以生成完美的推文内容但到发布那一步时如果没有正确配置它只会模拟一下或者直接跳过。如何启用真实发布你有两条主要路径配置Outbound Posting推荐这是ClawRecipes支持的标准路径。你需要配置一个外发发布服务例如通过kitchen-plugin-marketing插件集成Postiz等服务。然后在工作流中使用outbound.post这样的标准工具节点而不是旧的、可能不稳定的本地发布路径。使用本地补丁高级/不稳定如果你在使用某个特定的、修改过的OpenClaw控制器比如某些社区版本并且它包含了工作流发布的补丁那么你需要在每次更新ClawRecipes或OpenClaw后重新应用这个补丁。这种方式依赖特定环境不具普适性。核心原则永远假设工作流发布是关闭的。当你设计了一个包含发布步骤的工作流后第一件事就是去确认发布渠道是否已正确配置和启用。查看docs/OUTBOUND_POSTING.md文档是必做功课。6. 故障排查与最佳实践6.1 常见问题与解决方案问题现象可能原因排查步骤与解决方案运行openclaw recipes list无输出或报错1. 插件未正确安装或启用。2. OpenClaw网关未重启。3. 网络问题导致无法读取本地Recipe。1. 执行openclaw plugins list确认recipes插件在列且已启用。2. 执行openclaw gateway restart并查看日志有无错误。3. 检查~/.openclaw/plugins/node_modules/jiggai/recipes目录是否存在。scaffold-team成功但Agent不响应未使用--apply-config参数Agent配置未注入OpenClaw。1. 检查~/.openclaw/agents.json看是否有对应team-id的新Agent配置块。2. 如果没有可以手动运行openclaw recipes apply-config --team-id your-team-id来注入配置然后重启网关。工作流Workflow卡住状态不变1. 工作流定义有误如节点ID重复边连接错误。2. 遇到了审批节点在等待人工干预。3. Worker进程没有运行或崩溃。1. 检查工作流JSON文件的语法和逻辑。使用openclaw recipes workflows validate如果提供或手动检查。2. 运行openclaw recipes workflows runs --team-id id --status awaiting_approval查看是否有待审批任务。3. 确认Worker进程是否在运行查看其日志输出。Ticket文件被创建但AI角色“看不到”或无法处理1. Ticket文件不在正确的Agent工作空间或上下文中。2. 对应的Agent没有处理此类任务的技能或提示词配置。1. ClawRecipes的Ticket系统是文件驱动的AI角色需要被设计成能读取特定目录的文件。确保你的Recipe中角色的“技能”或“系统提示”包含了处理shared-context/work/目录下文件的逻辑。2. 你可能需要为角色安装或开发特定的“文件处理”技能。执行工作流时LLM调用失败1. OpenClaw中对应Agent的LLM配置API密钥、Base URL错误或过期。2. 网络问题。3. 提示词导致LLM输出格式不符合节点预期解析失败。1. 首先测试直接与相关Agent对话是否正常排除基础LLM配置问题。2. 查看工作流运行记录文件在workflow-runs/下找到失败节点的详细输入输出日志这是最直接的调试信息。6.2 性能与稳定性最佳实践控制并发度如果你运行多个工作流Worker或在同一团队内频繁派发大量Ticket注意OpenClaw和底层LLM API的并发限制。可以在OpenClaw的Agent配置中设置maxConcurrent参数避免同时发起过多请求导致失败或超时。工作流设计原则幂等性尽可能将工作流设计成可重复执行而不会产生副作用。例如生成内容的节点如果内容已存在则跳过或覆盖。设置超时为每个可能长时间运行或挂起的节点尤其是LLM调用和外部API调用设置超时时间。添加检查点复杂工作流中在关键步骤后可以将中间状态持久化以便失败后能从该点恢复而不是从头开始。文件系统监控由于重度依赖文件系统确保运行ClawRecipes的服务器有足够的磁盘空间和Inotify watches在Linux上。如果遇到文件变更未及时触发事件的情况可以检查系统相关限制。备份工作空间workspace-*/目录包含了所有团队的状态和产出。定期备份这个目录或者将其纳入版本控制系统注意排除可能含有API密钥的配置文件是保证工作不丢失的好习惯。从简单开始不要一开始就设计一个包含几十个节点的复杂工作流。先从创建一个只有“开始 - LLM生成 - 结束”三个节点的简单工作流跑通然后逐步添加条件、审批、工具调用等节点。利用好项目自带的examples/workflows/下的示例它们是极好的学习模板。6.3 与ClawKitchen的搭配使用ClawRecipes是强大的引擎但它的交互界面是命令行和文件。对于需要可视化管理的团队或者希望让非技术成员参与审批和监控的场景ClawKitchen是完美的补充。ClawKitchen是一个为ClawRecipes提供Web UI的项目。它可以可视化团队看板以拖拽方式管理Ticket状态。图形化工作流设计器通过界面设计、编辑和监控工作流。集中审批中心在一个网页上处理所有待审批的工作流任务。目标与进度管理为团队设定目标并跟踪完成情况。部署上ClawRecipes和ClawKitchen可以安装在同一台机器或不同机器上。ClawKitchen通过读取ClawRecipes生成的文件工作空间、工作流运行记录来提供UI两者通过文件系统耦合架构清晰。如果你的使用场景涉及多人协作或频繁的审批操作强烈建议搭配使用ClawKitchen。经过一段时间的深度使用我认为ClawRecipes最大的魅力在于它找到了一种“恰到好处”的抽象。它没有试图用AI解决所有问题而是用AI赋能了一个清晰、可控、基于文件系统的协作模型。它可能不像一些全自动Agent系统看起来那么“智能”但它带来的可控性、可解释性和可集成性对于需要将AI能力稳定、可靠地嵌入到实际生产流程中的团队来说价值是无可替代的。从编写Markdown菜谱开始到驱动一个自动运转的AI团队这个过程本身就像在编写一段可执行的、关于如何协作的“元程序”这种体验非常独特且强大。