# macOS에서 PaperWM.spoon 설치하고 기본 설정하기

Last updated: 2026-11-12

PaperWM.spoon은 macOS의 Hammerspoon에서 쓰는 무료 스크롤 타일링 창 관리자 플러그인입니다. Hammerspoon을 설치하고 PaperWM.spoon 저장소를 Spoons 폴더에 복제한 뒤 init.lua에서 불러와 시작하고 macOS 권한을 허용합니다. 아래 명령은 2026-11-12에 확인한 프로젝트 README를 따릅니다.

## 핵심 정보

- PaperWM.spoon은 독립 Mac 앱이 아니라 Hammerspoon Spoon입니다.
- README에는 복제 명령과 Lua 설정 예제가 있습니다.
- Mission Control에서 Spaces 자동 재정렬을 끄고 디스플레이마다 별도 Spaces를 켜도록 안내합니다.
- Lua 설정을 직접 관리하고 싶을 때 적합합니다. Hammerspoon 설정을 유지하고 싶지 않다면 다른 도구를 고려하세요.

## 먼저 Hammerspoon 설치하기

[Hammerspoon 공식 사이트](https://www.hammerspoon.org/)에서 설치하세요(2026-11-12 확인). 앱을 한 번 열어 macOS 권한 요청을 따릅니다. Hammerspoon은 자동화 스크립트를 실행하므로 설치하고 불러올 코드를 살펴보세요. PaperWM.spoon [공식 README](https://github.com/mogenson/PaperWM.spoon)는 플러그인 설치를 설명하지만 모든 macOS 버전에서 시험한 것은 아닙니다.

README의 설치 명령은 다음과 같습니다.

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

터미널에서 실행하면 저장소가 Hammerspoon의 Spoons 폴더에 복제됩니다. 사용자 지정 설정 디렉토리를 쓴다면 경로를 맞게 바꾸세요.

## Mission Control 옵션 설정하기

README는 시스템 설정 → 데스크탑 및 Dock의 Mission Control 항목을 안내합니다. **최근 사용 내역에 따라 Spaces를 자동으로 재정렬**은 끄고 **각각의 Spaces가 있는 디스플레이**는 켜세요. macOS 버전에 따라 문구와 위치가 다를 수 있습니다.

이 옵션은 Spaces 처리 방식에 영향을 주는 시스템 전체 설정입니다. 바꾸기 전에 현재 구성에 맞는지 생각하고 여러 디스플레이를 쓴다면 화면별 동작을 확인하세요.

## Spoon 불러오고 시작하기

`~/.hammerspoon/init.lua`를 열어 다음 Lua 줄을 추가하세요.

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

저장한 뒤 Hammerspoon 메뉴 막대 아이콘에서 **설정 다시 불러오기**를 선택합니다. 첫 줄은 Spoon을 불러오고 다음 줄은 기본 키 바인딩을 등록하며 마지막 줄은 창 관리를 시작합니다. README는 SpoonInstall 방식과 사용자 바인딩 예도 보여 줍니다. 먼저 기본값으로 제대로 작동하는지 확인하세요.

PaperWM.spoon을 멈추려면 Hammerspoon 콘솔이나 설정에서 `PaperWM:stop()`을 호출합니다. Spoon을 찾지 못한다면 복제 폴더 이름이 `PaperWM.spoon`이고 Hammerspoon이 사용하는 Spoons 안에 있는지 확인하세요. 여러 설정을 한꺼번에 바꾸기보다 콘솔의 Lua 오류부터 살펴보세요.

## 바인딩 확인하고 한 가지 변경하기

[PaperWM.spoon README](https://github.com/mogenson/PaperWM.spoon)는 포커스 이동 Option–Command–화살표, 교환 Option–Command–Shift–화살표, 너비 순환 Option–Command–R을 기본으로 안내합니다(2026-11-12 확인). 플로팅, Spaces, 크기 조절 바인딩도 있습니다. 다른 앱과 충돌하면 Lua 표를 편집해 설정을 다시 불러오고 작동을 멈춘 경우 Hammerspoon 콘솔을 확인하세요.

Spoon 설정은 앱 필터와 창 비율을 조정할 수 있습니다. README는 `window_filter`와 `window_ratios`를 설정 지점으로 안내합니다. 문서에서 확인한 항목 하나만 바꾸고 일반 창과 제외할 앱을 시험하세요. macOS는 창을 화면 밖으로 완전히 옮기는 데 제한을 두므로 가장자리 타일이 일부 보일 수 있습니다.

이 도구 체계는 Lua 기반입니다. 설정 파일을 읽고 Hammerspoon 유연성을 원하는 사람에게 맞습니다. 독립 앱과 설정 창을 선호한다면 관리가 부담스러울 수 있습니다. 오픈 소스 프로젝트는 바뀔 수 있으니 설치 전에 README의 최신 안내를 확인하세요.

PaperWM.spoon README는 [PaperWM 프로젝트](https://github.com/paperwm/PaperWM)에서 영감을 받았다고 밝힙니다(2026-11-12 확인). 두 프로젝트는 구현과 설정 방법이 서로 다릅니다.

저희가 만드는 SlidePane는 Lua 스크립트 유지 없이 창 레이아웃을 설정하려는 사람을 위한 macOS 앱입니다. 앱 설정과 내장 단축키 제어를 원하면 맞을 수 있고, Hammerspoon 스크립트 방식이 필요하면 PaperWM.spoon이 더 적합합니다. 앱 설정은 [SlidePane 설치 및 체험 시작](/ko/guides/installation)를 참고하세요.

## 관련 안내

다른 스크롤 흐름은 [Mac에서 Niri 사용하기](/ko/blog/niri-on-mac)를, 앱 키 확인은 [단축키와 키보드 배열](/ko/guides/shortcuts)를 참고하세요.
