---
title: "故障排查"
description: "按连接、配置、MCP、会话和同步分层定位常见问题。"
version: "zh"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ochub.org/zh/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

排查时一次只改变一个变量。先判断问题发生在“OcHub 没有写对配置”“目标工具没有重新读取”
还是“上游拒绝了请求”，再决定下一步。

## 通用排查顺序

1. 记录 OcHub 页面上的完整状态提示。
2. 确认当前选中的应用、连接或模型供应商。
3. 展开“将写入的文件”，核对路径和关键字段。
4. 重启目标 CLI，再发起一条最短请求。
5. 如果使用模型供应商，检查 OcHub 仍在运行并查看用量请求日志。
6. 最后才修改模型映射、思考参数或环境变量。

## 保存成功但工具没有变化

- 确认执行的是“切换”或“添加到工具”，而不只是保存连接。
- 检查应用设置中的自定义配置目录。
- 退出仍在运行的目标 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、令牌或个人会话内容。

Source: https://docs.ochub.org/zh/troubleshooting/index.mdx