Espanso Não está funcionando? 9 soluções comuns (2026)

Espanso é um poderoso expansor de texto de código aberto, mas sua configuração baseada em YAML significa que as coisas podem dar errado de maneiras que não são óbvias. Aqui estão os motivos mais comuns pelos quais Espanso para de funcionar – e como consertar cada um deles. Para CLI e caminhos oficiais, consulte a documentação do Espanso.

Divulgação: fazemos Lightning Assist, um expansor de texto pago, então Espanso é um concorrente nosso. Espanso é gratuito e de código aberto, e todas as correções abaixo são para o próprio Espanso – nenhuma delas exige mudar para outra ferramenta.

1. Espanso não está em execução

A causa mais comum: o serviço Espanso não foi iniciado.

Correção:

espanso start

Verifique se está funcionando:

espanso status

No Linux com systemd:

systemctl --user status espanso
systemctl --user start espanso

2. Erro de sintaxe YAML na sua configuração

Espanso falha silenciosamente quando um arquivo de configuração tem YAML inválido. Uma tabulação ou dois pontos mal colocados quebra o arquivo inteiro.

Correção: Execute o diagnóstico de configuração:

espanso doctor

Erros comuns a serem verificados:

• Usando tabulações em vez de espaços (YAML requer espaços)
• Faltam aspas em texto que contém caracteres especiais como :, # ou \
• Recuo deslocado em um espaço
• Um valor replace: que começa com { — deve ser colocado entre aspas: replace: "{{clipb}}"

Se falhas silenciosas de YAML são um problema recorrente para sua equipe, um editor de snippet baseado em GUI evita o problema completamente – você edita campos em um formulário em vez de validar o recuo a olho nu.

3. Espanso não funciona em um aplicativo específico

Alguns aplicativos – especialmente aplicativos Electron (VS Code, Slack, Discord), terminais e aplicativos com manipulação de entrada personalizada – não recebem as teclas simuladas de Espanso corretamente.

Correção no Linux: Certifique-se de estar usando o back-end de injeção correto. Edite ~/.config/espanso/config/default.yml:

backend: Auto

Tente alternar entre Auto, Clipboard e Inject:

backend: Clipboard

Correção no Windows: Execute o Espanso como administrador, especialmente para aplicativos executados com privilégios elevados.

Correção no macOS: Vá para Configurações do sistema → Privacidade e segurança → Acessibilidade, remova Espanso da lista e adicione-o novamente.

4. Permissões de acessibilidade ausentes (macOS)

Sem permissões de acessibilidade, Espanso não pode monitorar as teclas digitadas ou simular a saída de texto.

Correção:

1. Abra Configurações do sistema → Privacidade e segurança → Acessibilidade
2. Encontre Espanso na lista
3. Desligue e ligue novamente
4. Reinicie Espanso: espanso restart

Essa dança de redefinição de permissão é comum após cada versão pontual do macOS. Se preferir não repeti-la, veja como o Lightning Assist lida com as permissões do macOS (uma concessão única sobrevive às atualizações do sistema).

💡 Gastando mais tempo consertando o Espanso do que usando-o? Lightning Assist é um expansor de texto gráfico sem arquivos YAML, comandos de IA integrados e o mesmo suporte Linux. Experimente gratuitamente por 14 dias → — sem cartão de crédito.

5. Gatilho não dispara – Tipo de gatilho errado

Por padrão, Espanso usa gatilhos de palavras que só se expandem após um separador de palavras (espaço, nova linha, pontuação). Se você digitar o gatilho no meio de uma palavra, ele não se expandirá.

Correção: Verifique o tipo de gatilho no arquivo de correspondência. Use word: false se quiser acionar em qualquer lugar:

matches:
  - trigger: ":sig"
    replace: "Best regards,\nYour Name"
    word: false

Ou use o tipo de gatilho regex para ter mais controle:

matches:
  - regex: ":sig$"
    replace: "Best regards,\nYour Name"

6. Espanso não funciona após atualização do sistema

As atualizações do sistema operacional – especialmente em macOS e Linux – geralmente revogam permissões de acessibilidade ou quebram o serviço do sistema.

Correção:

1. Conceda novamente permissões de acessibilidade (consulte Correção 4 para macOS)
2. No Linux, registre novamente o serviço systemd: espanso service register
3. No Windows, verifique se o Espanso ainda está na lista de inicialização

7. Arquivo de configuração no local errado

Espanso procura arquivos de configuração em locais específicos. Colocar seus arquivos de correspondência .yml na pasta errada significa que eles nunca serão carregados.

Locais de configuração padrão:

• Linux: ~/.config/espanso/
• macOS: ~/Library/Application Support/espanso/
• Windows: %APPDATA%\espanso\

Os arquivos de correspondência devem estar no subdiretório match/. Execute espanso path para ver os caminhos exatos do seu sistema.

8. Espanso entra em conflito com outro aplicativo

Alguns aplicativos ou ferramentas de acessibilidade registram teclas de atalho globais que entram em conflito com o monitoramento de teclas do próprio Espanso.

Correção:

• Desative temporariamente outras ferramentas de acessibilidade, leitores de tela ou gerenciadores de teclas de atalho
• Verifique se há erros nos registros de Espanso: espanso log
• Tente executar espanso doctor para um diagnóstico completo

9. Espanso não inicia no Wayland

Nas sessões do Wayland (o padrão no Ubuntu, Fedora e GNOME modernos), o Espanso precisa da versão dedicada para Wayland e muitas vezes falha ao iniciar até ser reiniciado manualmente (problema #2223).

Correção: verifique seu tipo de sessão com echo $XDG_SESSION_TYPE. Se disser wayland: instale o pacote Espanso específico do Wayland (não o X11), adicione seu usuário ao grupo input - sudo usermod -aG input $USER - então saia e entre novamente e execute espanso restart. Se ainda falhar, conceda a capacidade diretamente: sudo setcap "cap_dac_override+p" $(which espanso). O suporte ao GNOME e KDE Wayland é parcial; se as expansões permanecerem não confiáveis, uma sessão X11/XWayland é a alternativa estável.

Ainda não está funcionando? Verifique os registros

espanso log

Isso mostra exatamente por que o Espanso está falhando. Procure erros de permissão, erros de análise ou problemas de back-end.

Visão geral: Espanso x Lightning Assist

Recurso	Espanso	Lightning Assist
Código aberto	✅	❌ (comercial, teste de 14 dias)
Preços	Grátis / doações	Plano base de US$ 5,99/mês (snippets, pastas, compartilhamento de equipe). Recursos de IA medidos por meio de Créditos de IA, adquiridos separadamente.
Multiplataforma (Windows, macOS, Linux)	✅	✅
Configuração	Arquivos YAML	Editor gráfico
Comandos de IA (reescrever, aprimorar, etc.)	❌	✅ — Equipe + Créditos de IA
Voz para texto push-to-talk	❌	✅ — também funciona no nível gratuito, consome créditos de IA
Compartilhamento de snippets em equipe	❌ (soluções alternativas da comunidade)	✅ embutido
Experiência de depuração	CLI (espanso doctor, registros)	Painel de status da GUI

Ambos estão disponíveis para Windows, macOS e Linux. A escolha geralmente se resume a: você prefere CLI + arquivos de configuração + grátis (Espanso) ou GUI + IA + voz + pago (Lightning Assist).

Quando a configuração de Espanso se torna um fardo de manutenção

A configuração YAML de Espanso oferece poder, mas adiciona atrito real - especialmente ao começar, depurar falhas silenciosas ou colaborar com uma equipe que não se sente confortável com arquivos de configuração.

Se você está gastando mais tempo consertando Espanso do que realmente usando-o, considere Lightning Assist - um expansor de texto gráfico para Windows, Mac e Linux com uma GUI completa, comandos de IA integrados, digitação por voz push-to-talk e compartilhamento de snippets em equipe. Sem arquivos de configuração, sem YAML. Baixe o teste gratuito de 14 dias – não é necessário cartão de crédito.

Por padrão, seus snippets se expandem conforme você digita — não é necessária nenhuma tecla de atalho: Lightning Assist vem com o Modo Conforme Você Digita ativado. Digite o gatilho do seu snippet — o texto exato que você salvou, como ;meeting ou meeting — e ele se expandirá embutido no momento em que você terminar de digitá-lo. Um ; inicial é opcional e mantém os gatilhos distintos das palavras normais. Prefere um gatilho deliberado? Mude para o Modo Hotkey (opcional) a qualquer momento. Veja todos os modos de ativação →

Para uma comparação detalhada, consulte Lightning Assist vs Espanso.