AIProxyServer - 指南

開始使用

1. 啟動應用程式

開啟 AIProxyServer。首次啟動時代理會自動執行，並監聽本機的連接埠 8421 。主視窗分為三個區域：

• 代理伺服器 — 目前狀態、基礎 URL，以及啟動或停止監聽器的按鈕
• Bearer Token — 可選的驗證開關與權杖顯示
• 服務商 — 所有支援的雲端 AI 服務商，每列都帶有一個 設定 API 金鑰 按鈕

2. 新增第一個 API 金鑰

1. 從服務商清單中任選一個（例如 OpenAI (ChatGPT))
2. 點擊 取得 API 金鑰 在瀏覽器中開啟該服務商的主控台，然後建立或複製一個金鑰
3. 點擊 設定 API 金鑰 ，在同一列中將該值貼到對話方塊內
4. 點擊 儲存。狀態標籤會變為 已設定 並顯示為綠色

3. 連接用戶端應用程式

將任何 OpenAI 相容用戶端指向該代理。基礎 URL 為 http://localhost:8421/<provider>/v1。URL 中的服務商區段決定請求要轉發到哪個雲端服務。

# 範例：將 OpenAI Python SDK 指向此代理
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

用戶端始終看不到真實金鑰。AIProxyServer 會在轉發請求時附加上游憑證。

介面總覽

代理伺服器面板

Bearer Token 面板

• 要求 Bearer Token 驗證 — 用於開啟或關閉驗證的核取方塊。預設為關閉，讓本機使用更加省事。
• 權杖欄位 — 以唯讀方式顯示目前的權杖，並以圓點呈現；使用 複製 即可取得。
• 重新產生 — 產生一個全新的隨機權杖。現有用戶端必須更新為新的值。

服務商面板

每個支援的雲端服務商各佔一列。每列會顯示：

• 顯示名稱（例如 Claude (Anthropic))
• 設定狀態 — 已儲存 API 金鑰時顯示綠色 已設定 ，否則顯示灰色 未設定 。
• 用戶端使用的 URL 路徑，例如 /anthropic/v1/chat/completions
• 設定 API 金鑰 — 開啟輸入憑證的對話方塊
• 取得 API 金鑰 — 在瀏覽器中開啟該服務商的主控台

支援的服務商

內建十一種雲端 AI 服務。多數原生使用 OpenAI Chat Completions 格式，可直接直通代理。其中三種（Anthropic、Gemini、ERNIE）使用各自的協定；AIProxyServer 會即時轉換請求與回應，因此您的用戶端始終只會接觸到 OpenAI 格式。

各服務商注意事項

• Azure OpenAI — 請將完整的部署端點貼到 端點基礎 URL 欄位中，例如 https://my-resource.openai.azure.com/openai/deployments/gpt-4o。代理會自動附加 API 端點：/chat/completions?api-version=2024-02-01 。
• ERNIE — 百度千帆使用 OAuth，因此 API Key 和 Secret Key 兩者都必須填寫。AIProxyServer 會在背景請求並快取存取權杖。
• Gemini — 驗證是透過 URL 查詢參數完成，代理會為您自動加上。免費方案的每分鐘配額限制仍然適用。

API 參考

端點

串流

當用戶端傳送 stream: true時，代理會以 OpenAI 格式回傳 Server-Sent Events：

SSE 回應範例：data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Anthropic 與 Gemini 的原生串流會被轉換為此格式，讓所有用戶端都能使用同一個剖析器。

驗證標頭

當 要求 Bearer Token 驗證 開啟時，請在每個請求中傳送主視窗顯示的權杖：

授權標頭：Authorization: Bearer <token-shown-in-app>

設定

點擊底部工具列的齒輪圖示即可開啟設定視窗。

用戶端範例

cURL

# OpenAI（直通）
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# 透過相同的 OpenAI 格式使用 Claude
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # Bearer Token 關閉時會被忽略
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// 使用任何 OpenAI 相容的 Dart 用戶端
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // Bearer Token 關閉時不會使用
);

使用技巧

• 在本機開發時可以讓 Bearer Token 保持關閉；一旦啟用區域網路存取，請立即開啟它。
• 在用戶端程式碼中為每個服務商使用不同的基礎 URL，這樣只需修改一個常數即可切換服務商。
• 代理會自動啟動，但如果發生連接埠衝突，您可以在主視窗中暫時停止它。
• 如果某個服務商的免費方案對您限制速率，上游的錯誤訊息會原樣轉發。不會對用戶端隱藏任何重試邏輯。
• 使用 /v1/providers 端點可以在執行時查看哪些服務商已完成設定。

疑難排解

代理無法啟動

• 可能已有其他處理程序佔用了 8421 連接埠。請在設定中修改連接埠並重新啟動代理。
• 請查看系統記錄檔中啟動時顯示的錯誤訊息。

請求回傳 401 Unauthorized

• 已開啟 Bearer Token 要求，但用戶端未傳送相符的 Authorization: Bearer ... 標頭。
• 服務商本身的 API 金鑰可能無效 — 上游錯誤會被轉發，請檢查訊息內容。

請求回傳「API key is not configured」

• 開啟服務商清單，並為相應服務商點擊 設定 API 金鑰 。
• 對於 ERNIE，API Key 與 Secret Key 都必須填寫。對於 Azure OpenAI，還需要填寫端點基礎 URL。

行動裝置無法連到代理

• 請開啟 允許區域網路存取 （位於設定中）。
• 請使用基礎 URL 欄位中顯示的區域網路 IP，而不是 localhost.
• 請確認兩台裝置處於同一 Wi-Fi 網路，並且防火牆允許代理連接埠的傳入連線。

串流回應一次全部到達

• 請確認您的用戶端在 JSON 內容中傳送了 stream: true 在 JSON 主體中。
• 部分 HTTP 函式庫預設會緩衝 SSE — 請在用戶端關閉回應緩衝。

隱私

• API 金鑰會以 Fernet 加密後儲存於 憑證檔案路徑：~/Library/Application Support/AIProxyServer/credentials.enc。加密金鑰保存在 master.key 中，權限為 0600。
• 啟用後的 Bearer Token 同樣僅保存在加密保險庫中，絕不會寫入一般設定檔。
• 代理只會將請求轉發到您明確設定過的服務商，不會發出任何其他對外呼叫。
• 無遙測、無分析、無當機回報。
• 預設的網路繫結僅為 127.0.0.1 。區域網路曝露需要您主動開啟。
• 不會保存對話內容。AIProxyServer 只轉發位元組，轉發後立即遺忘。