1. 설치 및 첫 실행

설치

플랫폼	설치 방법
macOS	brew install --cask warp 또는 warp.dev에서 .dmg 다운로드
Windows	warp.dev에서 .exe 다운로드 (Windows 10/11)
Linux	.deb / .rpm / AppImage 제공. Ubuntu: sudo apt install ./warp-terminal_*.deb

첫 실행 후 추천 설정

2. 핵심 개념 - Block 기반 UX

Warp가 기존 터미널과 가장 다른 점은 Block(블록) 개념입니다. 명령 하나와 그 출력이 하나의 "블록" 단위로 묶여서, 마치 Jupyter Notebook 셀처럼 다룰 수 있습니다.

Block의 장점

• 개별 선택/복사: 명령만 복사 (Shift+Cmd+C) / 출력만 복사 (Alt+Shift+Cmd+C)
• 북마크: 중요한 출력에 Cmd+B로 책갈피, Alt+↑/↓로 빠르게 점프
• 재실행: 이전 블록 선택 후 Cmd+I로 같은 명령 재입력
• 공유: Shift+Cmd+S로 블록 단위로 링크/이미지 공유 (디버깅 협업에 유용)

Modern Input Editor

커맨드 라인이 코드 에디터처럼 동작합니다. 멀티라인 편집, 구문 강조, 자동완성, 마우스 클릭으로 커서 이동, Cmd+Z Undo가 모두 가능합니다. SQL이나 긴 curl 명령을 작성할 때 압도적으로 편합니다.

3. 필수 단축키 정리

탭 / 패널 관리 macOS

단축키	동작
Cmd+T	새 탭 열기
Cmd+D	패널 우측 분할
Shift+Cmd+D	패널 하단 분할
Alt+Cmd+←/→/↑/↓	패널 간 이동
Cmd+1~9	탭 직접 이동
Shift+Cmd+Enter	현재 패널 최대화 토글
Cmd+W	탭/패널 닫기

탭 / 패널 관리 Windows Linux

단축키	동작
Ctrl+Shift+T	새 탭 열기
Ctrl+Shift+D	패널 우측 분할
Ctrl+Shift+E	패널 하단 분할
Ctrl+Alt+←/→/↑/↓	패널 간 이동
Ctrl+PageUp/PageDown	탭 전환
Ctrl+1~9	탭 직접 이동

핵심 기능 (공통)

단축키 (mac / win+linux)	동작
Cmd/Ctrl+P	Command Palette 열기
Ctrl+R	커맨드 히스토리 검색 (가장 강력함)
Ctrl+` (백틱)	자연어 → 명령어 생성 (AI)
Ctrl+Shift+R	Workflows 열기
Cmd+\ / Ctrl+Shift+\	Warp Drive 토글
Cmd/Ctrl+F	출력 내 텍스트 검색
Cmd/Ctrl+K	화면 비우기 (블록 클리어)
Ctrl+L	스크린만 클리어 (히스토리 유지)

입력 편집 (Emacs 스타일 - 모든 OS 공통)

단축키	동작
Ctrl+A / Ctrl+E	줄 처음 / 끝으로
Ctrl+W	왼쪽 단어 잘라내기
Ctrl+U	커서 이전 전체 잘라내기
Ctrl+K	커서 이후 전체 잘라내기
Ctrl+F / →	자동완성 제안 수락
Alt/Meta+.	이전 명령의 마지막 단어 삽입
Ctrl+J	줄바꿈 (멀티라인 명령)

4. 입력 모드 - Modern vs Classic

Warp는 두 가지 입력 모드를 제공합니다. Settings → Appearance → Input에서 변경.

5. AI Agent Mode 사용법

Warp의 핵심 차별점은 단순 자동완성이 아니라 에이전트가 직접 명령을 실행하고 결과를 보고 다음 단계를 결정하는 점입니다.

3가지 진입 방법

1. 자연어 자동 감지: 입력란에 한국어/영어 자연어를 입력하면 ✨ 아이콘이 뜨면서 Agent Mode 진입
2. 키보드 단축키: Cmd+I (mac) / Ctrl+I (win/linux)
3. 명시적 트리거: * (asterisk + space)로 시작하면 즉시 Agent

실전 예시 - Django 개발

# 자연어로 명령 생성
> postgresql 데이터베이스 백업 스크립트 만들어줘
→ AI가 pg_dump 명령을 자동 생성, Enter로 실행

# 에러 디버깅

> 방금 실행한 마이그레이션이 왜 실패했는지 분석해줘
> → AI가 이전 블록의 출력을 읽고 원인 분석 + 해결 명령 제안

# 멀티스텝 태스크 (Agent가 자율 실행)

> 새 Django 앱 ‘inventory’를 생성하고, models.py에 Item 모델 추가하고,
> 마이그레이션까지 실행해줘
> → Agent가 단계별로 명령을 실행하며 각 단계마다 승인 요청

모델 선택

Agent 대화 창의 모델 선택기에서 변경 가능합니다:

• Claude (Sonnet/Opus 계열) - 코드 분석·리팩토링 강점
• GPT-5 / GPT-4 계열 - 일반적인 명령 생성
• Gemini - 빠른 응답
• Auto - 작업 성격에 따라 자동 선택

Codebase Context - 코드베이스 인덱싱

프로젝트 폴더를 열면 (Cmd+O) Warp가 인덱싱해서 Agent가 코드 맥락을 이해합니다. Django 프로젝트라면 models, views, urls 구조를 파악하고 "이 모델에 외래키 추가해줘" 같은 요청에 정확히 응답합니다.

외부 CLI 에이전트 통합

Claude Code, Codex, OpenCode 같은 서드파티 CLI 에이전트를 Warp 안에서 실행하면, Warp의 풍부한 입력창·코드 리뷰·알림 UI를 그대로 활용할 수 있습니다. REMEMBER GOLD님이 평소 쓰시는 Claude Code도 Warp 안에서 더 편하게 동작합니다.

6. Workflows · Notebooks · Warp Drive

Workflows - 파라미터화된 명령 템플릿

자주 쓰는 명령을 파라미터 양식과 함께 저장해두는 기능. Ctrl+Shift+R로 열기.

# 예: Django 프로젝트 새 앱 생성 워크플로우
# ~/.warp/workflows/django_new_app.yaml

---
name: Django New App
command: |-
  cd {{project_path}}
  python manage.py startapp {{app_name}}
  echo "    '{{app_name}}'," >> {{project_path}}/{{settings_file}}
tags: ["django", "scaffold"]
description: 새 Django 앱 생성 후 INSTALLED_APPS에 자동 추가
arguments:
  - name: project_path
    description: 프로젝트 루트 경로
    default_value: "."
  - name: app_name
    description: 생성할 앱 이름
  - name: settings_file
    description: settings.py 경로 (config/settings.py 등)
    default_value: "config/settings.py"

Notebooks - 실행 가능한 문서

마크다운 텍스트와 실행 가능한 코드 블록을 섞어서 작성. 배포 절차서, 온보딩 가이드, 트러블슈팅 런북에 최적입니다.

Warp Drive - 클라우드 동기화 로그인 필요

Workflows · Notebooks · 환경변수 · 세션을 클라우드로 동기화. REMEMBER GOLD님처럼 MacBook + Dell Precision (Windows) + Ubuntu 서버를 오가는 환경에서는 큰 메리트입니다.

• 한 머신에서 만든 워크플로우가 다른 머신에서 그대로 사용 가능
• 팀 폴더로 공유하면 클라이언트 프로젝트별 표준 절차 배포 가능
• 비밀번호·API 키는 환경변수로 따로 암호화 저장

7. Command Palette · Search

Command Palette - Cmd/Ctrl+P

VS Code 스타일 팔레트로 Warp의 모든 기능(설정 페이지, 테마, 패널 분할 등)을 키워드로 검색해 실행.

Command Search - Ctrl+R

전통적인 reverse-i-search보다 강력합니다. 디렉토리·태그·날짜로 필터링 가능, 출력까지 미리보기 됨.

Generate (자연어 → 명령) - Ctrl+`

전체 Agent Mode 진입 없이 명령 한 줄만 생성. "포트 8000 점유 프로세스 죽이기" → lsof -ti:8000 | xargs kill -9.

8. SSH 및 Warpify (원격 서버)

일반적인 ssh user@host는 그대로 동작합니다. 하지만 원격 서버에서도 Block UI, 자동완성, AI를 쓰려면 Warpify가 필요합니다.

Warpify Subshell - Ctrl+I

SSH 호스트 자동 등록

Warp는 ~/.ssh/config를 읽어 호스트 목록을 자동으로 추출합니다. Command Palette에서 "ssh" 검색 시 등록된 호스트로 빠르게 접속 가능합니다.

9. 설정 - 테마 · 키바인딩 · 셸 통합

설정 파일 위치

OS	경로
macOS	~/.warp/
Linux	~/.warp/ (또는 ~/.config/warp/)
Windows	%LOCALAPPDATA%\warp\Warp\config\

주요 설정 파일

• keybindings.yaml - 키바인딩 (재할당)
• themes/*.yaml - 커스텀 테마
• workflows/*.yaml - 워크플로우 정의
• launch_configurations/*.yaml - 런치 구성 (탭/패널 자동 구성)

테마 자체 제작 예시

# ~/.warp/themes/django-dark.yaml
accent: '#0c4b33'   # Django 그린
background: '#1a1a1a'
foreground: '#e0e0e0'
details: 'darker'
terminal_colors:
  normal:
    black: '#1a1a1a'
    red: '#ff5555'
    green: '#0c4b33'
    yellow: '#f1d432'
    blue: '#44475a'
    magenta: '#bd93f9'
    cyan: '#8be9fd'
    white: '#f8f8f2'
  bright:
    black: '#6272a4'
    red: '#ff6e6e'
    green: '#69ff94'
    yellow: '#ffffa5'
    blue: '#d6acff'
    magenta: '#ff92df'
    cyan: '#a4ffff'
    white: '#ffffff'

Launch Configurations - 작업 환경 자동 구성

여러 탭·패널·디렉토리·명령을 한 번에 띄우는 프로필. Django 프로젝트 시작 시 매번 동일한 레이아웃을 만들 때 유용.

# ~/.warp/launch_configurations/django-dev.yaml
name: Django Dev Environment
windows:
  - tabs:
      - title: server
        layout:
          cwd: ~/projects/ppcsystem_erp
          commands:
            - exec: source venv/bin/activate
            - exec: python manage.py runserver
      - title: shell
        layout:
          cwd: ~/projects/ppcsystem_erp
          commands:
            - exec: source venv/bin/activate
            - exec: python manage.py shell_plus
      - title: db
        layout:
          cwd: ~/projects/ppcsystem_erp
          commands:
            - exec: psql -U postgres -d ppcsystem

Ctrl+Cmd+L로 Launch Configuration Palette를 열어 실행.

10. Django 개발자를 위한 실전 활용

패널 레이아웃 추천 (3분할)

┌──────────────────────┬──────────────────────┐
│ runserver 로그       │ shell_plus / pytest │
│ (좌측 메인)           │ (우상)               │
│                      │                      │
│                      ├──────────────────────┤
│                      │ psql / git           │
│                      │ (우하)               │
└──────────────────────┴──────────────────────┘

자주 쓰는 Workflow 예시

이름	용도
django:migrate	makemigrations + migrate 한번에
django:reset-db	DB drop → create → migrate (개발용)
django:dump-fixture	특정 모델 fixture 추출
postgres:backup	pg_dump로 압축 백업
deploy:gunicorn-restart	SSH로 원격 gunicorn 재시작

AI Agent에게 던지기 좋은 명령 예시

* 현재 git diff를 보고 적절한 커밋 메시지 5개 제안해줘 (Conventional Commits)

- docker-compose.yml에서 postgres 컨테이너만 재시작하고 로그 확인
- 방금 실패한 pytest 결과를 분석해서 어떤 fixture가 문제인지 알려줘
- manage.py shell_plus를 띄워서 User 모델의 최근 가입자 10명 조회
- requirements.txt와 현재 설치된 패키지 비교해서 누락된 것만 설치

Warp Drive 활용 - 클라이언트 프로젝트 분리

클라이언트별로 폴더를 만들어 환경변수·워크플로우를 분리해두면, 새 머신에서도 즉시 작업 환경을 복원할 수 있습니다.

• 📁 점자도서관-프로젝트 - DB 접속 정보, 배포 스크립트
• 📁 통신사ERP-ppcsystem - SSH 호스트, 로그 모니터링 명령
• 📁 CS채팅-Channels - Redis 모니터링, WebSocket 테스트

11. 프라이버시 및 텔레메트리 관리

최소화 설정

1. Telemetry / Crash Reports OFF: Settings → Privacy
2. AI 자동 제안 OFF: Settings → AI → Disable AI completions
3. Warp Drive 동기화 OFF: 로그아웃 상태 유지
4. Network Log 확인: Settings → Privacy → "View network logging"으로 실제 전송되는 내용 검증 가능

한국어 한국 IT 환경 특이사항

• 회사 보안 정책상 외부 클라우드 통신이 금지된 경우 Warp 사용이 어려울 수 있습니다.
• SSH 접속 정보, 환경변수에 들어간 비밀번호는 Warp 서버로 전송되지 않지만, AI 명령 입력 시 명령 텍스트는 전송됩니다.
• 주민번호·계좌번호 등 개인정보를 다루는 SQL 쿼리는 Agent Mode가 아닌 일반 모드에서 실행하세요.

12. 자주 겪는 문제와 해결법

한글 깨짐

Settings → Appearance → Text → Font에서 D2Coding, Pretendard Mono, JetBrains Mono 같은 한글 폴백이 있는 폰트로 변경. 그래도 깨지면 셸 로케일 확인:

echo $LANG
# ko_KR.UTF-8 이 아니면 ~/.zshrc에 추가:
export LANG=ko_KR.UTF-8
export LC_ALL=ko_KR.UTF-8

oh-my-zsh 프롬프트가 이상하게 표시

Settings → Appearance → Input을 Classic Input (Shell PS1)로 변경. Modern Input은 자체 프롬프트를 쓰므로 PS1 커스터마이징이 무시됩니다.

한글 입력기(IME) 이슈

macOS의 한영 전환이 입력창에서 한 박자 늦게 반영되는 경우, Settings → Features → Editor에서 "IME Composition Mode" 옵션을 토글해보세요.

SSH 자동완성이 동작하지 않을 때

원격 서버에서 자동완성·블록 기능을 쓰려면 Ctrl+I로 Warpify를 실행해야 합니다. 자동 실행을 원하면 ~/.zshrc에 다음을 추가:

printf '\eP$f{"hook": "SourcedRcFileForWarp", "value": { "shell": "zsh"}}\x9c'

AI 응답이 너무 느리거나 한도 초과

• 비로그인 상태라면 무료 한도가 매우 제한적입니다 → 로그인 권장
• 모델 선택기에서 Auto 대신 빠른 모델(Gemini Flash 등)로 변경
• Agent Mode 대신 Ctrl+` Generate 사용 (단발성 명령은 더 빠름)

Linux에서 Global Hotkey 작동 안 함

X11 기반 일부 윈도우 매니저(sowm, dwm, XMonad 등)는 Extended Window Manager Hints 미구현으로 글로벌 핫키가 동작하지 않습니다. Wayland 또는 GNOME/KDE 환경에서는 정상 동작합니다.

---