프록시 사용

네트워크 환경에서 LLM API나 기타 외부 서비스에 접근하려면 프록시 서버가 필요한 경우, Elftia는 유연한 프록시 구성 옵션을 제공합니다.

프록시 모드

Elftia는 세 가지 프록시 모드를 지원합니다.

모드	동작	사용 사례
시스템 프록시	운영 체제의 프록시 설정을 따름	시스템 수준에서 프록시를 이미 구성한 사용자
사용자 지정 프록시	Elftia에서 지정한 프록시 주소 사용	Elftia에 별도 프록시가 필요한 사용자
프록시 없음	프록시 없이 직접 연결	모든 서비스에 네트워크가 직접 접근 가능

구성 단계

방법 1: 설정 페이지에서 구성

1. 설정 → 일반을 엽니다.
2. 프록시 구성 영역을 찾습니다.
3. 프록시 모드를 선택합니다.

시스템 프록시

"시스템 프록시"를 선택하면 Elftia가 운영 체제의 프록시 설정을 자동으로 감지하고 사용합니다.

• Windows: 인터넷 옵션의 프록시 설정을 읽습니다.
• 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가 모든 프록시 설정을 건너뛰고 대상 서버에 직접 연결합니다.

방법 2: 환경 변수로 구성

시스템 환경 변수를 통해서도 프록시를 구성할 수 있으며, 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 공급자(OpenAI, Anthropic, Gemini 등)에 대한 API 요청
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. 일부 프록시 클라이언트는 기본적으로 0.0.0.0이 아니라 127.0.0.1에서만 수신합니다.

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

---

프록시를 구성한 뒤에도 연결 문제가 계속되면 연결 오류를 참고해 더 자세한 문제 해결 단계를 확인하세요.