排查时一次只改变一个变量。先判断问题发生在“OcHub 没有写对配置”“目标工具没有重新读取” 还是“上游拒绝了请求”，再决定下一步。
通用排查顺序
- 记录 OcHub 页面上的完整状态提示。
- 确认当前选中的应用、连接或模型供应商。
- 展开“将写入的文件”，核对路径和关键字段。
- 重启目标 CLI，再发起一条最短请求。
- 如果使用模型供应商，检查 OcHub 仍在运行并查看用量请求日志。
- 最后才修改模型映射、思考参数或环境变量。
保存成功但工具没有变化
- 确认执行的是“切换”或“添加到工具”，而不只是保存连接。
- 检查应用设置中的自定义配置目录。
- 退出仍在运行的目标 CLI；已有进程可能缓存配置。
- 查看是否出现外部修改冲突，或其他配置管理工具是否仍在写同一文件。
- OpenCode、OpenClaw 和 Hermes 使用可同时保存多个连接的模式；Claude、Claude Desktop、 Codex、Grok Build 和 Kimi Code 更强调当前连接。Cherry Studio 使用“导入”，并在自己的 窗口中要求确认。
地址可达但请求失败
“测试 URL”或“HTTP 延迟测试”收到 HTTP 响应就可能判断地址可达。继续检查：
- API Key 是否属于该地址。
- 模型名是否由该接口提供。
- 上游要求的是 Anthropic、OpenAI Chat 还是 OpenAI Responses。
- 账号是否有余额、额度或访问权限。
- 默认模型或模型例外是否改写了请求。
- 上游返回的具体状态码和错误信息。
模型供应商无法连接
- 确认卡片开关为启用。
- 确认应用已应用过该模型供应商，而不是只保存了它。
- 用供应商编辑器里的“HTTP 延迟测试”和“拉取模型”区分本地网关问题和上游问题。
- 临时切换到一个已验证的直接连接，确认目标 CLI 本身仍能工作。
MCP 没有出现在目标应用
- 确认服务器卡片上已启用目标应用。
- 修改开关后点击“同步到应用”。
- 检查服务器 JSON 是对象，并包含正确的
type、command或url。 - stdio 服务器的命令必须位于目标工具能看到的
PATH。 - 检查目标应用是否已启用，以及配置目录是否被覆盖。
- 同步后重启目标应用。
技能安装或更新失败
- 检查网络和仓库地址。
- 仓库格式使用
owner/repo、owner/repo@branch或 GitHub 链接。 - 确认 skills CLI 可用。
- “目录冲突”表示目标目录已存在；先检查现有文件，不要直接覆盖。
- 批量更新部分失败时，按状态提示逐个处理失败技能。
会话或用量为空
- 会话只读取受支持 CLI 实际写入的本地历史。
- 检查应用配置目录、会话时间范围和应用筛选。
- 点击刷新，等待扫描结束。
- 用量页面再检查 Provider、模型和状态筛选。
- 只有模型供应商请求一定包含网关级延迟；会话导入可能缺少部分字段。
同步或恢复失败
- 重新测试已保存的 WebDAV 或 S3 连接。
- 确认 Endpoint、区域、Bucket、远端目录和配置档。
- 测试连接不会保存表单，测试成功后仍需点击“保存”。
- 恢复前必须能创建本地安全备份；备份失败时还原会取消。
- 不要在多台设备上同时上传不同快照。
仍然无法解决
提交问题时附上：
- OcHub 版本、操作系统与安装方式。
- 目标应用和连接方式。
- 可复现的最短步骤。
- 页面显示的完整错误文本。
- 已脱敏的配置预览；不要附带 API Key、令牌或个人会话内容。