1. 项目概述一个为AI多智能体协作而生的“自动化监工”如果你正在用OpenClaw这类框架玩多AI智能体协作大概率会遇到一个头疼的问题怎么知道这群“数字员工”到底在不在干活谁在摸鱼任务到底完成了没有难道要自己24小时盯着聊天记录和Git提交吗我之前就被这个问题折磨得不轻直到我动手搭建了task-orchestrator——一个完全自动化的任务编排与监控系统。简单说它就像一个不知疲倦的“监工”或“项目经理”。你只需要定义好任务、分配好负责的AI智能体比如一个负责后端一个负责前端然后启动它。接下来它会每隔5分钟自动检查所有智能体的Git工作状态检测谁在“假装忙碌”自动发送提醒催促精准识别任务完成信号并通过Telegram向你汇报关键进展。整个过程无需人工干预全部由确定性的Bash脚本和按需唤醒的“指挥官”智能体协同完成。这尤其适合需要多个AI智能体长期、持续协作的复杂项目比如全栈应用开发、内容创作流水线等让你从繁琐的进度跟踪中彻底解放出来。2. 核心设计哲学让确定性的脚本干活让LLM做决策这个项目的架构核心源于一个深刻的教训绝对不要让LLM大语言模型去执行重复、机械的监控任务。早期的版本尝试过让一个AI智能体作为“心跳监测器”结果惨不忍睹它会“幻觉”出一切正常的报告“我检查了一切看起来都很好”实际上它可能根本没运行检查为了节省算力或“偷懒”它会直接跳过检查步骤甚至可能毫无征兆地陷入沉默。2.1 分层架构解析因此task-orchestrator采用了清晰的分层架构将确定性的、枯燥的工作与需要判断力的决策分离开系统层确定性执行 由两个通过macOSlaunchdLinux下可替换为systemd或cron定时运行的Bash脚本构成。task-monitor.sh每5分钟运行这是系统的“巡逻兵”。它的工作是完全确定性的检查每个智能体工作目录的Git提交历史运行算法检测“假装忙碌”模式根据需要发送催促Nudge消息扫描任务完成信号.done文件或[DONE]标签。只有当它检测到需要高级决策的情况如任务完成需要审核、分配下一阶段任务时才会去唤醒“指挥官”智能体。所有状态报告在发送到Telegram前都会经过内容哈希去重避免信息轰炸。system-watchdog.sh每30分钟运行这是系统的“健康检查员”。它检查更底层的状态OpenClaw网关是否存活各个智能体的“心跳”进程是否在运行如果所有智能体都失联了它会尝试自我修复如重启服务并发送警报。这一层是为了防止整个系统无声无息地瘫痪。指挥官层按需决策 这是一个特殊的OpenClaw智能体它平时处于休眠状态只有被task-monitor.sh唤醒时才工作。它的职责是需要人类级别判断的“领导工作”L2内容审核当巡逻兵检测到任务完成信号后指挥官会被唤醒去审查智能体提交的代码或内容质量判断是否真的达到交付标准。分配下一阶段任务当前置任务完成后指挥官根据任务注册表Registry和项目状态决定并指派下一个任务给合适的智能体。向“老板”汇报将关键的决策结果或需要人类关注的重大进展通过结构化消息通知用户。这种“脚本巡逻 LLM决策”的设计既保证了监控的可靠性和效率脚本永不“偷懒”又充分发挥了LLM在复杂判断和规划上的优势同时极大地降低了不必要的LLM调用成本。2.2 关键技术选型背后的思考项目文档中提到的几个技术选择都是“踩坑”后的经验结晶为什么用curl直连Telegram API早期设计是脚本生成报告文件 → 定时任务触发另一个LLM智能体 → 该智能体读取文件 → 再组织语言发送给Telegram。这个“四链路”设计脆弱无比任何一个环节LLM宕机、文件读取错误、消息格式误解都会导致静默失败。改为curl直接调用Telegram Bot API链路缩短为一步可靠性提升到接近100%。同时使用--data-urlencode参数对消息文本进行编码完美解决了Markdown特殊字符如_,*导致API调用失败的问题。为什么用mkdir而非flock做文件锁初衷是使用flock命令实现脚本执行的互斥锁防止上一个监控周期未结束下一个又启动。但发现macOS系统默认不包含flock命令。而mkdir是一个原子性的POSIX操作在所有Unix-like系统上都可用。尝试创建一个锁目录如果成功则获得锁如果目录已存在则说明有实例在运行当前脚本退出。配合一个“陈旧锁”检测机制比如判断锁目录的修改时间是否超过10分钟可以自动清理异常退出留下的死锁既实现了并发安全又保证了跨平台兼容性。为什么采用结构化的完成信号最初尝试在智能体的会话历史里用grep搜索“done”、“finished”等关键词。这立刻带来了歧义问题智能体可能会说“I haven‘t finished all done items yet”我还没完成所有该做的事这句话包含“done”但实际上表示未完成。因此我们定义了两种明确无误的、结构化的完成信号1在智能体的工作目录中创建一个空的.done文件并提交2在提交信息中包含明确的[DONE]标签。脚本只需检查这些特定的、不会产生歧义的结构化标记即可。3. 从零开始部署与配置实战理解了设计理念后我们来一步步把它跑起来。整个过程只需要配置一个文件和准备一个任务列表。3.1 环境与依赖准备首先确保你的基础环境满足要求OpenClaw这是多智能体协作的运行时环境。你需要已经按照其官方文档完成安装并且配置好了至少两个可以协同工作的智能体例如一个“工程师”一个“设计师”。操作系统项目原生支持macOS利用其launchd做定时任务。如果你使用Linux核心监控脚本完全通用只需要将launchd的配置.plist文件转换为systemd service或cron任务即可脚本逻辑无需改动。基础工具确保已安装Git、Python 3。curl和shasum用于生成哈希在macOS上通常是预装的。3.2 核心配置文件详解整个系统只有一个需要你手动编辑的配置文件config.json。我们从示例配置复制并开始修改cp config.example.json config.json现在打开config.json我们来逐部分解读其关键配置项{ project: { name: AI全栈博客项目, // 你的项目名称用于日志和报告 dir: /Users/yourname/code/my-ai-blog, // 主Git仓库的绝对路径 branch: dev // 主开发分支名 }, agents: { backend_agent: { branch: dev-backend, // 为该智能体创建的独立分支名 worktree: /Users/yourname/code/my-ai-blog-backend, // 该智能体的独立工作目录路径 role: 后端开发Django API 数据库设计 // 智能体角色描述用于报告 }, frontend_agent: { branch: dev-frontend, worktree: /Users/yourname/code/my-ai-blog-frontend, role: 前端开发React组件 页面样式 } }, telegram: { chat_id: 你的Telegram用户ID数字, // 如何获取见下文 bot_token_env: TG_BOT_TOKEN, // 存放Bot Token的环境变量名 proxy: // 如果需要代理访问Telegram API则填写否则留空 }, thresholds: { nudge_minutes: 30, // 无新提交超过30分钟触发催促 reset_minutes: 120, // 会话持续120分钟无实质进展强制重置会话防止token膨胀 nudge_cooldown_minutes: 15, // 发送一次催促后冷却15分钟再检查避免轰炸 session_max_lines: 300 // 智能体会话文件最大行数超过则自动轮转控制上下文长度 }, paths: { state_dir: ~/task-state, // 系统存放运行时状态如锁文件、上次报告哈希的目录 logs_dir: ~/task-logs, // 所有操作日志的存储目录 task_registry: ~/tasks/task-registry.json, // 任务清单文件路径 checks_file: ~/tasks/checks.md // L2审核时指挥官智能体可以参考的检查清单 } }实操要点与避坑指南Git工作树Worktree策略这是实现智能体并行开发不冲突的关键。worktree路径必须是一个尚未存在的目录或空目录。系统启动时会自动执行git worktree add worktree_path branch_name。这意味着backend_agent和frontend_agent将在完全独立的文件夹里工作但共享同一个Git仓库历史互不干扰。你无需手动管理git checkout。Telegram配置获取Bot Token通过Telegram的BotFather创建一个新的Bot你会得到一串类似1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ的令牌。切勿直接写在config.json里按照最佳安全实践将其放入环境变量。例如在~/.zshrc或~/.bash_profile中添加export TG_BOT_TOKEN你的Token然后source一下。项目脚本会自动从环境变量中读取。Chat ID给你创建的Bot发送一条任意消息如/start。然后在浏览器中访问这个URLhttps://api.telegram.org/botYourBOTToken/getUpdates。在返回的JSON中找到message.chat.id字段的值那个数字就是你的chat_id。阈值调优nudge_minutes催促阈值和reset_minutes重置阈值需要根据你的智能体工作节奏调整。对于编码任务30分钟无提交可能确实在思考可以适当延长。对于写作任务可能可以缩短。session_max_lines至关重要OpenClaw的会话文件会无限增长导致后续token消耗巨大、速度变慢。设置一个合理的行数限制如300行系统会自动备份旧会话并开启新会话。3.3 创建任务注册表任务注册表Task Registry是一个JSON文件定义了项目的任务流水线。系统指挥官会依据这个列表来分配任务。{ tasks: [ { id: T001, name: 设计并实现博客数据库模型User, Post, Comment, assignee: backend_agent, // 必须与config.json中定义的agent key一致 status: todo, // 初始状态。可选todo, in_progress, review, done metadata: { // 可选字段可存放任务详情链接、验收标准等 spec_link: https://your-confluence/page/123 } }, { id: T002, name: 创建用户注册登录RESTful API端点, assignee: backend_agent, status: todo }, { id: T003, name: 设计博客主页与文章列表UI原型, assignee: frontend_agent, status: todo } ] }将上述内容保存为~/tasks/task-registry.json路径与配置中paths.task_registry一致。系统启动时指挥官会读取此文件并将第一个状态为todo的任务分配给对应的智能体。4. 系统运行、监控与日常操作配置完成后整个系统的操作变得非常简单。4.1 启动与停止首次启动前强烈建议进行干跑测试bash task-start.sh --dry-run这个命令会模拟整个启动过程检查配置有效性、验证Git仓库状态、预览将要执行的git worktree add命令、检查Telegram连接但不会实际创建任何工作树或通知智能体。这是排查配置错误最安全的方式。确认无误后正式启动bash task-start.sh这个脚本会依次执行根据配置为每个智能体创建Git工作树。初始化OpenClaw会话并向每个智能体发送“开工”指令明确告知其工作目录、任务目标以及完成信号的约定提交.done文件或使用[DONE]标签。将两个监控脚本task-monitor.sh,system-watchdog.sh加载到macOSlaunchd开始定时运行。启动后你就可以关掉终端了。系统将在后台自动运行。如何优雅停止 当你需要暂停或结束项目时运行bash task-stop.sh这个停止脚本的设计非常周到它不会粗暴地杀死进程而是执行一个安全关闭流程通知所有智能体发送指令告知智能体当前任务即将中断请它们保存状态并生成一份工作小结Wrap-up。等待3分钟给予智能体足够时间完成手头操作并提交小结。归档小结将智能体生成的小结文件保存到特定目录供后续查阅。安全提交确保所有工作树的最新更改都提交到各自的分支。卸载定时任务从launchd中移除监控任务。可选合并如果你配置了主分支脚本会提示你是否将各个智能体的分支合并回主分支。4.2 理解“假装忙碌”检测算法这是task-monitor.sh的核心功能之一。它通过分析智能体最近一段时间默认最近50条消息的会话历史来识别低效或卡住的模式。其检测逻辑如下模式检测逻辑系统催促消息示例read_loop(空转阅读)连续多条消息都是read_file、search_web等“读取”类工具调用没有write_file、run_command等“输出”类动作。“检测到你在反复查阅资料。请停止空读开始动手写代码或产出具体内容。”stuck_retry(死循环试错)完全相同的命令如python test.py在短时间内连续执行了3次或以上且都失败了。“检测到你在重复执行同一失败命令。请先分析错误信息调整策略后再试不要盲目重试。”error_loop(错误循环)会话中近期出现了5次以上的工具调用错误非用户输入。“近期错误较多。请暂停一下系统分析错误日志找出根本原因改变当前策略。”chatting(空谈讨论)连续出现8条以上的纯文本消息用户或AI的对话中间没有穿插任何工具调用来推进任务。“检测到会话陷入理论讨论。请停止空谈立即执行下一个具体的工具调用来推进任务。”uncommitted(积压更改)在工作树中检测到超过5个已修改但未提交的文件。“你有大量未提交的更改。请立即执行一次git commit来保存当前进度避免工作丢失。”注意这些检测规则和阈值定义在helpers.py的检测函数中。你可以根据自己智能体的行为特点进行调整。例如对于创意写作型智能体chatting的阈值可以放宽对于研究型智能体read_loop的检测时间窗口可以加长。4.3 查看与排查日志系统运行后所有活动都会被详细记录。task-logs.sh是一个强大的日志查询工具# 查看最近20条系统事件 bash task-logs.sh # 只看后端智能体相关的日志 bash task-logs.sh -a backend_agent # 过滤出所有“催促”事件 bash task-logs.sh -e nudge # 查看过去60分钟内的所有日志 bash task-logs.sh -t 60 # 快速查看所有错误信息 bash task-logs.sh --errors # 生成一份完整的系统状态摘要报告 bash task-logs.sh --all日志文件存储在配置项paths.logs_dir指定的目录下按日期和智能体分文件存储便于追溯。当遇到智能体不响应、任务不推进等问题时首先查看日志是定位问题的第一步。5. 生产环境问题排查与经验复盘这个系统是从真实的生产事故中迭代出来的。下面这些“坑”和解决方案能帮你更好地运维它。5.1 常见问题速查表问题现象可能原因排查步骤与解决方案Telegram收不到任何通知1. Bot Token或Chat ID配置错误。2. 网络问题或代理配置错误。3. 脚本没有实际运行。1. 运行bash task-logs.sh --errors查看API错误。2. 手动执行curl命令测试Telegram API连通性。3. 检查launchd服务状态launchctl list | grep task。智能体没有在独立工作树工作1.git worktree add失败目录非空或已存在。2. OpenClaw启动指令未正确指向工作树路径。1. 检查日志中创建worktree的步骤是否报错。2. 手动进入智能体的worktree路径确认是否是一个独立的git目录。3. 停止系统删除旧的worktree目录重新启动。“假装忙碌”检测不准确频繁误报检测阈值如nudge_minutes设置得太短不符合当前任务类型节奏。1. 分析日志看催促触发时的具体上下文。2. 根据任务复杂度适当调整config.json中的thresholds数值例如将nudge_minutes从30调整为45。智能体会话文件巨大响应变慢session_max_lines设置过大或未生效会话历史无限增长。1. 检查智能体会话文件大小位于OpenClaw的会话目录。2. 确认config.json中session_max_lines已设置如300。3. 监控日志看是否有Rotating session file...的记录。系统监控脚本重复执行或死锁mkdir锁机制异常陈旧锁未被清除。1. 检查状态目录paths.state_dir下是否有残留的.lock目录。2. 查看该锁目录的修改时间如果超过10分钟可手动删除。3. 检查task-monitor.sh脚本中stale lock检测部分的逻辑。5.2 从事故中汲取的核心经验这些是文档中提到的“血泪教训”值得深入理解8小时静默故障早期版本依赖智能体自身汇报心跳。结果智能体进程崩溃后整个监控系统也随之沉默。教训监控系统必须与被监控对象在进程级别分离。因此才有了system-watchdog.sh这个独立的、用Bash脚本实现的系统级健康检查。报告轰炸最初每次监控循环都发送状态到Telegram即使状态未变。很快就被消息淹没了。教训状态报告必须去重。解决方案是利用shasum计算每次报告内容的哈希值只有哈希值变化了即状态真正改变了才发送新消息。LLM的“懒惰”曾用一个能力较弱的GLM模型做监控代理它经常直接返回HEARTBEAT_OK而不执行检查。教训永远不要用不可靠的LLM执行确定性任务。这也是整个架构将“巡逻”工作交给Bash脚本的根本原因。会话膨胀一个智能体会话文件曾增长到272k个token导致每次交互都极慢极贵。教训必须对会话长度进行主动管理。于是引入了session_max_lines配置和自动轮转机制。催促轰炸在调试期智能体卡住后每5分钟就收到一次催促体验极差。教训增加催促冷却期nudge_cooldown_minutes。发送一次催促后至少等待冷却期结束才会评估是否发送下一次。5.3 进阶技巧与扩展思路在稳定使用基础功能后你可以考虑以下扩展自定义检测规则helpers.py中的detect_fake_busy函数是检测逻辑的核心。你可以根据自己团队智能体的常见“摸鱼”模式添加新的检测规则。例如增加api_call_loop规则检测是否在反复调用同一个无响应的API。集成外部项目管理工具修改helpers.py中的报告生成函数在任务状态变更时不仅发送Telegram消息同时调用Jira、Trello或Linear的API来更新对应的工单状态。实现智能任务派发目前的task-registry.json是静态列表。你可以增强“指挥官”智能体的能力让它能够根据当前所有任务的完成情况、智能体的负载和专长动态地从任务池中选取下一个最合适的任务进行分配实现简单的动态调度。添加更丰富的完成信号除了.done文件和[DONE]标签可以支持与GitHub/GitLab的集成例如当智能体创建一个标记为“Ready for Review”的Pull Request时即视为任务完成。这个task-orchestrator系统本质上是一个“元自动化”工具它自动化了管理AI智能体这个过程本身。通过将确定性的监控与不确定性的决策分离它用极低的成本和极高的可靠性解决了多智能体协作中最繁琐的进度跟踪问题。当你不再需要手动去检查每个智能体的聊天窗口时你会发现自己才真正成为了那个指挥AI团队的“管理者”而不是它们的“保姆”。