---
url: https://docs.ogmabox.com/zh/troubleshooting.md
description: 排查 Ogma 常见的配置、代理捕获、HTTPS 拦截、桌面运行时、插件、MCP、扫描器和导出问题。
---

# 故障排查 {#troubleshooting}

本页用于排查 Ogma 常见的配置和运行问题。

## HTTP 历史记录中没有流量 {#no-traffic-appears-in-http-history}

请检查：

1. Ogma 实例正在运行。
2. 浏览器或应用的代理指向实例监听地址，通常为 `127.0.0.1:8080`。
3. 目标应用没有绕过代理。
4. VPN、系统代理、容器、模拟器或移动设备的代理设置没有覆盖测试客户端的设置。
5. 当前项目已在工作区中打开。

如果使用 Ogma 浏览器，请打开新标签页，确认显示**已通过代理**标记。

## HTTPS 请求失败 {#https-requests-fail}

请检查：

* Ogma CA 证书已安装到正确的信任存储区。
* CA 已导入实际使用的浏览器配置文件。
* 目标没有使用证书固定。
* TLS 透传规则没有排除该主机。
* 如果目标要求 mTLS，已在**设置 > 客户端证书**中配置客户端证书要求。

对于采用证书固定的移动或桌面应用，可能需要在 Ogma 之外进行针对该应用的测试配置。

## 拦截暂停了过多流量 {#intercept-pauses-too-much-traffic}

请缩小拦截规则的匹配范围。

建议步骤：

1. 禁用拦截。
2. 定义测试范围。
3. 添加主机、方法、路径、内容类型或请求头的匹配条件。
4. 重新启用拦截。
5. 留意队列大小。

当队列达到容量上限时，Ogma 会转发新流量，以避免客户端陷入死锁。

## 扫描器产生了过多噪声 {#scanner-reports-too-much-noise}

对于被动扫描器的噪声：

* 扫描前启用测试范围。
* 优先关注中危、高危和危急级别的安全发现。
* 根据具体情境判断缺少标头的问题。
* 使用自定义被动规则匹配项目特有的证据。

对于主动扫描器的噪声：

* 先扫描选定请求，再考虑扫描全部历史记录。
* 检查用于证明问题的请求和响应正文。
* 确认基线响应中不存在所用的响应证据。
* 检查安全发现的置信度是“较可能”还是“已确认”。

## 插件无法加载 {#plugins-do-not-load}

请检查：

1. 插件根目录包含 `manifest.json`。
2. 构建后 manifest 中指定的入口路径确实存在。
3. 插件已编译为普通 JavaScript。
4. 插件包包含前端资源。
5. 所需权限已声明并获授权。
6. 插件日志标签页没有 `init()` 或桥接错误。
7. 插件包大小低于配置的上限。

## MCP 助手无法访问 Ogma {#mcp-assistant-cannot-see-ogma}

请检查：

* 内嵌 HTTP：MCP 已在**设置 > MCP**中启动，客户端使用复制的 Streamable HTTP 端点，通常为 `http://127.0.0.1:3000/mcp`。
* 独立 stdio：二进制文件路径正确，且 `--api-url` / `OGMA_API_URL` 与运行中的后端一致。桌面实例可能使用动态 API 端口。
* 客户端跟随每个 `tools/list` 游标获取后续页面；仅第一页不包含全部工具。
* 写入或发送工具需要在设置中明确授权，或使用独立模式标志授权。
* MCP 重启后重新连接。旧会话 ID 和确认令牌不再有效。

请参阅 [MCP 配置](./mcp-setup.md)。

## Ogma 浏览器空白或位置异常 {#ogma-browser-is-blank-or-mispositioned}

请检查：

* 运行的是桌面应用，而非仅 Web 前端。
* 当前标签页有实际 URL，而不是 `about:blank`。
* 尝试将浏览器作为独立窗口打开。
* 调整 Ogma 窗口大小，强制重新计算浏览器边界。

## 自定义 JavaScript 或 CSS 导致界面异常 {#custom-javascript-or-css-breaks-the-ui}

使用以下任一种恢复方式：

* 点击**重置自定义界面**。
* 按下 `Ctrl+Alt+Shift+R`。

这会清除本地存储、桌面设置和后端偏好设置中的自定义 JavaScript 与 CSS，然后重新加载 Ogma。

## 数据或项目异常 {#data-or-project-looks-wrong}

请检查：

* 打开的是正确的实例。
* 当前活动项目正确。
* 启动偏好设置没有重新打开其他实例。
* 过滤器或测试范围没有隐藏预期记录。
* 静态资源隐藏功能没有排除你要查看的内容类型。

手动修改项目数据前请创建备份。