FAQ & troubleshooting
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
General
Section titled “General”Do I need an account?
Section titled “Do I need an account?”No. Oleafly has no accounts and no login. Install it and write. See the Philosophy.
Does it need the internet?
Section titled “Does it need the internet?”Only for explicit actions: fetching a LaTeX package the first time a document uses it, citation lookups and AI research searches, cloud AI providers (local Ollama excepted), GitHub sync, update checks, and on-demand downloads (template packs, fonts, pandoc, TinyTeX). Writing, compiling (after first fetch), spellcheck, grammar, diagrams, and Preflight all run offline. Offline mode (Settings, General) guarantees the compiler never touches the network.
Does Oleafly support Typst or Markdown, or only LaTeX?
Section titled “Does Oleafly support Typst or Markdown, or only LaTeX?”All three are first-class project engines. LaTeX compiles with the bundled Tectonic, Typst with a bundled Typst engine, and Markdown builds to PDF through a managed Pandoc. You pick the engine when you create the project, and the template gallery has starting points for each. Some features are LaTeX-specific (SyncTeX, the TikZ figure tools), and the interface hides what an engine cannot do.
How many templates are there?
Section titled “How many templates are there?”23 bundled, with real page-one previews, plus 99 more across 11 downloadable packs in Settings, Downloads. You can also generate a custom template with AI and keep it in the gallery. See Templates.
Where are my files?
Section titled “Where are my files?”Plain folders under ~/.oleafly/projects/, each with your .tex, .bib, images, and a real .git repo. Back them up, copy them, or open them with other tools freely. See Where your data lives.
Is the PDF output ATS-friendly?
Section titled “Is the PDF output ATS-friendly?”It’s built for it: the Tectonic engine emits real selectable Unicode text with embedded subset fonts, and the ATS-badged resume templates follow single-column, linear-reading-order rules. Then Preflight shows you exactly what a parser extracts from your PDF, so you’re not taking anyone’s word for it. No tool can guarantee how a specific ATS scores you, which is exactly why the extraction preview exists.
How is this different from Overleaf?
Section titled “How is this different from Overleaf?”Short answer: everything runs on your machine, for free, with your files in real Git repos, and editing and cached compilation work offline. Long answer with tables: Why Oleafly.
Which languages does the website support?
Section titled “Which languages does the website support?”oleafly.com is available in 18 locales. English is the default at /. Other languages use a path prefix. The language switcher shows a flag + native name for each option.
| Flag | Code | Language | Example URL |
|---|---|---|---|
| 🇺🇸 | en |
English | https://oleafly.com/ |
| 🇨🇳 | zh-cn |
简体中文 | https://oleafly.com/zh-cn/ |
| 🇹🇼 | zh-tw |
繁體中文 | https://oleafly.com/zh-tw/ |
| 🇯🇵 | ja |
日本語 | https://oleafly.com/ja/ |
| 🇰🇷 | ko |
한국어 | https://oleafly.com/ko/ |
| 🇪🇸 | es |
Español | https://oleafly.com/es/ |
| 🇧🇷 | pt-br |
Português (Brasil) | https://oleafly.com/pt-br/ |
| 🇫🇷 | fr |
Français | https://oleafly.com/fr/ |
| 🇩🇪 | de |
Deutsch | https://oleafly.com/de/ |
| 🇮🇳 | hi |
हिन्दी | https://oleafly.com/hi/ |
| 🇮🇹 | it |
Italiano | https://oleafly.com/it/ |
| 🇳🇱 | nl |
Nederlands | https://oleafly.com/nl/ |
| 🇵🇱 | pl |
Polski | https://oleafly.com/pl/ |
| 🇷🇺 | ru |
Русский | https://oleafly.com/ru/ |
| 🇺🇦 | uk |
Українська | https://oleafly.com/uk/ |
| 🇹🇷 | tr |
Türkçe | https://oleafly.com/tr/ |
| 🇸🇦 | ar |
العربية | https://oleafly.com/ar/ |
| 🇻🇳 | vi |
Tiếng Việt | https://oleafly.com/vi/ |
Language is not forced by your country. The URL always wins. The switcher can save a preference, and the home page may suggest a browser-language match on a first visit. Deep links are never rewritten. See Overview → Website languages.
Can I import an existing paper or resume?
Section titled “Can I import an existing paper or resume?”Three ways:
- PDF: the PDF to LaTeX tool (home screen, Oleafly Tools) reconstructs text-based PDFs into editable LaTeX. It runs locally and heuristically, without OCR, so scanned pages do not convert, and complex layouts, equations, and tables can need manual repair. You see the generated source before a project is created, and an optional AI pass can refine it.
- Word:
.docxfiles convert through the managed Pandoc into a normal project. - A photo or screenshot: a connected vision-capable model can transcribe it into LaTeX for your review.
Can two people edit at the same time?
Section titled “Can two people edit at the same time?”No. There is no real-time collaboration or cloud sync. Collaboration is Git-based. Publish to GitHub, then push and pull. Every project is a normal Git repository, so standard Git workflows work outside the app too.
Install
Section titled “Install”macOS says the app is damaged or can’t be checked
Section titled “macOS says the app is damaged or can’t be checked”Current macOS releases are signed and notarized. If you still see a Gatekeeper warning (older download, or a flipped quarantine bit), right-click the app and choose Open, or clear quarantine once. Commands: install guide.
Windows SmartScreen blocks it
Section titled “Windows SmartScreen blocks it”Click More info, then Run anyway. Some Windows builds still hit SmartScreen until signing is fully rolled out for that channel.
Which Linux distributions work?
Section titled “Which Linux distributions work?”Oleafly needs glibc 2.39 or newer, which includes Ubuntu 24.04+, Fedora 40+, and Debian 13+. AppImage and Debian packages are published for both x64 and ARM64.
Compiling
Section titled “Compiling”My first compile is slow
Section titled “My first compile is slow”With Tectonic, this is usually the first package fetch. It downloads what the document needs and caches it. Later compiles use the cache. See Compiling.
A package is missing and the compile errors out
Section titled “A package is missing and the compile errors out”If Offline mode is on, turn it off for one compile so the package can be fetched and cached, then turn it back on.
The compile succeeded but with warnings. Do I care?
Section titled “The compile succeeded but with warnings. Do I care?”You still got a PDF, as shown by the amber chip. Click Logs to read the warnings. Undefined references and citations are usually the most important, and Preflight locates them.
An error I don’t understand
Section titled “An error I don’t understand”Open Logs for the parsed error list, or just ask the AI: “fix the LaTeX errors” runs a compile-read-fix-verify loop with your approval on every change.
Word/HTML/Markdown export needs pandoc?
Section titled “Word/HTML/Markdown export needs pandoc?”Yes, and Oleafly downloads it for you automatically on first use. No manual install. See Export formats.
AI assistant
Section titled “AI assistant”Which providers work?
Section titled “Which providers work?”Built-in: OpenAI, Anthropic, Google Gemini, Perplexity, Z.AI (GLM), Groq, OpenRouter, DeepSeek, Mistral, xAI, and Ollama for local models. You can also add a custom OpenAI-compatible base URL (LM Studio, self-hosted, and similar). Setup: Set up AI.
The AI says it has no key / errors on send
Section titled “The AI says it has no key / errors on send”Open Settings → AI Assistant → Providers and keys. Confirm a provider has a saved key and a green Connected badge. Pasting a key should validate and refresh that provider’s model list. Error text usually names the problem: invalid key, empty balance, or rate limit.
Can I run it fully offline?
Section titled “Can I run it fully offline?”Yes: install Ollama, ollama pull llama3.2, then Check for Ollama in settings. No cloud key. Custom local OpenAI-compatible endpoints work the same way if they speak the OpenAI API.
Can the AI change my files without asking?
Section titled “Can the AI change my files without asking?”By default, every file-changing tool pauses for your approval with a diff, and the assistant checkpoints the project in Git before its first edit. “Always allow” applies only to writes for the current session and never covers deletes. See Chat & tools.
What can the AI actually do, and what can’t it?
Section titled “What can the AI actually do, and what can’t it?”It is a project-aware agent with 25 tools: read and edit files (approval-gated), compile, read the log, extract PDF text, look at rendered pages with a vision model, search literature through OpenAlex, Crossref, and alphaXiv, and keep a plan checklist and sticky per-project notes. It cannot touch files outside the open project, cannot delete anything without an explicit click, and cannot run shell commands. And it is only as good as the model you connect: research results and generated citations still need your verification.
Can Claude Desktop, Claude Code, or Cursor drive Oleafly?
Section titled “Can Claude Desktop, Claude Code, or Cursor drive Oleafly?”Yes. Oleafly can run a local MCP server on 127.0.0.1. The external client supplies its own model, so Oleafly does not need an AI provider key. Enable it in Settings, MCP. See Connect via MCP for routing and approval behavior when no app window is connected.
GitHub sync
Section titled “GitHub sync”I don’t see a device code when connecting
Section titled “I don’t see a device code when connecting”Try again in a moment, or use the PAT route under “Advanced: use a personal access token” in Settings, Integrations, GitHub.
Push fails with “No remote ‘origin’”
Section titled “Push fails with “No remote ‘origin’””Publish the project first (Source Control, Publish to GitHub). Push and Pull need a remote to exist.
Push says the remote has commits
Section titled “Push says the remote has commits”Pull first, then push. The ahead/behind indicator next to the branch pill warns you before this happens.
Can I sync across two computers?
Section titled “Can I sync across two computers?”Yes: push on one, pull on the other. The workflow is spelled out in GitHub sync.
A pull hit a merge conflict
Section titled “A pull hit a merge conflict”Oleafly shows the raw Git message and leaves resolution to you: fix it with any Git tool (the project is a normal repo), then keep working in the app.
Data & backups
Section titled “Data & backups”How do I back everything up?
Section titled “How do I back everything up?”Add ~/.oleafly/projects/ to your normal backup, export a .zip per project, or push to GitHub. All three, ideally. See Where your data lives.
I deleted a project. Can I get it back?
Section titled “I deleted a project. Can I get it back?”Deleting removes the folder from disk, so: from your backup or from GitHub if you pushed it. Files deleted inside a project can come back via Git history if they were ever committed.
Can I edit project files with another editor?
Section titled “Can I edit project files with another editor?”Yes, they’re plain files. Do it while the project is closed in Oleafly (or reopen it afterward), so the app’s autosave doesn’t overwrite your external changes with what it had in memory.