手機代理連接 AI 模型 API：FoneClaw 的 API Base URL、API Key 與安全測試指南
教你在 FoneClaw 內使用免費預設模型，或設定相容 AI 模型的 API Base URL、API Key 與 model ID，並用低風險 Android 動作驗證受治理的手機代理流程。
- FoneClaw 有兩條模型路徑：直接使用免費預設模型，或在 FoneClaw 內設定相容模型的 API Base URL、API Key 與 model ID。
- API Base URL 是相容服務端點，API Key 用來驗證請求，model ID 則決定要呼叫供應商的哪個模型；三者正確不代表已取得 Android 權限。
- 模型連線測試應先做無害文字回覆，再測低風險可見手機動作；成功聊天不等於每個 Android 工具都可執行。
- FoneClaw 目前已加入逐工具控制、核准覆寫、權限復原與更強的失敗處理，讓自訂模型驅動手機代理時仍保留治理邊界。
先選模型路徑：使用預設模型或接入自己的 API
如果你想做「手機代理連接AI模型API」，先不用急著找一串設定值。FoneClaw 有兩條路徑：你可以直接使用 FoneClaw 內建的免費預設模型，也可以在 FoneClaw 內設定相容模型，填入 API Base URL、API Key 和 model ID，讓該模型負責理解、推理與規劃。兩條路徑都由 FoneClaw 作為 Android 手機代理執行環境，不是讓兩個 App 在手機上互相代操。
這個分工很重要。模型回答「下一步應該開啟地圖」是一回事；FoneClaw 能不能呼叫支援的 Android 工具、是否需要權限、是否要你確認，以及結果是否可見，是另一回事。模型負責思考，FoneClaw 負責把支援的手機動作放進可治理流程。
| 路徑 | 需要準備 | 適合情境 | 注意事項 |
|---|---|---|---|
| 使用免費預設模型 | 不需要自行提供 API Key | 想快速測試 FoneClaw 的手機代理流程 | 先用低風險任務熟悉權限與核准 |
| 設定相容模型 API | API Base URL、API Key、model ID | 已有供應商帳號、想自訂模型能力或成本 | 端點相容、金鑰安全與模型工具理解都要測試 |
若你還不熟 Android 手機代理如何從自然語言變成可見動作，可先讀手機 AI Agent 控制是什麼？Android 手機自動化代理的能力、邊界與安全檢查。那篇會把執行層、工具、權限與結果顯示講完整；本篇則聚焦模型 API 設定與第一個安全驗證流程。
API Base URL、API Key 與 model ID 各代表什麼
設定自訂模型驅動手機代理時，最常混淆的是三個欄位。API Base URL 指向相容模型服務的基礎端點；API Key 用來證明你有權呼叫該服務；model ID 則指定供應商提供的哪一個模型。這三者要一起正確，FoneClaw 才能把請求送到你選定的模型。
API Base URL 不是品牌名稱，也不是文件首頁。它通常是一個以 HTTPS 開頭、由供應商指定的相容端點。不同供應商可能有不同路徑；有些供應商也提供 OpenAI-library compatibility，但這不代表所有服務都共用同一個 Base URL。Google 的Gemini API 相容性說明就是一個例子：供應商可以提供相容介面，但仍會要求使用自己的端點、憑證與模型名稱。
API Key 是憑證，不是設定註解，也不應出現在截圖、文章、客服對話或公開 issue 中。OpenAI 的API 驗證說明也把 API key 放在請求驗證的核心位置；實務上，你應把它當成密碼處理。本文只使用佔位字串，例如 sk-example-placeholder 或 YOUR_API_KEY，不要把真實金鑰貼進任何公開畫面。
| 欄位 | 用途 | 常見錯誤 |
|---|---|---|
| API Base URL | 告訴 FoneClaw 要連到哪個相容服務端點 | 填成官網首頁、少了 HTTPS、路徑不符合供應商要求 |
| API Key | 用來驗證你的模型服務請求 | 複製到多餘空白、用錯專案金鑰、把金鑰公開 |
| model ID | 指定要使用的模型 | 填成顯示名稱、大小寫錯誤、模型不支援所需能力 |
最後要記住：API Key 只能讓模型服務接受請求，不能替你授予 Android 權限。即使模型連線成功，讀取通知、開啟 App、建立提醒或執行其他手機動作，仍要看 FoneClaw 的支援工具、Android 系統權限與你的核准設定。
在 FoneClaw 內逐步設定相容模型
FoneClaw 能設定自訂模型嗎？可以。正確做法是在 FoneClaw 的模型設定流程中，從預設模型切換到相容模型端點，填入供應商提供的 API Base URL、API Key 和 model ID。不要把模型供應商的獨立聊天 App 當成手機代理入口；在 FoneClaw 裡，模型是被設定進代理執行環境，用來驅動 FoneClaw 的推理與規劃。
- 先決定是否真的需要自訂模型。如果只是第一次體驗手機代理，先用免費預設模型更簡單。
- 向模型供應商取得相容 API 資訊，包含 API Base URL、API Key 和正確 model ID。
- 確認端點使用 HTTPS，並檢查供應商文件是否要求特定相容路徑。
- 在 FoneClaw 的設定中開啟模型配置，選擇使用相容端點。
- 填入 API Base URL、API Key 和 model ID。貼上後檢查是否有前後空白或換行。
- 儲存設定後，把該模型設為目前使用的模型，再做連線測試。
- 若測試失敗，先不要改 Android 權限；先排查端點、金鑰和 model ID。
設定時請避免兩個風險。第一，不要把真實 API Key 放在螢幕錄製、教學圖片或共享文件裡。第二，不要把「模型能回答」誤解成「模型已能控制手機」。FoneClaw 的手機動作仍透過受治理的 Android 工具完成，並依任務需要請求權限。
如果你正在比較多個模型供應商、想知道哪些模型適合負責手機代理規劃，可以延伸閱讀Kimi K3、DeepSeek V4 與 GLM-5.2：手機 Agent 該如何選模型。那篇處理模型路由與選型；本篇則保留在設定欄位、連線測試和安全手機動作驗證。
控制手機前，先測模型連線
模型設定完成後，第一個測試應該是無害文字請求，而不是直接傳訊息、刪除資料或修改設定。你可以問：「請用一句話說明目前模型已連線。」如果 FoneClaw 能收到穩定回覆，代表 API Base URL、API Key 和 model ID 至少完成了基本通訊。但這只證明模型連線，不證明 Android 工具執行已可用。
第二步才是低風險手機動作。建議選擇可見、可停止、沒有外部效果的任務，例如請 FoneClaw 檢查目前手機狀態、開啟指定 App、整理可見資訊，或準備一段不會送出的文字草稿。這類任務能測出模型是否理解意圖，FoneClaw 是否能把計畫轉成支援工具，Android 權限是否足夠，以及結果是否能回到你看得懂的位置。
| 測試階段 | 建議輸入 | 通過代表什麼 | 不代表什麼 |
|---|---|---|---|
| 模型文字回覆 | 請模型回覆一句連線測試 | API 端點、金鑰與 model ID 基本可用 | 不代表手機工具可執行 |
| 低風險手機動作 | 開啟指定 App 或整理可見狀態 | 模型規劃與 FoneClaw 支援工具能配合 | 不代表所有 App 或所有動作都支援 |
| 需核准動作 | 準備訊息草稿，先不要送出 | 核准邊界與可見結果正常 | 不代表應跳過寄送確認 |
如果你想用特定供應商模型理解 Android 動作差異，可參考DeepSeek 手機 AI Agent 能控制 Android 手機嗎？推理模型與手機 AI Agent 的差別。模型能力可以提升推理品質，但手機執行仍要靠 FoneClaw 的工具、權限與確認流程。
排除 401、404、timeout、模型與權限錯誤
連接 AI 模型 API 時，錯誤訊息通常來自兩個不同層：模型 API 層和 Android 執行層。API 層問題多半發生在文字回覆前，例如 401、404、timeout 或 model not found；Android 執行層問題則常出現在模型已能回答後，例如工具不可用、權限不足、目標 App 狀態不對，或需要使用者核准。
| 症狀 | 可能原因 | 建議處理 |
|---|---|---|
| 401 或 authentication error | API Key 錯誤、過期、專案不符，或複製到多餘空白 | 重新複製金鑰，確認供應商帳號與專案狀態；不要把金鑰貼到公開位置 |
| 404 或 endpoint not found | API Base URL 路徑不符合相容介面，或把官網網址當成端點 | 回到供應商 API 文件，確認 HTTPS 端點與相容路徑 |
| model not found | model ID 填錯、模型未開通，或該金鑰無權使用 | 使用供應商列出的精確 model ID，檢查帳號資格 |
| timeout 或連線很慢 | 網路不穩、供應商服務延遲、端點地區不合適 | 換穩定網路重試，先測短文字請求，再測手機動作 |
| 模型能回答，但手機動作失敗 | Android 工具不支援、權限不足、目標 App 狀態改變 | 檢查 FoneClaw 工具支援、授權提示與畫面狀態，不要只改 API Key |
| 需要核准但沒有完成 | 動作屬於較高影響，需要使用者確認或工具政策限制 | 查看核准畫面，確認目標、內容與後果後再決定是否執行 |
401 通常指向驗證問題，但不同供應商可能有自己的錯誤格式；404 也可能是相容路徑、版本或模型路由問題。不要只憑狀態碼做永久結論，應把供應商文件、FoneClaw 設定欄位和實際任務階段一起看。
最容易誤判的是「模型 API 成功，手機動作仍失敗」。這不是矛盾。模型服務只負責回覆與規劃；Android 權限是系統層控制，工具可用性是 FoneClaw 執行層控制，動作核准則是使用者決策。想深入看權限、核准與稽核如何分開，可讀AI 代理身份與權限治理：逐工具核准、稽核紀錄與 FoneClaw Android 控制。
如何選擇適合 Android 手機動作的模型
選模型時，不要只看排行榜或單次聊天速度。手機代理需要的是穩定理解指令、能按工具邊界規劃、遇到資訊不足時會提問、知道高影響動作要等待確認，並能在失敗時給出可操作的下一步。模型越快不一定代表整個 Android 任務越快；如果它常常選錯工具、漏掉權限或把模糊目標當成確定事實，最後反而會增加重試。
可以用五個面向評估。第一，延遲：短指令回覆是否穩定。第二，成本：你能否接受高頻手機任務的 API 用量。第三，工具理解：模型是否能把「開啟 App、讀取可見狀態、準備草稿、等待確認」分清楚。第四，隱私：供應商如何處理輸入內容與保存政策。第五，可靠性：網路波動、錯誤回覆和模型不可用時，是否容易回到 FoneClaw 預設模型或停止任務。
不同使用者也會有不同答案。重視成本的人可以先用免費預設模型測流程；已有企業模型端點的人，可以把相容 API 設定進 FoneClaw；需要特定推理風格的人，則應用低風險任務逐步測試。如果你也在評估 Grok 這類模型入口與手機控制的差別，可看Grok 能控制 Android 手機嗎？通話、主要助理入口與 FoneClaw 模型設定解析。關鍵不是某個模型 App 自己控制手機，而是模型被設定在 FoneClaw 內，透過受治理工具執行支援動作。
把已連接模型變成受治理的手機動作
當模型連線穩定後，才適合把它放進真正的 Android 手機代理流程。完整路徑應該是：使用者提出目標，設定模型在 FoneClaw 內理解與規劃，FoneClaw 選擇支援的 Android 工具，必要時請求系統權限，依工具政策要求核准，最後把可見結果回給使用者。這樣做比直接讓模型輸出一串指令更可靠，因為每個手機效果都有邊界。
FoneClaw 的功能頁可以幫你理解目前可治理的手機能力，例如手機狀態、App、通訊、mail、導航與系統工作流等 100+ built-in tools。工具範圍不是模型自己決定的；模型只負責規劃，FoneClaw 才是 Android 執行層。
截至目前可取得的最新產品資訊，FoneClaw 已加入逐工具控制、核准覆寫、權限復原與更強的失敗處理。對自訂模型使用者來說，這代表你可以在模型能力之外，管理哪些工具可用、哪些動作需要確認，以及權限不足或任務失敗時如何回到可理解狀態。若你還沒有安裝或想從低風險流程開始，可以從FoneClaw 下載頁取得目前可用版本，再用「開啟指定 App」或「整理可見資訊」這類任務驗證模型、工具、權限與結果是否串起來。