故障排除

服务器所在的机器作出了应答，但没有任何程序在该端口上接受连接。

• 检查服务器是否在运行，以及是否在地址中的端口上。监听 3000 的本地服务器无法通过 localhost:8080 访问。
• 检查变量填入之后的地址：把指针停在 {{variable}} 标签上查看它的值，并在页面标题栏中检查当前使用的是哪个环境。
• Docker 或虚拟机中的服务器需要把端口发布到 Mac 上。

这个名称无法解析成地址。检查拼写、你的网络和 VPN。只存在于公司网络内部的主机，需要连上该网络或它的 VPN。

未能及时应答表示连接已建立，但响应所用的时间超过了请求的超时。如果服务器很慢，请在请求的设置标签页中调高超时。未能及时连接到 … 表示连接本身没有打开：可能是防火墙、VPN，或服务器已宕机。

Echolot 会复用已打开的连接。服务器恰好在请求发出时关闭了一个连接，没有任何响应返回。

对于可能被发送两次的请求（GET 和其他安全或幂等的方法，或带有 Idempotency-Key 标头的请求），Echolot 会自动在新连接上重试一次。对于其他请求，例如 POST，则不会重试，因为服务器可能已经处理了该请求：再次发送之前请先检查。

无法访问表示网络没有通往服务器的路由：检查 Wi-Fi、网络和 VPN。重置了连接表示服务器或中间的某个环节断开了连接，常见原因是防火墙，或服务器拒绝该协议（例如把纯 HTTP 发到了 HTTPS 端口）。

演示 API 是共用的，每个地址每分钟限 120 个请求，大型、慢速和流式端点（导出、bytes、delay、WebSocket 和 SSE）每分钟限 10 个。等待 Retry-After 响应标头中的秒数后再发送。对着演示 API 进行多次迭代的运行器运行很快就会达到限制；请调低迭代次数。

服务器的证书是自签名的、已过期，或不是由你的 Mac 信任的机构签发的。信息中会说明是哪一种。

• 对于公司或开发用的机构，请在工作区设置 › 证书中为该主机添加它的 CA 证书，而不要关闭检查。见请求设置。
• 仅对于开发服务器，可在请求的设置标签页中关闭验证 TLS 证书。

证书有效，但写的是另一个主机。请使用证书所对应的主机名，或在服务器上修正证书。

与服务器的 TLS 握手失败。冒号后面的文字是 TLS 库自己给出的原因。常见的原因是服务器要求客户端证书：请在工作区设置 › 证书中为该主机添加一个。

证书设置指向的文件已被移动，或者是另一种格式的文件。请在工作区设置 › 证书中重新选择文件；Echolot 读取 PEM 证书。

由设置 › 网络 › 代理决定：

工作区可以在工作区设置 › 代理中设置自己的代理，它优先于 App 的设置。如果你的公司使用 PAC 文件，请在手动下输入其中的代理。命令行工具读取 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY。

代理需要你登录。请在设置 › 网络或工作区的代理设置中，为代理添加用户名和密码。

代理本身正常，但不愿或无法访问那台服务器：它的规则拦截了该服务器，或者从代理所在的位置看服务器已宕机。如果服务器在本地或内部，请把它添加到直接连接到。

HTTP/3 在 macOS 27 及更高版本上可用。在较旧的 macOS 上，请在请求的设置标签页中选择 HTTP/2 或自动。

Echolot 不会通过代理（包括系统代理，与浏览器一样）、自定义 CA 文件或客户端证书发送 HTTP/3。请为该请求选择 HTTP/2 或自动。选择自动时，Echolot 只会在服务器提供 HTTP/3 且没有任何阻碍的情况下自行切换到 HTTP/3，并在 QUIC 连接无法打开时回退到 TCP。

服务器的检查把服务器已启动显示为失败。

• 先批准它。只有在你于“MCP 服务器”页面用信任并检查批准之后，Echolot 才会启动本地服务器的命令。在此之前，调用会显示 Echolot 此前未启动过 MCP 服务器“…”。请在“MCP 服务器”页面查看其命令，并先信任它。命令、参数或环境的更改会再次询问。
• 找不到命令。修复提示写着 检查“npx”是否已安装并位于 PATH 中，或者提供其完整路径。 Echolot 以你的登录 shell 的 PATH 启动服务器，因此在新的终端窗口中能用的 npx、uvx 以及版本管理器的 shim，在 Echolot 中也能用。如果该命令只有在你的 shell 交互式地做了某些事之后才能用，请提供它的完整路径（在终端中用 which npx 查找）。
• 启动后又停止。在终端中运行同一条命令，看看原因；服务器的错误输出也在消息日志中。

见添加服务器。

你使用的是 Mac App Store 版，它无法在你的 Mac 上启动程序。服务器仍保留在工作区中。如果服务器支持 HTTP，请通过 HTTP 添加它，用命令行工具运行它（echolot mcp check -- <command>），或使用直接下载版。见版本。

检查的修复提示行会说明该怎么做：对要求 OAuth 的服务器，是登录；对要求令牌的服务器，是 Authorization 标头；对于 404，则是正确的路径（MCP 端点通常是 /mcp）。

在 Mac App Store 版中，Echolot 只有在你选择了工作区之外的文件之后才能读取它。当正文从文件流式读取、表单部分、客户端证书，或路径是在 Echolot 之外写入的 .proto 文件时，就会出现这种情况。请在失败的响应上选择允许访问…，选取该文件，然后再次发送；Echolot 会记住它。

在直接下载版中，这条信息表示该文件自身的权限不允许你读取它。

请求、它的文件夹或工作区中有来自别处的脚本：导入、git pull，或在 Echolot 之外的编辑。只有在你信任它们之后才会运行。请选择查看脚本…，阅读它们，然后信任。见脚本和测试。

Echolot 无法写入请求的文件：磁盘已满、文件夹是只读的，或者工作区被移动了。重试会再试一次；继续编辑会把你的编辑保留在标签页中，该标签页会一直保持打开，直到它们存储成功。

你在标签页中有未存储的编辑时，另一个 App 或 Git 更改了该文件。使用文件中的版本会放弃你的编辑并载入该文件；保留我的版本会保留你的编辑并覆盖该文件。

该项由另一份 Echolot、另一个版本或命令行工具创建。macOS 会对每一项询问一次；请选择始终允许。

直接下载版已发布的 Beta 构建在发布 30 天后过期，如果开发者提前结束某个构建，则会更早。请从 echolot.dev 下载最新版本并覆盖安装：你的工作区会原样打开。如果提示说这台 Mac 的日期似乎不对，则表示时钟比 Echolot 已经见过的某个日期晚了一天以上：请在系统设置中设置日期和时间。见安装。

命令行工具还不在你的 PATH 中。请选择 Echolot › 安装命令行工具…，然后打开一个新的终端窗口（已打开的窗口保留着旧的 PATH）。设置 › 通用 › 命令行工具显示链接的位置；如果它显示警告，说明链接指向的 Echolot 副本已被移动：请选择重新安装。在 App Store 版中，请单独安装该工具；见命令行工具。

没有钥匙串时（Linux、CI，或 ECHOLOT_KEYCHAIN=0），工具会从名为 ECHOLOT_SECRET_<NAME> 的环境变量读取机密，例如机密变量 password 对应 ECHOLOT_SECRET_PASSWORD。请在 CI 的机密设置中设置它们。见 CI。

Echolot 无法创建它的储存文件夹，通常是因为可用空间或权限不足。在你重新启动 Echolot 之前，响应会保存在临时文件夹中。请腾出一些空间或修正文件夹的权限（设置 › 关于 › 响应和历史记录 › 在访达中显示会显示它的位置），然后重新启动。