Espanso가 동작하지 않을 때 | 흔한 해결 방법 9가지 (2026)
Espanso은 강력한 오픈 소스 텍스트 확장기이지만 YAML 기반 구성으로 인해 명확하지 않은 방식으로 문제가 발생할 수 있습니다. Espanso 작동이 중지되는 가장 일반적인 이유와 각 문제를 해결하는 방법은 다음과 같습니다. 공식 CLI 및 경로는 Espanso 문서를 참조하세요.
고지: 저희는 유료 텍스트 확장기인 Lightning Assist를 만들고 있으며, 따라서 Espanso는 경쟁 제품입니다. Espanso는 무료 오픈소스이고, 아래의 모든 해결책은 Espanso 자체를 위한 것입니다. 다른 도구로 옮길 필요는 없습니다.
기본적으로 스니펫은 입력 중에 확장됩니다 — 단축키 불필요: Lightning Assist는 As-You-Type Mode가 활성화된 상태로 제공됩니다. 스니펫의 트리거 — 저장한 그대로의 텍스트, 예:
;meeting또는meeting— 를 입력하면 입력을 마치는 순간 인라인으로 확장됩니다. 맨 앞의;는 선택 사항이며 트리거를 일반 단어와 구분해 줍니다. 의도적인 트리거를 선호한다면? 언제든지 Hotkey Mode(선택 사항)로 전환할 수 있습니다. 모든 활성화 모드 보기 →
2026년 9월 7일 업데이트: Espanso 2.4.1과 Ubuntu 26.04에 맞춰 #9번 문제 해결법을 다시 작성했습니다. Ubuntu 26.04는 더 이상 X11 세션을 제공하지 않습니다.
1. Espanso이(가) 실행되고 있지 않습니다.
가장 일반적인 원인: Espanso 서비스가 시작되지 않았습니다.
수정:
espanso start
실행 중인지 확인하세요.
espanso status
systemd를 사용하는 Linux에서:
systemctl --user status espanso
systemctl --user start espanso
2. YAML 구성의 구문 오류
구성 파일에 잘못된 YAML이 있으면 Espanso이 자동으로 실패합니다. 잘못 배치된 탭이나 콜론 하나가 전체 파일을 손상시킵니다.
수정: 구성 의사를 실행합니다.
espanso doctor
확인해야 할 일반적인 실수:
- 공백 대신 탭 사용(YAML에는 공백이 필요함)
:,#또는\와 같은 특수 문자가 포함된 텍스트 주위에 따옴표가 누락되었습니다.- 한칸씩 벗어난 들여쓰기
{로 시작하는replace:값 — 따옴표로 묶어야 합니다:replace: "{{clipb}}"
자동 YAML 실패가 팀에서 반복되는 문제인 경우 GUI 기반 스니펫 편집기는 문제를 완전히 회피합니다. 들여쓰기를 눈으로 확인하는 대신 양식의 필드를 편집합니다.
3. Espanso 특정 애플리케이션에서 작동하지 않음
일부 애플리케이션, 특히 Electron 앱(VS Code, Slack, Discord), 터미널 및 사용자 정의 입력 처리 기능이 있는 앱은 Espanso의 시뮬레이션된 키 입력을 올바르게 수신하지 못합니다.
Linux 수정: 올바른 주입 백엔드를 사용하고 있는지 확인하세요. ~/.config/espanso/config/default.yml 수정:
backend: Auto
Auto, Clipboard 및 Inject 간에 전환해 보세요.
backend: Clipboard
Windows 수정: 관리자 권한으로 Espanso을 실행하세요. 특히 높은 권한으로 실행되는 앱의 경우 더욱 그렇습니다.
macOS 수정: 시스템 설정 → 개인 정보 보호 및 보안 → 접근성으로 이동하여 목록에서 Espanso을(를) 제거한 다음 다시 추가하세요.
4. 접근성 권한 누락(macOS)
접근성 권한이 없으면 Espanso에서 키 입력을 모니터링하거나 텍스트 출력을 시뮬레이션할 수 없습니다.
수정:
- 시스템 설정 → 개인 정보 보호 및 보안 → 접근성을 엽니다.
- 목록에서 Espanso을(를) 찾으세요.
- 전원을 껐다가 다시 켜세요.
- Espanso 다시 시작:
espanso restart
이 권한 재설정 댄스는 macOS 포인트 릴리스마다 일반적입니다. 반복하고 싶지 않다면 Lightning Assist이 macOS 권한을 처리하는 방법(단일 부여는 시스템 업데이트 후에도 유지됨)을 참조하세요.
💡 Espanso을 사용하는 것보다 수정하는 데 더 많은 시간을 소비하십니까? Lightning Assist는 YAML 파일이 없고 내장된 AI 명령이 없으며 동일한 Linux 지원을 제공하는 그래픽 텍스트 확장기입니다. 14일 동안 무료로 사용해 보세요 → — 신용카드가 없습니다.
5. 트리거가 실행되지 않음 - 트리거 유형이 잘못됨
기본적으로 Espanso은 단어 구분 기호(공백, 줄 바꿈, 구두점) 뒤에서만 확장되는 단어 트리거를 사용합니다. 단어 중간에 트리거를 입력하면 확장되지 않습니다.
수정: 일치 파일에서 트리거 유형을 확인하세요. 어디서나 트리거하려면 word: false을 사용하세요.
matches:
- trigger: ":sig"
replace: "Best regards,\nYour Name"
word: false
또는 더 많은 제어를 위해 regex 트리거 유형을 사용하세요.
matches:
- regex: ":sig$"
replace: "Best regards,\nYour Name"
6. Espanso 시스템 업데이트 후 작동하지 않음
OS 업데이트(특히 macOS 및 Linux)는 접근성 권한을 취소하거나 시스템 서비스를 중단시키는 경우가 많습니다.
수정:
- 접근성 권한을 다시 부여합니다(macOS에 대한 수정 4 참조).
- Linux에서 systemd 서비스를 다시 등록합니다:
espanso service register - Windows에서 Espanso이(가) 아직 시작 목록에 있는지 확인하세요.
7. 잘못된 위치에 있는 구성 파일
Espanso은 특정 위치에서 구성 파일을 찾습니다. .yml 일치 파일을 잘못된 폴더에 넣으면 해당 파일이 로드되지 않습니다.
기본 구성 위치:
- Linux:
~/.config/espanso/ - macOS:
~/Library/Application Support/espanso/ - Windows:
%APPDATA%\espanso\
일치 파일은 match/ 하위 디렉터리에 있어야 합니다. 시스템의 정확한 경로를 보려면 espanso path을 실행하세요.
8. Espanso 다른 애플리케이션과의 충돌
일부 애플리케이션이나 접근성 도구는 Espanso의 자체 키 모니터링과 충돌하는 전역 단축키를 등록합니다.
수정:
- 다른 접근성 도구, 화면 판독기 또는 단축키 관리자를 일시적으로 비활성화합니다.
- Espanso 로그에서 오류를 확인하세요.
espanso log - 전체 진단을 위해
espanso doctor을 실행해 보세요.
9. Wayland에서 Espanso가 시작되지 않는 문제
Wayland 세션(Ubuntu, Fedora 및 최신 GNOME 데스크톱의 기본 세션)에서는 Espanso가 전용 Wayland 빌드와 바이너리에 대한 일회성 권한이 필요합니다. 이 둘 중 하나라도 없으면 시작에 실패하거나 시작은 되지만 확장이 되지 않습니다(이슈 #2223).
해결 방법: echo $XDG_SESSION_TYPE 명령어로 세션 유형을 확인하세요. 결과가 wayland라면:
- Wayland 전용 패키지(
espanso-debian-wayland-amd64.deb는 Debian/Ubuntu용, Terra RPM은 Fedora용)를 설치하세요. X11용 패키지가 아닙니다. - Espanso가
/dev/input을 읽고/dev/uinput에 쓸 수 있도록 권한을 부여하세요:sudo setcap "cap_dac_override+p" $(which espanso). 이 단계는 Espanso의 공식 Linux 설치 가이드에 나와 있습니다. 파일 권한은 바이너리에 직접 붙기 때문에, Espanso 업그레이드 후 확장이 멈춘다면 이 명령을 다시 실행하세요. espanso service register와espanso start를 실행하세요.
반드시 Espanso 2.4.0 이상(2.4.0은 2026년 7월 21일, 2.4.1은 2026년 9월 2일 출시) 버전을 사용하세요. 2.4.0에서는 wlroots 컴포지터(Sway, Hyprland, labwc, Wayfire)에 대한 앱 감지 기능이 추가되고 Fedora의 Wayland 세션 설치 실패가 수정되었습니다. 2.4.1에서는 Linux용 데스크톱 파일과 아이콘이 추가되었습니다. 그럼에도 불구하고 Espanso 설치 가이드에서는 Wayland 지원을 여전히 "실험적"으로 분류합니다: 비미국 키보드 레이아웃은 수동으로 설정해야 하고, 앱별 매치는 KDE에서 kdotool 설치 시에만 작동하며, GNOME에서는 클립보드 백엔드 사용 시 작은 깜박임이 발생하고, 새로 연결한 키보드는 espanso restart가 필요합니다.
2026년에 바뀐 점 하나: GNOME에서는 "그냥 X11 세션으로 로그인하세요"가 더 이상 선택지가 아닙니다. GNOME 50에서 X11 세션이 완전히 제거되어 Ubuntu 26.04 LTS 및 GNOME 50 기반 배포판은 Wayland 전용입니다(X11 앱은 여전히 XWayland를 통해 실행되지만, Espanso의 X11 빌드는 네이티브 Wayland 앱의 키 입력을 볼 수 없습니다). Wayland에서 확장이 불안정하다면, Espanso가 잘 지원하는 컴포지터(KDE 또는 wlroots 계열)나 Wayland 경로가 실험적이지 않은 텍스트 확장기를 사용하는 방법뿐입니다 — 자세한 내용은 Wayland 텍스트 확장 가이드를 참고하세요.
아직도 작동하지 않나요? 로그 확인
espanso log
이는 Espanso이(가) 실패하는 이유를 정확하게 보여줍니다. 권한 오류, 구문 분석 오류 또는 백엔드 문제를 찾아보세요.
한 눈에 보기: Espanso 대 Lightning Assist
| 기능 | Espanso | Lightning Assist |
|---|---|---|
| 오픈 소스 | ✅ | ❌ (상업용, 14일 평가판) |
| 가격 | 무료/기부 | 무료(최대 20개의 스니펫, 폴더, 팀 1개), Pro $5.99/월. AI 기능은 AI 크레딧(Pro에는 매달 1000 크레딧이 포함되며, 무료 플랜에서는 필요에 따라 구매합니다)을 통해 측정됩니다. |
| 크로스 플랫폼(Windows, macOS, Linux) | ✅ | ✅ |
| 구성 | YAML 파일 | 그래픽 편집기 |
| AI 명령(다시 쓰기, 강화 등) | ❌ | ✅ — AI 크레딧 사용, 구독 불필요 |
| 푸쉬투톡(Push-to-Talk) 음성-텍스트 | ❌ | ✅ — 무료 등급에서도 작동하며 AI 크레딧을 소비합니다 |
| 팀 스니펫 공유 | ❌ (커뮤니티 해결 방법) | ✅ 내장 |
| 디버그 경험 | CLI(espanso doctor, 로그) |
GUI 상태 패널 |
둘 다 Windows, macOS 및 Linux에서 배송됩니다. 선택은 일반적으로 CLI + 구성 파일 + 무료(Espanso) 또는 GUI + AI + 음성 + 유료(Lightning Assist) 중 무엇을 선호합니까?로 귀결됩니다.
Espanso 구성이 유지 관리 부담이 되는 경우
Espanso의 YAML 구성은 강력한 기능을 제공하지만 실질적인 마찰을 추가합니다. 특히 시작하거나, 자동 오류를 디버깅하거나, 구성 파일에 익숙하지 않은 팀과 공동작업할 때 더욱 그렇습니다.
Espanso을 실제로 사용하는 것보다 문제를 해결하는 데 더 많은 시간을 소비하는 경우 Lightning Assist — 그래픽 Windows, Mac 및 Linux용 텍스트 확장기, 내장된 AI 명령, 푸시-투-톡 음성 입력 및 팀 스니펫 공유. 구성 파일도 없고 YAML도 없습니다. 14일 무료 평가판을 다운로드하세요 - 신용카드가 필요하지 않습니다.
자세한 비교는 Lightning Assist 및 Espanso을 참조하세요.