常见问题：工具、数据与连接
工具调用失败
- 看智能体对失败原因的说明：工具返回的错误会由它转述，并给出下一步建议；
- 打开「设置 → 运行诊断」检查运行时和插件状态；
- 涉及外部服务的，到「设置 → 连接器」测试连接；
- 插件页提示「插件文件不完整」的，按提示在插件市场重新安装（内置插件则重新安装客户端）；
- 仍无法解决时，记下操作步骤与出错时间，发邮件到 opengeodex@zealmap.com 联系我们。
数据下载失败
- DEM 下载需要在连接器里配置 OpenTopography API Key 或 NASA Earthdata 账号；
- 下载大范围数据耗时较长，可以缩小范围或降低分辨率；
- 网络受限时配置代理；
- 公开服务偶尔不稳定，稍后重试或让智能体换一个数据源。
PostGIS / MySQL / GeoServer 连不上
- 在「设置 → 连接器」点「测试」，把鼠标移到红点上查看错误；
- 检查主机、端口、防火墙和白名单；
- MySQL 的账号按「用户名@来源地址」授权，远程连接时要请管理员为本机地址授权，并确认服务器没有只监听本机；
- 在项目中使用时，确认已在项目配置里勾选该连接器；
- 需要写入时，确认连接器权限设为「读写」。
MCP 服务连不上或没有工具
先确认服务已启用、命令或 URL 能单独正常运行，再检查环境变量和请求头，详见MCP 服务：管理与排查。
插件提示“插件文件不完整，已停用”
插件文件被杀毒软件删除或损坏。扩展插件到「设置 → 插件 → 插件市场」重新安装；内置插件请重新安装客户端。把 OpenGeodex 的安装目录和数据目录加入杀毒软件的信任列表，可以避免再次被删，见杀毒软件拦截或误删了文件。
保存到“文档”时提示找不到文件或保存失败
另存产物、备份数据，或让智能体把结果写到“文档”“图片”“视频”“音乐”这类文件夹时，如果“另存为”对话框提示“找不到文件，请检查文件名”，或者客户端提示写入失败，而保存到桌面或其他磁盘是正常的，原因通常不是路径有问题，而是 Windows 安全中心的“受控文件夹访问”（防勒索保护）拦截了写入。这项保护开启后，没有被系统信任的程序不能往这些文件夹里写文件，系统给出的提示却是找不到文件。
两种解决办法任选其一：
- 换一个位置保存，例如桌面、D 盘或其他不受保护的文件夹。
- 允许 OpenGeodex 写入：打开“Windows 安全中心 → 病毒和威胁防护 → 勒索软件防护 → 管理勒索软件防护 → 允许应用通过受控文件夹访问 → 添加允许的应用”，选择 OpenGeodex 安装目录下的
opengeodex-desktop.exe。公司电脑上这项设置可能由管理员统一管理，需要联系管理员添加。
客户端检测到这项保护开启时，会在保存对话框的标题里提醒，并在写入失败的提示里说明原因。