본문으로 건너뛰기

연결 오류

이 페이지는 Elftia에서 발생하는 다양한 네트워크 연결 문제 해결에 중점을 둡니다. LLM API 호출 오류, 프록시 관련 오류, SSL/TLS 문제, MCP 연결 실패, Channel 연결 이상을 다룹니다.

LLM API HTTP 상태 코드​

LLM API 호출이 오류를 반환할 때, HTTP 상태 코드가 가장 중요한 문제 해결 단서입니다. 각 상태 코드의 의미와 해결 방법은 다음과 같습니다:

401 Unauthorized​

의미: API Key가 유효하지 않거나 제공되지 않았습니다.

일반적인 원인:

  • API Key에 여분의 공백이나 줄바꿈이 포함됨
  • API Key가 취소되었거나 만료됨
  • API Key 형식이 잘못됨 (예: OpenAI 키는 sk-로 시작해야 함)
  • 잘못된 공급자의 키를 사용함

해결 단계:

  1. 설정 → 공급자 설정으로 이동하여 API Key를 다시 확인합니다.
  2. 전체 키를 복사하여 입력 상자의 기존 값을 교체합니다.
  3. 공급자 콘솔에서 키가 여전히 유효한지 확인합니다.
  4. API Key 풀을 사용하는 경우, 풀 내에 유효하지 않은 키가 있는지 확인합니다 (비활성화된 키는 회색으로 표시됨).
정보

풀 내의 API Key가 401을 반환하면 해당 키는 자동으로 비활성화되며, 시스템은 풀 내의 다른 사용 가능한 키로 자동 전환합니다.

403 Forbidden​

의미: 인증은 성공했지만 권한이 부족합니다.

일반적인 원인:

  • 계정 잔액 부족 또는 결제 수단 미연결
  • API Key가 요청한 모델에 대한 액세스 권한이 없음
  • IP 주소 또는 지역이 공급자에 의해 제한됨
  • 조직/프로젝트 권한 제한

해결 단계:

  1. 공급자 콘솔에 로그인하여 계정 잔액과 결제 상태를 확인합니다.
  2. API Key가 선택한 모델에 대한 액세스 권한이 있는지 확인합니다 (일부 고급 모델은 특별 권한 필요).
  3. 프록시를 사용하는 경우, 다른 지역의 프록시 노드로 전환해 봅니다.
  4. 공급자 콘솔에서 조직 및 프로젝트 설정을 확인합니다.

429 Too Many Requests​

의미: 요청 빈도가 너무 높아 속도 제한이 발동되었습니다.

일반적인 원인:

  • 짧은 시간 내에 너무 많은 요청을 전송함
  • 계정의 속도 할당량이 낮음 (무료 또는 저등급 계정)
  • 여러 애플리케이션이 동일한 API Key를 공유함

해결 단계:

  1. 잠시 기다렸다가 재시도합니다. Elftia는 쿨다운 알림을 표시합니다.
  2. 자주 발생한다면 공급자 계정의 등급을 업그레이드하는 것을 고려합니다.
  3. 여러 키를 사용하여 요청을 분산하는 API Key 풀을 구성합니다.

Elftia의 자동 처리:

  • 429를 만나면 현재 키는 쿨다운 기간에 진입합니다 (60초부터 시작하여 지수 백오프로 최대 15분).
  • API 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 풀이 구성된 경우, 시스템은 자동으로 키를 전환하여 재시도합니다.
  3. 서버 부하를 줄이기 위해 더 작은 모델을 사용해 봅니다 (예: Claude Opus 대신 Claude Haiku).

Elftia의 자동 처리: 429와 동일하게 쿨다운 및 자동 키 전환 메커니즘이 발동됩니다.

프록시 관련 오류​

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​

의미: 서버 인증서를 확인할 수 없습니다. 일반적으로 자체 서명된 인증서인 경우입니다.

일반적인 시나리오:

  • 기업 프록시가 HTTPS 검사를 위해 자체 서명 CA 인증서를 사용함
  • 자체 구축한 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. 도구가 설치되어 있지만 여전히 오류가 발생하면, PATH 환경 변수를 새로 고침하기 위해 Elftia를 재시작해야 할 수 있습니다.

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 풀 자동 전환​

단일 키가 429/529 오류를 만날 때:

  1. 현재 키가 쿨다운 기간에 진입합니다.
  2. 시스템은 즉시 풀에서 다음 사용 가능한 키를 시도합니다.
  3. 요청이 성공하면 사용자는 거의 인지하지 못합니다.
  4. 쿨다운은 지수 백오프를 사용합니다: 60초 → 120초 → 240초 → ... → 최대 15분.
  5. 쿨다운이 끝나면 키가 자동으로 복구됩니다.

세션 선호도​

LLM 공급자의 프롬프트 캐시 효율성을 유지하기 위해, 동일한 채팅 세션은 동일한 API Key를 사용하려고 시도합니다:

  • 첫 번째 요청은 가중치 라운드로빈으로 키를 선택합니다.
  • 이후 요청은 동일한 키를 우선적으로 사용합니다.
  • 바인딩된 키를 사용할 수 없는 경우(쿨다운 중이거나 비활성화됨)에만 전환합니다.

영구 실패 처리​

키가 401/403을 반환하면 해당 키는 영구적으로 무효입니다:

  • 해당 키는 자동으로 비활성화됩니다 (사용 불가로 표시).
  • 시스템이 다른 키로 전환합니다.
  • 공급자 설정의 API 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. DNS 확인: ping api.openai.com (또는 해당 공급자 도메인)을 실행하여 도메인 확인을 확인합니다.
  3. 포트 연결: curl -I https://api.openai.com을 실행하여 포트 443이 액세스 가능한지 확인합니다.
  4. 프록시 테스트: 프록시를 사용하는 경우, 터미널에서 프록시 환경 변수를 설정하고 위 명령을 재시도합니다.
  5. Elftia 테스트: Elftia의 공급자 설정에서 "연결 테스트"를 사용합니다.

1-4단계가 성공하지만 5단계가 실패하면, Elftia의 프록시 설정 문제일 수 있습니다; 프록시 사용을 참조하여 재설정합니다.

이 페이지가 경험하고 있는 연결 문제를 다루지 않는 경우, 진단 도구를 사용하여 진단 정보를 내보내고 커뮤니티에서 도움을 구하세요.