Claude Code 的定时任务怎么配：桌面端与命令行两处入口

想让 Claude Code 隔一阵子自己去看一眼部署跑完没有、PR 的 CI 有没有变红，第一反应是「它有没有定时任务」。有，但官方文档把这件事拆成了三条并不互通的路径，字段不一样、触发条件不一样、能活多久也不一样。选错入口的后果通常不是报错，而是任务安静地不触发，你还以为它在跑。这篇只把任务定义里有哪些字段、每个字段改的是什么、什么条件下才会被触发，按官方文档写明的内容对齐一遍。

先分清你要的是哪一种「定时」

code.claude.com/docs/en/scheduled-tasks 与 code.claude.com/docs/en/desktop-scheduled-tasks 两页各放了同一张对照表，列出三种方式：云端的 Routines、桌面端的本地 scheduled task、命令行会话里的 /loop，逐行对照跑在哪、是否要求机器与会话开着、重启后是否持久、能否访问本地文件、MCP 服务器从哪来、是否有权限询问、最小间隔等。

决定你走哪条路的是三行：/loop 文档写明是 session-scoped 的，任务活在当前这轮对话里，开新对话就清空；桌面端本地任务不要求你手上有会话，到点自己起一个新会话，但要求机器与应用开着；云端 Routines 不要求机器开着，代价是文档写明它拿不到本地文件（跑的是 fresh clone）。云端那条有单独一页，本文不展开。

前置条件

命令行侧需要一个开着的会话。文档在 Limitations 一节写明，任务只在 Claude Code 正在运行且空闲时触发，关掉终端或让会话退出就不再触发。另有一个容易踩的前提：Claude Code 把任务列表存在项目的 .claude 目录里，当该目录或里面的任务文件是符号链接时，创建任务会直接报错——用 dotfiles 软链方案的人会卡在这。还有个总开关：环境变量 CLAUDE_CODE_DISABLE_CRON=1 会整体关掉调度器，cron 工具与 /loop 都不可用，已排期的任务也停止触发；企业环境里发现 /loop 不存在，先查它。

桌面端侧需要 Claude Code Desktop，文档写明任务只在应用运行、电脑醒着时跑。保存任务前必须先选定工作文件夹；文档写明若该文件夹尚未被信任，会要求先信任再保存。

关于 Windows：这两页没有对 Windows 与 macOS/Linux 分别说明，路径一律写成 ~/.claude/... 这种形式，配置目录可由 CLAUDE_CONFIG_DIR 指定；这些路径在 Windows 上实际落在哪里，官方文档在这两页里没有说明这一点。对笔记本用户有一条直接相关：文档写明可以在 Settings 的 Desktop app → General 下打开 Keep computer awake 避免闲置休眠，但合上盖子仍然会睡眠。

命令行侧：/loop 的参数与三个 cron 工具

/loop 在文档里被称为 bundled skill，行为取决于你给了「间隔」和「提示词」中的哪几样：

你提供的内容	文档给的例子	行为
间隔 + 提示词	/loop 5m check the deploy	按固定日程跑你的提示词
只有提示词	/loop check the deploy	每轮由 Claude 自己挑一个间隔
只有间隔，或什么都不给	/loop	跑内置维护提示词，或你的 loop.md（若存在）

间隔支持的单位文档写明是 s、m、h、d，可以写在提示词前当裸 token（如 30m），也可以跟在后面当从句（如 every 2 hours）。两条取整规则值得记：秒向上取整到分钟，因为 cron 只有分钟粒度；不能映射成干净 cron 步长的间隔会被取整，文档举的例子正是 7m 和 90m，Claude 会告诉你它挑了哪个——也就是说你写 90m 拿到的不是 90 分钟。不给间隔时，文档写明 Claude 每轮结束后按观察到的情况挑一个一分钟到一小时的延迟，并打印选了多久与理由。

底层的任务定义由三个工具承载：

工具	用途
CronCreate	新建任务。接受一个 5 字段 cron 表达式、要跑的提示词、以及它是重复还是只触发一次
CronList	列出所有任务，带 ID、日程、提示词
CronDelete	按 ID 取消任务

这就是命令行侧任务定义的全部字段：cron 表达式、提示词、重复与否。没有独立的名称、工作目录、权限模式字段——MCP 服务器与权限询问文档都写明从当前会话继承。每个任务有一个 8 字符 ID，CronDelete 按它删。一次性提醒不用 /loop，文档写明用自然语言描述即可，Claude 会排一个跑完自删的单次任务，例如 remind me at 3pm to push the release branch。

cron 表达式支持到哪一层

CronCreate 收标准 5 字段表达式 minute hour day-of-month month day-of-week。文档写明所有字段支持通配符 *、单值（5）、步长（*/15）、区间（1-5）、逗号列表（1,15,30）。需要单独记住的是不支持的部分：L、W、? 这类扩展语法，以及 MON、JAN 这种名称别名，文档明确写了 not supported。星期字段用 0 或 7 表示周日、6 表示周六。还有一条经典坑文档照实写了：day-of-month 与 day-of-week 同时被限定时，两者任一匹配即算命中，遵循 vixie-cron 语义。

触发条件：不是「到点就跑」

文档写明调度器每秒检查一次到期任务并以低优先级入队；排期的提示词在你的两轮对话之间触发，不会打断 Claude 正在生成的回复，到点时 Claude 正忙就等当前这轮结束。所有时间按本地时区解释，0 9 * * * 指你所在时区的 9 点而非 UTC。

之上还叠了一层 jitter，文档自述理由是避免所有会话在同一墙钟时刻打 API：重复任务最多在排定时间之后 30 分钟触发（比每小时更频繁的任务，偏移上限是间隔的一半）；排在整点或半点的一次性任务最多提前 90 秒触发。偏移由任务 ID 推导，同一任务每次相同。文档也给了规避方法：时间必须准就挑一个既不是 :00 也不是 :30 的分钟，例如写 3 9 * * * 而不是 0 9 * * *，一次性任务的 jitter 就不生效。

寿命方面，重复任务在创建 7 天后自动过期，最后触发一次然后自删；文档自述这条是为了限制一个被忘掉的 loop 能跑多久。要更久就在过期前取消重建，或改用云端 Routines、桌面端任务。

另外两点：裸 /loop 的默认提示词可以用 .claude/loop.md（项目级优先）或 ~/.claude/loop.md（用户级）替换，取先找到的那个，且你在命令行上给了提示词时它会被忽略；loop 等待下一轮时按 Esc 清掉待触发的唤醒，但文档特意写明你直接跟 Claude 说话排出来的任务不受 Esc 影响，得显式删。

桌面端：本地任务的四个字段

文档写的入口是在侧栏 Routines 里新建 routine 并选 Local（同一页面也能建云端 routine，两者不是一回事）。要填的字段文档列了四个：

字段	文档写明的含义
Name	任务标识。转成小写 kebab-case 并用作磁盘上的文件夹名，必须唯一
Description	任务列表里显示的简短说明
Instructions	任务触发时要 Claude 做什么，按平时写消息的方式写
Schedule	多久跑一次

Name 不只是显示名，它直接决定磁盘上的目录名。文档写明 Instructions 这一项附带 permission mode 与模型的选择器，其下还要选工作文件夹、以及是否在隔离的 Git worktree 里跑。默认情况下文档写明任务对着工作目录的当前状态跑，包含未提交的改动，打开 worktree 开关才让每次运行拿到自己独立的 worktree——「定时任务会不会搅乱我手上正在改的代码」，答案就在这个开关上。

Schedule 是预设，文档列了五个：Manual（不排期，只在手动触发时跑）、Hourly、Daily（带时间选择器，默认本地时间 9:00 AM）、Weekdays（同 Daily 但跳过周六周日）、Weekly（带时间与星期选择器）。预设覆盖不到的间隔（文档举的例子是每 15 分钟、每月 1 号、将来某个时刻只跑一次），办法是在任意 Desktop 会话里用自然语言让 Claude 去排。

触发条件与补跑规则

文档写明 Desktop 在应用开着时每分钟检查一次日程，到点起一个全新会话，与你手上的会话互不相干；每个任务在排定时间后有几分钟的错开延迟，同一任务每次偏移相同。

补跑规则和命令行侧完全不同：应用启动或电脑唤醒时，Desktop 检查每个任务在过去七天里有没有漏跑，有的话只为最近一次错过的时间起一次补跑，更早的全部丢弃，文档举的例子是漏了六天的每日任务唤醒后只跑一次。而 /loop 侧文档写明是 no catch-up——漏掉的那次在 Claude 空闲时触发一次，不按漏掉的次数补。这条规则的直接后果文档自己点了出来：排在 9 点的任务可能因为电脑睡了一整天而在晚上 11 点才跑，应对办法是把时间约束写进提示词本身。

权限与磁盘上的那个文件

每个任务有自己的 permission mode，在创建或编辑时设定；~/.claude/settings.json 里的 allow 规则同样对定时任务的会话生效。文档写明任务跑在 Manual 这个 permission mode（注意与 Schedule 里那个同名的 Manual 预设不是一回事）下且要用未授权的工具时，这次运行会停住等你批准；规避办法是建完先手动触发一次，把权限询问逐个选成 always allow。两类例外文档写得很明确：被组织设为 ask 的连接器工具、标了 requiresUserInteraction 的 MCP 工具，每次调用都询问且不提供 always allow。

提示词在磁盘上有实体文件：~/.claude/scheduled-tasks/<task-name>/SKILL.md（设了 CLAUDE_CONFIG_DIR 则在其下）。文档写明它用 YAML frontmatter 放 name 和 description，提示词作为正文，改动在下次运行生效；但日程、文件夹、模型、启用状态都不在这个文件里，要走编辑表单或让 Claude 改。文档另提到 update_scheduled_task 这个 MCP 工具，任务可以在运行中改自己的日程或提示词。

边界：文档明说不行的部分

• /loop 里不是所有斜杠命令都会被执行。 文档写明只有 Claude 被允许自行调用的 skill 才在排期触发时执行；/permissions、/model、/clear 这类内置命令，标了 disable-model-invocation: true 的 skill（含内置的 /verify），被 skillOverrides 或 Skill deny 规则挡掉的 skill，以及 MCP prompt，都是以纯文本抵达 Claude 而不执行。
• 不同 provider 下 /loop 行为不同。 文档写明在 Amazon Bedrock、Claude Platform on AWS、Google Cloud’s Agent Platform、Microsoft Foundry 上有两处差异：不给间隔时跑固定 10 分钟日程而非 Claude 自选日程；不给提示词时打印用法说明而非跑维护提示词或读 loop.md。关掉 feature-flag 获取时行为相同。
• 会话相关的丢失。 开新对话清掉所有会话级任务；--resume 或 --continue 恢复的是未过期的重复任务与触发时间未到的一次性任务，而后台 Bash 与 monitor 任务一律不还原。
• 一个会话能同时持有的任务数有上限，loop.md 也有字节上限，具体数值以官方文档为准。
• 这两页文档里没有 beta、preview、experimental 或 deprecated 的标注，因此本文不给任何一处贴这类标签。

怎么验证配对了

命令行侧：排完直接问 what scheduled tasks do I have?，文档写明 CronList 返回每个任务的 ID、日程与提示词——对着返回的日程确认它没被取整成你没预期的值，再确认你知道那个 8 字符 ID 怎么删。首次触发时间要按 jitter 放宽，重复任务晚到 30 分钟内属于文档写明的正常范围，别在第 5 分钟就断定没生效。

桌面端做三件事：用 Run now 立刻跑一次把权限询问处理掉；到任务详情页看 Review history，文档写明那里能看到每次运行包括被跳过的运行，停在被跳过的条目上会显示原因（电脑在睡、上一次运行还没结束、或当时有别的定时任务在跑），这是判断「为什么没跑」最直接的证据；确认 Status 是 Active 而不是 Paused。删除时文档写明确认框里有 Also delete files on disk 勾选项，勾上才会一并删掉该任务在磁盘上的 SKILL.md 与相关数据。

还有个常见错配：目标若是「电脑关着也要跑」，上面两条路径都不满足——文档写明本地任务要求机器开着，/loop 还额外要求会话开着，这种情况文档指向的是云端 Routines 或 GitHub Actions 的 schedule 触发器。

以上命令与配置项均照抄自官方文档，组合使用时的具体行为未经我们验证，以官方文档与实际输出为准。

---

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。 该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。 该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。 本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。