概述
openclaw cron list（CLI）是对 Gateway WebSocket RPC cron.list 的封装。两者操作同一份数据，但层次不同：CLI 面向人类，WS RPC 面向程序化集成。
架构层次
用户 / 外部工具
│
├── openclaw cron list/show/... ← CLI 层（人类友好，含额外计算字段）
│ │
│ └── ws cron.list/... ──→ Gateway WS RPC ← 协议层（TypeBox schema 驱动）
│ │
│ └── jobs.json + jobs-state.json ← 持久化层
│
└── 插件 / 自定义客户端
│
└── ws cron.list/... ──→ Gateway WS RPC
Gateway 是唯一权威数据源。CLI、macOS app、Web UI、TUI 均通过 WebSocket 连接 Gateway，调用相同的 RPC 方法。
WS 方法与 CLI 命令对照
| WS 方法 | CLI 命令 | 说明 |
|---|---|---|
cron.list | openclaw cron list | 列出所有 cron job |
cron.get | openclaw cron get <id> | 获取单个 job 的原始 JSON |
cron.status | openclaw cron show <id> | 获取 job 状态（含投递路由预览） |
cron.add | openclaw cron add | 创建 job |
cron.update | openclaw cron edit <id> | 修改 job |
cron.remove | openclaw cron delete <id> | 删除 job |
cron.run | openclaw cron run <id> | 手动触发 job |
cron.runs | openclaw cron runs --id <id> | 查看 job 运行历史 |
WS 层 schema 定义在 src/gateway/protocol/schema.ts，运行时用 AJV 验证。
方法注册表在 src/gateway/server-methods-list.ts（listGatewayMethods）。
CLI 在 WS 之上额外做了什么
1. 计算 status 字段（--json 模式）
cron list --json 和 cron show <id> --json 在每个 job 上附加计算出的顶层 status 字段：
| 值 | 含义 |
|---|---|
disabled | job 已禁用 |
running | 当前正在运行（state.runningAtMs 非空） |
ok | 上次运行成功 |
error | 上次运行失败 |
skipped | 上次运行被跳过（如本地模型不可达） |
idle | 等待下次调度 |
由 enabled、state.runningAtMs、state.lastRunStatus 三个字段推导，省去外部工具自己推导的麻烦。
2. --agent 过滤
cron list --agent <id> 按 agent 过滤，没有存储 agent id 的 job 归属默认 agent（main）。
3. 投递路由预览
cron show（对应 cron.status）解析 channel: "last" 的实际投递目标，显示路由是从 main session 还是 current session 解析的，以及是否会 fail-closed。
4. 三种查看命令的区别
| 命令 | WS 方法 | 输出 |
|---|---|---|
cron list | cron.list | 表格（默认）或带 status 字段的 JSON |
cron get <id> | cron.get | 原始 job JSON（无额外计算） |
cron show <id> | cron.status | 人类可读视图 + 投递路由预览 |
持久化数据
两者读取同一份文件：
| 文件 | 内容 | 建议 |
|---|---|---|
~/.openclaw/cron/jobs.json | Job 定义 | 可纳入 git 管理 |
~/.openclaw/cron/jobs-state.json | 运行时状态（nextRunAtMs、lastRunStatus 等） | 建议 gitignore |
~/.openclaw/cron/runs/<jobId>.jsonl | 每个 job 的运行日志 | 受 runLog.maxBytes 控制 |
注意：直接编辑 jobs.json 时，Gateway 检测变更并重新加载调度，同时清除因 schedule 字段变化而过期的 nextRunAtMs；纯格式化/key 顺序变更不会清除 pending slot。
使用场景选择
| 场景 | 推荐方式 |
|---|---|
| 日常查看任务列表 | openclaw cron list（输出友好，--json 有计算好的 status） |
| 调试投递路由 | openclaw cron show <id>（对应 cron.status，显示路由解析结果） |
| 获取原始 job 定义 | openclaw cron get <id>（对应 cron.get，无加工） |
| 插件 / 自定义客户端集成 | 直接调用 ws cron.list 等 RPC，避免 CLI 进程开销 |
| 监听 job 变更事件 | 订阅 Gateway WS cron 事件（cron run/job change 推送） |
相关页面
- concepts/cli-cron —
openclaw cronCLI 完整参考 - typebox — Gateway WS 协议 Schema（TypeBox 驱动）
- architecture — Gateway 单进程架构与 WS 协议