如何用 Kortix 的 cron 触发器让 agent 按定时任务自动运行

如何用 Kortix 的 cron 触发器让 agent 按定时任务自动运行

【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress

Kortix 的 trigger（触发器）可以启动一个没有人参与的 session：其中cron类型按你设定的计划时间自动运行，触发时把 manifest 里配置好的prompt渲染为新 session 的第一条消息。本文覆盖从安装 CLI、添加一个 cron 触发器、上线到验证它确实在跑的完整路径，让 agent 按定时任务自动执行工作（例如每个工作日上午汇总昨日活动）。适用的环境是 macOS 或 Linux（官方安装脚本只提供这两个平台的预编译二进制，Windows 不受支持），前提是你已经拥有一个 Kortix 账号并能登录。

准备条件

安装 CLI 并登录：

curl -fsSL https://kortix.com/install | bash

安装脚本下载预编译的kortix二进制。然后登录：

kortix login

接着让当前目录关联到一个项目。两种方式，取决于你是否已有项目：

# 新建项目 kortix init my-app cd my-app # 或者，把已克隆的仓库关联到已有项目 kortix projects link <project-id>

kortix projects link会在当前目录写入.kortix/link.json，此后从该目录执行的kortix命令都指向这个项目。如果打算先跑kortix ship，可以跳过 link——首次 ship 会自动为不存在的项目创建云端项目。

确认 manifest 满足触发器运行的前提：kortix.yaml中agents不能为空，且必须声明default_agent（cron 触发器没有指定agent时默认用它）。manifest 结构和字段约束见 Manifest 参考。

添加一个 cron 触发器

在关联项目的仓库目录里执行：

kortix triggers add daily-digest --type cron \ --cron "0 0 9 * * 1-5" --timezone America/Los_Angeles \ --prompt "Summarize yesterday's activity and save it as a daily note."

这条命令的关键点：

• --type cron是默认类型，显式写出不影响行为，但便于与 webhook、monitor 类型区分；
• --cron是6 字段表达式：秒、分、时、日、月、星期。上例0 0 9 * * 1-5即工作日 9:00:00 触发，注意这是秒级精度表达式，不是常见的 5 字段写法；
• --timezone传 IANA 时区名，缺省为 UTC。定时按该时区的墙钟时间计算；
• --prompt必填，会渲染成触发时 session 的第一条消息。

执行后，触发器只写入了本地kortix.yaml，还没生效。等价的做法是直接在kortix.yaml的triggers:列表里手写配置，字段形态如下：

# kortix.yaml triggers: - slug: daily-digest # 必填，小写字母+连字符，项目内唯一 name: Daily digest # 可选，默认取 slug type: cron # 必填 agent: kortix # 可选，缺省为 default_agent，且必须命名 agents: 中的键 model: anthropic/claude-sonnet-4-5 # 可选，缺省在触发时解析模型 enabled: true # 可选，默认 true cron: "0 0 9 * * 1-5" # 6 字段表达式，与 run_at 二选一 timezone: America/Los_Angeles session_mode: fresh # "fresh" | "reuse" | "pinned" | "keyed"，默认 fresh prompt: "Summarize yesterday's activity and save it as a daily note."

cron触发器必须恰好提供cron或run_at之一，不能同时给。run_at是 ISO-8601 时间戳，只触发一次，之后进入 dormant 状态——适合一次性任务而不是周期任务。

session 复用策略由session_mode决定，默认fresh：每次触发都开新 sandbox 和新分支。若希望同一触发器反复复用同一个 session，可以设为reuse（pinned、keyed需要分别配session_id、session_key，属于进阶用法）。

prompt 支持模板变量。cron 触发可用{{ cron.schedule }}、{{ cron.timezone }}、{{ cron.scheduled_for }}（本次触发对应的计划槽位）、{{ cron.claimed_at }}（调度器实际领取时间）、{{ cron.last_scheduled_for }}（上一次槽位，首次触发时为空），以及{{ trigger.slug }}、{{ trigger.type }}等通用变量。缺失的变量渲染为空字符串，不会报错。

上线：ship 并落到默认分支

kortix ship

kortix ship会校验kortix.yaml、提交本地改动并推送到项目仓库的远端分支。调度计划在该提交落到项目默认分支后才生效。manifest 变更走的是正常分支流程，调度器在合并后数秒内会拾取 cron 或 webhook 的变更。

如果不想走本地编辑 + ship 的流程，add还支持--apply：直接提交到云端项目的main并立即对账，一步到位。kortix triggers set <slug>则只改云端线上触发器（只写你传入的字段），没有本地形态，也没有对应的--apply。

验证触发器在运行

先列出所有触发器及运行状态：

kortix triggers ls

输出包含每个触发器的 slug、state 和上次触发时间（last fire）。用kortix triggers info daily-digest可以查看单个触发器的详情，加--json可获得机器可读格式。

不想等到计划时间点，可以立即手动触发一次：

kortix triggers fire daily-digest

手动触发走的是和 cron 相同的 session 创建路径，因此能验证 prompt、agent、sandbox 整条链路是否通畅。随后可以用kortix sessions ls查看被触发的 session 是否在运行。

注意访问边界：触发器创建的 session 默认是私有策略，由触发器 agent 的 service account 持有；项目 manager（以及账号 owner、账号 admin）总能打开它们，但配置触发器或手动触发它本身不会给你额外的访问权限，除非你本身持有上述角色。

日常管理：启停与暂停

单个触发器的开关（编辑本地 manifest，需要kortix ship才生效）：

kortix triggers enable daily-digest kortix triggers disable daily-digest kortix triggers rm daily-digest

项目级暂停/恢复是服务端的独立开关，一次性停掉项目内所有触发器，与每个触发器自己的enabled字段互不影响：

kortix triggers pause kortix triggers resume

暂停期间调度器跳过该项目，webhook 入站请求返回200加{ status: "skipped" }，不会启动 session，但手动 fire 仍然可用。文档给出的典型使用场景：同一个仓库同时跑在两个控制面（例如 dev 和 production）时，用 pause 避免 cron 被两边重复触发。

修改已有 cron 表达式用set，例如：

kortix triggers set daily-digest --cron "0 0 10 * * 1-5" --timezone America/Los_Angeles

--cron和--run-at互斥，设置一个会清掉另一个。set立即作用于线上触发器，不产生本地 manifest 编辑。

限制与行为边界

• 调度精度：调度器大约每秒轮询一次（默认 1000 ms，可用KORTIX_TRIGGER_SCHEDULER_INTERVAL_MS配置），cron 精度是尽力而为的秒级，尽管表达式里有秒字段。
• 并发上限：每个项目默认同时允许 3 个由触发器发起的 session 处于 provisioning；超出限额的触发不报错，而是返回queued（202），等有空位再运行。账号计划层的活跃 session 上限同样可能生效。
• 去重：cron 触发按计划槽位去重，即使一次触发超时但实际落下了，重试也不会重复执行。
• 模型：触发器不指定model时，在触发时解析；指定后（model字段或--model <provider/model>）该 session 固定使用该模型。
• 触发不产生 commit：触发器触发、运行时状态（last fire time、status）都存在数据库里，不写 Git 历史。通过 API、SDK 或 dashboard 增删改触发器会直接写默认分支，不走 change request 流程。

完整字段表和端点参考见 Triggers 文档，全部kortix triggers子命令见 CLI 文档。

【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress