> 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/advanced-basic/api-server.md).
# API 伺服器
API 伺服器嘅核心作用：**將 Cherry Studio 入面已配置好嘅 AI 能力，經由本地介面對外開放**（同時亦係智能體功能嘅底層依賴），俾其他程式調用。
使用場景：你已喺 Cherry Studio 入面配置咗 OpenAI、Anthropic、DeepSeek 等服務商。若你其他工具（例如某個編程插件或者自訂腳本）想調用相同嘅 AI 能力，**API 伺服器**會喺本機開放一個標準介面，令呢啲工具可以直接復用 Cherry Studio 已有配置，無需重複註冊各家帳號。
**幾時需要啟用？**
* 使用 [智能體](/docs/zhong-wen-fan-ti/cherry-studio/preview/agent.md) → **必須啟用**
* 令 Agent 接入 IM 平台（[頻道](/docs/zhong-wen-fan-ti/advanced-basic/agent-channels.md)）→ **必須啟用**
* 只使用 Cherry Studio 普通對話、繪圖、翻譯等功能 → **無需啟用**
> 推薦先睇 [概念入門](/docs/zhong-wen-fan-ti/advanced-basic/concepts-101.md) 了解 Agent、頻道等相關概念。
### 啟用 API 伺服器
1. 打開 `設定 → API 伺服器`
2. 預設監聽埠為 **23333**，可填入 **1000-65535** 之間嘅任何空閒埠
3. 撳右上角綠色 **▶ 啟動** 按鈕
{% hint style="info" %}
**修改埠口嘅方式**：埠口輸入框喺伺服器運行時係唯讀嘅。如需修改，請先撳 ⏹ **停止**，改完埠口再啟動。
{% endhint %}
### API 密鑰同授權頭
**API 密鑰**格式如 `cs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`，喺首次啟用 API 伺服器時自動生成並**持續保留**，重啟伺服器都唔會刷新。
如需手動換新：**必須先撳 ⏹ 停止伺服器**，密鑰右邊先會出現 **重新生成** 按鈕（運行中只顯示複製按鈕）。撳完之後舊密鑰會即刻失效，再次啟動會生成新密鑰。
調用 API 時需要喺請求頭加入：
```
Authorization: Bearer cs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
{% hint style="warning" %}
API 密鑰擁有存取你 Cherry Studio 入面全部 Provider 嘅權限，**請唔好喺公網或者團隊共享渠道暴露**。
{% endhint %}
### 查看 API 文檔
頁面右上角撳 **API 文檔** 按鈕可以打開內置嘅 OpenAPI 介面文檔（Swagger 風格），包含完整嘅端點同請求示例。
### 埠口衝突排查
啟動失敗並提示 `EADDRINUSE: address already in use 127.0.0.1:` 時：
1. 好大機會係另一個 Cherry Studio 實例佔用咗同一個埠口
2. 撳 ⏹ 停止，將埠口改做其他空閒值再啟動
3. 或者喺終端執行 `lsof -i :`（macOS / Linux）查出佔用進程並處理
### 重啟同停止
* **重啟**：撳 ↻ 圖標，通常用喺密鑰重新生成之後強制刷新所有連接
* **停止**：撳紅色 ⏹ 圖標，會即時關閉服務； [智能體](/docs/zhong-wen-fan-ti/cherry-studio/preview/agent.md) 同 [頻道](/docs/zhong-wen-fan-ti/advanced-basic/agent-channels.md) 緊用緊
{% hint style="info" %}
API 伺服器只監聽 `127.0.0.1`，**唔會**暴露到區域網或者公網。若需要跨機存取，請配合 SSH 反向隧道或者類似方案。
{% endhint %}
### 下一步
* 啟用之後就可以繼續配置 [智能體](/docs/zhong-wen-fan-ti/cherry-studio/preview/agent.md)
* 如果想將 Agent 接入飛書 / Telegram / Discord 等 IM 平台，請閱讀 [頻道](/docs/zhong-wen-fan-ti/advanced-basic/agent-channels.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/advanced-basic/api-server.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.