본문으로 건너뛰기

문제 해결

일반적인 문제와 해결 방법입니다.

공급자(Provider) 문제​

"Error: 401 Unauthorized"​

  • 원인: API 키가 유효하지 않습니다.
  • 해결 방법: Settings > Providers로 이동합니다. API 키를 다시 입력합니다. 앞뒤에 불필요한 공백이나 줄바꿈이 없는지 확인합니다.

"Error: 403 Forbidden"​

  • 원인: 사용 중인 API 키가 요청한 모델에 대한 액세스 권한이 없습니다.
  • 해결 방법:
    • OpenAI의 경우: 일부 모델은 유료 등급이 필요합니다. platform.openai.com에서 액세스 권한을 확인하세요.
    • Anthropic의 경우: 요청 중인 Claude 모델에 대한 액세스 권한이 계정에 있는지 확인하세요.

"Error: 429 Too Many Requests"​

  • 원인: 요청 빈도 제한(rate limit)에 도달했거나 credit이 모두 소진되었습니다.
  • 해결 방법:
    • 몇 분 기다린 후 다시 시도합니다(요청 빈도 제한인 경우).
    • 결제 상태를 확인하고 공급자 웹사이트에서 credit을 추가합니다.
    • 일시적으로 다른 공급자로 전환하는 것을 고려합니다.

"Error: 500 Internal Server Error"​

  • 원인: 공급자 서버에 문제가 발생했습니다.
  • 해결 방법: 몇 분 기다린 후 다시 시도합니다. 공급자의 상태 페이지(status page)를 확인합니다.

"Connection Refused" (Ollama)​

  • 원인: Rephlo가 로컬 AI 서버와 통신할 수 없습니다.
  • 해결 방법:
    1. 터미널을 열고 ollama serve를 실행합니다.
    2. 실행 중인지 확인합니다: 브라우저에서 http://localhost:11434에 접속합니다.
    3. 다른 애플리케이션이 11434 포트를 사용하고 있는지 확인합니다.

"Model Not Found" (Ollama)​

  • 원인: 요청한 모델이 다운로드되어 있지 않습니다.
  • 해결 방법: 터미널에서 ollama pull [model-name]을 실행합니다(예: ollama pull llama3).

UI 문제​

"Hotkeys are not working"​

  • 원인 (Windows/Linux): 다른 애플리케이션(예: PowerToys 또는 게임)이 단축키를 가로챘을 수 있습니다.
  • 해결 방법: Settings > Hotkeys로 이동하여 트리거를 다른 조합으로 변경합니다(예: Ctrl + Shift + Alt + Z).

macOS 사용자: macOS에서의 단축키 문제 해결 방법은 아래 macOS 관련 문제를 참고하세요.

"Tray Icon is Missing"​

  • 원인: Windows가 이를 "overflow" 메뉴에 숨겼을 수 있습니다.
  • 해결 방법: 시계 옆의 ^ 화살표를 클릭합니다. Rephlo 아이콘을 메인 작업 표시줄 영역으로 드래그합니다.

기능 문제​

"Vision/Screenshot not working"​

  • 원인 (Windows): Windows 개인정보 설정에서 화면 녹화 권한이 거부되었을 수 있습니다.
  • 해결 방법 (Windows): Rephlo를 관리자 권한으로 실행하거나 Windows Privacy settings > Camera / Screen capture를 확인합니다.
  • 원인 (macOS): Rephlo는 Screen Recording 권한이 필요합니다.
  • 해결 방법 (macOS): 자세한 단계는 아래 macOS 관련 문제를 참고하세요.

"Space is not answering questions"​

  • 원인: Space가 비어 있거나 데이터 수집(ingestion)이 실패했을 수 있습니다.
  • 해결 방법: Space 세부 정보를 확인합니다. 파일이 목록에 표시되고 상태가 "Ready"인지 확인합니다. Advanced Settings에서 캐시 지우기를 시도합니다.

"Variable not found in Space"​

  • 원인: {{filename}} 변수를 사용하고 있지만 해당 파일이 활성 Space에 없습니다.
  • 해결 방법:
    1. Space에 참조된 파일이 포함되어 있는지 확인합니다.
    2. 변수 이름이 파일 이름과 일치하는지 확인합니다(snake_case로 변환됨, 예: "Style Guide.pdf" -> {{style_guide_pdf}}).
    3. 올바른 Space가 활성화되어 있는지 확인합니다.

macOS 관련 문제​

"Hotkeys are not working" (macOS)​

  • 원인: Rephlo가 전역 키보드 단축키를 감지하려면 Accessibility 권한이 필요합니다.
  • 해결 방법:
    1. System Settings > Privacy & Security > Accessibility를 엽니다.
    2. 목록에서 Rephlo를 찾아 ON으로 전환합니다.
    3. 목록에 Rephlo가 없다면 앱을 종료했다가 다시 실행합니다.
    4. 권한을 부여한 후 Rephlo를 재시작합니다.

중요: 전역 단축키는 서명된(signed) .app 번들로 Rephlo를 실행할 때만 작동합니다. 터미널에서 dotnet run으로 실행하는 개발자라면 단축키가 작동하지 않을 수 있습니다. .app 번들을 빌드하고 실행하는 방법은 macOS 설정 튜토리얼을 참고하세요.

"Screenshot / Vision not working" (macOS)​

  • 원인: Rephlo가 화면 콘텐츠를 캡처하려면 Screen Recording 권한이 필요합니다.
  • 해결 방법:
    1. System Settings > Privacy & Security > Screen Recording을 엽니다.
    2. 목록에서 Rephlo를 찾아 ON으로 전환합니다.
    3. Rephlo를 재시작합니다.

"Permission dialog keeps appearing"​

  • 원인: Rephlo가 안정적인 코드 서명(code signature) 없이 실행되고 있었습니다. 다시 빌드할 때마다 바이너리 해시가 변경되어 macOS가 이를 새로운 앱으로 취급하고 권한을 초기화합니다.
  • 해결 방법: 공식 배포처에서 제공하는 서명된 릴리스 빌드의 Rephlo를 사용하세요. 서명된 앱에 권한을 한 번 부여하면 업데이트를 거쳐도 권한이 유지됩니다.

"Overlay doesn't appear even after granting permissions"​

  • 해결 방법:
    1. Rephlo를 완전히 종료합니다(트레이 아이콘 우클릭 > Exit).
    2. .app 번들에서 다시 실행합니다.
    3. Accessibility와 Screen Recording 권한이 모두 부여되어 있는지 확인합니다.
    4. Settings > Hotkeys에서 Test Overlay 버튼을 사용해 보세요.

성능 문제​

"Responses are very slow"​

  • 원인: 다양한 요인이 응답 속도를 저하시킬 수 있습니다.
  • 해결 방법:
    • Space 컨텍스트가 큰 경우: Space를 압축(compact)하는 것을 고려합니다.
    • 공급자 응답이 느린 경우: GPT-5.4 Mini나 Gemini 3.5 Flash 같은 더 빠른 모델로 전환하면 응답 속도가 빨라집니다.
    • 로컬 모델(Ollama)의 경우: GPU가 사용되고 있는지 확인합니다. Ollama 로그를 확인합니다.

"App feels sluggish on startup"​

  • 원인: 대용량 Space나 많은 수의 명령을 로드하는 경우입니다.
  • 해결 방법: 사용하지 않는 명령을 보관(archive)합니다. 더 이상 필요하지 않은 오래된 Space를 삭제합니다.

Chat 문제​

"Chat history is missing"​

  • 원인: 대화 내용은 로컬에 저장되며, 삭제되었을 수 있습니다.
  • 해결 방법: Settings > Privacy에서 기록 보존 설정을 확인합니다. "Immediate"로 설정되어 있으면 기록이 보존되지 않습니다.

"Chat keeps forgetting context"​

  • 원인: 공급자의 컨텍스트 윈도우(context window)를 초과했습니다.
  • 해결 방법: 새 대화를 시작하거나 컨텍스트 윈도우가 더 큰 공급자를 사용합니다. 구체적인 컨텍스트 윈도우 크기는 해당 공급자의 문서를 확인하세요.

변수 및 Template 문제​

"Variable not found" or "Invalid variable"​

  • 원인: 변수 이름이 유효한 시스템 변수나 Space 내 파일과 일치하지 않습니다.
  • 해결 방법:
    • 정확한 구문을 사용합니다: {{input_content}}, {{space_data_all}}, 또는 {{filename}}.
    • 파일 변수의 경우: 파일 이름을 snake_case로 변환합니다(예: "Style Guide.pdf" -> {{style_guide_pdf}}).
    • 활성 Space에 해당 파일이 존재하는지 확인합니다.
    • 오타가 없는지 확인하세요—변수 이름은 대소문자를 구분하지 않지만 철자는 정확해야 합니다.

"Space variables ignored in Standalone mode"​

  • 원인: Standalone 명령은 Space 데이터를 자동으로 삽입하지 않습니다.
  • 설명: Standalone 모드는 완전한 수동 제어를 제공합니다. {{space_data_all}} 같은 변수는 자동으로 치환되지 않습니다.
  • 해결 방법: Space 데이터를 자동으로 삽입하려면 Combination 모드로 전환하거나, Space 데이터를 직접 프롬프트에 붙여넣으세요.

Space 문제​

"Space full" or "Token budget exceeded"​

  • 원인: Space가 설정된 토큰 한도를 초과했습니다.
  • 해결 방법:
    1. Space의 데이터 보기를 열어 현재 사용량을 확인합니다.
    2. Space에서 덜 중요한 파일을 제거하거나 토큰 예산을 늘립니다(최대 1,000,000 토큰) — 이 두 가지는 저장된 예산을 초과한 Space를 직접 줄여줍니다.
    3. 전체 텍스트 대신 AI 요약을 저장하도록 데이터 모드를 🗜️ Compact로 전환합니다 — 이는 Space에 집계되는 토큰 수를 낮춥니다(credit 비용을 확인하세요). 그런 다음 압축 수준을 선택합니다:
      • Conservative: 최소한의 요약(세부 정보 보존).
      • Balanced: 적당한 요약(기본값, 권장).
      • Aggressive: 강도 높은 요약(매우 큰 Space에 적합).
      • 참고: 매우 큰 Space(약 128,000 토큰 이상)의 경우 Compact는 설계상 비활성화됩니다 — 대신 파일을 제거하거나 예산을 늘리세요.
    4. 참고: 🔍 Smart Search는 관련 있는 구절만 전송하여 각 요청을 작게 유지하지만, Space의 예산에는 원본 전체 텍스트가 그대로 집계됩니다 — 따라서 이는 요청당 비용을 제어할 뿐, 저장 한도를 초과한 Space 자체를 해결하지는 않습니다.

"Space ingestion failed" (PDF/document error)​

  • 원인: 파일을 처리할 수 없습니다—손상되었거나, 비밀번호로 보호되어 있거나, 지원되지 않는 형식일 수 있습니다.
  • 해결 방법:
    • PDF가 비밀번호로 보호되어 있지 않은지 확인합니다.
    • 원본 애플리케이션에서 문서를 다시 내보내 보세요.
    • 스캔한 PDF의 경우: Rephlo는 텍스트만 추출합니다—PDF 내부의 이미지는 읽지 않습니다.
    • 다른 애플리케이션에서 먼저 열어보아 파일이 손상되지 않았는지 확인합니다.

이미지 생성 문제​

"This prompt was blocked by our content policy"​

  • 원인: 이미지 프롬프트가 콘텐츠 모더레이션에 의해 플래그되어 생성이 실행되기 전에 거부되었습니다.
  • 해결 방법: 허용되지 않는 내용을 제거하도록 프롬프트를 다시 작성한 후 다시 시도하세요. 허용되지 않는 내용에 대해서는 콘텐츠 정책 페이지를 참고하세요.

"Content moderation is temporarily unavailable"​

  • 원인: 콘텐츠 모더레이션 서비스가 일시적으로 중단되어(일시적인 장애) 프롬프트를 확인할 수 없었습니다.
  • 해결 방법: 잠시 후 다시 시도하세요.

도움 받기​

유해하거나 부적절한 AI 출력은 어떻게 신고하나요?​

  • 해결 방법:
    • 로그인한 경우: 사이드바 하단의 아바타를 클릭 > Help > Report inappropriate content.
    • 언제든지: Settings > About > Contact & Support > Report inappropriate content를 엽니다.
    • 이렇게 하면 신고 카테고리가 미리 선택된 상태로 브라우저에서 rephlo.app/contact가 열립니다.