CompozyOS定时任务与自动化指南Cron调度、Webhook触发器与自动化Job实战【免费下载链接】compozyAn operating system for AI agents. Plug in the agent CLIs you already use (Claude Code, Codex, Gemini CLI, Cursor) and they become a team: they split the work, hand tasks to each other, run automated on jobs and loops, and share one project memory. You steer everything from the browser.项目地址: https://gitcode.com/gh_mirrors/co/compozyCompozyOS 的自动化子系统让 AI Agent 摆脱人工值守你可以用Cron 表达式定义定时任务用事件触发器响应运行时变化再用Webhook 触发器接收外部系统CI、部署流水线的签名请求。这三种自动化原语最终都汇入同一个调度分发器产生与交互会话完全一致的审计记录——每一次运行都有据可查。本文将带你从零配置一个定时 Job并搭建一条 Webhook 自动化流水线。自动化的三大原语Job、Trigger、Webhook 怎么选在动手之前先建立整体认知。CompozyOS 的自动化围绕三个原语构建一句话口诀即可选型原语输入是什么典型场景Job定时任务时间每周一晨会前生成代码评审报告Trigger事件触发器运行时事件会话以错误退出后自动总结失败原因Webhook外部 HTTP 请求CI 部署完成后自动唤起验证 Agent时间 是输入 → 用 Job 事件是输入 → 用 Trigger 外部系统产生事件 → 用 Webhook 触发器三者共用同一套执行内核调度器 → 分发器 → 运行记录。区别只在于什么触发了这次运行。整体架构可以参考官方的自动化特性图定时Job入门Cron调度、间隔执行与一次性任务一个 Job 回答三个问题谁运行哪个 Agent 或 Loop、运行什么输入 prompt、何时运行schedule。CompozyOS 提供三种调度模式模式必填字段格式适用场景cronexpr标准五段式 Cron分 时 日 月 周工作日评审、夜间清理等日历任务everyintervalGo 时长格式如15m、2h30m轮询、周期性健康检查attimeRFC3339 时间戳如2026-04-17T15:00:00Z一次性未来执行第一个定时Job每工作日代码评审最简配置只需写入config.toml注意 Cron 只接受五段式不支持秒[[automation.jobs]] scope workspace workspace /Users/you/src/checkout-api name weekday-review agent reviewer prompt Review the current worktree and write a risk report. schedule { mode cron, expr 0 9 * * 1-5 }不想改配置文件用 CLI 动态创建效果相同compozy automation jobs create \ --name weekday-review \ --scope workspace \ --workspace /Users/you/src/checkout-api \ --schedule 0 9 * * 1-5 \ --agent reviewer \ --prompt Review the current worktree and write a risk report.几个新手容易踩的坑提前说明时区调度默认按UTC求值。想让08:30表示你的本地早晨请在[automation]下显式设置timezone一次性at任务注册时若时间戳已过期会被直接跳过触发后自动从调度器注销并发上限全局默认最多5个活跃 Job可用[automation] max_concurrent_jobs调整。可靠性三件套追赶策略、重试与触发上限守护进程重启后调度器如何补跑错过的触发点这就是**追赶策略catch-up policy**的职责策略重启后的行为skip_missed只补发宽限期内最近一次其余记为取消并跳过非 Loop 任务默认值coalesce合并为一次补跑然后从当前点继续replay按时间顺序重放每一次错过的触发run_once_on_catchup对最近一次错过恰好补跑一次再配合两个保险装置retry { strategy backoff, max_retries 3, base_delay 2s } # 失败按 2s→4s→8s 指数退避重试 fire_limit { max 1, window 24h } # 滚动窗口内最多触发1次防止调度洪水fire_limit的默认值是每小时 12 次。它和重试策略一起构成了自动化任务的安全护栏——即使配置出错任务也不会失控地刷爆你的守护进程。完整字段参考见 jobs.mdx。进阶让定时Job直接驱动一个Loop如果重复的是一整套流程而不是一条 prompt可以让 Job 的目标从 Agent 切换为已发布的Loopcompozy automation jobs create \ --name weekday-release-readiness \ --scope global \ --schedule 0 9 * * 1-5 \ --loop release-readiness \ --loop-workspace /path/to/workspace \ --loop-input channelstable注意定时触发没有事件信封可以映射所以 Loop 目标只接受静态inputsinput_mapping会被拒绝——这是设计使然也是与事件触发器的重要区别。事件触发器会话一停Agent自动跟进当你希望下一次运行取决于 CompozyOS 内部发生了什么就该用触发器了。当前内置的运行时事件家族事件来源典型用途session.created会话生命周期观察者工作区会话开始时启动辅助 Agentsession.stopped会话生命周期观察者总结工作、收集失败、安排跟进评审memory.consolidated记忆整理运行时记忆合并完成后复查持久记忆变化hook.名称.completedHook 运行时某个命名 Hook 完成后继续工作webhook签名 HTTP 入口响应外部 CI、部署、事件系统ext.*扩展触发器 API扩展自定义事件家族触发器支持精确匹配过滤器与prompt 模板。一个经典实战会话因错误退出时自动唤起总结 Agent——[[automation.triggers]] scope workspace workspace /Users/you/src/checkout-api name summarize-failed-sessions event session.stopped agent summarizer prompt Summarize session {{ index .Data \session_id\ }}. Stop reason: {{ index .Data \stop_reason\ }}. filter { data.stop_reason error } retry { strategy backoff, max_retries 2, base_delay 5s } fire_limit { max 4, window 1h }两个细节值得注意filter只做精确匹配data.stop_reason必须严格等于errorprompt是 Go 模板.Data里就是本次事件携带的数据。更复杂的条件判断可以交给生命周期 Hookpre-fire Hook 既能改写 prompt也能直接取消运行取消会被记录为canceled并保留在运行历史中。Webhook触发器让CI和部署事件唤醒你的AgentWebhook 是自动化的外部入口它接收带签名的 HTTP 请求规范化为webhook事件信封然后分发给所有匹配端点、作用域、工作区与过滤器的启用触发器。CompozyOS 没有独立的 webhook 命令组——Webhook 就是一种event webhook的触发器。签名机制时间戳 HMAC 幂等键每个 Webhook 请求必须携带三个请求头缺一不可请求头含义X-Compozy-Webhook-TimestampUnix 秒或 RFC3339 时间戳必须在 5 分钟新鲜度窗口内X-Compozy-Webhook-Signaturesha256 对时间戳.原始请求体计算的 HMAC-SHA256X-Compozy-Webhook-Delivery-ID幂等键窗口内的重放请求会被拒绝签名密钥支持两种存放方式env:NAME引用操作员管理的环境变量或vault:automation/...引用 CompozyOS 加密保管的密钥通过compozy vault put写入。密钥是只写的只参与验签永远不会从读取接口返回。实战部署完成后自动唤起验证Agent先用 CLI 创建 Webhook 触发器compozy automation triggers create \ --name deploy-webhook \ --scope workspace \ --workspace /Users/you/src/checkout-api \ --event webhook \ --endpoint-slug deploy \ --webhook-secret $COMPOZY_DEPLOY_WEBHOOK_SECRET \ --agent deployer \ --prompt Validate deployment {{ index .Data sha }} on {{ index .Data branch }}. \ --filter data.actiondeploy,data.branchmain \ --retry backoff:2:5s再用compozy automation triggers get trigger-id拿到投递 URL。CI 侧用openssl计算签名后即可投递body{action:deploy,branch:main,repository:checkout-api,sha:abc123} timestamp$(date -u %s) signaturesha256$(printf %s.%s $timestamp $body | \ openssl dgst -sha256 -hmac $COMPOZY_DEPLOY_WEBHOOK_SECRET -hex | awk {print $2}) curl -sS -X POST http://localhost:2123/api/webhooks/workspaces/ws_123/deploy--wbh_abc123 \ -H Content-Type: application/json \ -H X-Compozy-Webhook-Timestamp: $timestamp \ -H X-Compozy-Webhook-Signature: $signature \ -H X-Compozy-Webhook-Delivery-ID: deploy-$timestamp \ --data $body响应会告诉你匹配了几个触发器、生成了哪些运行{ result: { matched: 1, runs: [ { id: run_..., trigger_id: trg_..., status: scheduled } ] } }排障速查表HTTP 状态码含义状态码含义400端点格式错误、缺请求头、请求体超限上限 1MiB或缺少密钥配置401时间戳过期/超前或签名无效404路由上没有匹配的触发器注册409触发器被禁用、投递 ID 重放、触发上限、只读定义冲突429超出端点/来源的请求预算按Retry-After重试503自动化管理器未运行还有一点要牢记公共入口在守护进程离线期间不会排队投递。请把重试配置在发送端连接失败就应当视为投递失败。完整错误处理与入口绑定说明见 webhooks.mdx。监控运行历史与自动化建议每次被接受的派发都会写入一条运行记录状态机如下scheduled → running → completed / failed / canceledLoop 目标则为delegated。常用监控命令compozy automation runs --job-id job-id --last 20 # 查看某Job最近20次运行 compozy automation runs --status failed --last 20 # 全局查看失败运行 compozy automation jobs get job-id # 查看 next_run、misfire_count 等调度器元数据如果不想从零写第一条 prompt可以直接用自动化建议SuggestionsCompozyOS 会基于工作区默认 Agent 预填一份定时 Job 提案你只需审阅后一键接受或永久忽略compozy automation suggestions --workspace /abs/path -o json compozy automation suggestions accept suggestion-id --workspace /abs/path接受提案走的是与普通动态 Job 创建完全相同的校验与持久化路径且并发接受有原子保护——只有一个调用方会真正创建 Job。常见疑问 FAQ问Job 和 Trigger 能同时给同一个任务吗能。两者是各自独立的自动化定义都汇入同一分发器。典型搭配是Job 定时巡检 session.stopped触发器兜底失败会话。问定时任务会悄悄漏跑吗不会。CompozyOS 为每个定时任务维护一个持久调度游标记录下次触发时间、上次触发 ID、追赶策略与错失计数。守护进程重启后从游标续跑已认领的触发点不会重复派发。问能不能让自动化任务帮我重启守护进程不能也没有后门。动态 Job/Trigger 的创建与更新会拦截任何要求重启、停止或杀掉 CompozyOS 守护进程的指令包括systemctl/launchctl等系统服务命令并以稳定错误码拒绝。问Webhook 触发器和普通触发器有什么区别Webhook 触发器多了endpoint_slug人类可读的端点段与webhook_secret_ref两个字段并因此拥有唯一的投递 URL。其余字段——目标、过滤器、重试、触发上限——与普通触发器完全一致。小结三步搭好你的自动化体系定时 Job在config.toml里写一个 Cron 表达式给守护进程一个闹钟事件触发器监听session.stopped、memory.consolidated等内置事件让 Agent 对变化做出反应Webhook 触发器用 HMAC 签名把 CI/部署事件接进来外部世界也能唤醒你的 Agent。三者共享同一套运行历史、重试与触发上限机制配置一次即可在 CLI、HTTP API 与浏览器界面中统一观测。更多示例如每日晨报 Job、会话结束即响应的模板可参考 morning-briefing-job.mdx 与自动化总览 automation/index.mdx实现层代码集中在 internal/automation/ 目录核心调度逻辑见 schedule.go。【免费下载链接】compozyAn operating system for AI agents. Plug in the agent CLIs you already use (Claude Code, Codex, Gemini CLI, Cursor) and they become a team: they split the work, hand tasks to each other, run automated on jobs and loops, and share one project memory. You steer everything from the browser.项目地址: https://gitcode.com/gh_mirrors/co/compozy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考