Use Proxy

If your network environment requires a proxy server to access LLM APIs or other external services, Elftia provides flexible proxy configuration options.

Proxy Modes

Elftia supports three proxy modes:

Mode	Behavior	Use Case
System Proxy	Follow operating system proxy settings	Users who've configured proxy at system level
Custom Proxy	Use proxy address specified in Elftia	Users who need separate proxy for Elftia
No Proxy	Direct connection, no proxy	Network can directly access all services

Configuration Steps

Method 1: Configure in Settings Page

1. Open Settings → General.
2. Find the Proxy configuration area.
3. Select a proxy mode:

System Proxy

After selecting "System Proxy", Elftia will automatically detect and use the operating system's proxy settings.

• Windows: Reads proxy settings from Internet Options.
• macOS: Reads network proxy configuration from System Preferences.
• Linux: Reads http_proxy/https_proxy environment variables.

This is the simplest approach — if your operating system is already configured with a proxy (e.g., through Clash, V2Ray, or similar proxy clients), select this option.

Custom Proxy

After selecting "Custom Proxy", an input box will appear for entering the proxy address.

1. Enter the proxy URL in the format:

   http://host:port

   Or with authentication:

   http://username:password@host:port

2. Common examples:
   • Local HTTP proxy: http://127.0.0.1:7890
   • Local SOCKS5 proxy: socks5://127.0.0.1:1080
   • Proxy with authentication: http://user:[email protected]:8080
3. Click the Save button to apply the configuration.

No Proxy

After selecting "No Proxy", Elftia will skip all proxy settings and connect directly to target servers.

Method 2: Configure via Environment Variables

You can also configure proxy through system environment variables, which Elftia will automatically recognize:

Environment Variable	Purpose
HTTP_PROXY	Proxy address for HTTP requests
HTTPS_PROXY	Proxy address for HTTPS requests
ALL_PROXY	Proxy address for all requests (if the above two are not set)
NO_PROXY	Comma-separated list of domains that don't use proxy

Set environment variables on Windows:

# PowerShell (permanent for current user)
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:7890", "User")

Set environment variables on macOS / Linux:

# Add to ~/.bashrc or ~/.zshrc
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"

info

When Elftia's proxy mode is set to "Custom Proxy", the proxy address configured in the app takes precedence over environment variables. When set to "System Proxy", both environment variables and system proxy settings are considered.

Which Services Use Proxy

Proxy configuration affects the following network requests:

Service	Description
LLM API Calls	API requests to all LLM providers (OpenAI, Anthropic, Gemini, etc.)
MCP Connection	SSE/HTTP connections to MCP servers (stdio mode is not affected)
Web Search	Agent's web search and web scraping requests
Auto Update	Checking and downloading application updates
Remote Resources	Loading remote resources like wallpaper images, remote fonts

The following services are NOT affected by proxy:

Service	Reason
MCP stdio Connection	Uses local subprocess communication, no network
Local File Operations	Agent's file read/write, Shell commands, etc.
Database Operations	SQLite local database

Proxy Authentication

If your proxy requires username and password authentication:

1. Include authentication information in the custom proxy URL:

   http://username:[email protected]:8080

2. Alternatively, some proxy clients support enabling a forwarding port without authentication locally; you can connect to that port.

Verify Proxy is Working

After configuring the proxy, you can verify it's working by following these steps:

1. Open Settings → Provider Settings.
2. Select a provider with a configured API Key.
3. Click Test Connection.
4. If the test succeeds (green notification), the proxy configuration is correct.
5. If the test fails, check:
   • Whether the proxy address and port are correct
   • Whether the proxy service is running
   • Whether the proxy allows access to the target API domain

Common Issues

ECONNREFUSED Error

Cause: Proxy server is not running or address/port is incorrect.

Solution:

1. Confirm the proxy client (Clash, V2Ray, etc.) is running.
2. Check whether the proxy's listening address and port match those configured in Elftia.
3. Some proxy clients default to listening only on 127.0.0.1, not 0.0.0.0.

ETIMEDOUT Error

Cause: Proxy server cannot connect to the target address.

Solution:

1. Check whether the proxy's upstream connection is working.
2. Confirm that proxy rules allow access to LLM API domains (e.g., api.openai.com, api.anthropic.com).
3. Some proxy rule patterns may not proxy API domains by default; you may need to add them manually.

SSL/TLS Certificate Error

Cause: Proxy server uses a self-signed certificate for HTTPS decryption.

Solution:

1. If the proxy requires installing a root certificate, follow your proxy client's documentation to install and trust the certificate.
2. Some corporate proxies perform HTTPS man-in-the-middle inspection; you may need to trust the corporate root certificate in your system.

Proxy Works for Only Some Providers

Cause: Different providers' API domains may require different proxy rules.

Solution:

1. Confirm that your proxy's routing rules cover all needed API domains.
2. Common LLM API domains include:
   • api.openai.com
   • api.anthropic.com
   • generativelanguage.googleapis.com
   • api.deepseek.com

---

If you still have connection issues after configuring the proxy, see Connection Errors for more detailed troubleshooting steps.