Prime Agent Ollama 2026：本地模型部署教學

症狀：Prime Agent 已經啟動，但選不到 Ollama 模型，或第一個工具任務執行到一半便失敗。

最快解法：Prime Agent Ollama 2026 應先採用 Ollama 的 OpenAI 相容介面，建立 models.json 自訂 Provider；先驗證模型名稱、上下文容量、結構化輸出與工具呼叫，再逐步開啟長任務和子 Agent，而不是一連線成功就投入自治流程。(Prime Agent 官方自訂模型文件)

本文適合需要在本地或私有環境運行 Prime Agent 的開發者、處理敏感程式碼而不希望預設傳送到外部模型服務的團隊，以及準備租用獨占 Mac 環境測試本地模型的技術負責人。

最後更新於 2026 年 8 月 11 日；部署路徑與欄位核實自 Prime Agent 官方 Provider 文件、Prime Agent 官方自訂模型文件及 Ollama 官方 API 文件。

第一步：先確認模型、介面與權限邊界

Prime Agent 並不是只要收到文字回覆就算接入成功。它會在工作目錄中讀取檔案、執行命令、維持 Python 控制環境，並可透過 rlm(...) 呼叫子 Agent；官方文件亦提醒，模型產生的 Python 和專案命令會以目前使用者權限執行，並非安全沙盒。(Prime Agent 專案文件)

因此，部署前至少要確認以下三個限制：

1. 模型能力限制：一般對話模型可能能回答問題，卻不會穩定產生工具呼叫、正確 JSON 參數或工具結果後的續接訊息。
2. 上下文限制：Ollama 官方 FAQ 顯示，預設上下文長度是 4096 tokens；Prime Agent 自訂模型的 contextWindow 只是介面描述，不能代替 Ollama 實際可用的上下文設定。(Ollama 官方 FAQ)
3. 權限與資料限制：本地推理可降低程式碼外發風險，但 Prime Agent 仍可能修改檔案或執行命令；應使用可回滾的 Git worktree、測試專案或一次性複本。

Ollama 的 OpenAI 相容文件列出 Chat Completions 可支援 JSON mode、Vision、Tools 等欄位，但「介面接受欄位」不等於「每個模型都能可靠使用該能力」。(Ollama OpenAI 相容介面文件)

第二步：建立可重現的本地部署基線

Prime Agent 官方目前把 Ollama、LM Studio、vLLM 等本地服務放在自訂 Provider 路徑，設定檔位置是：

~/.prime/agent/models.json

建議先拉取一個已知模型，並記下 ollama list 顯示的完整模型 ID。不要自行把標籤改成簡短名稱，因為 Prime Agent 會把 id 原樣傳給 API。

ollama pull <MODEL_ID>
ollama list

接著確認 Ollama 的基本服務是否可回應：

curl http://localhost:11434/api/tags

若需要直接檢查 OpenAI 相容端點，可使用：

curl http://localhost:11434/v1/models

Ollama 預設只綁定本機 127.0.0.1 的 11434 埠；若要讓另一部電腦存取，必須調整 OLLAMA_HOST，但這會增加暴露面，不能只把 0.0.0.0:11434 設好便視為完成安全設定。

遠端部署時，較合理的順序是：

• 優先使用私有網路、VPN 或 SSH 轉發。
• 防火牆只允許指定來源 IP 或內部網段。
• 若使用反向代理，加入身分驗證、TLS 和請求記錄。
• 不要把沒有驗證機制的 Ollama HTTP 端點直接公開到網際網路。
• 若團隊不需要雲端模型或網頁搜尋，可啟用 Ollama 的本地限定模式，設定 OLLAMA_NO_CLOUD=1 後重新啟動服務。

第三步：依目前欄位設定 Prime Agent Provider

目前官方自訂模型文件給出的最小設定如下，apiKey 雖然是必要欄位，但 Ollama 會忽略其內容，因此可使用佔位值：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "<MODEL_ID>" }
      ]
    }
  }
}

這裡最容易出錯的是三個欄位：

欄位	應填內容	常見錯誤
baseUrl	Ollama OpenAI 相容服務的 /v1 路徑	寫成 /api，或重複加入 /v1/v1
api	openai-completions	照抄舊文章中的其他 API 類型
models[].id	ollama list 顯示的完整 ID	自行刪除版本標籤或大小標籤

某些本地服務不接受 developer role 或 reasoning_effort，Prime Agent 官方提供相容性開關，可先在 Provider 層停用：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        { "id": "<MODEL_ID>" }
      ]
    }
  }
}

官方文件說明，models.json 會在開啟 /model 時重新載入，因此修改後通常不必重啟整個 Prime Agent；若模型仍不出現，應先關閉目前工作階段，再檢查檔案路徑、JSON 語法和模型 ID。

若需要把測試環境與日常工作分開，可先參考 nuvcloud Mac mini 方案資訊，再決定是否將 Ollama 放在獨立的 Mac 環境，而不是直接佔用主力工作機的資源。

第四步：首個小時只做四項能力驗收

第一次連線不要直接啟用自治模式、排程或多個子 Agent。應按以下順序測試，讓錯誤可以被歸因到模型、API 或檔案權限其中一層。

1. 讀取檔案

準備一個不含機密的測試專案，要求 Prime Agent 只列出目錄結構並說明入口檔案，不准修改內容。若讀取結果已經混亂，先不要繼續測試工具呼叫。

2. 生成小段程式碼

要求模型修改一個可回滾的函式，並附上測試命令。觀察它是否能理解現有程式碼、是否產生不存在的套件，以及回覆是否保持可驗證的格式。

3. 執行一個低風險命令

只允許執行版本查詢、單元測試或靜態檢查，避免一開始讓模型接觸刪除、部署、網路掃描或憑證讀取命令。Prime Agent 官方明確表示，模型產生命令會以目前使用者權限執行。

4. 測試結構化輸出與工具呼叫

Ollama 官方 API 的工具呼叫回應會在訊息中帶有 tool_calls；但模型是否能正確填寫函式名稱和參數，仍取決於模型本身及其模板。(Ollama API 文件)

可勾選的首輪驗收清單如下：

• [ ] ollama list 的模型 ID 與 models.json 完全一致。
• [ ] curl http://localhost:11434/v1/models 能回應模型清單。
• [ ] Prime Agent 的 /model 能顯示自訂模型。
• [ ] 模型能讀取測試檔案而不擅自修改。
• [ ] 模型能生成小型程式碼並附上可執行的檢查方式。
• [ ] 模型能執行低風險命令並回報實際結果。
• [ ] 工具呼叫的函式名稱、參數格式和執行結果可被正確接續。
• [ ] 結構化輸出不是只在一次請求中偶然成功。

第五步：第一天再驗證長任務與子 Agent

Prime Agent 的特色包括持久化 IPython、背景工作階段、心跳、目標和子 Agent，但這些功能會把模型的短回覆能力放大成長時間資源消耗；因此，第一天應使用可回滾的倉庫，先做一個範圍明確、可中途停止的任務。

觀察以下四類訊號：

• 上下文增長：模型是否開始重複已完成的步驟，或忘記早期約束。
• 記憶體壓力：模型載入後是否大量使用系統記憶體；可用 ollama ps 查看模型處於 GPU、CPU 或混合載入狀態。
• 任務偏移：子 Agent 是否建立與主任務無關的檔案、測試或背景工作。
• 恢復行為：終端機中斷、服務重啟或模型切換後，Prime Agent 是否能從明確檢查點繼續，而不是重新猜測目前進度。

並行子 Agent 會放大資源需求。Ollama 官方說明，單一模型的平行請求數會增加上下文記憶體需求；OLLAMA_NUM_PARALLEL 與 OLLAMA_CONTEXT_LENGTH 的乘積會直接影響所需記憶體，請求過多時亦可能因佇列滿載而收到 503。

因此，初次驗證應將並行度維持在保守值，完成單一模型、單一工作階段的穩定測試後，再逐步增加子 Agent 數量。若長任務常常偏移，問題未必是 Prime Agent 連線錯誤，也可能是模型上下文不足、工具回傳過長或本地推理速度令狀態更新不及時。

第六步：按錯誤類型建立維護流程

連線失敗

先檢查 Ollama 服務是否正在監聽、baseUrl 是否含正確的 /v1，以及遠端環境的防火牆是否允許來源。若 Prime Agent 能啟動但模型清單為空，優先檢查 models.json 的 JSON 語法和實際檔案位置。

找不到模型

將 ollama list 輸出的完整名稱直接複製到 models[].id，不要使用自訂別名。若修改設定後仍看不到，重新開啟 /model；官方文件指出，設定檔會在該介面載入。

輸出格式異常

先停用推理參數、developer role 或不必要的串流選項，再用最小請求測試。不要一次更換模型、Provider 和相容性設定，否則無法判斷真正原因。

工具呼叫失敗

把普通問答、單一工具、工具結果回傳和多工具流程分開驗證。若模型只輸出「應該執行某命令」的文字，而不是正式 tool_calls，便不能把它當作已支援 Prime Agent 工具呼叫。

資源不足

先降低上下文長度、停止閒置模型、減少並行請求，並以 ollama ps 觀察載入位置。模型檔案通常位於 macOS 的 ~/.ollama/models，需要把模型快取、日誌和專案檔案納入硬碟清理流程。

長期運行時，至少固定以下四項：

• 鎖定經過驗收的 Ollama 與模型版本。
• 保留服務啟動、請求錯誤和資源使用記錄。
• 以可重建設定檔取代只存在於互動終端機的環境變數。
• 定期清理不再使用的模型和工作階段，並保留可回滾的專案檢查點。

常見問題

Prime Agent 能否使用 Ollama 模型？

可以，但截至 2026 年 8 月 11 日，較穩妥的路徑是使用官方文件所述的自訂 Provider，而不是照抄社群舊版設定。Prime Agent 的 Provider 目錄會隨版本更新，因此字段名稱和內建模型清單都應以目前文件為準。

連線 Ollama 後找不到模型，應先查甚麼？

先查三件事：baseUrl 是否為 http://localhost:11434/v1、models[].id 是否與 ollama list 完全相同，以及 models.json 是否位於 ~/.prime/agent/。其中任何一項不一致，都可能令模型無法在 /model 出現。

本地大模型適合直接執行子 Agent 嗎？

不建議一開始便直接執行。先完成單一工具的參數驗收，再測試一個子 Agent；只有當長任務中的上下文、記憶體、恢復和檔案修改均可觀察、可回滾，才適合增加自治程度。

遠端 Ollama 服務怎樣避免被任意存取？

最安全的起點是維持本機監聽；若 Prime Agent 與 Ollama 分開部署，應透過私有網路、VPN 或受限反向代理連線，並在防火牆層限制來源。只調整 OLLAMA_HOST 而不加入驗證和網路隔離，不能視為完整的權限控制。

本地電腦與獨占雲端 Mac 的取捨

在現有本地電腦上部署 Ollama，優點是資料不必離開設備、沒有額外遠端連線延遲；但常見缺點也很明確：可用記憶體可能不足、模型與日常工作爭用資源、遠端團隊難以重現同一環境，而且開放 OLLAMA_HOST 後還要自行處理防火牆、權限和長時間運行問題。

若目標只是先確認 Prime Agent 與本地大模型是否相容，直接購置長期設備未必划算。選擇 nuvcloud 的獨占雲端 Mac，可把測試環境與日常工作分開，完成 Ollama、Provider、工具呼叫及長任務驗證後，再決定是否購置實體設備。若只是短期測試、需要隨時重裝或要隔離敏感程式碼，這種可重建環境通常比在主力電腦上反覆調整更容易控制。

需要臨時算力或獨立測試環境時，可從 nuvcloud 繁體中文服務入口 了解可用方案；若是長期固定重負載、需要實體外設或必須完全掌握硬體，則應把自購 Mac 與本地部署一併納入評估，而不是把租用視為所有情況的唯一答案。

延伸閱讀

• 本地 AI 服務部署：伺服器記憶體與長期維護實測
• 個人 AI 與 Agent 架構：本地、私有環境的三層部署思路
• 私有 AI 工具接入層：隔離部署、權限控管與效能調校