跳到主要内容

连接错误

本页专注于 Elftia 中各类网络连接问题的排查。涵盖 LLM API 调用错误、代理相关故障、SSL/TLS 问题、MCP 连接失败以及 Channel 连接异常。

LLM API HTTP 状态码​

当 LLM API 调用返回错误时，HTTP 状态码是最重要的排查线索。以下是每个状态码的含义和解决方案：

401 Unauthorized​

含义： API Key 无效或未提供。

常见原因：

  • API Key 输入时包含多余空格或换行
  • API Key 已被撤销或过期
  • API Key 格式错误（如 OpenAI Key 应以 sk- 开头）
  • 使用了错误提供商的 Key

解决步骤：

  1. 前往 设置 → 提供商设置，重新检查 API Key。
  2. 复制完整的 Key，粘贴到输入框中替换现有值。
  3. 前往提供商的控制台，确认 Key 仍然有效。
  4. 如果使用 API Key 池，检查池中是否有失效的 Key（已禁用的 Key 会标记为灰色）。
信息

当 API Key 池中某个 Key 返回 401 时，该 Key 会被自动禁用，系统自动切换到池中其他可用 Key。

403 Forbidden​

含义： 认证成功但权限不足。

常见原因：

  • 账号余额不足或未绑定支付方式
  • API Key 不具备请求的模型的访问权限
  • IP 地址或地区被提供商限制
  • 组织/项目权限限制

解决步骤：

  1. 登录提供商控制台，检查账号余额和支付状态。
  2. 确认 API Key 有权访问你选择的模型（部分高级模型需要特殊权限）。
  3. 如果使用代理，尝试切换代理节点到不同地区。
  4. 检查提供商控制台中的组织和项目设置。

429 Too Many Requests​

含义： 请求频率过高，触发了速率限制。

常见原因：

  • 短时间内发送了太多请求
  • 账号的速率配额较低（免费或低层级账号）
  • 多个应用共享同一个 API Key

解决步骤：

  1. 等待一段时间后重试。Elftia 会显示冷却提示。
  2. 如果频繁触发，考虑升级提供商账号的用量层级。
  3. 配置 API Key 池，使用多个 Key 分散请求。

Elftia 的自动处理：

  • 遇到 429 时，当前 Key 会进入冷却期（从 60 秒开始，指数退避最长至 15 分钟）。
  • 如果配置了 API Key 池，系统会自动切换到池中其他可用 Key 重试请求。
  • 冷却期结束后 Key 自动恢复可用。

500 Internal Server Error​

含义： 提供商服务器内部错误。

解决步骤：

  1. 这是提供商端的问题，通常会自动恢复。等待几分钟后重试。
  2. 查看提供商的状态页面确认是否有已知故障。
  3. 如果持续出现，尝试切换到其他模型或提供商。

502 Bad Gateway​

含义： 提供商的网关/负载均衡器错误。

解决步骤：

  1. 通常是暂时性问题，等待 1-5 分钟后重试。
  2. 检查提供商状态页面。
  3. 如果使用自定义 Base URL（第三方中转），检查中转服务是否正常。

503 Service Unavailable​

含义： 提供商服务暂时不可用（维护或过载）。

解决步骤：

  1. 等待提供商恢复服务。
  2. 切换到备用提供商继续工作。
  3. 查看提供商的状态页面和社交媒体了解恢复时间。

529 Overloaded​

含义： 提供商服务器过载（Anthropic 特有的状态码）。

解决步骤：

  1. 等待一段时间后重试。
  2. 如果配置了 API Key 池，系统会自动切换 Key 重试。
  3. 尝试使用较小的模型（如 Claude Haiku 而非 Claude Opus），减轻服务器负担。

Elftia 的自动处理： 与 429 相同，触发冷却和自动 Key 切换机制。

代理相关错误​

ECONNREFUSED​

含义： 连接被拒绝，通常是代理服务未运行。

Error: connect ECONNREFUSED 127.0.0.1:7890

解决步骤：

  1. 确认代理客户端（Clash、V2Ray、Shadowsocks 等）正在运行。
  2. 检查代理监听的端口号与 Elftia 配置的端口是否一致。
  3. 确认代理是否监听了正确的地址（127.0.0.1 vs 0.0.0.0）。
  4. 如果不需要代理，在 设置 → 通用 → 代理 中切换为「无代理」。

ETIMEDOUT​

含义： 连接超时，代理无法连通目标服务器。

Error: connect ETIMEDOUT api.openai.com:443

解决步骤：

  1. 检查代理的上游连接是否正常（代理本身能否访问目标域名）。
  2. 检查代理的路由规则是否包含 LLM API 域名。
  3. 尝试切换代理节点。
  4. 检查防火墙规则。

ECONNRESET​

含义： 连接被远端重置，通常是代理中途断开。

解决步骤：

  1. 检查代理的连接稳定性。
  2. 增大代理的超时设置。
  3. 如果是长时间的流式请求（如大段代码生成），代理可能有连接时长限制，需要调整。

SSL/TLS 错误​

UNABLE_TO_VERIFY_LEAF_SIGNATURE​

含义： 无法验证服务器证书，通常是自签名证书。

常见场景：

  • 企业代理使用自签名 CA 证书进行 HTTPS 检查
  • 自建的 LLM API 中转服务使用自签名证书

解决步骤：

  1. 安装并信任代理/中转服务的根证书。
    • Windows：双击证书文件 → 安装证书 → 本地计算机 → 受信任的根证书颁发机构。
    • macOS：双击证书文件 → 添加到钥匙串 → 始终信任。
    • Linux：复制到 /usr/local/share/ca-certificates/ → 运行 sudo update-ca-certificates。
  2. 重启 Elftia 使证书变更生效。

CERT_HAS_EXPIRED​

含义： 服务器的 SSL 证书已过期。

解决步骤：

  1. 如果是自建服务，更新 SSL 证书。
  2. 如果是公共服务，通常是临时问题，稍后重试。
  3. 检查系统时间是否准确（错误的系统时间会导致有效证书被判定为过期）。

ERR_TLS_CERT_ALTNAME_INVALID​

含义： 证书的域名与实际访问的域名不匹配。

解决步骤：

  1. 检查提供商的 Base URL 是否拼写正确。
  2. 如果使用自定义端点，确认服务器证书覆盖了你使用的域名。

MCP 连接错误​

stdio 模式 — ENOENT​

含义： 找不到 MCP 服务器的启动命令。

Error: spawn npx ENOENT

解决步骤：

  1. 确认 command 字段指定的程序已安装：
    • npx / node：需要安装 Node.js。
    • uvx / python：需要安装 Python 和 uv。
  2. 在终端中手动运行该命令验证是否可执行。
  3. 检查 设置 → 通用 → 环境 中的工具安装状态。
  4. 如果工具已安装但仍报错，可能需要重启 Elftia 刷新 PATH 环境变量。

stdio 模式 — 进程启动后立即退出​

症状： MCP 服务器显示短暂连接后断开。

可能原因：

  • 缺少必要的 npm/pip 依赖
  • 启动参数错误
  • 缺少必要的环境变量

解决步骤：

  1. 在终端中手动运行 MCP 服务器命令，查看错误输出： 
    npx -y @modelcontextprotocol/server-filesystem /path
  2. 检查是否缺少依赖包，手动安装： 
    npm install -g @modelcontextprotocol/server-filesystem
  3. 确认 MCP 配置中的 env 包含所有必要的环境变量。

SSE/HTTP 模式 — 连接超时​

症状： 远程 MCP 服务器连接超时。

解决步骤：

  1. 确认 MCP 服务器正在运行且可从你的网络访问。
  2. 在浏览器中尝试访问 MCP 服务器的 URL 验证连通性。
  3. 检查防火墙是否允许访问 MCP 服务器的端口。
  4. 如果使用代理，确认代理规则允许访问 MCP 服务器的地址。

SSE 模式 — 连接频繁断开​

症状： SSE 连接建立后频繁断开重连。

可能原因：

  • 网络不稳定
  • 代理或负载均衡器的连接超时设置过短
  • MCP 服务器本身不稳定

解决步骤：

  1. 检查网络连接的稳定性。
  2. 如果使用代理或反向代理，增大连接超时和空闲超时设置。
  3. 联系 MCP 服务器的维护者确认服务状态。

Channel 连接错误​

Discord Bot 连接失败​

可能原因：

  • Bot Token 无效或过期
  • Bot 未被邀请到目标服务器
  • Bot 缺少必要的权限
  • Discord API 限速

解决步骤：

  1. 在 Discord Developer Portal 确认 Bot Token 正确。
  2. 确认 Bot 已被邀请到目标 Discord 服务器并有发言权限。
  3. 检查 Bot 的 Privileged Gateway Intents 是否已启用。

Telegram Bot 连接失败​

可能原因：

  • Bot Token 无效
  • 网络无法访问 Telegram API（api.telegram.org）
  • 另一个客户端在使用同一个 Bot Token

解决步骤：

  1. 通过 @BotFather 确认 Bot Token 正确。
  2. 确认你的网络可以访问 api.telegram.org（可能需要代理）。
  3. 确保没有其他应用正在使用相同的 Bot Token。

速率限制与退避机制​

Elftia 内置了智能的速率限制处理机制：

API Key 池自动切换​

当单个 Key 遇到 429/529 错误时：

  1. 当前 Key 进入冷却期。
  2. 系统立即尝试池中下一个可用 Key。
  3. 如果请求成功，用户几乎无感知。
  4. 冷却期使用指数退避：60s → 120s → 240s → ... → 最长 15 分钟。
  5. 冷却期结束后 Key 自动恢复可用。

会话亲和性​

为了保持 LLM 提供商的提示缓存效率，同一个对话会话会尽量使用同一个 API Key：

  • 首次请求通过加权轮询选择 Key。
  • 后续请求优先使用同一个 Key。
  • 仅当绑定的 Key 不可用（冷却中或被禁用）时才切换。

永久失败处理​

当 Key 返回 401/403 时，说明 Key 已永久失效：

  • 该 Key 会被自动禁用（标记为不可用）。
  • 系统切换到其他 Key。
  • 你会在提供商设置的 API Key 池中看到被禁用的 Key。

防火墙与杀毒软件​

防火墙阻止出站连接​

症状： 所有 LLM API 调用都超时或被拒绝。

解决步骤：

  1. 在防火墙设置中，将 Elftia 添加到允许列表。
    • Windows Defender 防火墙：控制面板 → Windows Defender 防火墙 → 允许应用通过防火墙 → 添加 Elftia。
    • macOS：系统偏好设置 → 安全性与隐私 → 防火墙 → 允许 Elftia。
  2. 如果使用企业防火墙，联系 IT 管理员开放以下域名的出站访问：
    • api.openai.com（OpenAI）
    • api.anthropic.com（Anthropic）
    • generativelanguage.googleapis.com（Google Gemini）
    • api.deepseek.com（DeepSeek）

杀毒软件误报​

症状： 杀毒软件阻止 Elftia 运行或网络连接。

解决步骤：

  1. 在杀毒软件中将 Elftia 的安装目录添加到排除/白名单。
  2. 常见需要排除的路径：
    • Windows：C:\Users\<用户名>\AppData\Local\Elftia\
    • macOS：/Applications/Elftia.app

网络连通性快速检查​

遇到连接问题时，可以按以下顺序快速排查：

  1. 基本网络：在浏览器中打开任意网页，确认网络正常。
  2. 域名解析：在终端运行 ping api.openai.com（或对应提供商域名），确认域名可解析。
  3. 端口连通：在终端运行 curl -I https://api.openai.com，确认 443 端口可访问。
  4. 代理测试：如果使用代理，在终端设置代理环境变量后重试上述命令。
  5. Elftia 测试：在 Elftia 的提供商设置中使用「测试连接」功能。

如果步骤 1-4 都正常但步骤 5 失败，可能是 Elftia 的代理配置问题，请参考 使用代理 重新配置。

如果本页未涵盖你遇到的连接问题，请使用 诊断工具 导出诊断信息，然后在社区中寻求帮助。