Claude Code 异步任务调度系统
核心用法
本技能提供了一套完整的异步任务编排框架，允许用户在后台启动 Claude Code 执行复杂任务，并将结果自动推送到指定的通讯渠道（Telegram DM 线程或 WhatsApp 群组）。核心入口为 run-task.py 脚本，通过 nohup 实现进程隔离，避免执行超时限制。
关键操作模式
1. 后台异步执行：使用 nohup 启动任务，主进程立即返回，Claude Code 在 detached 模式下运行
2. 文件化任务注入：所有任务文本必须写入临时文件，通过 $(cat /tmp/prompt.txt) 传入，避免 shell 引号转义问题
3. 线程安全路由：Telegram 任务必须使用 agent:main:main:thread:<THREAD_ID> 格式的 session key，系统会自动验证路由一致性，阻止误投递到主聊天
4. 端到端验证流程：--validate-only 模式可在实际启动前验证路由配置，确认 session-id、thread-id、target 三者匹配
通知管道
系统实现了五级通知机制：
- 🚀 启动通知（静默 HTML 格式，含可展开任务引用）
- ⏳ 心跳保活（每 60 秒，显示运行时长、token 消耗、工具调用数、活跃子代理数）
- 📡 任务中更新（通过
/tmp/cc-notify-{pid}.py脚本，Claude Code 主动调用） - ✅/❌/⏰/💥 完成/错误/超时/崩溃通知（HTML 格式，含结果引用）
- 🤖 代理续接（通过
openclaw agent --deliver唤醒同一会话，保持对话连续性）
显著优点
- 零 API 成本：Claude Code 运行在 Max 订阅（$200/月）上，不消耗 OpenClaw API tokens
- 防误投机制：
--telegram-routing-mode默认为auto，会阻止非线程 session key 启动线程任务，宁可失败也不静默错投 - 会话连续性：支持
--resume续接 Claude Code 会话，--session-label人工命名便于追踪 - 可靠性设计：超时保护（SIGTERM→SIGKILL）、崩溃捕获、PID 追踪、重复唤醒去重（
wake_id+ 输出哈希） - 多平台支持：WhatsApp 群组与 Telegram DM 线程均有完整支持，渠道自动检测
潜在缺点与局限性
- 不适合即时交互：任务启动后即脱离当前会话，无法实时追问，需等待唤醒或主动查询
- Telegram 格式陷阱：
parse_mode="Markdown"会被 Telegram 拒绝（CommonMark**不兼容），必须使用 HTML 模式 - Git 依赖：目标项目必须初始化为 git 仓库（脚本自动
git init但可能不符合预期） - Python 3.9 语法限制：源码使用
Optional[X]而非X | None，维护者需注意兼容性 - 调试复杂度：线程路由失败时仅返回
Invalid routing，需手动检查sessions_list和本地会话文件定位问题
适合人群
- 需要执行 >1 分钟的复杂代码分析、重构、研究任务
- 需要跨平台（Telegram/WhatsApp）异步接收 AI 结果的工作流
- 多步骤自动化场景（Claude Code 可调用子代理完成子任务）
- 对消息投递可靠性有高要求，能接受"宁可失败不静默错误"的严格模式
常规风险
- 路由误配导致消息丢失：若
thread_id与session_uuid不匹配，任务会被拒绝启动，但旧版本或强制模式可能错投到主聊天 - 敏感信息泄露：
run-task.py的日志路径/tmp/cc-*.log为全局可读写，多用户环境需注意隔离 - token 消耗不可控：长任务可能消耗大量 Claude Code 额度，建议设置
--timeout和--max-iterations - 唤醒死循环：
iterate模式下若未正确检测完成条件，可能无限续接；系统要求"可见决策消息"作为强制缓冲 - prompt 注入防护：严禁在任务文本中硬编码 bot token 或 curl 命令，Claude Code 会拒绝执行