1. 项目概述Claude Code Dispatch 是什么如果你和我一样经常需要让 Claude Code 去处理一些耗时较长的开发任务比如重构一个模块、编写一个完整的微服务或者跑一套复杂的测试那你肯定遇到过两个烦人的问题第一你得一直守在终端前等着它跑完生怕中间出什么岔子第二你根本不知道它什么时候结束可能你离开一会儿回来发现它早就跑完了或者更糟卡在某个地方消耗了大量 Token 却毫无进展。Claude Code Dispatch 这个 OpenClaw 技能就是为了解决这两个痛点而生的。它的核心思想非常直接“发射后不管”。你只需要一条命令把任务描述丢给 Claude Code然后就可以关掉终端去做别的事了。当任务完成或失败、或达到预算上限时你会自动收到一条详细的 Telegram 通知告诉你一切结果。这听起来简单但背后是一套相当精巧的设计。它不是一个简单的脚本封装而是深度集成了 Claude Code 的生命周期钩子Hooks、多智能体协作Agent Teams、成本控制以及 Git 工作树隔离等高级特性。我花了相当一段时间来打磨这套流程让它既能应对简单的单任务也能驾驭复杂的、需要安全审查和性能测试的并行开发场景。接下来我就带你彻底拆解这个工具从设计思路到每一个实操细节包括我踩过的那些坑。2. 核心设计思路与架构解析为什么我们需要一个“Dispatch”系统直接运行claude -p “任务”不行吗对于几分钟就能搞定的小修小补当然可以。但对于动辄半小时、一小时甚至更长的任务这种交互式等待就变得不可接受了。Claude Code Dispatch 的设计目标很明确将一次性的、长时间的 AI 编码任务转变为可异步管理、可监控、可复现的“工作流”。2.1 核心流程从命令到通知整个系统的运行流程可以用一个清晰的链条来描述这也是我经过多次迭代后定型的稳定架构任务派发用户执行dispatch.sh脚本传入任务提示、工作目录、成本限制等参数。元数据记录脚本首先会在指定位置通常是data/claude-code-results/生成一个task-meta.json文件。这个文件至关重要它记录了任务的“出生证明”任务ID、提示词、工作目录、启动时间、成本上限等。这是后续所有回调Callback和去重Deduplication的基石。启动 Claude Code这里有一个关键点脚本通过claude_code_run.py这个 Python 脚本以 PTY伪终端的方式启动 Claude Code。为什么不用直接的claude命令因为在非交互式环境如 CI/CD、cron 任务、后台进程中直接调用claude命令可能会因为终端属性问题导致挂起或输出异常。PTY 包装器确保了在任何环境下Claude Code 都能像一个真正的终端会话一样稳定运行。执行与监控Claude Code 开始工作。如果启用了--agent-teams则会根据配置启动多个子智能体如测试智能体、安全评审智能体并行工作。钩子触发当 Claude Code 任务结束无论是正常完成、被用户停止、达到预算上限还是出错它会自动触发预设的钩子Hook。我们主要监听三个事件StopClaude 停止响应、TaskCompleted任务被明确标记为完成、SessionEnd会话终止。这些钩子会调用我们配置好的notify-agi.sh脚本。通知处理notify-agi.sh脚本被触发。它的工作非常精细读取与验证读取task-meta.json和 Claude Code 的完整输出task-output.txt。去重检查通过一个基于时间的锁文件.hook-lock机制防止在短时间内如30秒内因多个钩子事件比如Stop和SessionEnd接连触发导致重复发送通知。结果聚合将任务名称、耗时、最终输出摘要、甚至生成的文件树变化等信息整合起来。消息发送通过 OpenClaw 的 Telegram 集成将一条格式清晰、信息丰富的通知发送到预设的个人或群组。状态持久化将最终结果写入latest.json并生成一个pending-wake.json作为心跳回退机制防止主通知失败。这个流程确保了从任务开始到结果送达全程无需人工干预且状态可追溯。2.2 关键设计决策为什么这么选基于钩子Hook而非轮询Polling这是最核心的效率设计。轮询意味着需要写一个循环每隔几秒去检查 Claude Code 进程是否还在运行这既浪费资源CPU周期又无法精准捕获“完成”瞬间。而 Claude Code 内置的钩子机制是事件驱动的任务状态一变立刻回调零延迟、零额外 Token 消耗。PTY 包装器的必要性这是我早期踩的一个大坑。在服务器上通过ssh执行命令或者在 CI 流水线中直接调用claude命令经常会卡住因为进程在等待一个不存在的“终端”输入。claude_code_run.py这个包装器模拟了一个终端环境彻底解决了这个问题让 Dispatch 可以在任何后台场景下可靠运行。元数据驱动所有脚本都不依赖内存中的临时状态而是通过读写task-meta.json这样的文件来通信。这使得整个系统非常健壮即使某个进程意外崩溃只要文件还在就能恢复现场或准确报告失败原因。成本控制前置在任务开始前就通过--max-budget-usd和--max-turns设定硬性天花板。这比事后查看账单要主动得多尤其在进行多智能体任务时能有效避免因意外循环或复杂任务导致的巨额费用。3. 从零开始的完整部署与配置指南理论讲完了我们动手把它装起来。整个过程大概需要15-20分钟请一步步跟着操作。3.1 环境准备基石必须打牢首先确保你的系统满足以下三个先决条件缺一不可OpenClaw这是整个生态的调度中心。你需要按照其官方文档完成安装和基础配置。通常就是克隆仓库、运行安装脚本、进行初始设置。确保openclaw命令在终端中可用。Claude Code CLI这是执行任务的主力。前往 Anthropic 官方文档安装并配置好claude命令行工具。你需要拥有有效的 API 密钥并且通过claude auth完成登录验证。在终端输入claude --version确认安装成功。Telegram Bot这是我们的“信使”。你需要通过BotFather创建一个新的 Telegram 机器人获取它的Bot Token。然后将这个机器人添加到你的目标通知群组并获取该群组的Chat ID通常是一个负数。最后在 OpenClaw 的配置中将 Telegram 机器人集成进去。这部分 OpenClaw 的文档会有详细说明。注意获取 Telegram 群组 Chat ID 有个小技巧。你可以先将机器人拉进群然后向群里随便发条消息。接着在浏览器中访问https://api.telegram.org/bot你的BotToken/getUpdates。在返回的 JSON 数据里找到message.chat.id字段那个负数值就是你的群组 ID。3.2 技能安装与钩子配置假设你的 OpenClaw 技能目录是默认的~/.openclaw/skills/。# 1. 克隆或下载 Claude Code Dispatch 仓库 git clone https://github.com/win4r/claude-code-dispatch.git cd claude-code-dispatch # 2. 将技能复制或链接到 OpenClaw 技能目录 cp -r . ~/.openclaw/skills/claude-code-dispatch # 或者使用符号链接方便后续更新 # ln -s $(pwd) ~/.openclaw/skills/claude-code-dispatch # 3. 创建 Claude Code 的钩子目录如果不存在 mkdir -p ~/.claude/hooks # 4. 复制核心通知钩子脚本并赋予执行权限 cp scripts/notify-agi.sh ~/.claude/hooks/ chmod x ~/.claude/hooks/notify-agi.sh接下来是最关键的一步配置 Claude Code 的钩子。编辑 Claude Code 的配置文件~/.claude/settings.json。如果文件不存在就创建它。{ hooks: { Stop: [ { hooks: [ { type: command, command: ~/.claude/hooks/notify-agi.sh } ] } ], TaskCompleted: [ { hooks: [ { type: command, command: ~/.claude/hooks/notify-agi.sh } ] } ], SessionEnd: [ { hooks: [ { type: command, command: ~/.claude/hooks/notify-agi.sh } ] } ] } }这个配置告诉 Claude Code无论任务以何种方式结束正常停止、标记完成、会话结束都去执行我们的notify-agi.sh脚本。脚本会根据内部逻辑判断只发送一次通知。3.3 首次运行测试让我们用一个最简单的任务来验证整个链路是否通畅。# 进入一个临时目录避免弄乱现有项目 mkdir -p /tmp/test-dispatch cd /tmp/test-dispatch # 使用 nohup 和 在后台运行这是标准做法 nohup bash ~/.openclaw/skills/claude-code-dispatch/scripts/dispatch.sh \ -p Create a simple hello world Python script and print the current date. \ -n my-first-dispatch \ -g 你的Telegram群组ID \ --permission-mode bypassPermissions \ --workdir $(pwd) \ /tmp/dispatch-test.log 21 命令解释-p: 任务提示词。-n: 给你的任务起个名字方便在通知里识别。-g: 你的 Telegram 群组 ID通知将发到这里。--permission-mode bypassPermissions: 这是为了测试方便让 Claude Code 拥有最大权限读、写、执行。在生产环境中请根据任务风险使用plan仅计划或acceptEdits需确认编辑等更安全的模式。--workdir: 任务执行的工作目录。 /tmp/dispatch-test.log 21 : 将脚本的所有输出包括错误重定向到一个日志文件并在后台运行。执行后你会立刻得到一个进程 ID。现在你可以关掉这个终端窗口。几分钟内你应该会在配置的 Telegram 群组里收到一条类似这样的通知✅ Task Completed: my-first-dispatch ⏱️ Duration: 2m 15s Workdir: /tmp/test-dispatch Prompt: Create a simple hello world Python script... Output Preview: Created hello.py Running hello.py: Hello, World! 2024-05-27 Task completed successfully.同时在工作目录下你会看到 Claude Code 生成的hello.py文件。恭喜你的 Dispatch 系统已经跑通了4. 高级特性深度使用与实战技巧基础功能跑通后我们来探索那些让这个工具真正强大的高级特性。这些功能能帮你处理真实世界中复杂得多的开发场景。4.1 多智能体团队协作这是最令人兴奋的功能。传统的 AI 编码是单线程的一个智能体既要写代码又要思考测试容易顾此失彼。Claude Code Dispatch 通过--agent-teams和--agents-json参数实现了多智能体并行开发。场景你让 Claude Code 开发一个用户注册模块。你希望主智能体专注实现功能同时有一个专门的“测试智能体”同步编写单元测试和集成测试甚至再有一个“安全智能体”检查代码是否存在常见漏洞。如何使用默认测试智能体nohup bash scripts/dispatch.sh \ -p Implement a user registration endpoint with email verification using FastAPI and SQLAlchemy. \ -n auth-module \ --agent-teams \ --permission-mode acceptEdits \ --max-budget-usd 3.00 \ --workdir /home/user/projects/auth-service \ /tmp/dispatch-auth.log 21 当你只添加--agent-teams参数时Dispatch 会自动为你在 Claude Code 命令中注入一个结构化的“测试智能体”。这个智能体拥有独立的上下文、工具集读、写、编辑、Bash等并默认使用sonnet模型。它会与主智能体并发工作专门负责为所有代码变更编写和运行测试。如何自定义智能体团队--agents-json参数给了你无限的灵活性。你可以定义任意数量、任意角色的智能体。AGENTS_JSON { architect: { description: High-level system design and API contract definition, prompt: Focus on designing clean, scalable interfaces and data models. Do not write implementation code., tools: [Read, Write], model: opus }, implementor: { description: Primary coder, implements the modules based on design, prompt: Write production-ready, well-commented code following the design spec. Prioritize clarity and efficiency., tools: [Read, Edit, Write, Bash, Glob], model: claude-3-5-sonnet-20241022 }, security-auditor: { description: Security specialist focusing on OWASP Top 10 and common vulnerabilities, prompt: Review all code changes for security issues: SQLi, XSS, auth flaws, insecure dependencies. Provide fixes., tools: [Read, Grep, Glob], model: sonnet }, qa-engineer: { description: Writes comprehensive integration and E2E tests, prompt: Create practical integration tests that mock external services and verify business logic flows., tools: [Read, Edit, Write, Bash], model: haiku } } nohup bash scripts/dispatch.sh \ -p Build a payment processing webhook handler with idempotency and retry logic. \ -n payment-webhook \ --agents-json $AGENTS_JSON \ --permission-mode acceptEdits \ --max-budget-usd 8.00 \ --max-turns 80 \ --workdir /home/user/projects/payment-service \ /tmp/dispatch-payment.log 21 在这个例子中四个智能体各司其职“架构师”画蓝图“实现者”写代码“安全审计员”查漏洞“QA工程师”编测试。他们共享同一个文件系统可以互相看到对方的产出并进行协作。你需要特别注意成本多智能体消耗的 Token 是单体的数倍务必设置合理的--max-budget-usd。实操心得定义智能体时prompt是关键。要像给真人分配工作一样清晰角色、职责、边界。避免指令模糊导致智能体间工作重叠或冲突。例如告诉“架构师”不要写具体实现代码可以防止它越界。4.2 精细化成本与资源控制用 AI 干活不谈成本就是耍流氓。Dispatch 提供了多层控制机制让你花钱花在刀刃上。--max-budget-usd这是硬止损线。一旦 Claude Code 估算的任务成本超过这个值任务会立即被停止。这是你必须设置的参数尤其是对于探索性任务。我通常根据任务复杂度设置一个保守值比如小功能 1-2 美元中等模块 3-5 美元复杂任务 10 美元并密切监控。--max-turns限制智能体与环境的交互轮数。一轮通常包含一次“思考”和一次“工具调用”如运行命令、编辑文件。对于目标明确的任务如“修复这个已知 bug”限制轮数可以防止 AI 陷入无意义的尝试循环。--fallback-model当指定的主模型如opus因过载或配额不足而不可用时自动降级到备用模型如sonnet。这保证了任务的可用性虽然可能牺牲一些性能。--model直接指定主模型。你可以根据任务需求选择追求极致代码质量用opus平衡性能与成本用sonnet做简单的文本处理或格式化用haiku。一个兼顾成本与可靠性的配置示例--model opus \ --fallback-model sonnet \ --max-budget-usd 4.50 \ --max-turns 604.3 Git 工作树隔离实现并行开发想象一下你同时有两个功能分支需要 AI 协助开发。如果都在同一个工作目录下肯定会冲突。--worktree参数利用 Git 的 worktree 功能为每个任务创建一个完全隔离的目录。# 假设你的项目主仓库在 /home/user/projects/my-app cd /home/user/projects/my-app # 任务A开发登录功能 nohup bash scripts/dispatch.sh \ -p Implement JWT-based user login and session management. \ -n feature-login \ --worktree feature-login \ --permission-mode acceptEdits \ --workdir $(pwd) \ /tmp/dispatch-login.log 21 # 任务B同时优化数据库查询 nohup bash scripts/dispatch.sh \ -p Analyze and optimize slow database queries in the user profile module. \ -n optimize-queries \ --worktree optimize-queries \ --permission-mode acceptEdits \ --workdir $(pwd) \ /tmp/dispatch-query.log 21 这两个任务会在my-app/.claude/worktrees/feature-login和my-app/.claude/worktrees/optimize-queries下独立进行。它们基于同一个代码库的不同分支互不干扰。任务完成后你可以轻松地审查每个工作树中的变更并决定如何合并回主分支。4.4 系统提示词定制与 MCP 集成--append-system-prompt/--append-system-prompt-file有时候你需要给 AI 一些固定的上下文比如公司的代码规范、项目的架构说明、特定的 API 密钥前缀等。你可以将这些内容写在一个文件里然后通过--append-system-prompt-file company_rules.txt附加到每次任务的系统提示词中确保 AI 始终在正确的约束下工作。--mcp-configModel Context Protocol 是 Claude 生态中一个强大的功能允许 Claude Code 连接外部数据源或工具如数据库、JIRA、内部文档系统。你可以编写一个 MCP 服务器的配置文件JSON然后通过此参数加载。例如让 AI 在编码时能查询你的项目管理系统中的 ticket 详情。这极大地扩展了 AI 的能力边界。5. 通知、回调与结果管理详解任务派出去不是终点如何优雅地接收结果和管理状态同样重要。5.1 通知内容与格式notify-agi.sh脚本会生成信息量非常丰富的 Telegram 消息。一条典型的成功通知包含状态图标与任务名✅ Task Completed: feature-login耗时⏱️ Duration: 12m 34s让你对任务复杂度有直观感受工作目录方便你快速定位生成的文件。原始提示词摘要提醒你这个任务最初是要做什么。输出预览截取 Claude Code 最后一部分关键输出通常是任务总结或最终执行结果。文件树变化如果启用了相关功能列出任务过程中新建或修改的主要文件。测试结果摘要如果启用了 Agent Teams显示测试通过/失败的数量。如果任务失败如达到预算上限、出错通知会明确标记为❌ Task Failed或⚠️ Task Stopped (Budget)并附上错误信息让你能第一时间排查问题。5.2 灵活的回调机制除了在派发时通过-g或--callback-group指定固定的通知群组Dispatch 还支持更动态的回调机制。你可以在项目工作目录下放置一个dispatch-callback.json文件// 方式1回调到特定群组 { type: group, group: -1001234567890 } // 方式2回调到特定用户的私信需要知道用户ID和机器人账号 { type: dm, dm: 123456789, account: my_telegram_bot } // 方式3唤醒事件用于更复杂的自动化流水线 { type: wake }当脚本运行时它会优先查找这个文件。这意味着你可以为不同的项目或分支配置不同的通知目的地非常灵活。wake类型则可以用来触发下游的 CI/CD 流程比如在 AI 完成代码后自动运行部署脚本。5.3 结果文件与调试所有任务的历史记录和原始数据都保存在data/claude-code-results/目录下相对于dispatch.sh脚本的位置。这是一个宝贵的数据金矿。latest.json最新一次任务的全部结果结构化 JSON包含输出、元数据等。task-meta.json当前运行任务或最后一次任务的元数据。task-output.txtClaude Code 的完整标准输出。这是最详细的日志任何打印信息都在这里。hook.log钩子脚本自身的执行日志用于调试通知发送问题。pending-wake.json如果通知发送失败会生成此文件作为重试或备用机制的依据。调试常用命令# 实时查看钩子日志 tail -f data/claude-code-results/hook.log # 以美观格式查看最新结果 cat data/claude-code-results/latest.json | jq . # 查看任务花了多少钱如果元数据里有记录 cat data/claude-code-results/task-meta.json | jq .estimatedCost # 直接测试 Telegram 发送功能 openclaw message send --channel telegram --target -1001234567890 --message Dispatch 通知测试6. 常见问题、故障排查与避坑指南在实际使用中我遇到了各种各样的问题。这里把最常见的坑和解决方案整理出来希望能帮你节省大量时间。6.1 问题任务启动后没有任何反应日志里也没有 Claude Code 的输出。排查首先检查ps aux | grep claude看看 Claude Code 进程是否存在。如果不存在很可能 PTY 包装器出了问题。解决确保你使用的是项目提供的claude_code_run.py脚本并且 Python 环境正常。可以手动测试一下python3 /path/to/claude_code_run.py “echo test”看能否正常输出。有时可能是文件权限问题确保notify-agi.sh和claude_code_run.py都有执行权限 (chmod x)。6.2 问题收到了重复的 Telegram 通知。原因这是最常见的问题之一。因为 Claude Code 可能会先后触发Stop和SessionEnd等多个钩子事件间隔很短。解决notify-agi.sh脚本内置了基于文件锁的去重机制.hook-lock文件默认30秒窗口。如果还出现重复请检查任务工作目录是否有写权限脚本需要能创建.hook-lock文件。系统时间是否同步锁机制依赖时间戳。可以尝试稍微增大notify-agi.sh脚本中的HOOK_LOCK_WINDOW_SECONDS值比如改为45。6.3 问题通知内容显示“Stale metadata”或任务信息不对。原因钩子脚本读取task-meta.json时会检查文件的“新鲜度”默认超过2小时则认为过期和会话ID是否匹配。这防止了旧任务的元数据被误读。解决这通常意味着钩子被一个非常旧的任务触发或者是环境异常。可以安全忽略。如果频繁出现检查你的任务是否运行时间异常长或者系统是否有清理data/claude-code-results/目录的定时任务。6.4 问题使用--agent-teams后费用飙升得很快。原因这是预期之内。每个子智能体都是一个独立的 Claude Code 进程有独立的上下文窗口。一个主智能体加一个测试智能体Token 消耗几乎是单体的两倍。解决务必设置--max-budget-usd这是最重要的安全阀。谨慎使用opus模型对于子智能体可以考虑使用sonnet甚至haiku模型除非任务对代码质量要求极高。在--agents-json中可以为每个智能体单独指定模型。明确智能体职责模糊的指令会导致智能体进行大量无效的探索。给每个智能体清晰、具体的prompt和tools列表限制其行动范围。6.5 问题任务因为“Rate limit”停止了但通知显示“完成”。原因Claude API 有每日速率限制。当达到限制时Claude Code 会停止并触发Stop钩子状态是done这会被脚本识别为“完成”。解决你需要区分这是“真完成”还是“被限制”。查看task-output.txt文件的末尾通常会有明确的速率限制错误信息。对于重要任务建议在非峰值时间运行或者使用--fallback-model配置一个备用的、配额可能不同的模型。6.6 提示词编写技巧Dispatch 只是工具任务成败的七成取决于提示词。几个原则清晰具体避免“优化代码”这种模糊指令。要说“将函数process_data的运行时间降低20%优先考虑算法优化保持接口不变”。提供上下文使用--append-system-prompt-file提供项目结构、技术栈、代码风格指南。拆分复杂任务一个巨型提示词效果往往不好。考虑拆分成多个连续的 Dispatch 任务。第一个任务做设计和规划输出一个计划第二个任务根据计划实现模块A第三个任务实现模块B并集成。设定验收标准在提示词末尾加上“完成时请运行pytest并确保所有测试通过然后输出 ‘ALL TESTS PASSED’。” 这样通知里的输出预览就能直接告诉你结果。我个人习惯为不同类型的任务建立提示词模板文件比如refactor_prompt.txt、new_feature_prompt.txt、bug_fix_prompt.txt然后在 Dispatch 时使用--prompt-file参数加载这样能保证每次任务的质量基线。7. 将 Dispatch 融入你的开发生态Claude Code Dispatch 不是一个孤立的工具它可以成为你自动化开发流水线中的核心一环。与 CI/CD 集成在 GitLab CI 或 GitHub Actions 中你可以配置一个“AI 助手”任务。当新的 Issue 被创建或代码被推送到特定分支时自动触发 Dispatch 任务让 AI 尝试修复 bug 或生成初始实现并将结果评论到 Issue 或 Pull Request 中。定时任务通过系统的cron你可以让 AI 在夜间自动运行代码质量扫描、依赖库升级评估、生成每日报告等重复性工作。与项目管理工具联动结合 MCP 和自定义脚本可以实现“从 JIRA 领取任务 - AI 编码 - 自动提交 PR - 通知负责人”的半自动化流程。这个工具解放了我的双手让我能从繁琐的、模式化的编码工作中抽身更专注于架构设计、复杂问题解决和代码审查。它就像一位不知疲倦的初级开发伙伴严格遵循你的指令并在完成后轻轻拍你的肩膀告诉你“嘿事情办妥了这是结果请过目。”