# 故障排除

> 常见 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-cn/docs/deployment/troubleshooting/#a-flow-fails-with-failed-to-select-primary-docker-image-via-llm-call)

[Flow](https://pentagi.com/zh-cn/docs/glossary/#flow) 启动时首先会通过 `simple` [agent type](https://pentagi.com/zh-cn/docs/glossary/#agent-type) 请求模型选择一个 Docker 镜像。此错误几乎总是指向模型后端问题，而非 Docker 本身：

1. 检查 PentAGI 日志以及您的模型后端日志。
2. 确认基础 URL、API 密钥和模型名称正确无误，且从容器内可以访问。
3. 此调用不发送任何 [tool](https://pentagi.com/zh-cn/docs/glossary/#tool)，因此失败原因在于连接、密钥或模型，而非 tool calling：请检查 `simple` [agent](https://pentagi.com/zh-cn/docs/glossary/#agent) 的模型是否能响应纯聊天请求。缺少 [tool call](https://pentagi.com/zh-cn/docs/glossary/#tool-call) 解析器的问题会在稍后 agents 开始调用 tool 时显现。

## [自托管模型的 tool call 解析器错误](https://pentagi.com/zh-cn/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-cn/docs/glossary/#provider)。
* 更新 PentAGI：最新版本会对格式错误的参数进行清理，单次异常响应不再导致 flow 停滞。

## [macOS 标记安装程序](https://pentagi.com/zh-cn/docs/deployment/troubleshooting/#macos-flags-the-installer)

macOS 构建版本已签名并经过公证。如果 macOS 仍然警告安装程序，请勿使用**仍要打开**来绕过：请删除该文件，并从官方链接重新下载适合您 CPU 的压缩包——Intel 芯片选用 `darwin/amd64`，Apple Silicon 选用 `darwin/arm64`。切勿使用来自非官方渠道的压缩包。

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

启用[执行监控与 task 规划](https://pentagi.com/zh-cn/docs/concepts/agents/#safeguards)，并为 `adviser` agent 配置更强的模型或更高的推理等级。

## [仍然遇到问题？](https://pentagi.com/zh-cn/docs/deployment/troubleshooting/#still-stuck)

欢迎在 [Discord](https://discord.gg/2xrMh7qX6m) 中提问，或[提交 Issue](https://github.com/vxcontrol/pentagi/issues) 并附上相关日志片段。