본문으로 건너뛰기

자주 발생하는 문제

이 페이지는 Elftia 사용 중 가장 자주 발생하는 문제와 그 해결 방법을 모아 놓은 곳입니다. 각 문제에는 증상 설명, 가능한 원인, 구체적인 해결 단계가 포함되어 있습니다.

시작 및 인터페이스 문제​

앱 시작 후 빈 화면 표시​

증상: Elftia를 열었을 때 창에 빈 화면 또는 흰 화면만 표시되고 인터페이스 내용이 없습니다.

가능한 원인:

  • GPU 가속과 그래픽 카드 드라이버 비호환성
  • 프론트엔드 렌더러 프로세스 충돌
  • 설치 파일 손상

해결 단계:

  1. Elftia를 닫고 명령줄에서 --disable-gpu 파라미터를 추가하여 시작해 GPU 문제인지 테스트합니다.
  2. 그래픽 카드 드라이버를 최신 버전으로 업데이트합니다.
  3. 시스템에 남아 있는 Elftia 프로세스가 있는지 확인합니다. 작업 관리자를 사용하여 관련 프로세스를 모두 종료하고 다시 시도합니다.
  4. 문제가 지속되면 Elftia를 재설치해 보세요.

시작 즉시 앱 충돌​

증상: 더블 클릭하여 시작하면 창이 잠깐 깜빡이다가 즉시 닫힙니다.

가능한 원인:

  • 시스템 런타임 종속성 누락 (예: Visual C++ Redistributable)
  • 사용자 데이터 디렉터리 권한 문제
  • 이전 버전의 잔여 데이터로 인한 충돌

해결 단계:

  1. Windows: 최신 버전의 Visual C++ Redistributable을 설치합니다.
  2. 사용자 데이터 디렉터리에 쓰기 권한이 있는지 확인합니다.
  3. 사용자 데이터 디렉터리의 캐시 파일을 삭제하고 재시작해 봅니다 (대화 데이터는 손실되지 않습니다).
  4. 관리자 권한으로 Elftia를 실행합니다.

인터페이스 텍스트 깨짐​

증상: 인터페이스의 텍스트가 사각형 박스나 깨진 문자로 표시됩니다.

가능한 원인:

  • 커스텀 폰트 설정에 시스템에 설치되지 않은 폰트가 지정됨
  • 폰트 파일 손상

해결 단계:

  1. 설정 → 외관을 열고 UI 폰트 및 코드 폰트의 커스텀 입력 필드를 지웁니다.
  2. 설정 페이지에 접근할 수 없는 경우, 사용자 데이터 디렉터리에서 테마 구성 파일을 수동으로 삭제합니다.

LLM 제공자 문제​

제공자 테스트 연결 실패 — 401​

증상: 테스트 연결 시 401 Unauthorized 또는 Invalid API Key가 표시됩니다.

가능한 원인:

  • API Key 잘못 입력 (여분의 공백, 누락된 접두사 등)
  • API Key 만료 또는 취소됨
  • 잘못된 제공자의 API Key 사용

해결 단계:

  1. API Key를 다시 복사하여 여분의 공백이나 줄 바꿈이 없는지 확인합니다.
  2. 제공자의 콘솔에서 Key가 여전히 유효한지 확인합니다.
  3. API Key가 올바른 제공자와 일치하는지 확인합니다.

제공자 테스트 연결 실패 — 403​

증상: 테스트 연결 시 403 Forbidden이 표시됩니다.

가능한 원인:

  • 계정 잔액 부족 또는 결제 수단 미연결
  • API Key의 권한 부족 (예: 읽기 전용 키)
  • IP 주소가 제공자에 의해 차단됨

해결 단계:

  1. 제공자 계정의 잔액 및 결제 상태를 확인합니다.
  2. API Key가 모델 호출 권한을 가지고 있는지 확인합니다.
  3. 프록시를 사용하는 경우 다른 프록시 노드로 전환해 보세요.

제공자 테스트 연결 타임아웃​

증상: 테스트 연결이 오랫동안 응답이 없다가 결국 타임아웃됩니다.

가능한 원인:

  • 네트워크 연결 문제
  • 잘못된 프록시 구성
  • 방화벽이 아웃바운드 요청 차단

해결 단계:

  1. 네트워크 연결이 정상인지 확인합니다.
  2. 프록시를 사용하는 경우 프록시가 실행 중이고 올바르게 구성되어 있는지 확인합니다 (프록시 사용 참조).
  3. 방화벽이 Elftia의 인터넷 접근을 허용하는지 확인합니다.
  4. 브라우저에서 제공자의 API 도메인에 직접 접근해 보세요 (예: api.openai.com). 도메인이 해석되는지 확인합니다.

스트림 응답 중단​

증상: AI 응답이 중간에 멈춰 메시지가 불완전하게 됩니다.

가능한 원인:

  • 불안정한 네트워크 연결로 인한 SSE 스트림 중단
  • 모델의 최대 토큰 한도에 도달
  • 프록시 연결 타임아웃 설정이 너무 짧음

해결 단계:

  1. 응답 재생성을 시도합니다.
  2. 반복적으로 발생하면 네트워크 연결 안정성을 확인합니다.
  3. 프록시(사용 시)의 타임아웃 설정이 최소 120초인지 확인합니다.
  4. 모델 파라미터에서 max_tokens 값을 줄이거나 긴 응답 요청을 분할합니다.

Agent 관련 문제​

Agent 도구 실행 불가​

증상: Agent가 도구(Bash, Write 등)를 사용하려 하지만 권한이 거부됩니다.

가능한 원인:

  • GuardianAgent가 엄격 모드로 설정되어 작업 차단
  • 권한 모드가 "계획만"으로 설정됨
  • 실행 방화벽의 결정론적 규칙에 의해 작업 차단

해결 단계:

  1. 설정 → Clawia → GuardianAgent 모드를 확인하고 필요에 따라 보안 수준을 낮춥니다.
  2. 권한 모드가 "계획만"으로 설정되어 있는지 확인합니다.
  3. 감사 로그를 확인하여 어떤 보안 레이어가 작업을 차단했는지 확인합니다.

Agent 도구 실행 실패 — command not found​

증상: Agent가 Shell 명령을 실행할 때 command not found가 표시됩니다.

가능한 원인:

  • 필요한 CLI (명령줄 인터페이스) 도구가 시스템에 설치되지 않음
  • 환경 변수 PATH에 도구 경로가 포함되지 않음

해결 단계:

  1. 설정 → 일반 → 환경을 열고 도구의 설치 상태를 확인합니다.
  2. 누락된 도구를 설치합니다 (Node.js, Git 등).
  3. 도구가 설치되어 있지만 여전히 찾을 수 없는 경우 Elftia를 재시작하여 환경 변수를 새로 고쳐야 할 수 있습니다.

MCP 관련 문제​

MCP 서버 연결 불가 — stdio 모드​

증상: 추가된 MCP 서버가 stdio (서브프로세스) 모드에서 연결 실패를 표시합니다.

가능한 원인:

  • 명령이 존재하지 않거나 경로가 올바르지 않음
  • 종속성이 설치되지 않음 (예: Node.js 패키지 미설치)
  • 환경 변수 누락

해결 단계:

  1. MCP 서버의 명령이 터미널에서 직접 실행될 수 있는지 확인합니다 (예: npx -y @modelcontextprotocol/server-filesystem /path).
  2. Node.js (node --version) 또는 Python (python --version)이 설치되어 있는지 확인합니다.
  3. MCP 서버에 추가 환경 변수(API Key 등)가 필요한 경우 MCP 구성의 env에 올바르게 설정되어 있는지 확인합니다.
  4. Elftia를 재시작하고 다시 시도합니다.

MCP 서버 연결 불가 — SSE/HTTP 모드​

증상: 원격 MCP 서버 연결이 타임아웃되거나 거부됩니다.

가능한 원인:

  • MCP 서버가 실행되지 않고 있음
  • URL 또는 포트가 올바르지 않음
  • 네트워크/방화벽이 연결 차단

해결 단계:

  1. MCP 서버가 실행 중이고 접근 가능한지 확인합니다.
  2. URL 형식이 올바른지 확인합니다 (http:// 또는 https:// 접두사 포함).
  3. 프록시를 사용하는 경우 프록시 규칙이 MCP 서버 주소 접근을 허용하는지 확인합니다.

채널 관련 문제​

채널 봇 응답 없음​

증상: Discord/Telegram 등의 플랫폼을 통해 메시지를 보냈지만 봇이 응답하지 않습니다.

가능한 원인:

  • 트리거 규칙이 일치하지 않음 (예: @멘션이 필요하지만 @하지 않음)
  • PromptGuardian에 의해 메시지 차단됨
  • 채널이 시작되지 않았거나 Token이 잘못 구성됨
  • 속도 제한 트리거됨

해결 단계:

  1. 메시지가 채널의 트리거 규칙(@멘션, 키워드, 접두사 등)을 충족하는지 확인합니다.
  2. PromptGuardian 모드를 확인하고 일시적으로 "끄기"로 설정하여 주입 감지 오탐인지 테스트합니다.
  3. 채널의 Bot Token이 올바르고 Bot이 온라인인지 확인합니다.
  4. 감사 로그에서 차단된 메시지 기록이 있는지 확인합니다.

미디어 생성 문제​

이미지/비디오/음악 생성 실패​

증상: 미디어 콘텐츠 생성 요청 시 오류가 발생합니다.

가능한 원인:

  • 해당 미디어 생성 제공자가 구성되지 않았거나 잔액 부족
  • 요청 내용이 제공자의 보안 필터에 의해 거부됨
  • 네트워크 연결 문제

해결 단계:

  1. 미디어 생성에 사용되는 제공자가 올바르게 구성되어 있고 잔액이 충분한지 확인합니다.
  2. 생성 프롬프트를 단순화하거나 수정하여 민감한 내용을 피해 보세요.
  3. 네트워크 연결 및 프록시 구성을 확인합니다.

표시 문제​

배경화면 설정 후 텍스트 가독성 저하​

증상: 배경화면을 설정한 후 높은 투명도로 인해 일부 인터페이스 텍스트를 읽기 어렵습니다.

해결 단계:

  1. 마스크 불투명도 값을 높입니다 (70-85 권장).
  2. 블러 강도 값을 높입니다 (8-15 권장).
  3. 특정 영역이 여전히 읽기 어려운 경우 커스텀 CSS를 사용하여 조정합니다.

다크 모드에서 인터페이스 요소가 보이지 않음​

증상: 다크 모드에서 일부 테두리, 구분선 또는 텍스트 색상이 너무 밝아 읽기 어렵습니다.

해결 단계:

  1. 다른 강조 색상으로 전환해 보세요. 일부 색상은 다크 모드에서 대비가 더 좋습니다.
  2. 커스텀 CSS가 색상 표시에 영향을 주는지 확인하고 커스텀 CSS를 지워 보세요.
  3. 모니터 밝기를 높입니다.

성능 문제​

높은 메모리 사용량​

증상: Elftia의 메모리 사용량이 지속적으로 증가합니다.

가능한 원인:

  • 너무 많은 대화 탭이 열려 있음
  • 단일 대화에 많은 수의 메시지가 포함됨 (수백 개 이상)
  • 첨부 파일(특히 이미지)이 너무 많음

해결 단계:

  1. 불필요한 대화 탭을 닫습니다.
  2. 매우 긴 대화의 경우 새 대화를 시작하는 것을 고려합니다.
  3. 설정 → 시스템을 열고 Clear Caches를 실행하여 캐시를 정리합니다.
  4. Elftia를 재시작하여 메모리를 해제합니다.

데이터베이스 관련 오류​

증상: 데이터베이스 작업 오류 또는 데이터 불일치가 발생합니다.

해결 단계:

  1. 설정 → 시스템을 열고 VACUUM을 실행하여 데이터베이스를 최적화합니다.
  2. 문제가 지속되면 추가 조사를 위해 진단 정보(Export Diagnostics)를 내보냅니다.
  3. 극단적인 경우 사용자 데이터 디렉터리의 데이터베이스 파일(.db)을 안전하게 백업하고 교체할 수 있습니다.

업데이트 관련 문제​

업데이트 후 비정상 동작​

증상: 새 버전으로 업데이트한 후 앱이 비정상적으로 동작합니다.

해결 단계:

  1. 설정 → 시스템을 열고 Clear Caches와 VACUUM을 순서대로 실행합니다.
  2. Elftia를 재시작합니다.
  3. 문제가 지속되면 Elftia 업데이트의 롤백 단계를 참조하세요.

위의 해결 방법으로 문제가 해결되지 않는 경우 진단 도구를 사용하여 자세한 정보를 수집하거나, 네트워크 관련 문제의 자세한 해결 방법은 연결 오류를 참조하세요.