Prime Agent Ollama 2026：連不上排查

模型已顯示，但編碼任務仍失敗：不要先重裝，先按 Ollama 服務、存取位址、models.json、API 相容參數、模型能力五層隔離。

Prime Agent Ollama 2026 的最快排查路徑，是先用最小請求證明 Ollama 能獨立回應，再逐層確認 Prime Agent 讀到的設定與實際送出的參數。若基礎請求正常、編碼任務仍反覆失敗，就換具備工具遵循能力的模型，或把長任務移到資源穩定、可持續執行的獨立環境。

這篇適合三類讀者：

• 在 Prime Agent 中看不到 Ollama 模型、需要確認設定是否載入的個人開發者。
• 已能連線，但遇到請求報錯、工具行為消失或輸出中斷的 AI 工程師。
• 準備讓 Prime Agent 在遠端或持續執行環境中處理長任務的平台團隊。

最後更新於 2026 年 8 月 11 日；配置欄位已重新核對 Prime Agent 主分支文件，Ollama 介面與日誌行為已核對官方 API、FAQ 與 Troubleshooting 文件。

先建立五層隔離，避免把不同故障混在一起

Prime Agent 官方文件目前確認，Ollama 等自訂模型可以透過 ~/.prime/agent/models.json 加入，並使用 OpenAI 相容的 Chat Completions 介面。文件同時指出，設定檔會在你開啟 /model 時重新載入，不必因為每次修改都重啟整個環境。參考 Prime Agent Custom Models 文件

你可以把症狀分成以下五層：

• 服務層：Ollama 沒有啟動、模型尚未下載，或本機端口沒有監聽。
• 位址層：baseUrl 指向錯誤環境；尤其是容器、SSH 或遠端主機中的 localhost 意義不同。
• 設定層：models.json 路徑、JSON 格式、provider 名稱或模型 ID 不一致。
• 介面層：Prime Agent 送出的 developer role、reasoning_effort 或串流用量欄位，後端不接受。
• 能力與資源層：模型能聊天，卻不能可靠執行檔案操作、工具呼叫或長流程。

這樣分層的好處是，每一層都有不同證據。服務層看命令與 HTTP 回應；介面層看請求欄位與錯誤內容；能力層則要靠遞進式任務驗證，不能只看模型是否回了一段文字。

第一個里程碑：先證明 Ollama 自己真的可用

先在 Ollama 所在的主機執行：

ollama list
curl http://localhost:11434/api/tags
curl http://localhost:11434/api/version

你要確認三件事：

1. ollama list 中有目標模型。
2. /api/tags 回傳的模型名稱，與你準備寫入 models.json 的 id 完全一致。
3. /api/version 能回傳 JSON，而不是連線逾時或拒絕。

Ollama 官方 API 文件列出 /api/tags、/api/version 等端點；OpenAI 相容介面則使用 /v1/models 與 /v1/chat/completions。參考 Ollama API 文件參考 Ollama OpenAI 相容性文件

接著測試最小的 OpenAI 相容請求：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [
      {"role": "user", "content": "只回覆 OK"}
    ],
    "stream": false
  }'

預期結果是 HTTP 成功回應，並在 choices 中看到模型文字。若這一步失敗，不要先改 Prime Agent；先看 Ollama 服務日誌。macOS 的官方排查方式是：

cat ~/.ollama/logs/server.log

Linux 若由 systemd 管理，則可使用：

journalctl -u ollama --no-pager --follow --pager-end

容器環境則查看容器標準輸出。參考 Ollama Troubleshooting 文件

第二個里程碑：把 localhost 與 baseUrl 分開判斷

Prime Agent 與 Ollama 在同一部 Mac 上時，baseUrl 通常可寫成：

{
  "baseUrl": "http://localhost:11434/v1"
}

這裡的 /v1 很重要。Prime Agent 使用的是 OpenAI 相容路徑，不是把原生 Ollama 的 /api/chat 直接當成 OpenAI Chat Completions 端點。

但只要兩者不在同一個執行環境，localhost 就可能是錯的：

• Prime Agent 在 Docker 容器，Ollama 在主機：容器內的 localhost 指向容器本身。
• Prime Agent 在遠端 Mac，Ollama 在你的工作站：遠端環境中的 localhost 不會回到工作站。
• Prime Agent 透過 SSH 啟動，Ollama 只監聽本機回環位址：即使主機可連，遠端也可能無法存取。
• Ollama 只綁定在本機介面：外部主機即使知道端口，也會收到拒絕或逾時。

請從 Prime Agent 實際執行的環境測試：

curl http://<OLLAMA_HOST>:11434/v1/models

判斷依據不要只看瀏覽器或 Ollama 主機上的測試結果，而要看：

• HTTP 狀態是否成功。
• 回應中的模型清單是否包含目標 id。
• Ollama 日誌是否同步出現請求。
• Prime Agent 所在環境是否能解析主機名稱並通過防火牆。

若遠端環境只是臨時測試，建議先使用受控的內網位址或安全通道，不要把 Ollama 服務直接暴露到公開網路。可先閱讀 Kvmkit 的幫助中心，確認遠端環境的連線與權限邊界，再進行模型測試。

第三個里程碑：逐項核對 models.json，而不是只看檔案存在

Prime Agent 目前的自訂模型文件使用 providers、baseUrl、api、apiKey 與 models 等欄位。Ollama 的最小配置可整理成：

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

其中 apiKey 仍需填入，但 Ollama 會忽略其內容；問題通常不在密鑰真假，而在 JSON 結構、讀取路徑與模型 ID。Prime Agent 文件也說明，模型清單會依 id 顯示，因此 llama3.1:8b、llama3.1 或其他別名不能視為同一個字串。參考 models.json 欄位與模型 ID 說明

按以下順序檢查：

1. 確認實際檔案位置：

bash ls -la ~/.prime/agent/models.json

2. 驗證 JSON 語法：

bash python -m json.tool ~/.prime/agent/models.json

3. 比對模型名稱：

bash ollama list

4. 重新開啟 Prime Agent 的 /model。
5. 若仍未顯示，再執行：

bash prime-agent doctor prime-agent status

三種現象要分開處理：

• Ollama 沒有模型：先 ollama pull <MODEL_ID>，這是安裝問題。
• Ollama 有模型、Prime Agent 不顯示：優先檢查路徑、JSON 結構與是否重新載入。
• Prime Agent 顯示模型、請求找不到模型：通常是 id 與 Ollama 實際名稱不一致，或 baseUrl 指到另一個 Ollama 實例。

第四個里程碑：從錯誤欄位判斷 API 相容性

模型已經出現在 /model，但請求仍回傳錯誤時，不要籠統寫成「Ollama 不相容」。先看錯誤是否指向特定欄位。

常見分流如下：

• developer role is not supported：將 compat.supportsDeveloperRole 設為 false。
• reasoning_effort 不被接受：將 compat.supportsReasoningEffort 設為 false。
• 串流回應因用量欄位失敗：檢查 supportsUsageInStreaming。
• 模型拒絕 max_completion_tokens 或 max_tokens：依後端要求設定 maxTokensField。
• 工具結果格式錯誤：再檢查 requiresToolResultName 或 requiresAssistantAfterToolResult，不要一次把所有相容選項都關閉。

配置可以先在 provider 層設定：

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

若只有一個模型需要例外，再把 compat 放到該模型項目，而不是影響整個 provider。Prime Agent 文件明確區分 provider 層與 model 層的相容設定；每次只改一個欄位，改完重新執行同一個最小請求，才能知道哪個變更有效。參考 OpenAI 相容欄位說明

經驗判斷： 如果錯誤訊息已經明確指出某個 JSON 欄位，優先做最小化修改。一次刪除整段 compat，或同時更換模型、端口與提示詞，會讓下一輪無法追溯根因。

第五個里程碑：用遞進任務區分模型能力與 Prime Agent 故障

「Ollama 可以對話」只代表基礎文字生成成功，不能證明模型適合 Prime Agent 的程式化工作。Prime Agent 的工作環境會使用 IPython 控制環境處理檔案、命令、工具與持續狀態；官方文件也提醒，模型產生的程式與專案命令會以你的使用者權限執行。參考 Prime Agent Quickstart

請不要直接丟一個大型重構任務，按以下順序驗證：

1. 讀取檔案：要求列出指定檔案的關鍵函式，確認路徑與內容沒有誤讀。
2. 修改小檔案：只改一個註解或測試字串，檢查差異。
3. 執行測試命令：要求執行既有測試，確認工具回傳內容被正確理解。
4. 處理失敗結果：故意讓一個測試失敗，觀察模型是否能讀取錯誤並提出修正。
5. 執行短流程：設定明確的完成條件，要求修改、測試、回報檔案差異。
6. 最後才測長任務：加入多個檔案、子任務或背景工作，並保留可恢復的檢查點。

如果模型在第 1、2 步就無法遵循指令，偏向模型能力或提示遵循問題。如果能讀檔和改檔，但在工具回傳後開始捏造「已完成」，不要把它記錄成 Prime Agent 或 Ollama 的確定 Bug；先換一個更適合程式工作的模型，或把任務拆成更短的階段。

長任務卡住時，沿著時間線找第一個異常

長任務的停頓通常不是單一原因。你需要建立一條最小時間線：

• T0： Prime Agent 發出請求，記錄模型 ID、provider 與提示摘要。
• T1： Ollama 開始載入或處理模型，查看伺服器日誌。
• T2： 首次回應是否出現，是否在串流中途停止。
• T3： 上下文變長、工具回傳或子任務增加後，記憶體與處理時間是否異常。
• T4： 終端斷開後，Prime Agent session、worker 與 Ollama 模型程序是否仍在執行。

Ollama FAQ 指出，預設上下文長度為 4096 tokens，可以透過 OLLAMA_CONTEXT_LENGTH 覆寫；同時，服務在請求過多時可能回傳 503，表示伺服器過載。參考 Ollama FAQ 這些數值不是 Prime Agent 的保證值，而是排查時應記錄的環境條件。

你還要檢查三項隱性成本：

• 模型載入成本：每次模型被卸載再載入，表面上像斷流，實際可能是資源不足或保留時間設定。
• 上下文成本：長對話、工具輸出與子任務結果會持續增加請求負擔。
• 並發成本：多個子任務同時使用同一個本地模型，可能令服務佇列變長或回傳過載。

Prime Agent 官方文件提供 prime-agent agents、attach、--resume、status 與 doctor 等命令，用於查看及恢復背景 session；遠端部署時要確認終端斷開後，session 與 worker 是否真的留在背景執行。參考 Prime Agent 長任務文件

修復後用這份驗收清單決定是否可上線

你可以把結果分成三個方案，而不是只問「連不連得上」。

方案 A：本機執行

• 適合模型測試、短程式修改與單人開發。
• 優點是 localhost 路徑簡單，資料不必離開本機。
• 缺點是工作站睡眠、終端關閉、記憶體波動都可能中斷長任務。
• 若第 1 至第 3 級驗收成功，但長任務不穩，不能直接視為設定完成。

方案 B：獨立遠端環境

• 適合需要固定 IP、持續執行、多人共用或與本機分離的團隊。
• 優點是 Prime Agent、Ollama、日誌與工作目錄可以集中管理。
• 缺點是需要處理防火牆、SSH、權限、網路延遲與遠端模型資源。
• 若遠端環境中的 /v1/models 可用，但工具請求失敗，回到 API 相容層排查。

方案 C：彈性算力或租用 Mac 環境

• 適合短期測試、臨時模型評估、團隊驗收或不想長期維護本機服務的情況。
• 優點是可把主機資源、持續執行與工作環境分開管理。
• 缺點是仍要核對網路、權限、資料安全與實際模型需求，不適合需要直接接觸本地硬體介面的工作。
• 若你只是要完成一次 Prime Agent 與 Ollama 的驗收，租用環境通常比反覆重裝本機軟體更容易控制變因。

最低驗收標準應包括：模型能被發現、最小對話成功、能讀檔、能修改小檔案、能執行測試、能處理失敗結果，並能在終端斷開後恢復短任務。請記錄 Prime Agent 版本、Ollama 版本、模型 ID、models.json 配置摘要、日誌位置、主機環境與失敗邊界，下一次才有可重現的比較基準。

如果你目前的方案是把 Ollama 綁在個人電腦上，常見缺點是工作站休眠會中斷服務、終端關閉後 session 未必持續、資源波動會令長任務重試，而且遠端團隊很難共享同一套環境。若你已完成五層排查，卻仍受這些條件限制，可以比較 Kvmkit 的 Mac 租用方案；對臨時算力、遠端驗收或需要持續執行的 Prime Agent 工作，獨立 Mac 環境往往比在本機配置層反覆試錯更容易管理。需要先確認具體連線條件時，也可以透過 Kvmkit 聯絡頁面詢問適合的環境範圍。

常見問題