メインコンテンツまでスキップ

使用代理

如果你的网络环境需要通过代理服务器才能访问 LLM API 或其他外部服务，Elftia 提供灵活的代理配置选项。

代理模式​

Elftia 支持三种代理模式：

模式行为适用场景
系统代理跟随操作系统的代理设置已在系统级别配置代理的用户
自定义代理使用用户在 Elftia 中指定的代理地址需要为 Elftia 单独配置代理的用户
无代理直连，不使用任何代理网络可以直接访问所有服务

配置步骤​

方式一：在设置页面中配置​

  1. 打开 设置 → 通用。
  2. 找到 代理 配置区域。
  3. 选择代理模式：

系统代理​

选择「系统代理」后，Elftia 会自动检测并使用操作系统的代理设置。

  • Windows：读取 Internet 选项中的代理设置。
  • macOS：读取系统偏好设置中的网络代理配置。
  • Linux：读取 http_proxy/https_proxy 环境变量。

这是最简单的方式——如果你的操作系统已经配置了代理（例如通过 Clash、V2Ray 等代理客户端），选择此选项即可。

自定义代理​

选择「自定义代理」后，会出现一个输入框用于填写代理地址。

  1. 在输入框中填写代理 URL，格式为： 
    http://host:port
    或带认证信息： 
    http://username:password@host:port
  2. 常见示例：
    • 本地 HTTP 代理：http://127.0.0.1:7890
    • 本地 SOCKS5 代理：socks5://127.0.0.1:1080
    • 带认证的代理：http://user:[email protected]:8080
  3. 点击 保存 按钮应用配置。

无代理​

选择「无代理」后，Elftia 会跳过所有代理设置，直接连接目标服务器。

方式二：通过环境变量配置​

你也可以通过系统环境变量配置代理，这些变量会被 Elftia 自动识别：

环境变量用途
HTTP_PROXYHTTP 请求的代理地址
HTTPS_PROXYHTTPS 请求的代理地址
ALL_PROXY所有请求的代理地址（如果上面两个未设置）
NO_PROXY不使用代理的域名列表（逗号分隔）

Windows 设置环境变量：

# PowerShell（当前用户永久生效）
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:7890", "User")

macOS / Linux 设置环境变量：

# 添加到 ~/.bashrc 或 ~/.zshrc
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
備考

当 Elftia 的代理模式设置为「自定义代理」时，应用内配置的代理地址优先于环境变量。设置为「系统代理」时，环境变量和系统代理设置都会被考虑。

哪些服务使用代理​

代理配置会影响以下网络请求：

服务说明
LLM API 调用所有 LLM 提供商的 API 请求（OpenAI、Anthropic、Gemini 等）
MCP 连接MCP 服务器的 SSE/HTTP 连接（stdio 模式不受影响）
网页搜索Agent 的网页搜索和网页抓取请求
自动更新检查和下载应用更新
远程资源壁纸远程图片、远程字体等资源加载

以下服务 不受 代理影响：

服务原因
MCP stdio 连接通过本地子进程通信，不经过网络
本地文件操作Agent 的文件读写、Shell 命令等
数据库操作SQLite 本地数据库

代理认证​

如果你的代理需要用户名和密码认证：

  1. 在自定义代理的 URL 中包含认证信息： 
    http://username:[email protected]:8080
  2. 或者，一些代理客户端支持在本地启用无需认证的中转端口，你可以连接到该中转端口。

验证代理是否生效​

配置代理后，你可以通过以下步骤验证：

  1. 打开 设置 → 提供商设置。
  2. 选择一个已配置 API Key 的提供商。
  3. 点击 测试连接。
  4. 如果测试成功（绿色提示），说明代理配置正确。
  5. 如果测试失败，请检查：
    • 代理地址和端口是否正确
    • 代理服务是否正在运行
    • 代理是否允许访问目标 API 域名

常见问题​

ECONNREFUSED 错误​

原因： 代理服务器未运行或地址/端口错误。

解决：

  1. 确认代理客户端（Clash、V2Ray 等）正在运行。
  2. 检查代理的监听地址和端口是否与 Elftia 中配置的一致。
  3. 部分代理客户端默认只监听 127.0.0.1，不监听 0.0.0.0。

ETIMEDOUT 错误​

原因： 代理服务器无法连接到目标地址。

解决：

  1. 检查代理的上游连接是否正常。
  2. 确认代理规则是否允许访问 LLM API 的域名（如 api.openai.com、api.anthropic.com）。
  3. 部分代理的规则模式可能默认不代理 API 域名，需要手动添加。

SSL/TLS 证书错误​

原因： 代理服务器使用了自签名证书进行 HTTPS 解密。

解决：

  1. 如果代理需要安装根证书，请按照代理客户端的文档安装信任证书。
  2. 某些企业代理会进行 HTTPS 中间人检查，可能需要在系统中信任企业的根证书。

代理只对部分提供商有效​

原因： 不同提供商的 API 域名可能需要不同的代理规则。

解决：

  1. 确认代理的路由规则覆盖了所有需要的 API 域名。
  2. 常见的 LLM API 域名包括：
    • api.openai.com
    • api.anthropic.com
    • generativelanguage.googleapis.com
    • api.deepseek.com

如果代理配置后仍有连接问题，请参阅 连接错误 获取更详细的排查指南。