ClawRecipes：基于文件优先与菜谱驱动的AI团队协作脚手架

1. 项目概述ClawRecipes一个为AI团队协作而生的“脚手架”工具如果你正在使用OpenClaw并且已经厌倦了在聊天界面里手动协调多个AI助手、来回传递文件、或者为每个新项目重复搭建相同的工作目录结构那么ClawRecipes可能就是你在找的那个“生产力倍增器”。简单来说它不是一个独立的AI应用而是一个OpenClaw的插件它的核心价值在于用Markdown“菜谱”来一键生成和驱动结构化的AI团队与工作流。想象一下你有一个标准的“开发团队”工作模式需要项目经理、前端、后端、测试等角色每个角色有特定的指令集和技能工作项需要经过“待办→进行中→测试→完成”的流程。如果没有ClawRecipes你可能需要手动创建一堆文件夹、配置文件并记住一堆命令来管理这个流程。而有了ClawRecipes你只需要一个定义好的Markdown“菜谱”Recipe运行一条命令整个团队的工作空间、角色配置、工单系统就自动生成了。这就像是为你的AI协作环境准备了一套预制好的、可复用的“乐高积木”套装。我最初接触ClawRecipes是因为在管理多个内容创作和产品开发项目时发现人工协调AI助手比如让一个助手写文案另一个生成图片第三个负责发布的效率瓶颈非常明显。状态跟踪混乱文件散落各处。ClawRecipes提出的“文件优先”File-First理念吸引了我——所有状态、工单、工作流都以文件形式保存在磁盘上清晰可见版本可控而不是隐藏在某个Web应用的后台数据库里。这对于追求透明、可审计和自动化集成的开发者或团队管理者来说是一个至关重要的设计哲学。2. 核心设计理念为什么是“文件优先”与“菜谱驱动”在深入实操之前理解ClawRecipes背后的两个核心设计理念能让你更好地运用它而不是仅仅把它当作一个命令集合。2.1 “文件优先”工作流告别黑盒拥抱透明与可控大多数AI协作平台或复杂的自动化工具其运行状态、历史记录、中间产物都存储在中心化的数据库或内存中。这对于用户来说是个“黑盒”你很难直观地看到当前有哪些任务在排队某个任务进行到哪一步了或者回溯昨天某个工作流失败的具体原因。ClawRecipes彻底颠覆了这一点它强制推行“文件优先”架构。这意味着团队工作空间是一个实实在在的文件夹例如~/.openclaw/workspace-myteam/。工单Ticket就是工作空间内work/目录下的Markdown或JSON文件文件名就是工单号内容包含了任务描述、状态、负责人、历史记录。工作流Workflow定义是JSON文件存放在shared-context/workflows/下每一次工作流运行实例也会在shared-context/workflow-runs/下生成一个对应的状态文件。角色配置、共享记忆等也都是以文件形式存在。这样做的好处是巨大的可调试性极强任何环节出问题你可以直接打开对应的文件查看内容用你最熟悉的文本编辑器或命令行工具cat,jq,grep进行分析。版本控制友好整个工作空间可以轻松地纳入Git等版本控制系统。你可以清晰地看到工单状态的变迁、工作流定义的迭代实现真正的“基础设施即代码”。无供应商锁定风险你的所有工作资产都是纯文本或通用格式文件不依赖于任何特定的在线服务或封闭数据库。即使未来不再使用ClawRecipes或OpenClaw你的历史数据也完全可读、可迁移。易于集成其他脚本或工具可以非常方便地读取或写入这些文件与ClawRecipes进行交互实现更深度的自动化。实操心得刚开始可能会觉得文件多了有点乱但一旦习惯你会发现自己对系统的掌控力达到了新的高度。我经常用tree命令快速浏览团队目录结构或者写个简单的Shell脚本批量处理处于某种状态的工单这在传统黑盒系统里是不可想象的。2.2 “菜谱”即蓝图标准化与可复用的团队模式“菜谱”Recipe是ClawRecipes的基石单元。它本质上是一个遵循特定格式的Markdown文件描述了一个可复用的团队或代理模板。一个菜谱里定义了元信息名称、描述、版本。角色Roles团队由哪些成员构成如lead,dev,tester每个角色的系统指令System Prompt、技能Skills配置。工作流Workflows预定义的工作流模板。文件结构初始化时需要创建的目录和示例文件。例如项目自带的development-team菜谱就定义了一个标准的软件研发团队结构。当你执行scaffold-team命令时ClawRecipes便会读取这个菜谱像脚手架一样在磁盘上搭建出完整的工作空间。这种设计的优势在于快速启动新项目无需从零开始配置一键复用成熟模式。一致性保障团队内的所有项目都遵循相同的结构和流程降低了管理成本。知识沉淀最佳实践可以封装成菜谱在组织内部分享和迭代。你可以为自己公司特有的“周报生成流程”或“社交媒体发布审核流程”创建专属菜谱。3. 从零开始安装、配置与第一个团队搭建理论说得再多不如动手一试。我们从头开始搭建一个可用的环境。3.1 环境准备与插件安装首先你需要一个正在运行的OpenClaw环境。假设你已经安装好了OpenClaw CLI。首选安装方式推荐使用OpenClaw自带的插件管理器。这是最干净、最易于管理的方式。# 安装ClawRecipes插件 openclaw plugins install jiggai/recipes # 启用插件将其加入允许列表 openclaw plugins enable recipes # 重启OpenClaw网关以使插件生效 openclaw gateway restart # 验证插件已成功加载 openclaw plugins list你应该能在列表中看到recipes插件状态为enabled。安装过程中可能遇到的提示与处理警告plugins.allow is empty这是正常提示执行enable命令后即可解决。版本不匹配错误如果OpenClaw核心与插件API版本不兼容安装器会报错。此时可以尝试第二种方法。安全警告suspicious code pattern(s)ClawRecipes需要读取你的OpenClaw配置例如用于图像生成的API密钥并将其传递给工作流中的脚本。对于工作流执行来说这是必要行为并非恶意代码可以安全忽略。备选安装方式通过npm直接安装到插件目录。npm install jiggai/recipes --prefix ~/.openclaw/plugins openclaw gateway restart开发模式安装如果你想贡献代码或测试最新特性可以克隆仓库并链接安装。git clone https://github.com/JIGGAI/ClawRecipes.git ~/ClawRecipes openclaw plugins install --link ~/ClawRecipes openclaw gateway restart安装完成后运行openclaw recipes list如果能看到内置的菜谱列表如development-team,clinic-team说明安装成功。3.2 探索与理解内置菜谱在搭建之前先看看我们有什么“食材”。# 列出所有可用菜谱 openclaw recipes list # 查看某个菜谱的详细定义例如开发团队 openclaw recipes show development-teamshow命令会输出菜谱的完整Markdown内容。花几分钟浏览一下你会看到它定义了lead、dev、tester等角色以及backlog,in-progress等工作流状态。这有助于理解你即将创建的东西。3.3 搭建你的第一个AI团队现在我们来创建一个基于development-team菜谱的团队团队ID设为my-dev-team。openclaw recipes scaffold-team development-team \ --team-id my-dev-team \ --apply-config \ --overwrite逐参数解析scaffold-team: 核心命令意为“搭建团队”。development-team: 指定使用的菜谱名称。--team-id my-dev-team: 为你即将创建的团队指定一个唯一ID。这将成为工作空间目录名的一部分。--apply-config:关键参数。这个选项会让ClawRecipes自动将菜谱中定义的各个角色作为独立的AI助手Agent配置写入到你的OpenClaw主配置文件中。这样这些角色就能立即在OpenClaw中被识别和调用。如果不加此参数你只得到了文件结构还需要手动配置助手。--overwrite: 如果同名团队工作空间已存在则覆盖它。首次运行可不加如果报错提示已存在再加上此参数。命令执行后系统会创建以下内容工作空间目录~/.openclaw/workspace-my-dev-team/。这是所有团队活动的根目录。角色目录workspace-my-dev-team/roles/下会为每个角色lead, dev, tester创建子目录包含各自的系统指令文件directive.md和技能配置。工单工作流目录workspace-my-dev-team/work/下会创建backlog/,in-progress/,testing/,done/等子目录对应工单的不同状态。OpenClaw配置更新如果使用了--apply-config你的~/.openclaw/config.yaml中会新增几个助手的配置块例如my-dev-team-lead,my-dev-team-dev等。注意事项--apply-config会修改你的全局OpenClaw配置。建议在操作前备份你的config.yaml文件。虽然ClawRecipes的修改通常是增量的、结构清晰的但备份是个好习惯。4. 核心工作流实操从派发任务到闭环完成团队搭建好了我们来模拟一个完整的任务处理流程。假设你是团队负责人lead有一个新功能需求需要处理。4.1 派发任务Dispatch作为负责人你通过CLI向团队派发一个新任务。openclaw recipes dispatch \ --team-id my-dev-team \ --owner lead \ --request 为项目主页添加一个‘特性对比’表格需要列出基础版、专业版和企业版的核心功能差异。--owner lead: 指定该任务的初始负责人为“lead”角色。通常由负责人创建任务并做初步细化。--request: 任务的具体描述。执行后系统会在backlog目录下创建一个新的工单文件例如0001-request.md。工单号会自动递增。你可以用openclaw recipes tickets --team-id my-dev-team查看所有工单状态此时应该能看到ID为0001的工单状态为backlog负责人为lead。4.2 认领与执行任务Take开发人员dev可以查看待办事项并认领任务。# 查看所有工单 openclaw recipes tickets --team-id my-dev-team # 开发认领0001号工单 openclaw recipes take --team-id my-dev-team --ticket 0001 --owner devtake命令会做两件事将工单文件从work/backlog/移动到work/in-progress/。更新工单文件内部的元数据将负责人改为dev并记录状态变更历史。现在开发助手配置中对应的my-dev-team-dev就可以开始处理这个任务了。在实际操作中你可能会通过OpenClaw的聊天界面与该助手对话或者通过更复杂的工作流来自动化处理。工单文件本身可以作为上下文的一部分提供给AI。4.3 转交测试Handoff开发完成后需要转交给测试人员。openclaw recipes handoff --team-id my-dev-team --ticket 0001 --tester tester这个命令会将工单从in-progress移动到testing并将负责人改为tester。同时它通常会在工单中附加一个“等待测试”的标记。测试人员或对应的测试AI助手就可以基于此工单进行验证。4.4 完成任务Complete测试通过后可以将工单标记为完成。openclaw recipes complete --team-id my-dev-team --ticket 0001complete命令将工单文件移至work/done/目录并在工单中标记完成时间和状态。至此一个简单的工单生命周期就结束了。这个基于文件的工单系统其强大之处在于它的可追溯性和可脚本化。你可以很容易地写一个脚本统计本周done目录下完成了多少任务或者找出所有在in-progress中停留超过3天的“僵尸任务”。5. 进阶能力自动化工作流引擎详解工单流解决了任务跟踪问题但复杂任务往往涉及多个AI的链式调用、条件判断、甚至人工审批。这就是ClawRecipes的工作流Workflow引擎大显身手的地方。5.1 工作流的核心概念工作流在ClawRecipes中是一个JSON文件定义了一个有向无环图DAG。图中的节点Node可以是LLM节点调用指定的AI助手处理输入产生输出。工具节点执行一个Shell脚本或调用一个API。条件节点根据上一步结果决定下一步走向。批准节点暂停流程等待人工审批。每个工作流运行实例都会在workflow-runs目录下生成一个独立的JSON文件记录整个执行过程的状态、输入、输出和错误信息。5.2 运行与管理工作流项目内置了几个开箱即用的工作流示例位于examples/workflows/。我们以运行一个简单的营销节奏工作流为例。首先你需要将这些示例工作流文件复制到你的团队共享上下文中。# 假设你的团队空间在默认位置 cp -r /path/to/ClawRecipes/examples/workflows/marketing-cadence-v1/* ~/.openclaw/workspace-my-dev-team/shared-context/workflows/然后可以手动触发一次运行openclaw recipes workflows run \ --team-id my-dev-team \ --workflow-file marketing-cadence-v1.workflow.json运行后在~/.openclaw/workspace-my-dev-team/shared-context/workflow-runs/下会生成一个类似run-20250410_112233-abc123.json的文件记录了这次执行的详细信息。5.3 实现自动化调度Runner与Worker模型手动运行不是目的自动化才是。ClawRecipes采用了经典的Runner/Worker运行器/工作者模型来实现调度。Runner负责扫描需要执行的工作流定义例如那些配置了定时任务的并将它们实例化为“运行”Runs放入队列。你可以把它看作“调度器”。Worker负责从队列中领取具体的“运行”任务并执行其中的节点。一个Worker通常绑定一个特定的AI助手Agent由该助手来执行工作流中的LLM节点。设置定时任务Cron 内置示例提供了cron-jobs.example.json和install-crons.sh脚本。你需要根据实际情况调整时间表达式然后运行安装脚本将定时调用Runner的命令添加到系统的crontab中。启动Runner和Worker 你可以通过命令行手动启动更适合调试# Runner执行一次调度检查 openclaw recipes workflows runner-once --team-id my-dev-team # Worker执行一次任务处理绑定给lead助手 openclaw recipes workflows worker-tick --team-id my-dev-team --agent-id my-dev-team-lead在生产环境中你可能会将runner-tick和worker-tick命令配置为后台常驻进程或由systemd管理的服务。5.4 关键陷阱工作流发布配置这是新手最容易踩坑的地方ClawRecipes出于安全考虑默认安装后工作流中任何涉及“发布”到外部的操作如发布到社交媒体都是关闭的。如果你按照示例运行了营销工作流可能会发现它生成了文案但并没有真正发布出去。你必须显式地配置发布渠道推荐路径使用outbound.post这是ClawRecipes设计的标准外部发布接口。你需要配置一个支持outbound.post技能的服务端例如一个自定义的Webhook服务器或集成好的第三方发布插件。然后在工作流中使用“工具节点”调用这个接口。检查并配置查看docs/OUTBOUND_POSTING.md文档了解如何设置。这通常涉及在OpenClaw配置中为某个助手添加outbound.post技能并配置对应的端点URL和认证信息。重要提醒不要假设安装后就能自动发帖。如果你从社区或其它地方获得了需要“打补丁”才能本地发布的工作流请务必记录下补丁内容并在每次更新ClawRecipes后重新应用。清晰地区分“工作流逻辑”和“发布通道配置”是管理好自动化内容管线的关键。6. 故障排查与日常维护指南即使设计再精良在实际运行中也会遇到问题。以下是我在长期使用中总结的常见问题与解决方法。6.1 插件安装与命令找不到问题现象可能原因解决方案执行openclaw recipes提示命令不存在1. 插件未成功安装。2. 网关未重启。3. 插件未启用。1. 用openclaw plugins list确认recipes在列表中且为enabled。2. 运行openclaw gateway restart。3. 检查安装时是否有错误输出尝试用npm install方式重装。安装时提示API版本不匹配OpenClaw核心版本与ClawRecipes插件版本不兼容。1. 检查OpenClaw版本openclaw --version。2. 查看ClawRecipes的README或发布页确认其支持的OpenClaw版本范围。3. 考虑升级或降级OpenClaw或寻找对应版本的ClawRecipes插件。6.2 团队与工作空间问题问题现象可能原因解决方案scaffold-team失败提示目录已存在之前创建过同名团队ID。使用--overwrite参数覆盖或先使用openclaw recipes remove-team --team-id xxx --plan查看删除计划再用--yes确认删除。工单状态不对文件不在预期目录手动移动或修改了工单文件导致CLI命令状态不一致。ClawRecipes严重依赖文件位置。不要手动移动work/下的工单文件。使用openclaw recipes tickets --team-id id查看状态并使用move-ticket命令进行状态变更。--apply-config后OpenClaw配置混乱多次运行或团队ID冲突导致配置重复。1. 备份你的config.yaml。2. 手动清理配置文件中重复或错误的助手配置块搜索你的团队ID。3. 更安全的方法是先remove-team再重新scaffold-team。6.3 工作流执行失败问题现象可能原因解决方案工作流运行后一直处于pending或awaiting_approval1. 没有启动Worker。2. 批准节点无人处理。1. 运行worker-tick命令处理任务。2. 对于审批节点使用openclaw recipes workflows approve命令进行批准或拒绝。Worker执行失败日志显示助手调用错误1. 助手ID配置错误。2. 助手所需的技能未安装或配置。3. API密钥错误或额度不足。1. 检查工作流JSON中agentId字段是否与--apply-config创建的助手ID匹配通常是团队ID-角色名。2. 检查对应助手的配置确保其具备工作流节点所需的技能如web-search,image-generation。3. 检查OpenClaw中相关AI模型供应商的API配置。工作流输出的文件找不到工作流中文件输出路径配置有误。工作流中工具节点或LLM节点输出的文件路径通常是相对于团队工作空间根目录或共享上下文目录。检查工作流定义中的路径并在workflow-runs的日志文件中查找具体的输出位置。6.4 性能与并发调优当你运行多个工作流或团队时可能会遇到性能瓶颈。控制并发度在cron-jobs.example.json和运行worker-tick时注意--concurrency参数。设置过高可能导致OpenClaw网关或API供应商过载。建议从1开始逐步增加观察系统负载和API错误率。清理旧数据定期清理已完成的工单和旧的工作流运行文件可以使用自定义脚本或find命令配合rm。使用cleanup-closed-assignments这个命令可以帮助清理那些已经关闭但仍被标记为“已分配”的陈旧绑定关系保持系统整洁。7. 扩展与集成ClawKitchen UI与自定义菜谱7.1 为系统添加图形界面ClawKitchen如果你觉得纯CLI操作不够直观或者需要给非技术团队成员提供一个管理界面那么ClawKitchen是完美的补充。它是建立在ClawRecipes之上的一个Web UI提供了团队、工作流、目标、审批等功能的可视化管理和监控。安装和运行ClawKitchen通常是独立的进程它会通过读取ClawRecipes生成的文件工作空间、工单、工作流运行状态来渲染界面。这意味着你的所有数据依然安全地保存在本地文件中ClawKitchen只是一个“查看器”和“控制器”。这对于向项目经理或运营人员展示AI团队的工作进度非常有用。7.2 创作你自己的专属菜谱当内置菜谱无法满足你的特定流程时你就需要创作自己的菜谱。这是ClawRecipes最强大的地方——将你的工作模式产品化。创建菜谱的基本步骤学习格式详细阅读docs/RECIPE_FORMAT.md。菜谱是一个标准的Markdown文件包含特定的FrontmatterYAML头和章节结构。规划角色思考你的流程需要哪些AI角色每个角色的职责和系统指令是什么例如一个“短视频创作团队”可能需要“编剧”、“分镜师”、“视频生成师”、“文案润色师”等角色。定义工作流在菜谱的“Workflows”部分你可以嵌入初始的工作流JSON定义。或者也可以先创建团队再在UI或通过文件手动创建复杂的工作流。设计文件结构在“Files”部分定义团队初始化时需要创建的文件夹和模板文件。例如为内容创作团队创建drafts/,assets/,published/目录并在drafts/下放一个script-template.md。测试与分享将你的菜谱文件.md放在OpenClaw能发现的目录下如~/.openclaw/recipes/或项目内的recipes/目录运行openclaw recipes list看是否能识别。然后尝试用scaffold-team命令基于它创建团队进行测试。成熟的菜谱可以提交到社区或内部知识库。一个自定义菜谱的价值它不仅仅是一套配置更是你们团队关于“如何利用AI协作”的标准化、可传承的操作规程。新成员加入只需一条命令就能获得一个配置齐全、符合最佳实践的AI协作环境。经过从安装、团队搭建、任务流转到工作流自动化、故障排查乃至自定义扩展的完整旅程你会发现ClawRecipes的精髓在于它用极简的“文件”和“菜谱”抽象构建了一套强大且透明的AI协同操作系统。它不替代你的AI助手而是为它们提供了有序作战的战场和指挥体系。刚开始可能需要适应这种基于文件和命令行的操作方式但一旦掌握你将获得对自动化流程前所未有的控制力和灵活性。