API 伺服器

API 伺服器嘅核心作用：將 Cherry Studio 入面已配置好嘅 AI 能力，經由本地介面對外開放（同時亦係智能體功能嘅底層依賴），俾其他程式調用。

使用場景：你已喺 Cherry Studio 入面配置咗 OpenAI、Anthropic、DeepSeek 等服務商。若你其他工具（例如某個編程插件或者自訂腳本）想調用相同嘅 AI 能力，API 伺服器會喺本機開放一個標準介面，令呢啲工具可以直接復用 Cherry Studio 已有配置，無需重複註冊各家帳號。

幾時需要啟用？

• 使用 智能體 → 必須啟用
• 令 Agent 接入 IM 平台（頻道）→ 必須啟用
• 只使用 Cherry Studio 普通對話、繪圖、翻譯等功能 → 無需啟用

推薦先睇 概念入門 了解 Agent、頻道等相關概念。

啟用 API 伺服器

1. 打開 設定 → API 伺服器
2. 預設監聽埠為 23333，可填入 1000-65535 之間嘅任何空閒埠
3. 撳右上角綠色 ▶ 啟動 按鈕

未啟用時顯示「已停止」，並提示「請啟用 API 伺服器以使用智能體功能」

啟動成功後，狀態會變成綠色 運行中，並顯示監聽地址 http://127.0.0.1:<port>：

運行中狀態，包含「重啟」同「停止」按鈕

修改埠口嘅方式：埠口輸入框喺伺服器運行時係唯讀嘅。如需修改，請先撳 ⏹ 停止，改完埠口再啟動。

API 密鑰同授權頭

API 密鑰格式如 cs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx，喺首次啟用 API 伺服器時自動生成並持續保留，重啟伺服器都唔會刷新。

如需手動換新：必須先撳 ⏹ 停止伺服器，密鑰右邊先會出現 重新生成 按鈕（運行中只顯示複製按鈕）。撳完之後舊密鑰會即刻失效，再次啟動會生成新密鑰。

調用 API 時需要喺請求頭加入：

Authorization: Bearer cs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

API 密鑰擁有存取你 Cherry Studio 入面全部 Provider 嘅權限，請唔好喺公網或者團隊共享渠道暴露。

查看 API 文檔

頁面右上角撳 API 文檔 按鈕可以打開內置嘅 OpenAPI 介面文檔（Swagger 風格），包含完整嘅端點同請求示例。

埠口衝突排查

啟動失敗並提示 EADDRINUSE: address already in use 127.0.0.1:<port> 時：

1. 好大機會係另一個 Cherry Studio 實例佔用咗同一個埠口
2. 撳 ⏹ 停止，將埠口改做其他空閒值再啟動
3. 或者喺終端執行 lsof -i :<port>（macOS / Linux）查出佔用進程並處理

重啟同停止

• 重啟：撳 ↻ 圖標，通常用喺密鑰重新生成之後強制刷新所有連接
• 停止：撳紅色 ⏹ 圖標，會即時關閉服務； 智能體 同 頻道 緊用緊

API 伺服器只監聽 127.0.0.1，唔會暴露到區域網或者公網。若需要跨機存取，請配合 SSH 反向隧道或者類似方案。

下一步

• 啟用之後就可以繼續配置 智能體
• 如果想將 Agent 接入飛書 / Telegram / Discord 等 IM 平台，請閱讀 頻道

---

💡 獲取幫助同提交反饋

如果您喺配置或使用過程中遇到任何疑問、Bug 或有功能改進建議，請參考 反饋同建議 入面提供嘅官方渠道。