Wave Terminal 설치 및 사용 가이드

Hermes × Codex 강의에서 명령창을 자주 다룹니다. 본인 컴퓨터에 기본 설치된 터미널(Mac "터미널", Windows PowerShell)도 충분히 강의를 따라갈 수 있지만, 입문자 분들은 Wave Terminal 을 사용하시면 학습 속도가 한층 빨라집니다. 이 가이드를 따라 5분 안에 깔고 기본 사용법까지 익힐 수 있습니다.

Wave Terminal 공식 홈페이지의 슬로건 "The open source, AI-native terminal that sees your entire workspace" 와 핵심 기능 6가지(원격 머신 관리·화면 분할·원격 파일 작업·원격 편집·인라인 웹 브라우저)가 소개된 메인 화면 > ⚠️ 한국 사용자 안내 (2026-05-26 기준): Wave Terminal 공식 빌드는 한국어 IME(한글 조합) 처리에 결함이 있어 한글 입력이 깨지는 문제가 있습니다. 단테가 직접 패치해 만든 한글 입력 정상화 빌드 를 만들어 배포했고, 본가에 PR 도 송부한 상태입니다. 공식 merge 가 끝나기 전까지는 아래 안내드리는 단테 패치 빌드 를 사용하시는 게 가장 매끄럽습니다.

💡 공식 사이트: https://www.waveterm.dev 💡 공식 GitHub: https://github.com/wavetermdev/waveterm (Apache 2.0 오픈소스) 💡 단테 한글 패치 포크: https://github.com/dandacompany/waveterm/releases/tag/v0.14.6 (한글 사용자는 이걸로 다운로드하세요)

왜 Wave Terminal 인가요

Wave Terminal 은 "AI 에이전트와 함께 일하는 명령창" 을 표방하는 오픈소스 터미널입니다. 강의에서 다룰 Claude Code, Codex CLI 같은 명령창 기반 AI 도구들이 가장 매끄럽게 동작하도록 설계됐습니다. 입문자에게 좋은 이유 세 가지를 짚어드릴게요.

1. 한 화면 안에 여러 패널 (블록 UI)

일반 터미널은 창 하나에 명령 한 줄씩 입력하는 구조라, 여러 작업을 동시에 보려면 창을 여러 개 띄워야 합니다. Wave 는 한 탭 안에 여러 패널(블록)을 가로·세로로 자유롭게 배치할 수 있습니다.

예를 들어 좌측 상단엔 헤르메스 에이전트 터미널, 우측 상단엔 관련 웹페이지를 띄운 브라우저, 좌측 하단엔 프로세스 모니터, 우측 하단엔 CPU·메모리 그래프. 이 네 가지를 한 화면에서 동시에 보실 수 있습니다. 단테 강의 영상에서도 단테는 Wave 위에서 작업합니다.

Wave Terminal 한 탭 안에 네 개 블록(헤르메스 터미널 · 브라우저 · 프로세스 모니터 · CPU 메모리 그래프)이 분할된 작업 화면 예시 ### 2. 인라인 미리보기

Wave 안에서 이미지·PDF·CSV·Markdown 파일을 명령창을 떠나지 않고 바로 미리볼 수 있습니다. 일반 터미널은 cat image.png 가 깨진 글자만 출력하지만, Wave 는 파일을 클릭하면 옆 패널에 이미지가 뜹니다. 헤르메스 에이전트가 만든 결과물을 빠르게 확인하기 좋습니다.

3. SSH 세션 영구 보존

노트북 뚜껑을 닫거나 네트워크가 잠시 끊겨도 SSH 연결이 끊기지 않습니다. 미니PC 에 SSH 로 접속해 작업하다 자리 옮길 때 매번 다시 접속하는 번거로움이 사라집니다.

Wave Terminal, 한 줄 정의

Wave Terminal 은 블록 UI · 인라인 미리보기 · 영구 SSH · BYOK(본인 AI 키 등록) 를 묶어, 명령창 안에서 AI 에이전트를 가장 자연스럽게 운영할 수 있게 만든 오픈소스 터미널 입니다.

설치 (권장 방법): 한글 패치 빌드

공식 빌드 대신 단테 한글 패치 빌드 를 사용하시면 한글 입력이 깨지지 않습니다. 그 외 기능은 공식과 완전히 동일합니다.

👉 https://github.com/dandacompany/waveterm/releases/tag/v0.14.6

dandacompany/waveterm 의 IME composition test 릴리즈 페이지에서 macOS · Windows · Linux 별 11종 설치 자산이 빨간 박스로 강조된 화면 릴리즈 페이지 아래쪽 Assets 항목에서 본인 운영체제에 맞는 파일을 받으시면 됩니다.

macOS

Apple Silicon (M1·M2·M3·M4) 사용자는 파일명에 arm64 가 포함된 .dmg 또는 .zip 을 선택
Intel Mac 사용자는 파일명에 x64 가 포함된 자산을 선택
받은 .dmg 를 더블 클릭해 마운트한 뒤, 안의 Wave 앱을 Applications 폴더로 드래그

Windows

파일명에 win 이 포함된 .exe 또는 .zip 을 받습니다 (최근 5년 안에 산 PC 라면 대부분 64-bit)
다운로드한 .exe 를 더블 클릭해 설치 마법사 실행
Windows Defender 가 "PC 보호" 경고를 띄우면 "추가 정보" 를 누른 뒤 "실행" 으로 진행
옵션은 모두 기본값으로 진행. 설치 경로 변경 불필요.

Linux

본인 배포판에 맞는 자산을 선택합니다.

Ubuntu·Debian 계열: .deb 파일을 받아 sudo apt install ./Wave-*.deb
Fedora·RHEL 계열: .rpm 파일을 받아 sudo dnf install ./Wave-*.rpm
그 외: .AppImage 받아서 실행 권한 부여 후 더블 클릭 (chmod +x Wave-*.AppImage)

설치 (대안): 공식 빌드

한글을 거의 안 치시거나, 단테 패치가 본가 merge 된 이후 정식판으로 옮기실 때 사용합니다.

👉 https://www.waveterm.dev/download

공식 사이트에서 본인 OS 용 설치 파일을 받아 같은 방식으로 진행하시면 됩니다. 본가 merge 가 완료되면 이 가이드를 업데이트해 공식 빌드를 첫 권장으로 옮길 예정입니다.

첫 실행

Wave 를 처음 실행하면 다음 두 가지를 거칩니다.

사용 통계 수집 동의: 본인 판단으로 허용 또는 거부. 강의 진행에는 영향 없습니다.
워크스페이스 자동 생성: 빈 터미널 패널 하나가 뜬 기본 워크스페이스가 만들어집니다.

Wave Terminal 첫 실행 직후 기본 워크스페이스. 좌측 Wave AI Welcome 패널, 우측 상단 빈 터미널, 우측 하단 CPU 그래프가 함께 뜬 모습 빈 패널에서 익숙한 명령 한두 줄을 쳐 보시면 일반 터미널과 동일하게 동작합니다. ls, pwd, echo hello 정도면 충분합니다.

한글 입력 테스트 (패치 빌드 사용자)

패치 빌드를 깔았다면 한글 입력이 정상 동작하는지 한 번 확인하세요. 빈 패널에서 echo 명령 뒤에 한글을 입력해봅니다.

echo "안녕하세요 단테랩스"

출력이 깨지지 않고 그대로 나오면 패치가 잘 적용된 것입니다.

핵심 사용법

패널 분할 (가장 자주 쓰는 기능)

Wave 의 핵심은 패널을 자유롭게 쪼개는 것 입니다.

가로 분할: Cmd/Ctrl + D 로 현재 패널 오른쪽에 새 패널 추가
세로 분할: Cmd/Ctrl + Shift + D 로 현재 패널 아래에 새 패널 추가
패널 닫기: Cmd/Ctrl + W
패널 사이 이동: Cmd/Ctrl + 화살표 또는 마우스 클릭

Wave Terminal 한 탭 안에 좌측은 Hermes Agent 터미널, 우측은 강의 학습 페이지를 띄운 브라우저 패널을 함께 배치한 화면. 우측 사이드바의 web 아이콘이 빨간 박스로 강조돼 브라우저 패널 추가 메뉴 위치를 보여줌 작업 중 강의 영상이나 문서를 같이 띄우고 싶으시면 새 블록 추가 메뉴에서 "Web" 을 선택해 브라우저 패널을 띄우실 수도 있습니다.

파일 미리보기

좌측 사이드바의 Files 아이콘을 클릭하면 폴더 트리가 뜹니다. 이미지·PDF·Markdown 파일을 클릭하면 옆 패널에 본문이 인라인으로 표시됩니다.

Markdown 파일은 렌더링된 결과로 보이고, CSV 파일은 표 형태로 정렬돼 나옵니다. 단순히 보기만 가능한 게 아니라 오른쪽 상단의 Edit 버튼으로 그 자리에서 바로 편집할 수도 있어서, 헤르메스 에이전트가 만든 README 나 보고서를 빠르게 훑어보고 즉시 손볼 때 매우 편합니다.

Wave 의 Files 패널에서 README.md 파일을 우클릭해 Open Preview in New Block 메뉴로 미리보기를 열고, 오른쪽 패널의 Edit 버튼으로 즉시 편집할 수 있는 화면 ### SSH 연결 관리

원격 SSH 서버를 자주 쓰신다면 Wave 에 미리 등록해두시면 편합니다. 매번 ssh user@host 를 치지 않아도, 한 번 등록한 서버는 드롭다운에서 클릭 한 번으로 접속됩니다.

1단계. Connections 설정 파일 편집

우측 하단의 Settings(톱니바퀴 아이콘) 를 누르고, 좌측 메뉴의 Connections 탭으로 이동하면 connections.json 편집 화면이 뜹니다. 여기에 자주 쓰는 SSH 서버를 JSON 형식으로 등록합니다.

{
  "example-server": {
    "conn:wsenabled": true,
    "ssh:addkeystoagent": true,
    "ssh:hostname": "your-server-address.com",
    "ssh:identityonly": true,
    "ssh:identityfile": ["~/.ssh/your-private-key"],
    "ssh:user": "your-username"
  },
  "another-server": {
    "conn:wsenabled": true,
    "ssh:hostname": "another-server.com",
    "ssh:user": "another-user"
  }
}

각 키의 의미는 다음과 같습니다.

example-server: 본인이 원하는 별칭. 이 이름이 드롭다운에 표시됩니다.
ssh:hostname: 서버 주소(도메인 또는 IP).
ssh:user: 접속할 사용자 이름.
ssh:identityfile: SSH 개인 키 경로 (선택사항). 비밀번호 접속이면 생략 가능합니다.

여러 서버는 같은 형식으로 항목을 늘려가시면 됩니다. 입력 후 우측 상단의 Save 버튼을 누르면 저장됩니다.

Wave Config 의 Connections 탭에서 SSH 원격 서버 정보를 JSON 형식(example-server, another-server)으로 등록하는 편집 화면 2단계. 등록한 서버에 접속

새 터미널 블록을 열고, 블록 상단 헤더의 왼쪽 컴퓨터 아이콘을 클릭하면 드롭다운이 뜹니다. 방금 등록한 서버들이 Remote 섹션에 표시되니, 원하는 항목을 클릭하면 그 자리에서 SSH 접속이 시작됩니다.

Wave 터미널 블록 헤더 좌측 아이콘을 클릭해 뜬 드롭다운에서 등록된 원격 서버 목록(user@remote-server, user@server-dev 등)이 표시되고 그중 하나를 선택해 접속하는 화면 SSH 키 인증을 미리 설정해두셨다면 비밀번호 입력 없이 바로 들어갑니다. 처음 접속할 때만 "이 호스트를 신뢰하시겠습니까?" 확인이 한 번 뜨고, 이후로는 자동입니다.

wsh CLI — AI 에 명령 결과 파이프

Wave 가 함께 깔아주는 자체 명령 wsh 가 있습니다. 명령 결과를 AI 에 그대로 전달할 수 있어요.

ls -la | wsh ai - "용량 큰 파일 5개만 표 형태로 정리해줘"

이런 패턴은 셸 결과를 직접 AI 에 던질 때 유용합니다. 다만 사용하려면 다음 단계의 AI 키 등록이 먼저 필요합니다.

(선택) AI 키 등록과 모델 연결 (BYOK)

Wave 의 내장 AI 를 쓰려면 본인 AI 키 를 등록해야 합니다. Wave 가 자체 AI 비용을 받지 않고, 본인 OpenAI · Anthropic · Google · OpenRouter 키를 그대로 가져다 쓰는 방식입니다 (BYOK = Bring Your Own Key).

1단계. API 키 등록 (Secrets 탭)

우측 하단의 Settings (톱니바퀴 아이콘) 를 누르고, 좌측 메뉴의 Secrets 탭으로 이동합니다. Add New Secret 버튼을 눌러 키를 추가합니다. 키 이름은 본인이 정하시되, 모델 설정에서 동일한 이름으로 참조하니 알아보기 쉬운 대문자 이름(예: OPENROUTER_KEY, OPENAI_KEY)을 권장합니다.

Wave Config 의 Secrets 탭에서 OPENROUTER_KEY 가 등록된 모습과 CLI Access 영역에 명령 사용법이 표시된 화면 Add New Secret 버튼을 누르면 입력 폼이 뜹니다. Secret Name 칸에 키 이름을 (예: OPENROUTER_KEY), Secret Value 칸에 실제 키 값을 붙여넣은 뒤 우측 하단의 Add Secret 버튼을 누르면 등록이 완료됩니다.

Add New Secret 폼 화면. Secret Name 입력란과 Secret Value 입력란, 그리고 우측 하단 Add Secret 버튼이 빨간 박스로 강조된 모습 키 등록은 GUI 외에 CLI 로도 가능합니다. 같은 화면 아래쪽의 CLI Access 영역에 안내된 명령을 터미널 블록에서 그대로 쓰시면 됩니다.

# 등록된 시크릿 전체 목록 보기
wsh secret list

# 특정 시크릿 값 확인
wsh secret get OPENROUTER_KEY

# 새 시크릿 등록 또는 갱신
wsh secret set OPENROUTER_KEY=sk-or-v1-...

스크립트로 일괄 등록하거나, dotenv 파일에서 한꺼번에 옮기실 때 CLI 방식이 편합니다.

2단계. 모델 연결 (Wave AI Modes 탭)

키를 등록했으면 Settings → Wave AI Modes 탭으로 이동해 waveai.json 을 편집합니다. 이 파일에 "어떤 공급자의 어떤 모델을 쓸지" 를 항목별로 정의해두면, Wave AI 패널 상단 드롭다운에 모드로 추가됩니다.

다음은 OpenRouter 의 DeepSeek-V4-Flash 모델을 등록하는 예시입니다.

{
  "openrouter-deepseek-v4-flash": {
    "display:name": "OpenRouter - DeepSeek-V4-Flash",
    "ai:provider": "openrouter",
    "ai:model": "deepseek/deepseek-v4-flash",
    "ai:capabilities": ["tools"]
  }
}

각 키의 의미는 다음과 같습니다.

모드 식별자 (openrouter-deepseek-v4-flash): 본인이 정하는 내부 키. 중복만 안 되면 자유.
display:name: 드롭다운에 표시될 이름.
ai:provider: 공급자 식별자. openai / anthropic / google / openrouter / ollama 등이 가능합니다.
ai:model: 공급자 측 모델 ID.
ai:capabilities: 도구 호출(tools), 이미지 입력(vision) 등 기능 플래그.

ai:provider 가 openrouter 면 Wave 가 자동으로 Secrets 탭에서 OPENROUTER_KEY 를 찾아 인증에 씁니다. 다른 공급자도 같은 규칙으로 매칭되니, Secrets 의 키 이름을 표준 형식(<PROVIDER>_KEY)으로 정해두시면 추가 설정이 거의 필요 없습니다.

Wave Config 의 Wave AI Modes 탭에서 waveai.json 에 OpenRouter DeepSeek-V4-Flash 모델이 등록된 JSON 편집 화면 설정 후 Wave AI 패널 상단의 모드 드롭다운에서 방금 추가한 항목을 선택하면 그 모델로 대화가 시작됩니다.

로컬 LLM (Ollama, LM Studio) 도 같은 방식으로 등록할 수 있습니다. 다만 강의 진행에는 Claude Code · Codex CLI 가 메인이라, Wave 내장 AI 는 보조 용도로만 쓰셔도 충분합니다.

Widget Context — Wave AI 가 화면 안 모든 블록을 직접 읽는다

Wave AI 가 다른 AI 챗봇과 결정적으로 다른 점은 같은 워크스페이스 안의 다른 블록(터미널 출력, 파일 트리, 미리보기 등)을 자동으로 읽어 분석에 활용한다 는 점입니다. 일반 챗봇은 파일을 첨부하거나 명령 결과를 복사·붙여넣기 해줘야 보는데, Wave AI 는 옆 블록을 그대로 봅니다.

활성화 방법은 단순합니다. Wave AI 패널 상단의 Widget Context 토글을 ON 으로 켜면 끝입니다. OFF 일 때는 일반 챗봇처럼 격리된 상태로 동작합니다.

예를 들어 옆 터미널 블록에서 ls -al 을 친 뒤 Wave AI 에 "위젯 컨텍스트 분석해봐" 라고 물으면, Wave AI 가 터미널 스크롤백을 읽어와 어느 프로젝트인지 파악하고, 거기서 추가로 주요 파일들을 자동으로 열어서 본문까지 훑은 뒤 답변을 만들어 줍니다.

이 기능 덕에 "이 명령 결과 어떻게 해석해야 돼?", "이 프로젝트 구조 요약해줘" 같은 질문을 추가 입력 없이 한 줄로 던질 수 있습니다. 헤르메스 에이전트가 만든 코드나 출력물을 빠르게 점검할 때 특히 유용합니다.

입문자 팁

첫 1주일은 한 가지 기능씩: 처음부터 모든 기능을 익히려 하면 부담스럽습니다. 1주 차에는 패널 분할만, 2주 차에는 SSH 등록, 3주 차에 미리보기. 이 순서가 자연스럽습니다.
기본 셸은 그대로: Mac 사용자는 zsh, Windows 사용자는 PowerShell 이 Wave 안에서도 기본으로 동작합니다. 설정을 굳이 바꾸실 필요가 없어요.
단축키 외우려 하지 말기: Wave 의 키 단축키는 메뉴에서 마우스로 누르는 것과 동일합니다. 자주 쓰는 두세 가지만 자연스럽게 익히고, 나머지는 메뉴에서 그때그때 찾으시면 됩니다.
테마는 마지막에: 화면 색깔 바꾸기는 학습이 끝난 후 취향에 맞게. 처음에는 기본 테마로 익숙해지는 게 우선입니다.

자주 만나는 문제

한글 입력이 여전히 깨짐: 공식 빌드를 받으셨을 가능성이 큽니다. 위 "한글 패치 빌드" 섹션의 dandacompany 릴리즈 페이지에서 다시 받아 재설치하세요.
Windows Defender 가 막음: "추가 정보" 를 누른 뒤 "실행" 으로 진행하시면 됩니다. Wave 는 Apache 2.0 오픈소스라 코드가 공개돼 있어 안전합니다.
Linux AppImage 가 안 켜짐: chmod +x Wave-*.AppImage 로 실행 권한을 먼저 부여하세요.
wsh 명령을 못 찾음: Wave 가 자동으로 wsh 를 시스템 PATH 에 추가하지만, 가끔 누락됩니다. Settings 의 Terminal 탭에서 "Install wsh CLI" 버튼을 한 번 더 클릭하시면 해결됩니다.

Wave Terminal 설치 및 사용 가이드

Wave Terminal 설치 및 사용 가이드

왜 Wave Terminal 인가요

1. 한 화면 안에 여러 패널 (블록 UI)

3. SSH 세션 영구 보존

Wave Terminal, 한 줄 정의

설치 (권장 방법): 한글 패치 빌드

macOS

Windows

Linux

설치 (대안): 공식 빌드

첫 실행

한글 입력 테스트 (패치 빌드 사용자)

핵심 사용법

패널 분할 (가장 자주 쓰는 기능)

파일 미리보기

wsh CLI — AI 에 명령 결과 파이프

(선택) AI 키 등록과 모델 연결 (BYOK)

Widget Context — Wave AI 가 화면 안 모든 블록을 직접 읽는다

입문자 팁

자주 만나는 문제

댓글