> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/zhong-wen-fan-ti/advanced-basic/developer-tools/api-gateway.md).

# API 網關

API 網關會將 Cherry Studio 已配置嘅模型能力，透過同 OpenAI 同 Anthropic 相容嘅 HTTP API 提供畀本機程式。佢亦都係 Agent 運行所需嘅內部服務。

路徑：【設定】→【API 網關】。

<figure><img src="/files/02d1bdd2df942ea219a90c44284632d3782ccf83" alt="API 网关设置中的运行状态、连接地址、端口和访问凭据"><figcaption><p>外部程式連接前先檢查狀態同埠口；密鑰只提供畀可信嘅本機程式或受控網絡。</p></figcaption></figure>

## Agent 使用同外部調用要分開

* 只用 Cherry Studio Agent：跟住應用提示【啟用並啟動】就得，唔需要將 URL 或密鑰複製畀其他程式；
* 本機程式需要調用 Cherry Studio：啟動網關，複製 URL 同 API 密鑰，並按 API 文件揀相容介面；
* 如果要畀其他裝置存取：咁樣會擴大暴露範圍，需要自行確認網絡監聽、防火牆同存取控制，唔建議喺冇安全措施時開放。

## 啟動同連接

{% stepper %}
{% step %}

### 1. 檢查埠口

網關停止時可以修改埠口。揀未俾其他程式佔用嘅埠口；埠口衝突時服務無法正常啟動。
{% endstep %}

{% step %}

### 2. 啟動網關

撳【啟動】之後，狀態變成【運行中】時，頁面會顯示可用 URL，並提供【API 文件】入口。
{% endstep %}

{% step %}

### 3. 配置授權

外部程式使用 `Authorization: Bearer <API 密鑰>`。頁面可以直接複製授權標頭，唔好將密鑰寫入代碼倉庫或截圖。
{% endstep %}

{% step %}

### 4. 用最小請求驗證

先按照 API 文件請求模型列表或者發送短文本，再接入完整應用。出現錯誤時記錄 HTTP 狀態同回應，唔好公開完整授權頭。
{% endstep %}
{% endstepper %}

## 使用場景：畀本機腳本調用模型

先喺【設定】→【模型服務】確認模型可以正常對話，再啟動 API 網關。腳本只儲存本機網關地址同密鑰，先請求模型列表，再發送一句短文本。接入完整程式前，確認客戶端支援 OpenAI 或 Anthropic 相容介面。

| 配置     | 建議起點       | 作用        | 注意事項                  |
| ------ | ---------- | --------- | --------------------- |
| 監聽範圍   | 只限本機使用     | 減少網絡暴露    | 唔好為咗方便調試就直接開放到局域網或者公網 |
| API 密鑰 | 為當前網關獨立保管  | 驗證客戶端請求   | 唔好寫入倉庫、截圖或者共享日誌       |
| 驗證請求   | 先查模型列表同短文本 | 分開驗證連接同生成 | 失敗時記錄狀態碼，唔記錄完整密鑰      |

### 完成標準

網關顯示【運行中】；模型列表可讀取；短文本請求成功；停止網關之後客戶端無法繼續調用。

## 安全操作

{% hint style="danger" %}
API 密鑰可以調用你喺 Cherry Studio 入面配置嘅模型服務。密鑰洩露之後，應該先停止網關，喺停止狀態下撳【重新生成】，再更新所有本機客戶端。
{% endhint %}

* 網關運行時埠口同密鑰保持只讀，修改前先停止；
* 唔好喺公共倉庫、Issue、日誌或者教程截圖入面展示密鑰；
* 只畀需要調用嘅程式保存密鑰；
* 用量同費用仍然由實際模型服務商產生，可以喺【設定】→【用量統計】查看 Cherry Studio 記錄。

<details>

<summary>API 網關同模型服務有咩關係？</summary>

模型服務會保存上游服務商連接；API 網關會將呢啲能力轉換成相容介面。網關本身唔提供模型，仍然需要至少一個可用服務商同模型。

</details>

<details>

<summary>埠口正常但客戶端返回未授權點算？</summary>

確認請求頭係 `Authorization: Bearer ...`，冇多餘引號或者空格，並檢查客戶端使用嘅密鑰係咪仍然係頁面當前值。

</details>


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/docs/zhong-wen-fan-ti/advanced-basic/developer-tools/api-gateway.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.