使用代理

如果你的网络环境需要通过代理服务器才能访问 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:pass@proxy.example.com:8080
3. 点击 保存 按钮应用配置。

无代理

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

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

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

环境变量	用途
HTTP_PROXY	HTTP 请求的代理地址
HTTPS_PROXY	HTTPS 请求的代理地址
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:password@proxy.example.com: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

---

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