07 Troubleshooting

---

created: 2026-10-25 last_updated: 2026-10-25 tags:

• assistant-emily
• troubleshooting
• faq
• error-codes type: user-manual order: 7

---

[제7편] 장애 진단 및 문제 해결 가이드 (Troubleshooting & FAQ)

🧭 위키 내비게이션: 🏠 위키 홈 · 제1편: 빠른 시작 · 제2편: 연동 설정 · 제3편: 번역 & 단축키 · 제4편: AI 교열 & 대조 · 제5편: 유튜브 자막 · 제6편: 문법 보호 · 제7편: FAQ & 해결 | FreeLLMAPI 가이드 · 문법 마스킹 가이드

Assistant Emily 사용 중 통신 장애, 설정 오류, 단축키 충돌 등 예상치 못한 문제를 만났을 때 빠르게 원인을 진단하고 해결할 수 있는 공식 문제 해결 가이드입니다.

---

📌 주요 증상별 빠른 해결 매트릭스

발생 증상	주된 원인	가장 빠른 해결책
502 Bad Gateway / 통신 실패	FreeLLMAPI 일시적 네트워크 지연 또는 프록시 점검	설정 탭에서 [연결 테스트] 재확인 및 API 키 점검
413 Payload Too Large / 입력 초과	단일 요청 토큰 컨텍스트 한도 초과	지시창 프롬프트 분량 축소(300자 이내) 및 전체 번역 모드(1,800자 청킹) 활용
** 단축키 Ctrl+Shift+C 가 동작하지 않음**	다른 옵시디언 플러그인 또는 OS 단축키 충돌	옵시디언 설정 > 단축키 에서 다른 키 조합으로 재지정
목차 타임스탬프가 한 줄로 엉김	구버전 설정 또는 서식 손상	v1.1.2 최신 버전 업데이트 및 TOCTIME 불릿 리스트화 확인
번역 중 작업 취소가 안 됨	이전 버전 사용	사이드바 상단 우측의 ❌ 작업 취소 버튼 클릭

---

1. 네트워크 및 AI 연결 오류 해결

1.1 502 Bad Gateway 또는 Connection Refused

• 진단:
  • FreeLLMAPI 서버와의 통신이 일시적으로 지연되거나 네트워크 방화벽에 의해 차단된 경우.
  • FreeLLMAPI 인증 키가 만료되었거나 오탈자가 있는 경우.
• 해결 방법:
  1. 설정 탭에서 [연결 테스트] 버튼을 눌러 엔드포인트 URL(https://api.freellmapi.com/v1)과 발급받은 인증 키를 다시 확인합니다.
  2. 네트워크 환경에서 외부 API 통신이 방화벽이나 사내 보안 프로그램에 의해 차단되어 있지 않은지 점검합니다.

---

2. 토큰 및 컨텍스트 한도 초과 (413 Payload Too Large)

• 진단:
  • 사이드바 지시사항 입력창(customPrompt)에 수천 자 이상의 과도한 텍스트를 기입한 경우.
• 해결 방법:
  1. 지시사항 창에는 "더 정중한 어조로", "기술 용어 원문 병기"와 같이 ** 핵심 작업 지침(300자 내외 권장)** 만 간결하게 입력하십시오.
  2. 본문 텍스트가 매우 긴 경우(수만 자 이상), 범위를 전체 완전 번역(All) 으로 설정하여 실행하면 플러그인이 자동으로 1,800자 스마트 청킹 을 가동하여 순차 분할 번역하므로 한도 초과 없이 안전하게 처리됩니다.

---

3. 단축키 충돌 및 커스텀 재지정 방법

• 진단:
  • 웹 개발자 도구 단축키나 다른 옵시디언 플러그인의 단축키와 Ctrl + Shift + C 가 겹치는 경우.
• 해결 방법:
  1. 옵시디언 좌측 하단 설정 > 단축키 로 이동합니다.
  2. 상단 필터 검색창에 선택 영역 번역 후 바로 아래에 덧붙이기 를 입력합니다.
  3. 해당 커맨드 우측의 단축키 아이콘을 클릭하여 사용자가 원하는 키 조합(예: Alt + T, Ctrl + Alt + T 등)으로 자유롭게 재지정합니다.

---

4. 번역 취소 및 에디터 원상 복구 흐름

• 사용자 시나리오:
  • 긴 텍스트를 실수로 번역 요청했거나, 다른 급한 메모를 작성해야 하는 경우.
• 조치 요령:
  1. 번역이 시작되면 우측 사이드바 상단 우측에 ❌ 작업 취소 버튼이 활성화됩니다.
  2. 취소 버튼을 클릭하면 백그라운드 LLM 호출이 즉시 중단(AbortController.abort())됩니다.
  3. 에디터 본문에 임시로 삽입되었던 > ⏳ [Assistant Emily] 번역 진행 중... 블록이 깨끗이 삭제되어 원문이 100% 무손실 상태로 복구됩니다.
  4. 사이드바 상태 박스는 작업 취소됨 으로 전환되며, ✕ 닫기 버튼으로 정리할 수 있습니다.

---

5. 자주 묻는 질문 (FAQ)

Q1. 정말 100% 무료로 사용할 수 있나요?

네, 완전 무료로 사용하실 수 있습니다.

• Assistant Emily는 FreeLLMAPI 전용으로 설계되었습니다. FreeLLMAPI를 통해 전 세계 34개 AI 기업의 무료 티어(월 74억 토큰, 635개 엔드포인트)를 단 하나의 일원화된 키로 완전 무료 제공하므로, 유료 구독 결제나 고가의 개인 GPU 없이도 즉시 고품질 번역과 교열을 이용하실 수 있습니다.

Q2. 여러 컴퓨터에서 동일한 볼트를 쓰는데 설정이 꼬이지 않나요?

** 전혀 꼬이지 않습니다.**

• Assistant Emily는 기기별 독립 프로필(Device Profile) 시스템을 갖추고 있습니다. 볼트 파일(data.json)이 Obsidian Sync나 클라우드 드라이브로 동기화되더라도 각 머신의 고유 deviceId 에 맞춰 데스크톱 설정과 노트북 설정을 엄격히 분리 관리합니다.

Q3. 번역 후 원문 위키링크([[Note]]) 파일명이 바뀌진 않나요?

절대 바뀌지 않습니다.

• 플러그인의 MarkdownMasker 가 [[Note|별칭]] 형태에서 대상 파일명(Note)을 불변 토큰으로 완전히 잠그고, 오직 사용자에게 표시되는 별칭만 번역하므로 옵시디언 그래프 뷰와 백링크 구조가 100% 무결하게 유지됩니다.

---

💡 추가 문의 및 지원

• 해결되지 않는 문제나 버그가 있다면 GitHub Issues 에 로그와 함께 제보해 주시면 신속하게 개선해 드립니다.

---

🧭 위키 내비게이션

이전 단계	현재 페이지	다음 단계
◀ 제6편: OFM 문법 마스킹 & 보호	제7편: 장애 진단 & FAQ	FreeLLMAPI 아키텍처 가이드 ▶