# 定时任务

定时任务为 [智能体](/cherry-studio/preview/agent.md) 提供按计划自动运行的能力，适用于 "每日早上 9 点生成新闻简报"、"每周一汇总团队工作量"、"每小时同步数据看板" 等周期性需求。

* **本质**：让 Cherry Agent 按预设时间表自动执行
* **能力范围**：任何可由 Agent 完成的任务均可定时化
* **运行记录**：每次运行均保留日志，可随时查阅

> 推荐先阅读 [概念入门](/advanced-basic/concepts-101.md) 了解 Agent 相关概念。

## 不想填表？让 AI 替你建任务

如果你不熟悉 Cron 表达式和各类调度字段，最简单的方式是直接对一个 **具备自主权限的 Agent**（如内置的 Cherry Claw）描述你的需求：

> "每天早上 9 点用最近的新闻给我做一份 5 条要点的简报，结果发到我的飞书。"

Agent 会自动判断需要创建一个怎样的定时任务，并按你描述的内容补齐字段（调度类型、时间、提示词等），中途仅在需要更多信息时向你确认。

{% hint style="warning" %}
**核心前提说明**：

* 内置的 **Cherry Claw** 以及你自建的智能体，默认状态均为 **「自主模式关闭 + 普通模式」**。
* **在使用频道（或定时任务）前，必须手动进入该智能体的编辑面板开启「自主模式」**。
* 开启「自主模式」后，底层的工具调用授权将全自动接管，原有的「权限模式」配置项将随之隐藏，无需再手动进行设置。详见 [智能体](/cherry-studio/preview/agent.md)。
  {% endhint %}

如果希望手动配置或了解每个字段的含义，可继续按下方流程操作。

## 手动配置流程

### 前置要求

定时任务依赖 Agent 运行，所以必须先满足：

1. **已启用** [**API 服务器**](/advanced-basic/api-server.md)
2. **已配置至少一个 Agent**，且该 Agent 已在编辑面板的「基础设置」中开启了 **自主模式**。
   * *注：一旦开启自主模式，原有的「权限模式」配置将自动隐藏，底层的权限将自动接管为全自动运行。*

未满足上述条件的 Agent **不会** 出现在新建任务的下拉中。两类设置的详细说明见 [智能体](/cherry-studio/preview/agent.md#di-5-bu-tiao-zheng-zhi-neng-ti-de-ti-shi-ci-gong-ju-yu-ji-neng)。

{% hint style="info" %}
定时任务空态提示文本仍使用早期命名 "灵魂模式 / 无权限模式"，分别对应当前的 **自主模式 / 全自动模式**。
{% endhint %}

<figure><img src="/files/CPTs4grIkGcmjjPkWooW" alt=""><figcaption><p>未配置可用 Agent 时的空态</p></figcaption></figure>

### 创建一个定时任务

打开 `设置 → 定时任务`，点击中间列顶部的 **+ 添加** 按钮，右侧出现 **添加任务** 表单：

<figure><img src="/files/OknYgvtRGLCvhxM86itL" alt=""><figcaption><p>添加任务表单</p></figcaption></figure>

各字段含义：

| 字段        | 说明                                                                     |
| --------- | ---------------------------------------------------------------------- |
| **名称**    | 任务展示名，便于日后识别（例如 "每日代码审查"）                                              |
| **提示词**   | 任务运行时发给 Agent 的指令，描述 "这次运行 Agent 应该做什么"                                |
| **调度类型**  | `间隔` / `Cron` / `一次性` 三选一                                              |
| **调度值**   | 与调度类型对应：间隔填分钟数；Cron 填表达式；一次性选具体日期时间                                    |
| **超时时间**  | 单次运行的最大时长（分钟），留空为无限制                                                   |
| **发送到频道** | （可选）选择一个已配置的 [频道](/advanced-basic/agent-channels.md)，任务结果会自动推送到该 IM 平台 |

填完点击 **保存**，新任务会显示在中间列表中并立即按调度规则等待触发。

{% hint style="warning" %}
若选择了 **发送到频道**，需要确保该频道在对应平台上有可用的接收目标（Chat ID）。系统会在频道下没有任何用户给 Bot 发送过消息时给出警告 —— **请先在对应平台上给 Bot 发送一条消息**，触发 Cherry Studio 记录 Chat ID。
{% endhint %}

### 调度类型说明

{% tabs %}
{% tab title="间隔（推荐入门）" %}
按固定分钟数循环执行，例如 `60` 即每小时运行一次。
{% endtab %}

{% tab title="Cron" %}
接受标准 Cron 表达式（5 字段）：`分 时 日 月 星期`。常用示例：

| 表达式            | 含义        |
| -------------- | --------- |
| `0 9 * * *`    | 每天上午 9:00 |
| `*/15 * * * *` | 每 15 分钟   |
| `0 0 * * 1`    | 每周一 0:00  |
| {% endtab %}   |           |

{% tab title="一次性" %}
选择一个具体的日期与时间，到点运行一次后任务自动标记为"已完成"，不再触发。

适合 "周五下午 5 点提醒我提交周报" 这类只跑一次的场景。
{% endtab %}
{% endtabs %}

### 管理已有任务

每条任务在列表中都有完整的管理操作：

* **运行**：手动立即触发一次（不影响后续调度）
* **暂停 / 恢复**：临时停掉调度而不删除任务，需要时再恢复
* **编辑 / 删除**：修改任务字段或删除
* **任务状态**：活跃 / 已暂停 / 已完成（仅一次性任务到点后会进入 "已完成"）

### 查看运行结果

每个任务都会保留 **运行历史**：

* 点击任务卡片可查看历次运行记录：时间、耗时、状态（成功 / 错误）、输出
* 失败的运行会附带错误信息，便于排查
* 可点击 **查看会话** 进入该次任务对应的完整对话记录

### 与频道的联动

定时任务的 Agent 输出可以通过 [频道](/advanced-basic/agent-channels.md) 自动推送到：

* 飞书 / Lark
* Telegram / Discord / Slack
* QQ / 微信

例如 "每天早上 9 点把任务结果推送到飞书群"。

{% hint style="warning" %}
长期运行的定时任务会持续消耗模型 token，请在 Provider 后台设置月度上限避免超支。
{% endhint %}

### 提示与技巧

* 建议先以 **间隔 = 5 分钟、最大运行 1 次** 进行试运行，确认输出符合预期后再调长间隔
* 不同任务可共用同一个 Agent，也可为不同场景准备专门 Agent
* 提示词中可引用 `{date}` 等占位符（具体支持以 Agent 模板为准）

***

### 💡 获取帮助与提交反馈

如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions.md) 中提供的官方渠道。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cherry-ai.com/advanced-basic/scheduled-tasks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.