# PaperWM.spoon no macOS: instale e configure o básico

Last updated: 2026-11-12

O PaperWM.spoon é um plugin gratuito de gerenciamento de janelas em mosaicos com rolagem para o Hammerspoon, no macOS. Para configurá-lo, instale o Hammerspoon, clone o repositório do PaperWM.spoon na pasta Spoons do Hammerspoon, carregue e inicie o Spoon a partir do init.lua e conceda as permissões que o macOS solicitar. Os comandos abaixo seguem o README do projeto, conferido em 12/11/2026.

## Principais fatos

- O PaperWM.spoon é um Spoon do Hammerspoon, e não um app independente para Mac.
- O README traz um comando de clonagem e exemplos de configuração em Lua.
- O README pede que você altere duas configurações do Mission Control: desativar o reposicionamento automático dos Spaces e ativar Spaces separados para as telas.
- Ele é uma boa escolha se você quer uma configuração baseada em Lua e personalizável; quem prefere não manter a configuração do Hammerspoon pode escolher outra ferramenta.

## Instale o Hammerspoon primeiro

Baixe o Hammerspoon no [site oficial](https://www.hammerspoon.org/), conferido em 12/11/2026. Abra-o uma vez e siga as solicitações de permissão do macOS. O Hammerspoon executa scripts de automação, então revise o que você instala e o código que escolhe carregar. O README do projeto PaperWM.spoon descreve o plugin e a configuração. Não testamos estes passos em todas as versões do macOS.

O [README oficial](https://github.com/mogenson/PaperWM.spoon) do PaperWM.spoon, conferido em 12/11/2026, traz este comando de instalação:

```bash
git clone https://github.com/mogenson/PaperWM.spoon ~/.hammerspoon/Spoons/PaperWM.spoon
```

Execute-o no Terminal. Ele clona o repositório na pasta Spoons usada pelo Hammerspoon. Se você usa um diretório de configuração personalizado do Hammerspoon, ajuste o destino para corresponder a ele.

## Ajuste as opções do Mission Control

O README indica Preferências do Sistema → Mesa e Dock e a seção do Mission Control. No macOS atual, abra Ajustes do Sistema → Mesa e Dock e role até Mission Control. Desative **Reorganizar os Spaces automaticamente com base no uso mais recente** e ative **As telas têm Spaces separados**. A redação exata e a localização dessas opções podem variar conforme a versão do macOS. O README lista essas opções como parte da configuração.

São escolhas que valem para todo o sistema e afetam como o macOS trata os Spaces. Decida se elas combinam com a sua configuração antes de alterá-las. Se você usa várias telas, confirme se o comportamento dos Spaces corresponde ao que você quer.

## Carregue e inicie o Spoon

Abra o arquivo de configuração do Hammerspoon em `~/.hammerspoon/init.lua`. Acrescente as seguintes linhas em Lua:

```lua
PaperWM = hs.loadSpoon("PaperWM")
PaperWM:bindHotkeys(PaperWM.default_hotkeys)
PaperWM:start()
```

Salve o arquivo. No ícone do Hammerspoon na barra de menus, escolha **Reload Config**. A primeira linha carrega o Spoon, a segunda registra os atalhos padrão documentados e a terceira inicia o gerenciamento de janelas. O README do projeto também mostra um caminho com SpoonInstall e exemplos de atalhos personalizados. Comece com os padrões antes de editar as teclas, para saber se a configuração foi carregada.

Para parar o PaperWM.spoon, chame `PaperWM:stop()` pelo console ou pela configuração do Hammerspoon. Se a inicialização informar um Spoon ausente, confira se a pasta clonada se chama `PaperWM.spoon` e está dentro da pasta Spoons que o Hammerspoon usa. Verifique o console do Hammerspoon em busca de erros de Lua antes de alterar várias configurações de uma vez.

## Confira os atalhos e faça uma alteração

O [README](https://github.com/mogenson/PaperWM.spoon) do PaperWM.spoon, conferido em 12/11/2026, documenta os padrões de foco com Option–Command e as setas, troca com Option–Command–Shift e as setas, e alternância de largura com Option–Command–R. Ele também mostra atalhos para flutuar janelas, para Spaces e para o tamanho das janelas. Se um atalho conflitar com outro app, edite a tabela em Lua, recarregue a configuração e verifique o console do Hammerspoon caso o plugin deixe de responder.

A própria configuração do Spoon pode filtrar apps e ajustar as proporções das janelas. O README mostra `window_filter` e `window_ratios` como pontos de configuração. Altere apenas um ajuste que você consiga identificar na documentação e depois teste uma janela de app comum e um app que você queira excluir. Os mantenedores também observam que o macOS limita mover janelas totalmente para fora da tela, então janelas em mosaico nas bordas podem continuar parcialmente visíveis.

Esta é uma cadeia de ferramentas baseada em Lua. Ela serve a quem se sente à vontade para ler um arquivo de configuração e quer a flexibilidade do Hammerspoon. Quem prefere um app independente e uma janela de ajustes pode achar essa configuração exigente de manter. Para o PaperWM.spoon, a referência é o README de configuração; confira o repositório antes de seguir os passos, porque projetos de código aberto podem mudar.

O README do PaperWM.spoon diz que ele é “Inspired by PaperWM” e leva ao [projeto PaperWM](https://github.com/paperwm/PaperWM), conferido em 12/11/2026. Os projetos têm implementações e instruções de configuração separadas.

Nós criamos o SlidePane, um app para macOS para quem quer configurar layouts de janelas sem manter scripts em Lua. Ele pode servir a você se preferir ajustes de app e controles de atalho integrados; o PaperWM.spoon é melhor escolha se você quer o modelo de script do Hammerspoon. Veja o [Instale SlidePane e comece o teste grátis](/pt-BR/guides/installation) para configurar o app.

## Páginas relacionadas

O [artigo sobre o niri no Mac](/pt-BR/blog/niri-on-mac) compara outro fluxo com rolagem. O [Atalhos e layouts de teclado](/pt-BR/guides/shortcuts) explica como revisar os atalhos dos apps.
