> For the complete documentation index, see [llms.txt](https://docs.cherry-ai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherry-ai.com/docs/zhong-wen-fan-ti/cherry-studio/preview/agent.md). # 智能體 智能體令 AI 唔止可以對話，仲可以**自主完成任務**。 類比： * 普通對話入面嘅 AI 好似 **只可以畀建議嘅同事** —— 你問方法，佢就話你知步驟 * 智能體好似 **具備執行能力嘅同事** —— 你畀定目標，佢會自主讀檔、查資料、調用工具，逐步完成 適用場景示例： * "將 `~/Downloads` 中所有 PDF 整理成 Excel 清單" * "查詢今日主流科技媒體頭條，生成一份 5 條要點嘅簡報" * "審閱指定嘅 Python 文件，畀出改進建議並直接修改" * "每日朝早 9 點自動執行以上任務"（結合 [定時任務](/docs/zhong-wen-fan-ti/advanced-basic/scheduled-tasks.md)） > 推薦先睇 [概念入門](/docs/zhong-wen-fan-ti/advanced-basic/concepts-101.md) 理清助手／智能體／技能／MCP／頻道之間嘅關係。 ### 開始前嘅兩項準備 #### 1. 一家支援 Anthropic 協議嘅 Provider 智能體依賴「工具調用」格式嘅對話方式，目前最成熟嘅實現係 Anthropic Claude 系列模型。因此需要一家提供該協議嘅模型服務商，推薦選項： * [**CherryIN**](/docs/zhong-wen-fan-ti/pre-basic/providers/cherryin-1.md)（最方便）：單一帳號即可同時支援普通對話同智能體 * [**Anthropic 官方**](/docs/zhong-wen-fan-ti/pre-basic/providers/anthropic.md)：直接用 Claude 帳號 * 其他主流 AI gateway（如 [OpenRouter](/docs/zhong-wen-fan-ti/pre-basic/providers/openrouter.md)） #### 2. 啟用 API 伺服器 Cherry Studio 需要喺本機運行一個內部服務嚟承載 Agent。操作上淨係需要喺 `設定 → API 伺服器` 入面撳啟動按鈕就得，詳見 [API 伺服器](/docs/zhong-wen-fan-ti/advanced-basic/api-server.md)。 {% hint style="warning" %} **Token 消耗提示**：Agent 模式涉及多輪對話同工具調用，單次任務嘅 token 消耗明顯高過普通對話。建議喺 Provider 後台設定月度上限以避免超支。 {% endhint %} ### 第 1 步：配置 Anthropic 類型嘅 Provider 打開 `設定 → 模型服務`，搵到（或新建）一個支援 Anthropic endpoint 嘅 Provider： * 填寫 **API 密鑰** * 確認 **API 地址** 指向正確嘅 Anthropic endpoint（CherryIN 預設 `https://open.cherryin.cc`） * 撳 **獲取模型列表**，新增至少一個對話模型（如 `claude-sonnet-4` / `agent/deepseek-v4-pro` 等）

已配置 CherryIN 並新增 agent 模型

{% hint style="info" %} 訂閱咗 Claude Code 嘅用戶可直接將 Anthropic key 同 endpoint 填入對應欄位取得模型。 {% endhint %} ### 第 2 步：啟用 API 伺服器 打開 `設定 → API 伺服器`，確認 port 同密鑰後撳 ▶ 啟動。詳細說明見 [API 伺服器](/docs/zhong-wen-fan-ti/advanced-basic/api-server.md)。

API 伺服器運行中，Agent 先可以工作

### 第 3 步：進入智能體頁面 頂部 Tab 撳 **智能體**。Cherry Studio 預設內置 **Cherry Assistant** 同 **Cherry Claw** 兩個智能體，可直接使用，亦可以按自己需求新建一個。

智能體頁面：左側列表 + 右側對話區

### 第 4 步：新建一個智能體 撳左側欄頂部 **+ 智能體** 按鈕，彈出 **添加 Agent** 表單：

添加 Agent 表單

各字段說明： | 欄位 | 說明 | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **名稱** | Agent 喺列表入面嘅顯示名 | | **模型** | 揀上一步喺 Anthropic 類型 Provider 底下新增嘅對話模型 | | **自主模式** | 一個獨立嘅開關。開啟後會啟用工作區 `soul.md` 自訂身份、自動注入任務管理工具，並停用唔適合無人值守嘅互動式工具。[**頻道**](/docs/zhong-wen-fan-ti/advanced-basic/agent-channels.md) **同** [**定時任務**](/docs/zhong-wen-fan-ti/advanced-basic/scheduled-tasks.md) **要求開啟呢項，並將權限模式設為全自動模式** | | **權限模式** | 控制 Agent 調用工具時係咪需要人工授權，詳見下表。預設 `普通模式` | | **工作目錄** | Agent 可讀寫嘅本地目錄。留空則自動建立預設目錄 | 填完撳 **添加** 就完成建立。 ### 第 5 步：調整智能體嘅提示詞、工具同技能 撳智能體卡片右邊嘅 ⋮ 選單 → **編輯**，進入完整編輯面板：

智能體編輯面板（基礎設定 Tab）

左側 Tab 分類對應唔同設定： * **基礎設定**：頭像、名稱、模型、工作目錄、自主模式、啟用心跳、心跳間隔、描述 * **提示詞設定**：編輯系統提示詞，決定 Agent 嘅角色同對話風格 * **權限模式**：喺 4 種權限策略之間切換（見下方表格） * **工具**：勾選 Agent 可使用嘅內置工具，同掛載來自 [MCP 伺服器](/docs/zhong-wen-fan-ti/advanced-basic/mcp.md) 嘅外部工具 * **技能**：掛載預先安裝嘅 [技能](/docs/zhong-wen-fan-ti/advanced-basic/skills.md) * **高級設定**：最大會話輪數上限同環境變量兩個配置 #### 權限模式嘅 4 種選擇 | 模式 | 行為 | 適用場景 | | ------------ | ------------------------ | --------------------------------------- | | **普通模式**（預設） | 可以自由讀檔；編輯文件或執行命令前會請求人工授權 | 日常對話型 Agent | | **計劃模式** | 只能讀檔同制定計劃，唔可以編輯或執行命令 | 令 Agent 幫你「出方案」但由你執行 | | **自動編輯模式** | 可以自由讀寫文件；執行命令前仍會請求授權 | 令 Agent 接管代碼／文檔編輯，但保留對命令嘅控制 | | **全自動模式** | 所有工具都唔需要人工授權 | **頻道同定時任務必須用呢個模式，並同時開啟自主模式**；自主決策嘅全自動場景 | {% hint style="warning" %} **全自動模式**會令 Agent 跳過所有人工確認，包括寫文件、執行命令、調用外部 API 等。**請只喺受控環境下啟用**，並將 `工作目錄` 限制喺你願意畀 Agent 修改嘅範圍內。 {% endhint %} {% hint style="info" %} **自主模式 vs 權限模式**： * **自主模式** 決定 Agent **可唔可以**進入「無人值守、長任務」形態（載入 soul.md、注入任務管理工具） * **權限模式** 決定 Agent **點樣**處理工具調用授權 兩者獨立。要令 Agent 自動運行定時任務並發到飛書群，需要：**開啟自主模式 + 選擇全自動模式**。 {% endhint %} ### 第 6 步：同智能體對話 返回智能體頁面，撳智能體卡片入會話： * 喺底部輸入框輸入任務，例如「請幫我將 `~/Downloads/report.md` 轉成 PPT 大綱」 * Agent 會自動判斷要調用邊啲工具、係咪需要多輪推理 * 工具調用同決策過程會以可摺疊卡片形式逐步展示 #### 結果展示

智能體調用工具並返回結果示例

### 常見問題 #### 智能體頁面提示「請啟用 API 伺服器以使用智能體功能」 返回 `設定 → API 伺服器`，撳綠色 ▶ 啟動按鈕。詳情見 [API 伺服器](/docs/zhong-wen-fan-ti/advanced-basic/api-server.md)。 #### 建立 Agent 時下拉清單入面冇模型 * 確認所選 Provider 至少新增咗一個對話模型 * 確認該 Provider 類型係 **Anthropic** 或者 **CherryIN**（淨係 OpenAI 嘅 Provider 唔會出現喺 Agent 模型選擇入面） #### Agent 輸出突然停止 可能撞到工具調用上限或者單次會話長度上限。提高 Agent 設定入面嘅最大輪數同單次輸出 token 上限就得。 ### 下一步 * 將 Agent 接去 IM 平台（飛書 / Telegram / QQ / 微信 / Discord / Slack）→ [頻道](/docs/zhong-wen-fan-ti/advanced-basic/agent-channels.md) * 令 Agent 定時自動執行任務 → [定時任務](/docs/zhong-wen-fan-ti/advanced-basic/scheduled-tasks.md) * 拓展工具能力 → [MCP 使用教學](/docs/zhong-wen-fan-ti/advanced-basic/mcp.md) *** ### 💡 獲取幫助同提交反饋 如果您喺配置或使用過程中遇到任何疑問、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/cherry-studio/preview/agent.md?ask= ``` 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.