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-team

show命令会输出菜谱的完整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 dev

take命令会做两件事：

将工单文件从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 0001

complete命令将工单文件移至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_approval`	1. 没有启动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文件，包含特定的Frontmatter（YAML头）和章节结构。
规划角色：思考你的流程需要哪些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助手，而是为它们提供了有序作战的战场和指挥体系。刚开始可能需要适应这种基于文件和命令行的操作方式，但一旦掌握，你将获得对自动化流程前所未有的控制力和灵活性。