# 定時任務

定時任務係 [智能體](/docs/zhong-wen-fan-ti/cherry-studio/preview/agent.md) 提供按計劃自動運行嘅能力，適用於「每日朝早 9 點生成新聞簡報」、「每逢星期一匯總團隊工作量」、「每個鐘同步數據看板」等周期性需求。

* **本質**：令 Cherry Agent 按預設時間表自動執行
* **能力範圍**：任何可由 Agent 完成嘅任務都可以定時化
* **運行記錄**：每次運行都會保留日誌，可隨時查閱

> 推薦先睇 [概念入門](/docs/zhong-wen-fan-ti/advanced-basic/concepts-101.md) 了解 Agent 相關概念。

## 唔想填表？等 AI 幫你建任務

如果你唔熟悉 Cron 表達式同各類調度欄位，最簡單嘅方法係直接對一個 **具備自主權限嘅 Agent**（如內置嘅 Cherry Claw）描述你嘅需求：

> 「每日朝早 9 點用最近嘅新聞幫我做一份 5 點要點嘅簡報，結果發到我嘅飛書。」

Agent 會自動判斷需要建立一個點樣嘅定時任務，並按你描述嘅內容補齊欄位（調度類型、時間、提示詞等），途中只會喺需要更多資訊時向你確認。

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

* 內置嘅 **Cherry Claw** 以及你自建嘅智能體，預設狀態都係 **「自主模式關閉 + 普通模式」**。
* **喺使用頻道（或定時任務）前，必須手動入去該智能體嘅編輯面板開啟「自主模式」**。
* 開啟「自主模式」後，底層嘅工具調用授權會全自動接管，原有嘅「權限模式」配置項亦會隨之隱藏，唔使再手動設定。詳見 [智能體](/docs/zhong-wen-fan-ti/cherry-studio/preview/agent.md)。
  {% endhint %}

如果想手動配置或者了解每個欄位嘅意思，可以繼續跟住下面流程做。

## 手動配置流程

### 前置要求

定時任務依賴 Agent 運行，所以必須先滿足：

1. **已啟用** [**API 伺服器**](/docs/zhong-wen-fan-ti/advanced-basic/api-server.md)
2. **已配置至少一個 Agent**，而且該 Agent 已經喺編輯面板嘅「基礎設定」入面開啟咗 **自主模式**。
   * *註：一旦開啟自主模式，原有嘅「權限模式」配置會自動隱藏，底層嘅權限會自動接管成全自動運行。*

未滿足上述條件嘅 Agent **唔會** 出現喺新建任務嘅下拉選單入面。兩類設定嘅詳細說明見 [智能體](/docs/zhong-wen-fan-ti/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/178395709a308f087b710a7f2192878459aea6ba" alt=""><figcaption><p>未配置可用 Agent 時嘅空態</p></figcaption></figure>

### 建立一個定時任務

打開 `設定 → 定時任務`，撳中間欄最上面嘅 **+ 添加** 按鈕，右邊會出現 **添加任務** 表單：

<figure><img src="/files/e7e3d539bff4bc3c43f5ceed839e34cff0cad839" alt=""><figcaption><p>添加任務表單</p></figcaption></figure>

各欄位意思：

| 欄位        | 說明                                                                                          |
| --------- | ------------------------------------------------------------------------------------------- |
| **名稱**    | 任務展示名，方便日後識別（例如「每日代碼審查」）                                                                    |
| **提示詞**   | 任務運行時發俾 Agent 嘅指令，描述「今次運行 Agent 應該做乜」                                                       |
| **調度類型**  | `間隔` / `Cron` / `一次性` 三揀一                                                                   |
| **調度值**   | 同調度類型對應：間隔填分鐘數；Cron 填表達式；一次性揀具體日期時間                                                         |
| **超時時間**  | 單次運行嘅最長時長（分鐘），留空就係無限制                                                                       |
| **發送到頻道** | （可選）揀一個已配置嘅 [頻道](/docs/zhong-wen-fan-ti/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 輸出可以透過 [頻道](/docs/zhong-wen-fan-ti/advanced-basic/agent-channels.md) 自動推送到：

* 飛書 / Lark
* Telegram / Discord / Slack
* QQ / 微信

例如「每日朝早 9 點將任務結果推送到飛書群」。

{% hint style="warning" %}
長期運行嘅定時任務會持續消耗模型 token，請喺 Provider 後台設定每月上限避免超支。
{% endhint %}

### 提示同技巧

* 建議先用 **間隔 = 5 分鐘、最長運行 1 次** 去試運行，確認輸出符合預期之後再拉長間隔
* 唔同任務可以共用同一個 Agent，亦可以為唔同場景準備專門 Agent
* 提示詞入面可以引用 `{date}` 等佔位符（具體支援以 Agent 模板為準）

***

### 💡 獲取幫助同提交反饋

如果您喺配置或使用過程中遇到任何疑問、Bug 或有功能改進建議，請參考 [反饋同建議](/docs/zhong-wen-fan-ti/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/docs/zhong-wen-fan-ti/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.