常见问题与排查
先读取可见错误，判断它属于资源准备、模型请求、工具还是插件，修复对应边界后再重试。保留实际报错与应用版本，避免一次修改很多设置。
无法启动或发送消息
Section titled “无法启动或发送消息”| 现象 | 检查与下一步 |
|---|---|
| 首次资源一直未就绪 | 检查网络或代理与具体失败的资源，重试准备，或使用同平台受支持的离线导入／完整包 |
| Release 没有安装程序 | 仅组件版本用于更新已有应用；选择包含桌面安装程序的 Release |
| 发送按钮不可用 | 完成资源设置，启用包含可用模型的服务，选择有效的对话模型；也要等待附件保存或更新激活结束 |
| 检测连接成功但对话失败 | 实际调用当前模型，核对账号权限、接口模式、模型／部署 ID 与必要参数 |
| 认证失败／401／403 | 检查服务凭据或受支持的登录、账号授权与端点，不要将 token 粘贴进问题报告 |
| 404／找不到模型 | 核对 API 根地址、接口模式和精确模型／部署标识，不只检查服务展示名称 |
| 429／限流 | 阅读服务商返回的额度或频率限制，按提示等待，减少并发，或选择可用备用模型 |
| 超时或反复重试 | 检查服务网络与重试队列，必要时停止；重试无法修复错误密钥或不支持的模型 |
| 标题、压缩或自动检查失败 | 单独测试配置的 Flash 模型与其备用队列 |
OpenAI 兼容表示接口选择，不保证所有服务都支持每项可选参数。服务拒绝图片或推理字段时，应修正模型能力声明，或选择合适的模型与接口。
文件、附件与等待中的工具
Section titled “文件、附件与等待中的工具”| 现象 | 检查与下一步 |
|---|---|
| Agent 在错误目录工作 | 检查当前工作区与会话，目录被移动或改名时重新打开实际项目目录 |
| 文件或命令被拒绝 | 检查“运行 → 执行与权限”的路径规则、只读保护目录和网络策略；允许审批不会扩大权限 |
| Windows 命令提示沙盒准备失败 | 完成普通沙盒准备流程并检查辅助程序错误；插件安装不能代替准备，也不是模型服务故障 |
| 无法发送图片 | 选择真正支持视觉的模型并启用其视觉设置；文本模型不会因为附加图片就获得识图能力 |
| PDF 已上传但没有桌面预览 | PDF 不提供内嵌预览；能否读取仍由模型与接口决定，不支持时提取相关文本 |
| 长粘贴变成文件 | 支持附件时，超过 1,000 个 Unicode 字符的粘贴会变为文本附件；发送前检查卡片与引用 |
| 任务似乎卡住 | 先查看待审批、结构化问题、重试倒计时、活动终端与插件进度，再决定是否重新提交 |
| 停止后文件没有恢复 | 停止只取消后续工作，先审阅已完成修改，再选择对应文件恢复动作 |
插件与更新问题
Section titled “插件与更新问题”| 现象 | 检查与下一步 |
|---|---|
| 已安装插件没有工具 | 确认启用、组件诊断、Direct/Relay 覆盖、角色可用性、必要配置和进程依赖 |
| 工具连接但业务不可用 | 完成包的账号授权，实际调用核心业务工具；配置或状态响应不能证明业务成功 |
| 电脑控制工具失败 | 检查独立的真实电脑访问授权、支持的系统与前提；启用插件不等于授权 |
| 修改源码后没有变化 | 使用已关联本地源码的安装，点击刷新并等待活动任务结束；源码无效时保留旧包 |
| 换会话后侧栏消失 | 检查工作区／会话作用域与工作流激活条件，视图可能按分支可用 |
| 更新一直等待 | 先完成活动 Agent 任务；桌面外壳更新需要重启，不要为强行替换而终止工作 |
| 离线或校验阶段更新失败 | 保留可工作的安装，恢复连接后使用界面恢复入口重试，不要删除插件数据 |
插件作者可进一步使用开发排错表。
历史记录在哪里，如何备份？
Section titled “历史记录在哪里，如何备份？”普通安装版在 Windows、macOS、Linux 都使用 ~/.openagent/，其中 ~ 是用户主目录。调试版使用 ~/.openagent-dev/，Alpha 使用 ~/.openagent-alpha/；显式 OPENAGENT_HOME 则选择另一根目录。先检查打开的是哪个安装与数据目录，再判断历史是否丢失。切换工作区或分支，也会改变当前可见对话。
根目录包含配置、messages.db、附件、日志、已安装包、plugin-data 和插件私有设置。手动备份时，先完成活动任务，退出全部 OpenAgent 窗口与进程，再把整个活动根目录复制到受保护位置。工作区文件及其 .agents/ 另行备份；只复制正在使用的 SQLite 主文件，可能遗漏 WAL 中已提交的数据。
保留应用报告的迁移或数据转换备份，直到新版应用和历史验证正常。启动要求备份并替换不支持的数据时，先阅读影响范围和备份目的地，再作决定。不要为排查连接而删除 messages.db 或重置数据目录。重装、卸载插件与重置设置的影响范围不同，都不能替代已验证的备份。Windows 保护的凭据绑定当前用户，不是可移植凭据导出。
如何反馈可复现问题
Section titled “如何反馈可复现问题”打开帮助 → 上报问题，写明操作步骤、预期与实际结果、系统和应用版本，以及相关服务或插件版本。确认上传会附带近期 Runtime 与桌面日志，可能包含错误细节和本地路径。“附带当前对话完整轨迹”默认关闭；开启后可能包含已保存消息、模型请求与响应、工具参数和结果，确认前先检查这一选择。
常规设置 → 隐私与诊断的自动诊断开关，与主动上报分别控制。上传失败会保留草稿供重试，成功后保留报告编号以便跟进。本地日志位于当前根目录的 logs/，共享相关错误片段即可，不要上传完整配置、凭据或整个数据目录。