调度

OpenSquilla 调度让你可以从 gateway 运行周期性或一次性的 agent 工作。可将其用于提醒、周期性摘要、状态检查、channel 更新以及 Webhook 投递的自动化。

调度通过 opensquilla cron 命令组进行管理。

要求

调度作业通过 gateway 运行：

opensquilla gateway run

对于长期的本地使用，启动受管 gateway：

opensquilla gateway start --json
opensquilla gateway status

列出作业

opensquilla cron list
opensquilla cron list --agent main
opensquilla cron list --json

添加间隔作业

每小时运行一次 prompt：

opensquilla cron add \
  --every 1h \
  --text "Summarize important project updates" \
  --name hourly-project-check

间隔接受诸如 30s、5m 和 1h 的取值。

添加 cron 表达式

在工作日 09:00 按命名时区运行：

opensquilla cron add \
  --cron "0 9 * * 1-5" \
  --tz "America/Los_Angeles" \
  --text "Prepare a short morning brief" \
  --name weekday-morning-brief

若不希望使用默认错峰，使用 --exact。

添加一次性作业

opensquilla cron add \
  --at "2026-06-01T09:00:00+00:00" \
  --text "Remind me to review the launch checklist" \
  --name launch-checklist-reminder

选择 Session 目标

默认目标是隔离的 session。对于大多数调度工作，这是最不令人意外的选项。

可用目标：

目标	使用时机
`isolated`	每次调度运行都应独立。
`session`	你希望投递到由 runtime 入口配置的特定 session。
`main`	你希望为 main session 生成一个系统事件。

示例：

opensquilla cron add \
  --every 30m \
  --session-target isolated \
  --text "Check for urgent channel updates" \
  --name urgent-update-check

投递

禁用投递：

opensquilla cron add \
  --every 1h \
  --text "Create a private summary" \
  --no-deliver \
  --name private-hourly-summary

通过 Webhook 投递：

opensquilla cron add \
  --every 1h \
  --text "Post a compact status summary" \
  --webhook-url https://example.com/hooks/opensquilla \
  --webhook-token-env OPENSQUILLA_WEBHOOK_TOKEN \
  --name webhook-status-summary

优先使用 --webhook-token-env 或 --webhook-token-file 而非内联令牌，避免密钥进入 shell 历史。

查看与运行作业

opensquilla cron status <job-id>
opensquilla cron runs <job-id>
opensquilla cron runs <job-id> --limit 50

立即运行作业：

opensquilla cron run <job-id> --yes

更新或移除作业

opensquilla cron update <job-id> --enabled
opensquilla cron update <job-id> --disabled
opensquilla cron update <job-id> --every 2h
opensquilla cron remove <job-id> --yes

主要投递目标不会从 CLI 原地修补。当主 channel 或 Webhook 目标需要变更时，请移除并重新添加作业。

排障

检查 gateway 与作业状态：

opensquilla gateway status
opensquilla cron list
opensquilla cron status <job-id>
opensquilla cron runs <job-id>

如果作业向 channel 发布内容，还需检查：

opensquilla channels status

接下来阅读：

文档索引 · 产品指南 · 改进此页面 · 报告文档问题