# FAQ 및 문제 해결

시작하기, 프로젝트, 컴파일, 어시스턴트, 백업에 대한 빠른 답변입니다.

## 시작하기

### 계정이 필요한가요?

아니요. Oleafly를 내려받아 열고 바로 쓰시면 됩니다. 클라우드 AI 제공자, GitHub, Dropbox 같은 선택 서비스는 각자의 계정을 사용합니다.

### Oleafly는 LaTeX, Typst, Markdown을 지원하나요?

네. 프로젝트를 만들 때 엔진을 고르세요. 엔진마다 편집과 내보내기 기능이 다릅니다. [빠른 시작](/docs/getting-started/)에서 첫 PDF를 만드는 과정을 안내합니다.

### 이미 있는 논문이나 이력서를 가져올 수 있나요?

네. 프로젝트 소스, ZIP 아카이브, Git 저장소를 가져올 수 있습니다. DOCX와 텍스트 기반 PDF를 위한 변환 경로도 있습니다. [기존 프로젝트 가져오기](/docs/import-project/)에서 알맞은 방법을 고르세요.

### 오프라인에서 작업할 수 있나요?

클라우드에 연결하지 않아도 글을 쓰고, 파일을 정리하고, 로컬 교정을 쓰고, 내려받은 로컬 AI 모델을 실행할 수 있습니다. Tectonic은 캐시된 패키지로 컴파일할 수 있습니다. 새 패키지, 원격 참고 자료, 클라우드 모델, GitHub, 다운로드에는 연결이 필요합니다. 오프라인으로 가져가기 전에 컴파일에 한 번 성공해서 프로젝트를 준비해 두세요.

### 내 파일은 어디에 있나요?

프로젝트는 로컬 라이브러리에 있는 일반 폴더입니다. 복사하거나 백업하거나 다른 도구에서 열 수 있습니다. [데이터가 저장되는 위치](/docs/where-your-data-lives/)에서 프로젝트 파일, 앱 설정, 체크포인트를 설명합니다.

### 학위논문이나 이력서에도 Oleafly를 쓸 수 있나요?

네. [학위논문 작업 흐름](/docs/workflows/thesis/)이나 [이력서 작업 흐름](/docs/workflows/resume/)으로 시작하세요. 둘 다 연구 논문과 같은 편집기, 미리보기, 참고문헌, 내보내기 도구를 씁니다.

## 설치

### 운영체제가 설치 프로그램을 차단합니다

파일이 [공식 릴리스](https://github.com/Oleafly/Oleafly/releases/latest)에서 받은 것이고 사용 중인 플랫폼에 맞는지 확인하세요. 플랫폼별 첫 실행 단계는 [설치 가이드](/docs/install/#first-launch)를 따르세요.

### 어떤 Linux 패키지를 써야 하나요?

컴퓨터에 맞는 아키텍처를 고르고, AppImage, Debian 패키지, RPM 중 하나를 선택하세요. 시스템 요구 사항은 [Linux 설치](/docs/install/#linux)를 참고하세요.

## 컴파일

### 첫 컴파일이 느립니다

Tectonic이 이 문서에서 쓰는 패키지를 내려받아야 할 수 있으며, 한 컴퓨터에서 처음 컴파일할 때는 자주 쓰는 패키지도 한꺼번에 가져옵니다. 내려받은 패키지는 이후 빌드를 위해 캐시됩니다. 패키지를 아직 내려받는 동안에는 컴파일이 보통의 5분 제한을 넘겨 실행될 수 있습니다. [로그](/docs/compiling/#reading-the-logs)를 열어 진행 상황을 확인하세요.

### 패키지가 없다고 나옵니다

오프라인 모드가 켜져 있다면 메시지에서 **끄고 컴파일**을 선택하거나, 한 번만 끄고 컴파일해서 패키지를 가져오세요. 시스템 TeX 툴체인에서는 오류의 **찾아서 설치**를 사용하세요. Debian, Ubuntu, Fedora의 TeX Live는 `apt`나 `dnf`로 패키지를 받습니다. [LaTeX 엔진과 패키지](/docs/latex-engines/#recover-from-a-missing-file)를 참고하세요.

### pdfLaTeX를 골랐더니 Oleafly가 TeX 배포판을 요구합니다

pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX, pLaTeX는 컴퓨터에 설치된 TeX 배포판에서 실행됩니다. 배포판이 없을 때 이 중 하나를 고르면 아무것도 컴파일하기 전에 대화 상자가 열립니다. **TinyTeX 내려받아 사용**을 선택해 설치하거나, **Tectonic으로 되돌리기**를 선택해 내장 엔진으로 돌아가세요. 컴파일이 실패한 뒤에는 미리보기가 같은 선택을 **TinyTeX 내려받아 사용**과 **Tectonic 사용**으로 제안합니다. [TeX가 설치되어 있지 않을 때](/docs/latex-engines/#when-no-tex-is-installed)를 참고하세요.

### MiKTeX가 latexmk에 Perl이 필요하다고 합니다

MiKTeX의 `latexmk`는 Perl로 실행되는데 MiKTeX에는 Perl이 들어 있지 않습니다. Strawberry Perl을 설치하거나, **설정 → 엔진 → LaTeX**에서 자체 Perl이 딸린 TinyTeX를 설치하세요. 그러면 MiKTeX 대신 TinyTeX가 컴파일을 맡습니다. [MiKTeX와 Perl](/docs/latex-engines/#miktex-and-perl)을 참고하세요.

### PDF에서 글자가 빠집니다

글꼴에 해당 문자의 글리프가 없는 경우입니다. 한국어, 중국어, 일본어 텍스트에서 가장 흔하며, TeX는 컴파일을 실패시키지 않고 그 문자를 건너뜁니다. Oleafly가 경고하고 로그에 목록을 보여 줍니다. LaTeX에서는 경고가 알려 주는 문자 체계별 설정을 붙여 넣으세요. Typst에서는 알림이 제안하는 글꼴 팩을 내려받거나, 그 문자를 가진 글꼴을 프로젝트의 `fonts` 폴더에 추가하세요. Markdown에서는 YAML 머리말의 `mainfont`나 `CJKmainfont`를 그 문자를 가진 글꼴로 지정하세요. [PDF에서 빠진 문자](/docs/latex-engines/#characters-missing-from-the-pdf)와 [상자로 표시되는 문자](/docs/typst/#characters-that-show-as-boxes)를 참고하세요.

### 컴파일이 너무 오래 걸려서 Oleafly가 중단했습니다

컴파일은 5분 동안 실행될 수 있습니다. 패키지를 아직 내려받는 중이면 제한이 최대 30분까지 늘어납니다. Markdown에서 PDF로의 변환은 15분, Quarto와 Calepin은 1시간입니다. 다시 컴파일하세요. 다운로드는 멈춘 지점부터 이어집니다. Tectonic에서 긴 초안을 컴파일한다면 컴파일 메뉴에서 **컴파일 모드**를 **빠르게**로 설정하세요.

### 새 프로젝트에서 내 TeX 설치를 쓸 수 있나요?

네. **설정 → 엔진 → LaTeX**을 열고 **기본 컴파일 엔진**을 **latexmk(시스템 TeX)** 항목으로 설정하세요. 그러면 새로 만들거나 가져오거나 변환한 LaTeX 프로젝트가 이 엔진으로 시작합니다. [새 프로젝트의 기본값 설정](/docs/engines/#set-a-default-for-new-projects)을 참고하세요.

### 문서에서 minted나 PythonTeX를 씁니다

이 패키지들은 문서를 컴파일하는 동안 다른 프로그램을 실행하는데, Oleafly는 기본적으로 이를 차단합니다. 시스템 LaTeX가 필요합니다. 프로젝트의 모든 파일을 신뢰한다면 편집기 위쪽 배너에서 **외부 명령 허용**을 선택하세요. [외부 명령 허용](/docs/latex-engines/#allow-external-commands)을 참고하세요.

### 컴파일은 끝났지만 경고가 있습니다

**로그**를 열어 정의되지 않은 인용과 참조부터 확인하세요. [프리플라이트](/docs/preflight/)를 쓰면 내보내기 전에 해당 소스 위치를 찾기 쉽습니다.

### 빌드 오류를 이해하지 못하겠습니다

어시스턴트에게 로그를 읽고, 오류를 고치고, 다시 컴파일해 달라고 요청하세요. 진행하는 동안 제안된 작업을 직접 검토하고 싶다면 **승인 요청**을 사용하세요. [Discord](/discord)의 도움말 포럼에 로그를 올려도 됩니다.

### 내보내기 형식이 왜 없나요?

사용할 수 있는 형식은 엔진과 문서 유형에 따라 다릅니다. [내보내기 표](/docs/export/#editable-formats)를 확인하세요.

## AI 어시스턴트

### 어떤 어시스턴트를 쓸 수 있나요?

모델 제공자를 연결하거나, 로컬 모델을 쓰거나, [CLI 에이전트](/docs/cli-agents/)를 선택하세요. 각 방법은 [AI 설정하기](/docs/ai-setup/)에서 다룹니다.

### 편집기를 쓰려면 AI가 필요한가요?

아니요. 글쓰기, 컴파일, 인용, 미리보기, 다이어그램, 프로젝트 기록, 내보내기는 어시스턴트 없이 쓸 수 있습니다.

### 어시스턴트는 무엇을 할 수 있나요?

프로젝트 파일을 다루고, 자료를 찾아보고, PDF를 살펴보고, 그림을 만들고, 도구를 실행하고, 빌드 복구를 도울 수 있습니다. 작업에 맞는 계획과 승인 정책을 고르세요. [어시스턴트와 함께 작업하기](/docs/ai-chat/)를 참고하세요.

### 모델 옆의 "검증됨"은 무슨 뜻인가요?

해당 모델이 도구 호출 검사를 통과했다는 뜻입니다. 프로젝트 작업에 쓸 모델을 고르는 데 도움이 되지만, 그 모델이 쓰는 글이나 연구의 품질을 평가하지는 않습니다. [AI 설정하기](/docs/ai-setup/)를 참고하세요.

### 사용량이 왜 "알 수 없음"으로 표시되나요?

일부 제공자와 CLI 에이전트는 사용량을 보고하지 않습니다. 알 수 없음은 값을 구할 수 없다는 뜻입니다. [AI 사용량과 예산](/docs/ai-usage/)을 읽어 보세요.

### 외부 어시스턴트를 연결할 수 있나요?

네. 내장된 [CLI 에이전트 연결](/docs/cli-agents/)을 쓰거나, Oleafly의 로컬 [MCP 서버](/docs/mcp/)를 켜거나, 앱이 닫혀 있어도 작동하는 [`oleafly` 명령](/docs/cli/)에 에이전트를 연결하세요.

## 기록과 공동 작업

### 이전 버전을 복구하려면 어떻게 하나요?

[체크포인트](/docs/checkpoints/)를 열어 성공한 빌드의 소스를 비교하고 버전을 복원하세요. 직접 관리하는 Git 커밋에는 [소스 관리](/docs/git-history/)를 사용하세요.

### 공저자와 함께 작업할 수 있나요?

네. [실시간 공동 작업](/docs/collaboration/)을 쓰면 여러분과 공저자가 그룹에서 운영하는 공동 작업 서버를 통해 같은 프로젝트를 동시에 편집합니다. 각자 자기 컴퓨터에 프로젝트를 파일로 보관합니다. 소스 아카이브를 공유하거나 [GitHub 동기화](/docs/github-sync/)로 커밋을 주고받을 수도 있습니다.

### 컴퓨터 두 대에서 내 프로젝트를 쓸 수 있나요?

네. [클라우드 동기화](/docs/cloud-sync/)는 라이브러리 프로젝트와 설정을 여러분의 Dropbox에 보관하고, 연결한 각 컴퓨터가 이를 내려받을 수 있습니다. 연결하려면 **설정 → 데이터 저장 → 클라우드 동기화**를 여세요. [GitHub 동기화](/docs/github-sync/)로 컴퓨터 사이에 프로젝트를 옮길 수도 있습니다.

### 소스를 내보내면 모든 것이 백업되나요?

프로젝트 소스는 백업됩니다. 자동 체크포인트, 앱 환경설정, 자격 증명은 따로 저장됩니다. 필요한 항목이 포함되도록 [백업 가이드](/docs/where-your-data-lives/#back-up-your-work)를 따르세요.

## 문제 신고

**설정 → 도움말 및 정보 → 정보 복사**를 열어 그 내용을 짧은 설명, 문제를 재현하는 단계, 관련 로그와 함께 보내 주세요. [Issues](https://github.com/Oleafly/Oleafly/issues)에 신고하시고, 질문이나 작업 흐름 도움은 [Discord 커뮤니티](/discord)를 이용하세요.
