常见问题与排查
先保留错误原文，再定位失败发生在哪一步：连接模型、读取文件、调用工具，还是运行 Graph。每次只改一个相关设置，更容易判断原因。
模型连接失败
| 现象 | 优先检查 |
|---|---|
| 认证失败，常见为 401 或 403 | 当前 Provider 的 API Key 是否有效、是否有对应权限；结合错误正文确认，网关也可能返回这些状态。 |
| 模型不存在或无权限 | 模型 ID 是否属于当前服务，账号是否有使用权限。 |
| 连接超时或地址错误 | API Base、所需路径前缀、网络或代理；本地服务是否已启动。 |
| 限流或额度错误 | 服务商返回的错误详情、调用限额与账号状态。 |
| 切换默认模型后仍用旧模型 | 已有会话保留自己的模型，在会话中切换或新建会话。 |
先用一句简短问题复现，不附加大文件或复杂工具任务。详细配置见 Provider 与模型。
找不到文件或工作区
确认文件在磁盘上仍然存在，当前会话关联了正确的工作区，任务中使用的相对路径是相对于该目录的。
通过附件发送时，检查发送前是否已显示附件。不要假设“提到了文件名”就等于“提供了文件”。目录移动后，需要重新选择有效目录。
插件或 MCP 不可用
依次检查：
- 插件是否导入成功并已启用。
- Skill 或项目 MCP 是否属于当前会话的工作区。
- STDIO 启动命令及依赖是否可运行；HTTP 地址是否可达。
- 凭据、参数和环境变量是否符合服务说明。
- 配置后是否已经开始新的对话轮次。
查看页面中的连接状态与具体错误。不要反复重装来替代对错误的检查。更多说明见 插件、Skills 与 MCP。
Graph 无法运行
检查 Graph 是否已经保存、运行输入是否为空、Agent 的执行工作区是否存在、模型是否可用。检查节点必需字段，以及从 Input 到 Output 的连接。
使用 Router 时，每条路径需要填写选择条件并连接出口。运行过程中失败，选择对应的最近运行记录，再查看失败节点的消息。
为什么还在执行？
一项任务可能包含多次模型请求与工具调用。检查是否有等待你填写的表单、仍在运行的工具，或明确的错误提示。
如果决定停止，等待界面确认结束，再检查已经产生的文件和操作结果。停止不会自动撤销已完成的动作。
反馈问题时附上什么
建议准备以下信息，并在 GitHub Issues 中用英文描述问题：
- Tinybot 版本、操作系统和相关环境信息。
- 能复现问题的最少步骤。
- 预期发生什么，实际发生什么。
- 错误原文与发生时间。
- 涉及的 Provider 和模型 ID，或插件、MCP、Graph 的必要配置，不包含密钥。
需要进一步定位时，可以在应用的 性能追踪 面板开启 诊断模式，复现一次问题后 导出诊断包，然后关闭诊断模式。
诊断包先保存在本地，不会自动上传。附到 Issue 之前检查内容，移除密钥、个人路径和不适合公开的任务信息。截图也应使用演示数据或做好遮挡。