# 疑難排解

> 常見 PentAGI 問題的修復方案 — flow 在首次模型呼叫時失敗、tool call parser 錯誤、macOS 安裝程式警告以及小型模型停滯。

請先檢查連線雙方的日誌：執行 `docker compose logs -f pentagi` 查看 PentAGI 日誌，並檢查您的模型後端或代理伺服器日誌。

## [Flow 因「failed to select primary docker image via llm call」而失敗](https://pentagi.com/zh-tw/docs/deployment/troubleshooting/#a-flow-fails-with-failed-to-select-primary-docker-image-via-llm-call)

[Flow](https://pentagi.com/zh-tw/docs/glossary/#flow) 啟動時的第一個動作，是透過 `simple` [agent type](https://pentagi.com/zh-tw/docs/glossary/#agent-type) 要求模型選擇 Docker 映像檔。此錯誤幾乎都指向模型後端問題，而非 Docker 本身：

1. 檢查 PentAGI 日誌與您的模型後端日誌。
2. 確認基礎 URL、API 金鑰與模型名稱正確無誤，且可從容器內正常存取。
3. 此呼叫未傳送任何 [tool](https://pentagi.com/zh-tw/docs/glossary/#tool)，因此失敗原因在於連線、金鑰或模型，而非 tool calling：請確認 `simple` [agent](https://pentagi.com/zh-tw/docs/glossary/#agent) 的模型能回應純文字聊天請求。缺少的 [tool call](https://pentagi.com/zh-tw/docs/glossary/#tool-call) 解析器會在稍後 agent 開始呼叫 tool 時才會顯現。

## [自託管模型的 tool call 解析器錯誤](https://pentagi.com/zh-tw/docs/deployment/troubleshooting/#tool-call-parser-errors-with-self-hosted-models)

PentAGI 透過 tool calls 來驅動 agents，因此自訂後端必須回傳有效的 OpenAI 格式 tool call JSON。若解析器缺失或不匹配，可能出現 `Failed to parse tool call arguments as JSON`、flows 在數個步驟後停止，以及 tool calls 陷入迴圈而無法收斂等症狀。

* 針對您在 llama.cpp、SGLang 或 vLLM 中提供的模型，啟用其推薦的 tool call 解析器與聊天範本。
* 在執行完整 flow 前，請先使用 `ctester` 工具驗證 [provider](https://pentagi.com/zh-tw/docs/glossary/#provider)。
* 更新 PentAGI：最新版本會清理格式錯誤的參數，避免單一錯誤回應導致整個 flow 停滯。

## [macOS 對安裝程式發出警告](https://pentagi.com/zh-tw/docs/deployment/troubleshooting/#macos-flags-the-installer)

macOS 版本已簽署並經過公證。若 macOS 仍對安裝程式發出警告，請勿使用**仍要打開**來略過：請刪除該檔案，並從官方連結重新下載適合您 CPU 的封存檔——Intel 處理器請選 `darwin/amd64`，Apple Silicon 請選 `darwin/arm64`。切勿使用來自非官方來源的封存檔。

## [較小的模型卡住](https://pentagi.com/zh-tw/docs/deployment/troubleshooting/#smaller-models-get-stuck)

請啟用[執行監控與 task 規劃](https://pentagi.com/zh-tw/docs/concepts/agents/#safeguards)，並為 `adviser` agent 指定更強大的模型或調高推理設定。

## [仍然遇到問題？](https://pentagi.com/zh-tw/docs/deployment/troubleshooting/#still-stuck)

歡迎至 [Discord](https://discord.gg/2xrMh7qX6m) 提問，或[建立 Issue](https://github.com/vxcontrol/pentagi/issues) 並附上相關日誌內容。