WezTerm 설정

MobaXterm처럼 SSH 연결과 세션을 빠르게 전환할 수 있도록 구성한 개인 WezTerm 설정입니다. Windows 사용을 중심으로 하며, 탭/패인 관리, SSH 도메인, 대화형 설정 메뉴와 GPU 가속 렌더링을 한 파일에 담고 있습니다.

현재 상태

• 기본 브랜치: main
• 설정 파일: wezterm.lua
• 확인 기준: 2026-07-23, origin/main과 로컬 브랜치가 동일함
• 최근 설정 변경: 기본 SSH 도메인 제거
• 등록된 SSH 도메인: 없음
• 시작 동작: 메인 메뉴를 표시하며, SSH 도메인이 등록된 경우 첫 번째 도메인에 한 번 자동 연결

현재 홈 디렉터리의 ~/.wezterm.lua는 저장소 버전보다 이전 상태입니다. 저장소 버전에는 다음 변경이 더 포함되어 있습니다.

• SSH 연결에 AttachDomain을 사용해 최초 연결 시 중복 탭 방지
• 메인 메뉴와 설정 메뉴 항목에 아이콘 추가
• 일반 우클릭, Shift+우클릭, Ctrl+Shift+우클릭 붙여넣기 지원

주요 기능

• JetBrains Mono와 Noto Sans KR 폰트 폴백
• Catppuccin Mocha 테마, 투명도 0.92
• 호스트별 탭 색상과 프로세스 기반 탭 제목
• 도메인, 워크스페이스, 접속 경과 시간, 현재 시각을 표시하는 상태바
• SSH 도메인 및 Unix mux 도메인
• 폰트, 테마, 투명도, SSH 연결 등을 수정하는 대화형 메뉴
• 탭/패인, 검색, Copy mode, Quick Select, 워크스페이스 단축키
• WebGPU 고성능 렌더링, 최대 120 FPS
• Kitty graphics, iTerm2, Sixel 이미지 프로토콜
• IPv4 주소 Quick Select

설치

Windows

저장소의 wezterm.lua를 사용자 홈의 .wezterm.lua로 복사합니다.

Copy-Item .\wezterm.lua $HOME\.wezterm.lua

Linux/macOS

cp wezterm.lua ~/.wezterm.lua

기본 폰트인 JetBrains Mono와 Noto Sans KR을 설치한 뒤 WezTerm을 완전히 종료하고 다시 실행합니다. 설정 오류는 다음 명령으로 확인할 수 있습니다.

wezterm show-config

메뉴

WezTerm을 시작하면 메인 메뉴가 열립니다. 등록된 SSH 도메인에 연결하거나 설정 메뉴로 들어갈 수 있습니다. 메뉴를 닫은 뒤에는 Leader+m으로 다시 열 수 있습니다.

설정 메뉴에서 다음 항목을 직접 변경할 수 있습니다.

• 폰트 크기, 영문/한글 폰트, 줄 높이, 색상 테마, 창 투명도
• SSH 도메인 추가 및 수정, 도메인 목록, 통합 런처
• 스크롤백, 최대 FPS, 탭바 위치, 창 닫기 확인

메뉴에서 바꾼 값은 실행 중인 설정 파일에 기록되고 설정이 다시 로드됩니다. SSH 도메인을 추가하거나 수정한 경우 WezTerm 프로세스를 완전히 종료한 뒤 다시 실행해야 합니다.

단축키

Leader 키는 Ctrl+a이며, 다음 키를 1초 안에 이어서 누릅니다.

키	동작
Ctrl+Shift+t	현재 도메인에 새 탭
Ctrl+Shift+w	현재 탭 닫기
Ctrl+Shift+1/2/3	1/2/3번 탭으로 이동
Leader+\	좌우 패인 분할
Leader+-	상하 패인 분할
Leader+h/j/k/l	패인 이동
Leader+x	현재 패인 닫기
Leader+z	현재 패인 확대/복원
Leader+r	패인 크기 조절 모드
Leader+w	워크스페이스 목록
Leader+s	SSH 도메인 목록
Leader+e	저장된 실행 메뉴
Leader+Tab	통합 런처
Leader+m	메인 메뉴
Leader+Enter	현재 패인을 새 창으로 이동
Leader+/	스크롤백 검색
Leader+[	Copy mode
Leader+Space	Quick Select
Ctrl+=/-/0	폰트 크기 확대/축소/초기화
Ctrl+Shift+c/v	복사/붙여넣기

마우스 동작은 다음과 같습니다.

동작	결과
우클릭	클립보드 붙여넣기
Shift+우클릭	마우스를 캡처하는 전체 화면 앱에서 붙여넣기
Ctrl+클릭	커서 아래 링크 열기
Ctrl+Shift+클릭	메인 메뉴
Ctrl+Shift+더블클릭	현재 패인을 새 창으로 이동

SSH 설정

SSH 도메인은 기본으로 등록되어 있지 않습니다. 도메인을 추가하면 첫 번째 SSH 도메인이 시작 시 자동 연결됩니다.

config.ssh_domains = {
}

메인 메뉴의 설정 > 연결 설정 > SSH 도메인 추가에서 연결 정보를 등록할 수 있습니다. 접속 정보를 커밋하면 호스트 주소와 사용자명이 저장소에 포함되므로 공개 범위를 확인해야 합니다.

Unix mux 세션을 사용하려면 먼저 서버를 실행합니다.

wezterm-mux-server --daemonize

사용자 설정

자주 실행하는 명령은 config.launch_menu에 추가합니다.

config.launch_menu = {
  { label = "Local bash", args = { "bash", "-l" } },
  { label = "htop", args = { "htop" } },
}

WebGPU에서 문제가 생기면 다음 값을 OpenGL 또는 Software로 변경합니다.

config.front_end = "WebGpu"

새 탭과 분할 패인이 현재 작업 디렉터리를 이어받게 하려면 사용하는 셸에 WezTerm shell integration을 설정해야 합니다.