Apple Foundation Models

捆綁的 Apple Foundation Models 外掛程式透過原生 Foundation Models 框架執行 Apple 的裝置端模型。這是一個免費的本地設定與工具模型。設定時會將其儲存於 utilityModel，並保留你平常使用的 agent 模型。當未配置主要模型時，它可以驅動 OpenClaw 設定精靈。在開始一般 agent 聊天前，請先選擇獨立的主要模型。

要求¶

以下要求適用於執行 Gateway 的 Mac。連線到 Linux 或 Windows Gateway 的 Mac App 不會提供此本地推論途徑。

• 配備 Apple 晶片且執行 macOS 27 或以上版本的 Mac。
• 在系統設定中啟用 Apple Intelligence，並已下載其模型。
• 已安裝包含 macOS 27 SDK 的 Apple Swift 開發者工具。
• 有至少 8,192 個 context token 的可用系統模型。

外掛程式會查詢實際的模型名稱、可用性與 context window。AFM 3 Core Advanced 已通過 8,192 token 視窗的測試。具備 4K 視窗的舊版裝置端變體不符合此設定選項的資格；擁有 Mac 並不代表一定可使用較大的變體。

设置¶

執行：

openclaw onboard

允許本機探索，然後在出現時選擇 Apple Foundation Models。只有在背景探測確認模型可用且具備至少 8,192 個 context token 後，設定才會提供此選項。當資格未知、必要條件缺失或模型視窗較小時，此選項會保持隱藏。

在首次探索時，OpenClaw 會使用你已安裝的 Apple 工具，在暫存目錄中編譯捆綁的 Swift helper，讀取原生模型的可用性與 context 大小，然後移除暫存 helper。編譯與探測會在子處理程序中執行，因此不會阻塞 Gateway 的事件迴圈。探索不會安裝推論 helper，也不會變更你的配置。它是有界限且可取消的；若檢查失敗或逾時，就不會提供該模型。

選擇偵測到的模型會建立其持久 helper，並在啟用前重新檢查資格。OpenClaw 不會為你安裝開發者工具、下載第三方可執行檔或接受授權條款。如果缺少工具，請安裝 Xcode 或對應的 Apple Command Line Tools 後重試。這些工具必須包含 macOS 27 SDK。

OpenClaw 會在儲存前測試所選的工具途徑。模型參照為 apple-fm/system；設定會記錄偵測到的模型名稱與 context 限制。不會建立 API key 或 provider auth profile。即使你的主要模型使用不同的 agent runtime，此原生途徑仍使用 OpenClaw runtime。

在新安裝環境中，onboarding 會開啟 OpenClaw 設定精靈。它可以檢查配置，並協助設定 channel 與其他項目。該介面會讓一般 agent 設定保持未完成狀態，直到你在 Model Setup 中選擇並驗證主要模型，或重新執行 openclaw onboard。之後，Apple 仍作為工具模型；系統 assistant 會正常遵循主要模型。

在既有安裝環境中，選擇 Apple 會保留你的主要模型、fallback 與憑證。如果舊配置依賴隱含的主要模型，設定會先記錄該既有途徑，再加入 Apple provider。Doctor 與一般配置寫入皆套用相同的 utility-model migration。如果該 migration 仍在等待中，設定會要求你在連接 Apple 前執行 openclaw doctor --fix 或選擇明確的主要模型。 明確的 utility-model 配置也可以透過 agents.entries.<id>.utilityModel 為每個 agent 設定。

之後的探索會重複使用已準備好的 helper，並再次檢查目前的模型。若要從指令碼明確選擇 Apple：

openclaw onboard --non-interactive --auth-choice apple-fm --accept-risk

运行时行为¶

模型推論在 Gateway 的 Mac 上執行；提出的 tool call 會透過 OpenClaw 正常的執行與核准流程進行。Helper 僅在模型請求時啟動；不會安裝 HTTP server、launch agent 或獨立的模型 daemon。OpenClaw 保有工具執行與正常核准檢查的所有權。

工具呼叫會透過 OpenClaw 既有的 utility-model 路由，為 session 標題與進度敘述等簡短內部任務提供支援。Onboarding 不會將 Apple 選為一般 agent 的主要模型。

模型會在其 context window 中共享指令、工具定義、對話、工具結果與輸出。Provider 預設每則回覆最多輸出 1,024 個 token。大型工作區或完整的 agent prompt 可能在累積有用的對話歷史之前就超出視窗。請保持設定問題的焦點；這個較小的裝置端模型在複雜請求上可能不如較大的模型可靠。

原生生成支援 closed objects、arrays、primitive types、enums、nullable values 與受支援的 schema unions。字串長度與 regex 約束仍由 OpenClaw 在生成後執行，因為 Apple 未提供可用的原生 guides。結構化回應會在發布前依呼叫者的原始 schema 進行檢查。不支援的結構化 schema 會明確失敗。

故障排除¶

如果 Apple Intelligence 不可用，請在系統設定中啟用，並等待模型下載完成。變更可用性後重試設定。

如果回報的 context window 低於 8,192 個 token，請選擇其他本地或雲端模型。OpenClaw 不會誇大模型宣稱的限制。

如果更新後缺少原生 helper，請在 Model Setup 中對已配置的 utility card 使用 Recheck & repair，或重新執行 onboarding 並選擇偵測到的 Apple 模型。這會編譯符合已安裝外掛程式的 helper，並再次驗證工具途徑。一般推論絕不會編譯程式碼或安裝相依套件。

其他推論選項請參閱 Model providers。