ClawRecipes：基于文件优先架构的AI团队协作与工作流自动化实践

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, Workflow

ClawRecipes建立在一套自洽的概念体系上，理解它们的关系是高效使用的前提。

1. 菜谱（Recipe）：这是一切的蓝图。一个Recipe就是一个Markdown文件，它描述了一个智能体或一个团队应该如何被构建。里面定义了角色名称、系统提示词（System Prompt）、拥有的技能（Skills）、默认配置、甚至初始的待办事项模板。你可以把Recipe看作是一个“类”（Class），而通过它创建出来的Agent或Team就是“实例”（Instance）。项目自带了一些预置Recipe，如development-team（开发团队）、project-manager（项目经理）等。

2. 智能体（Agent）：一个具备特定角色和能力的大语言模型实例。它由Recipe定义，拥有独立的配置、记忆和技能。在ClawRecipes中，Agent通常是Team的一个成员。

3. 团队（Team）：由多个Agent组成的协作单元。Team Recipe定义了团队的结构（有哪些角色）、协作规则（如交接流程）和共享的工作空间。创建团队时，ClawRecipes会为每个角色实例化对应的Agent，并搭建好整个文件目录结构和通信通道。

4. 工作流（Workflow）：这是ClawRecipes将自动化提升到新高度的部分。一个Workflow是一个JSON文件，定义了一系列的节点（Node）和边（Edge），描述了一个复杂的、多步骤的自动化过程。节点可以是“LLM调用”、“工具执行”、“条件判断”、“人工审批”等。工作流引擎会按定义执行这些节点，并将每个步骤的输入输出持久化到文件。这使得创建定期的内容生成、审核发布流水线成为可能。

5. 票证（Ticket）：代表一项具体的工作任务。它从创建到完成，会经历backlog（待办）、in-progress（进行中）、testing（测试中）、done（已完成）等状态。每个Ticket也是一个文件，包含了任务描述、分配信息、历史评论和最终产出物。

这五个概念层层递进，Recipe定义模板，基于模板创建Agent和Team，Team通过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 restart

3.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的团队或目录，这个参数会强制覆盖。首次创建时可以不加，如果遇到冲突再加。

执行后，系统会创建什么？

1. 工作空间目录：~/.openclaw/workspace-my-dev-team/。这是该团队所有活动的“大本营”。
2. 角色目录：workspace-my-dev-team/roles/。里面会有lead/,dev/,test/等子目录，每个目录包含对应Agent的详细配置、提示词和技能定义文件。
3. 工作流目录：workspace-my-dev-team/shared-context/work/。里面初始会有backlog/,in-progress/,testing/,done/等子目录，对应看板的不同列，用于存放Ticket文件。
4. 共享上下文：workspace-my-dev-team/shared-context/。用于存放团队共享的知识库、工作流定义文件等。
5. 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执行的效果越好。

执行成功后，系统会做几件事：

1. 在workspace-my-dev-team/shared-context/work/backlog/目录下，创建一个新的Markdown文件，例如0001-welcome-email-draft.md。文件名包含了自动生成的序列号和任务描述的缩写。
2. 这个文件里记录了任务ID、创建时间、请求内容、状态（初始为open）、负责人等信息。
3. 命令行会输出新创建的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 & Complete）

dev完成初稿后，按照流程可能需要交给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）的关键。
• 开始/结束节点：定义流程的起点和终点。

一个简单的营销内容生成工作流可能如下：

1. 开始-> 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 2

runner-tick命令是调度器的“心跳”。它每次执行时，会检查workflows/目录下所有已启用的工作流定义，看看是否有需要触发的新运行实例（比如根据cron表达式到了该运行的时间）。如果有，它会创建对应的“运行记录”文件，并将其状态置为pending。

创建了运行实例后，需要执行器（Worker）来实际执行它。执行器通常以常驻进程或另一个定时任务的形式运行。

# 在另一个终端或进程中，运行执行器 openclaw recipes workflows worker-tick \ --team-id my-dev-team \ --agent-id my-dev-team-lead

worker-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的发布版本出于安全考虑，默认关闭了所有会产生实际外部影响（如发帖、发邮件）的“副作用”。一个工作流可以生成完美的推文内容，但到发布那一步时，如果没有正确配置，它只会模拟一下或者直接跳过。

如何启用真实发布？你有两条主要路径：

1. 配置Outbound Posting（推荐）：这是ClawRecipes支持的标准路径。你需要配置一个外发发布服务（例如，通过kitchen-plugin-marketing插件集成Postiz等服务）。然后在工作流中，使用outbound.post这样的标准工具节点，而不是旧的、可能不稳定的本地发布路径。
2. 使用本地补丁（高级/不稳定）：如果你在使用某个特定的、修改过的OpenClaw控制器（比如某些社区版本），并且它包含了工作流发布的补丁，那么你需要在每次更新ClawRecipes或OpenClaw后，重新应用这个补丁。这种方式依赖特定环境，不具普适性。

核心原则：永远假设工作流发布是关闭的。当你设计了一个包含发布步骤的工作流后，第一件事就是去确认发布渠道是否已正确配置和启用。查看docs/OUTBOUND_POSTING.md文档是必做功课。

6. 故障排查与最佳实践

6.1 常见问题与解决方案

6.2 性能与稳定性最佳实践

1. 控制并发度：如果你运行多个工作流Worker，或在同一团队内频繁派发大量Ticket，注意OpenClaw和底层LLM API的并发限制。可以在OpenClaw的Agent配置中设置maxConcurrent参数，避免同时发起过多请求导致失败或超时。
2. 工作流设计原则：
   • 幂等性：尽可能将工作流设计成可重复执行而不会产生副作用。例如，生成内容的节点，如果内容已存在则跳过或覆盖。
   • 设置超时：为每个可能长时间运行或挂起的节点（尤其是LLM调用和外部API调用）设置超时时间。
   • 添加检查点：复杂工作流中，在关键步骤后可以将中间状态持久化，以便失败后能从该点恢复，而不是从头开始。
3. 文件系统监控：由于重度依赖文件系统，确保运行ClawRecipes的服务器有足够的磁盘空间和Inotify watches（在Linux上）。如果遇到文件变更未及时触发事件的情况，可以检查系统相关限制。
4. 备份工作空间：workspace-*/目录包含了所有团队的状态和产出。定期备份这个目录，或者将其纳入版本控制系统（注意排除可能含有API密钥的配置文件），是保证工作不丢失的好习惯。
5. 从简单开始：不要一开始就设计一个包含几十个节点的复杂工作流。先从创建一个只有“开始 -> 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团队，这个过程本身就像在编写一段可执行的、关于如何协作的“元程序”，这种体验非常独特且强大。