OpenHands

Settings → LLM → Advanced 需要三個欄位 — Custom Model、Base URL、API Key — 模型 ID 帶有 openai/ 前綴，Base URL 保留 /v1。

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

逐步操作

1. 在 /app/keys 建立金鑰並複製——金鑰只會顯示一次。
2. 前往 Settings → LLM，開啟 Advanced 切換鈕。接著會依序顯示三個欄位：Custom Model、Base URL、API Key。
3. 輸入帶有前綴的模型 ID——openai/claude-sonnet-5，而不是 claude-sonnet-5。Kunavo 提供的 ID 可透過 GET /v1/models 取得，這也符合 OpenHands 官方文件指示的自訂 ID 來源。
4. 將 https://api.kunavo.com/v1 貼到 Base URL，並將金鑰貼到 API Key，然後點選 Save Changes。OpenHands 文件指出，儲存本機設定檔時會先驗證後端設定，驗證失敗就會阻止儲存，因此此處出現的錯誤代表設定確實遭到拒絕，並非單純的介面提示。
5. 確認後端可連線的目標，而非瀏覽器可連線的目標。base URL 必須能從執行 Agent Server 的機器解析——文件明確指出，若 Agent Canvas 在 Docker 中執行，127.0.0.1 指的是容器。Kunavo 這類公用端點是簡單情況；若前方有企業 proxy，則較複雜。
6. 開始一段新的對話，交給它一項需要讀取並編輯檔案的任務。OpenHands 指出，已儲存的 LLM 設定會套用至新對話，舊對話則必須先重新啟動；實際執行工具的測試，比只打招呼更能驗證這組設定。

已於 2026年9月21日 根據 OpenHands 的 Language Model (LLM) Settings 頁面 進行確認。第三方設定會變動；如果這裡的欄位名稱不再與你看到的內容相符，應以該頁面為準，而不是本頁。

除錯用戶端前先驗證

一個請求就能判斷失敗原因是端點、金鑰還是設定檔。如果這裡回傳 JSON，則相同的基礎 URL 與金鑰在 OpenHands 中也能運作。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

欄位中應填入哪個模型 ID

每個文字模型都能以模型 ID 存取——即時清單位於 GET /v1/models，帶有價格的目錄位於模型頁面。費率是每 1M 權杖的美元價格，輸入／輸出。

除錯前值得了解的三個界線

OpenHands 比單一程序的 CLI 涉及更多元件，其中兩項看起來像 LLM 端點，實際上卻不是。以下內容整理自上述日期查閱的官方文件：

1. 沙箱不是模型。 OpenHands 會在 agent-server 沙箱中執行工作，並透過網路呼叫模型；兩者是各自獨立的介面，也使用不同憑證。在此設定金鑰，只能用於模型呼叫。它與沙箱可連線的對象無關，而沙箱網路問題也不會呈現為驗證錯誤。
2. ACP 代理完全獨立於此設定。 Agent Canvas 可以委派工作給 Claude Code、Codex 或 Gemini CLI，將它們作為 ACP 代理執行；「設定模型」頁面指出，這些代理「會自行管理模型存取權」，因此 LLM 設定檔不會重新導向該子程序。如果你預期金鑰應有流量，卻看不到任何流量，請確認實際執行的是哪個代理。OpenHands 與 Claude Code 的比較會說明這種差異，包括決定優先使用哪組憑證的規則。
3. 設定檔與 10 個的上限。 儲存的設定會成為 LLM 設定檔，最近儲存的設定檔會在新對話中啟用；你也可以在對話中途切換設定檔，而不會遺失 context——因此能在同一把金鑰下使用低價和高價模型。文件規定每個帳戶最多可有 10 個設定檔。Provider Connection 可為多個設定檔儲存一次 provider、API 金鑰和選填的 base URL；同一頁也指出，這個面板只會出現在本機 agent-server 後端，在 OpenHands Cloud 後端中則會隱藏。