# 常见问题排查指南
---
## 1. 模型连接相关问题
### 问题：提示模型连接失败
排查步骤：
1. 检查API密钥是否正确，有没有多余空格、换行符等特殊字符
2. 确认API密钥有对应模型的调用权限，账户余额/配额充足
3. 检查接口地址（base_url）是否正确，有没有多写或少写路径后缀（比如不要漏了/v1）
4. 确认本地网络可以正常访问模型服务商的接口，可以尝试在终端ping或curl测试
5. 如果是代理访问，检查代理配置是否正确，代理服务器是否正常运行
6. 查看logs/gateway.log中的详细错误日志，确认是网络问题还是鉴权问题

### 问题：模型回复慢/超时
排查：
1. 检查网络连接是否正常，是否有网络波动
2. 确认模型服务商的服务状态，是否有服务降级或故障
3. 尝试降低最大生成长度参数，减少输出内容
4. 如果是复杂任务，可以拆分成多个小任务分别处理
5. 切换到其他模型尝试，确认是否是特定模型的问题

---
## 2. 工具/技能调用问题
### 问题：AI不会调用技能/工具
排查：
1. 进入「技能」页面，确认该技能已经安装并处于启用状态
2. 进入「智能体」页面，编辑当前使用的智能体，确认已经勾选了对应技能/工具的权限
3. 需求描述尽量明确，明确说明要使用什么技能/工具做什么事，比如「使用Python运行工具执行这个脚本」
4. 检查模型是否支持工具调用，部分轻量化模型可能不支持工具调用能力

### 问题：工具执行失败
排查：
1. 检查本地权限是否足够，比如终端执行命令需要对应文件/命令的操作权限，写入文件需要目录写入权限
2. 确认依赖环境已经安装，比如运行Python脚本需要本地有Python环境，相关依赖包已经安装
3. 点击工具调用卡片的「查看日志」按钮，查看详细错误信息，根据错误提示针对性解决
4. 如果是MCP工具，检查MCP服务器是否正常运行，配置是否正确
5. 尝试手动在本地执行相同命令，确认命令本身是否可以正常运行

### 问题：MCP服务器连接失败
排查：
1. 进入「工具」页面，检查MCP服务器是否处于启用状态
2. 确认MCP服务器的配置参数正确：命令路径、参数、URL地址等
3. 如果是stdio类型的MCP，确认命令依赖的运行环境已经安装
4. 如果是SSE/HTTP类型的MCP，确认服务已经启动，网络可以正常访问对应地址
5. 查看logs/gateway.log中的MCP相关错误日志

---
## 3. 托管/定时任务问题
### 问题：托管任务运行失败
排查：
1. 点击托管任务面板的「查看日志」，查看具体的错误信息
2. 确认模型配置正确、API配额充足，没有调用限制
3. 确认任务目标描述清晰，没有歧义，如果需要特定上下文或权限请补充说明
4. 检查是否需要用户补充信息，任务是否处于等待反馈状态
5. 查看logs/hosted.log中的托管任务相关日志

### 问题：托管任务自动停止
排查：
1. 检查是否达到了设置的最大运行轮次或自动停止时间
2. 查看是否是任务已经完成，达到了停止条件自动结束
3. 检查是否连续执行失败超过了重试阈值，自动暂停
4. 确认EvoPanel是否处于运行状态，没有被关闭

### 问题：定时任务没触发
排查：
1. 进入「定时任务」页面，确认定时任务状态是「已启用」
2. 检查Cron表达式是否正确，可以使用在线Cron表达式验证工具确认
3. 确认EvoPanel软件处于运行状态，没有被关闭，电脑没有休眠
4. 查看定时任务的执行历史，是否有执行失败记录
5. 查看logs/automation.log中的定时任务相关日志
6. 如果是飞书推送任务，确认飞书渠道配置正确，机器人有发送消息权限

---
## 4. 客户端运行问题
### 问题：EvoPanel启动闪退/打不开
排查：
1. 检查是否有其他进程占用了默认端口8001、2024，可以使用`netstat -ano`命令查看端口占用
2. 尝试以管理员/root权限运行，避免权限不足导致的启动失败
3. 查看安装目录下logs文件夹的错误日志，根据错误信息解决
4. 尝试删除~/.evoflow/config.yaml配置文件，重新启动（会重置配置，建议先备份）
5. 卸载重装最新版本，确认下载的安装包对应你的操作系统版本

### 问题：聊天页面加载异常/空白
排查：
1. 刷新页面重试，或按Ctrl+F5强制刷新
2. 检查本地网络是否正常，是否可以正常访问其他网站
3. 重启EvoPanel软件尝试
4. 清除浏览器缓存（如果是Web端使用）
5. 查看控制台错误信息（按F12打开开发者工具），确认具体错误原因

### 问题：消息发送没反应
排查：
1. 检查是否有正在运行中的任务，等待当前任务完成后再发送
2. 确认模型配置正确，没有连接失败
3. 检查输入内容是否为空，或包含违规内容
4. 重启EvoPanel软件尝试
5. 查看logs/gateway.log中的错误日志

---
## 5. 飞书渠道相关问题
### 问题：飞书发消息没有回复
排查：
1. 确认飞书应用配置正确，事件订阅、消息接收权限、机器人能力都已经开启
2. 确认回调地址是公网可访问的地址，不能是内网地址或localhost
3. 进入EvoPanel「设置」→「飞书配置」，确认飞书渠道已经开启，App ID和App Secret填写正确
4. 确认消息内容不是敏感词被飞书拦截，尝试发送简单的测试消息如「你好」
5. 查看logs/feishu.log中的飞书相关日志，确认是否收到消息、处理是否正常
6. 确认机器人在群聊中有@权限，或者单聊时已经添加机器人为好友

### 问题：收不到推送通知
排查：
1. 进入「设置」→「通知配置」，确认推送渠道配置正确，点击「测试推送」可以收到测试消息
2. 确认任务的推送规则已经开启对应通知类型（任务完成、异常告警、进度更新等）
3. 检查飞书机器人有没有被禁言，有没有在对应群聊/单聊的发消息权限
4. 确认飞书账号没有设置免打扰，消息没有被归类到消息盒子
5. 查看logs/feishu.log中的推送相关日志，确认推送是否成功

### 问题：飞书卡片内容显示不全/乱码
排查：
1. 这通常是因为内容过长导致，飞书卡片有字数限制，过长内容会自动截断
2. 可以点击卡片的「查看完整内容」链接查看完整内容
3. 如果是乱码，确认飞书客户端是最新版本，尝试升级客户端
4. 如果是代码块显示异常，可以复制内容到本地编辑器查看
