[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 4/12화: opencode TUI 단축키 완전 정복 — 키보드만으로 코딩하기

이 글은 「opencode 12일 집중」 시리즈의 4일차로, opencode TUI를 키보드만으로 자유자재로 다루는 방법을 다룹니다.

어제는 BYOK 설정으로 75개 이상의 프로바이더 중 최적의 모델을 골라 연결하는 방법을 다뤘습니다. 오늘부터는 Phase 2 — 핵심 사용법 구간에 진입합니다. 첫 주제는 TUI 그 자체, 키보드만으로 모든 것을 해결하는 워크플로우입니다.

마우스를 내려놓으면 속도가 달라진다

터미널 기반 AI 코딩 도구를 쓰면서 마우스에 손이 가는 순간, 이미 컨텍스트 스위칭이 일어나고 있습니다. opencode의 TUI는 Go의 Bubble Tea 프레임워크 위에 만들어졌고, 모든 조작이 키보드 하나로 완결되도록 설계되어 있습니다. 오늘 이 단축키 체계를 손에 익혀 두면, 내일부터 다룰 Plan/Build 모드 전환이나 내장 툴 활용이 체감 2배 이상 빨라집니다.

오늘의 핵심 3가지

• Leader 키(Ctrl+X) 체계 — 모든 고급 조작의 관문. 두 번째 키 하나로 모델 전환, 세션 관리, 자동 승인까지 제어합니다.
• TUI 레이아웃 구조 파악 — 입력창·대화 영역·상태 바의 정보 흐름을 이해하면 시선 이동이 최소화됩니다.
• 테마·키바인드 커스터마이징 — config.toml 한 파일로 색상, 폰트 스타일, 단축키 매핑을 내 손에 맞게 바꿉니다.

TUI 레이아웃 한눈에 보기

opencode를 실행하면 터미널 전체를 채우는 TUI가 나타납니다. 크게 세 영역으로 나뉩니다.

• 상단 — 대화 영역(Chat Pane): AI와의 대화 이력이 표시됩니다. 코드 블록은 구문 강조가 적용되고, diff가 있으면 색상으로 변경분을 보여줍니다.
• 하단 — 입력 영역(Input Pane): 프롬프트를 입력하는 곳입니다. 여러 줄 입력이 가능하고, @를 누르면 파일 퍼지 검색이 즉시 열립니다.
• 최하단 — 상태 바(Status Bar): 현재 모드(Plan/Build), 연결된 모델명, 토큰 사용량, 세션 ID 등 핵심 정보가 한 줄에 표시됩니다.

사이드 패널은 기본적으로 숨겨져 있다가 파일 탐색이나 세션 목록을 열 때 나타납니다. 터미널 폭이 충분하면(120컬럼 이상 권장) 대화 영역과 나란히 표시되어 컨텍스트를 놓치지 않습니다.

Bubble Tea가 주는 이점

opencode의 TUI는 Go 생태계에서 가장 널리 쓰이는 터미널 UI 프레임워크인 Bubble Tea로 구현되어 있습니다. 단순한 텍스트 출력이 아니라, 구조화된 컴포넌트 모델 위에서 렌더링과 이벤트 처리가 분리되어 있어서 키 입력 반응이 빠르고, 화면 깜빡임 없이 부드럽게 갱신됩니다. Vim이나 tmux에 익숙한 분이라면 이질감 없이 적응할 수 있는 수준입니다.

Leader 키 — 모든 고급 조작의 시작점

opencode TUI의 조작 체계는 Leader 키 패턴을 따릅니다. Vim의 leader 키나 tmux의 prefix 키(Ctrl+B)와 같은 개념입니다. opencode에서 leader 키는 Ctrl+X입니다.

작동 방식은 간단합니다. Ctrl+X를 누르면 상태 바에 “waiting for key…” 같은 힌트가 잠깐 표시되고, 이어서 누르는 두 번째 키에 따라 동작이 결정됩니다. 두 키를 동시에 누르는 것이 아니라, 순차적으로 누른다는 점이 중요합니다.

Leader 키 단축키 치트시트

아래는 실무에서 가장 자주 쓰게 될 조합입니다. 이 표 하나를 모니터 옆에 붙여 두면 일주일 안에 손에 익습니다.

키 조합	동작	언제 쓰나
Ctrl+X → ?	도움말 / 단축키 목록 표시	단축키가 기억나지 않을 때. 이것만 외워도 나머지를 찾을 수 있습니다
Ctrl+X → m	모델 선택기 열기	작업 도중 모델을 바꾸고 싶을 때 (예: 빠른 응답용 → 정밀 추론용)
Ctrl+X → s	세션 선택기 열기	이전 대화 세션으로 돌아가거나 새 세션을 시작할 때
Ctrl+X → t	테마 선택기 열기	다크/라이트 전환, 색상 테마 변경
Ctrl+X → a	자동 승인 토글	파일 수정 시 매번 확인 묻는 것을 끄거나 켤 때
Ctrl+X → c	대화 압축 (/compact)	토큰이 많이 쌓여 컨텍스트를 정리하고 싶을 때
Ctrl+X → q	종료	세션을 끝낼 때 (세션은 자동 저장됨)

Leader 키 없이 바로 쓰는 단축키

Leader 키 조합 외에도, 입력 영역에서 바로 사용 가능한 단축키들이 있습니다.

키	동작	비고
Tab	Plan ↔ Build 모드 전환	5일차에서 자세히 다룹니다
@	파일 퍼지 검색 (멘션)	타이핑 즉시 프로젝트 파일을 검색해서 컨텍스트에 추가
/	슬래시 커맨드 입력	/init, /compact, /clear 등
Ctrl+C	현재 생성 중단	AI가 응답을 생성하는 도중 취소
Ctrl+L	화면 정리	대화 내용은 유지, 화면 렌더링만 새로고침
Esc	팝업/패널 닫기	모델 선택기, 파일 검색 등 열려 있는 패널을 닫음
Enter	프롬프트 전송	여러 줄 입력 시 Shift+Enter로 줄바꿈

실습: 단축키 워크플로우 체험하기

백문이 불여일타입니다. 프로젝트 디렉터리에서 opencode를 실행한 뒤, 아래 순서대로 따라 해 보세요.

# 1. 프로젝트 디렉터리로 이동 후 opencode 실행
cd ~/my-project
opencode

# 2. TUI가 열리면, 먼저 도움말을 확인합니다
#    Ctrl+X 를 누르고, 손을 떼고, ? 를 누릅니다
#    → 사용 가능한 모든 단축키 목록이 표시됩니다

# 3. Esc로 도움말을 닫고, 모델을 확인합니다
#    Ctrl+X → m
#    → 설정된 모델 목록에서 화살표 키로 선택, Enter로 확정

# 4. 모드를 확인합니다
#    상태 바에 현재 모드(Plan 또는 Build)가 표시됩니다
#    Tab 키로 토글해 봅니다

# 5. 파일 멘션을 체험합니다
#    입력창에 @ 를 타이핑합니다
#    → 프로젝트 파일 퍼지 검색이 열립니다
#    → 파일명 일부를 타이핑하면 실시간으로 필터링
#    → Enter로 선택하면 프롬프트에 파일 컨텍스트가 추가됩니다

# 6. 간단한 질문을 던져 봅니다
#    "이 프로젝트의 구조를 설명해 줘" + Enter
#    → AI가 응답하는 동안 Ctrl+C로 중단할 수 있습니다

# 7. 테마를 바꿔 봅니다
#    Ctrl+X → t
#    → 다크/라이트, 색상 계열을 골라 적용

# 8. 세션을 종료합니다
#    Ctrl+X → q

이 8단계를 한 번만 직접 손으로 쳐 보면, leader 키 패턴이 몸에 익기 시작합니다. 핵심은 Ctrl+X를 누르고 잠깐 기다렸다가 두 번째 키를 누르는 리듬입니다.

@ 파일 멘션 — 컨텍스트의 핵심

단축키 중에서 실무 영향이 가장 큰 것은 단연 @ 파일 멘션입니다. AI 코딩 도구의 품질은 결국 “얼마나 정확한 컨텍스트를 주느냐”에 달려 있기 때문입니다.

파일 멘션 활용 패턴

@를 누르면 퍼지 검색 창이 뜹니다. 프로젝트의 모든 파일을 대상으로 하며, 파일명의 일부만 타이핑해도 매칭됩니다.

• 단일 파일 참조: @main.py 이 파일의 에러 핸들링을 개선해 줘 — 해당 파일 전체가 컨텍스트에 들어갑니다.
• 복수 파일 참조: @routes.py @models.py 두 파일 간의 의존성을 분석해 줘 — 여러 @ 멘션을 한 프롬프트에 넣을 수 있습니다.
• 디렉터리 참조: @src/handlers/ 이 디렉터리의 테스트 코드를 작성해 줘 — 디렉터리를 멘션하면 그 안의 파일들이 컨텍스트에 포함됩니다.

퍼지 검색은 .gitignore를 존중합니다. node_modules/나 .venv/ 같은 디렉터리는 기본적으로 제외되므로 검색 결과가 깔끔합니다.

파일 멘션 vs. AI 자체 탐색

opencode의 AI는 내장 툴(6일차에서 상세히 다룹니다)을 사용해 스스로 파일을 읽을 수 있습니다. 하지만 @ 멘션으로 미리 파일을 지정해 주면 두 가지 이점이 있습니다.

• 토큰 절약: AI가 파일을 탐색하는 데 쓰는 “도구 호출” 왕복이 줄어듭니다.
• 정확도 향상: 어떤 파일을 봐야 하는지 AI가 추측할 필요 없이, 정확한 파일이 처음부터 컨텍스트에 들어갑니다.

경험 법칙 하나: 수정 대상 파일은 @로 명시적으로 넣고, 관련 파일 탐색은 AI에게 맡기세요. 예를 들어 “이 API 핸들러를 리팩터링해 줘”라고 할 때, 핸들러 파일은 @로 직접 지정하되, 핸들러가 호출하는 서비스 레이어는 AI가 알아서 찾게 두는 식입니다.

테마 커스터마이징

하루 종일 터미널을 보는 개발자에게 색상 테마는 취향이 아니라 생산성입니다. opencode는 여러 빌트인 테마를 제공하고, 설정 파일로 세밀하게 조정할 수 있습니다.

빌트인 테마 전환

가장 빠른 방법은 TUI 안에서 leader 키를 사용하는 것입니다.

# TUI 안에서 (런타임 전환)
# Ctrl+X → t → 화살표로 선택 → Enter

# 또는 config.toml 에서 기본 테마 지정
# ~/.config/opencode/config.toml (Linux/macOS)
# %APPDATA%\opencode\config.toml (Windows)

TUI 안에서 전환한 테마는 즉시 적용되며, 세션이 끝나도 선택이 유지됩니다. catppuccin, dracula, tokyo-night, gruvbox 등 개발자에게 익숙한 계열의 테마를 지원합니다.

설정 파일로 세밀하게 조정하기

config.toml에서 테마를 직접 지정할 수 있습니다.

# config.toml 예시

[tui]
theme = "catppuccin"  # 빌트인 테마명 지정

터미널 에뮬레이터의 색상 설정과 opencode 테마가 충돌하면 글자가 배경에 묻혀 보이지 않는 경우가 있습니다. 이럴 때는 터미널 자체의 색상 스킴과 계열이 같은 opencode 테마를 선택하는 것이 가장 깔끔한 해결책입니다. 예를 들어, 터미널에서 Catppuccin Mocha를 쓰고 있다면 opencode에서도 catppuccin 계열을 맞춰 주는 식입니다.

키바인드 커스터마이징

기본 단축키가 손에 맞지 않거나, 기존 터미널 습관과 충돌하는 경우에는 키바인드를 재정의할 수 있습니다.

흔한 충돌 시나리오

가장 자주 보고되는 충돌은 tmux 사용자에게서 나옵니다. tmux의 기본 prefix가 Ctrl+B이고, 일부 사용자는 이를 Ctrl+X로 바꿔 쓰기 때문입니다. 이 경우 opencode의 leader 키와 정면충돌합니다.

해결 방법은 두 가지입니다.

• tmux 쪽을 변경: tmux의 prefix를 Ctrl+A 등 다른 키로 변경합니다. screen에서 넘어온 사용자에게 자연스러운 선택입니다.
• opencode 쪽을 변경: config.toml에서 opencode의 leader 키를 다른 조합으로 재정의합니다.

# config.toml — leader 키 변경 예시

[keybinds]
leader = "ctrl+a"   # 기본 ctrl+x 대신 ctrl+a 사용

어느 쪽을 바꾸든, 한쪽만 바꾸면 됩니다. 양쪽을 동시에 바꾸면 혼란만 가중됩니다.

개별 키 재정의

leader 키 자체뿐 아니라, leader 이후의 개별 동작 키도 재정의할 수 있습니다.

# config.toml — 개별 키바인드 재정의 예시

[keybinds]
leader = "ctrl+x"          # leader 키는 기본값 유지
model_picker = "p"          # Ctrl+X → p 로 모델 선택기 (기본: m)
session_picker = "l"        # Ctrl+X → l 로 세션 목록 (기본: s)
theme_picker = "h"          # Ctrl+X → h 로 테마 변경 (기본: t)

재정의할 때 주의할 점은, 같은 키를 두 동작에 중복 할당하지 않는 것입니다. 중복이 있으면 opencode가 시작 시 경고를 표시하거나, 나중에 할당된 쪽만 동작합니다.

opencode 실전 키보드 워크플로우 — 5분 시나리오

지금까지 배운 단축키를 엮어서, 실제 작업 하나를 키보드만으로 처리하는 흐름을 따라가 봅니다.

시나리오: “API 엔드포인트에 입력 검증을 추가하라”

# 1단계: opencode 실행 (터미널에서)
cd ~/api-server
opencode

# 2단계: 현재 모드 확인 — 상태 바에 "Plan" 표시
#         먼저 Plan 모드에서 분석부터 하겠습니다
#         (이미 Plan 모드면 그대로, Build면 Tab으로 전환)

# 3단계: 파일 멘션으로 대상 지정 + 분석 요청
#         입력창에 타이핑:
#         @src/routes/users.py 이 엔드포인트들의 입력 검증 현황을 분석해 줘

# 4단계: AI의 분석을 읽고 동의하면, Build 모드로 전환
#         Tab 키 → 상태 바가 "Build"로 변경

# 5단계: 수정 지시
#         @src/routes/users.py @src/schemas/user.py
#         POST /users 엔드포인트에 이메일 형식 검증과 비밀번호 길이 검증을 추가해 줘.
#         Pydantic validator를 사용해.

# 6단계: AI가 파일을 수정합니다 (자동 승인이 꺼져 있으면 y/n 확인)
#         수정 내용이 diff로 표시됩니다

# 7단계: 토큰이 많이 쌓였으면 대화 압축
#         Ctrl+X → c

# 8단계: 작업 완료 후 종료
#         Ctrl+X → q

전체 과정에서 마우스를 한 번도 쓰지 않았습니다. 모드 전환(Tab), 파일 지정(@), 대화 압축(Ctrl+X → c), 종료(Ctrl+X → q) — 네 가지 조작만으로 하나의 작업이 완결됩니다.

상태 바 읽는 법

TUI 최하단의 상태 바에는 항상 네 가지 정보가 표시됩니다. 코딩에 집중하느라 놓치기 쉽지만, 이 한 줄을 주기적으로 확인하는 습관이 실수를 줄여 줍니다.

• 모드 표시: Plan 또는 Build. Build 모드에서만 파일 수정이 실행됩니다. 읽기 전용 분석을 원하는데 Build 모드인 채로 질문하면 AI가 불필요하게 파일을 수정할 수 있습니다.
• 모델명: 현재 사용 중인 모델. 모델을 바꿨다면 여기서 확인하세요.
• 토큰 카운트: 현재 대화의 누적 토큰 수. BYOK 사용 시 비용과 직결됩니다. 숫자가 크게 올라가면 Ctrl+X → c로 압축을 고려하세요.
• 세션 정보: 현재 세션의 식별 정보. 여러 세션을 오갈 때 지금 어디에 있는지 확인하는 데 필수입니다.

효율을 높이는 소소한 팁 세 가지

1. 여러 줄 프롬프트 작성

복잡한 지시를 한 번에 전달하고 싶을 때, Shift+Enter로 줄바꿈을 넣어 여러 줄 프롬프트를 작성할 수 있습니다. 마크다운 리스트 형태로 구조화하면 AI가 더 정확하게 이해합니다.

# 입력창에서 Shift+Enter로 줄바꿈하며 작성:

다음 세 가지를 순서대로 처리해 줘:
1. src/db/connection.py 의 커넥션 풀 사이즈를 5에서 20으로 변경
2. 변경에 맞춰 src/config.py 의 기본값도 수정
3. tests/test_db.py 에 커넥션 풀 테스트 추가

# 작성이 끝나면 Enter로 전송

2. 슬래시 커맨드 빠르게 접근

입력창에서 /를 치면 사용 가능한 슬래시 커맨드 목록이 자동 완성으로 뜹니다. 자주 쓰는 것들만 기억해 두세요.

• /init — AGENTS.md 파일 생성 (7일차에서 상세히 다룹니다)
• /compact — 대화 컨텍스트 압축
• /clear — 대화 초기화
• /undo — 마지막 파일 변경 되돌리기 (Git 기반)
• /redo — 되돌린 변경 다시 적용

3. 자동 승인 모드 활용

파일 수정 시마다 y/n 확인을 받는 것이 기본 동작입니다. 반복적인 리팩터링처럼 신뢰도가 높은 작업을 할 때는 Ctrl+X → a로 자동 승인을 켜 두면 흐름이 끊기지 않습니다. 작업이 끝나면 다시 Ctrl+X → a로 꺼 두는 것을 잊지 마세요.

Gotcha 미니 코너: Leader 키가 안 먹힐 때

함정: Ctrl+X를 눌렀는데 아무 반응이 없다면, 높은 확률로 터미널 에뮬레이터가 해당 키 조합을 먼저 가로채고 있습니다.

대표적인 충돌 사례:

• tmux: prefix를 Ctrl+X로 설정한 경우
• 일부 터미널 에뮬레이터: Ctrl+X가 “잘라내기(Cut)”에 바인딩된 경우 (Windows Terminal의 특정 프로필, 또는 일부 Linux 터미널)
• screen: 기본 escape가 Ctrl+A지만, 커스텀 설정으로 바꾼 경우

해결법: 터미널 에뮬레이터 설정에서 Ctrl+X 바인딩을 해제하거나, 앞서 설명한 대로 opencode의 config.toml에서 leader 키를 다른 조합으로 변경하세요. 진단이 먼저입니다 — 어떤 프로그램이 키를 가로채는지부터 확인하세요.

# 진단 방법: opencode 없이 터미널에서 Ctrl+X를 눌러 봅니다
# - 아무 일도 안 일어나면 → 터미널이 가로채지 않음 (opencode 내부 문제)
# - "잘라내기" 동작이 발생하면 → 터미널 설정에서 해당 바인딩 해제
# - tmux prefix 표시가 바뀌면 → tmux prefix를 다른 키로 변경

# opencode 쪽에서 해결하려면:
# config.toml
[keybinds]
leader = "ctrl+b"   # 또는 충돌하지 않는 다른 조합

키보드 워크플로우 정착을 위한 체크리스트

오늘 다룬 내용을 정착시키기 위해, 일주일간 아래 체크리스트를 의식하며 사용해 보세요.

• ☐ Ctrl+X → ?로 도움말을 열어 본 적 있는가
• ☐ Tab으로 Plan ↔ Build 전환을 해 봤는가
• ☐ @로 파일 멘션을 3번 이상 써 봤는가
• ☐ Ctrl+X → m으로 모델을 전환해 봤는가
• ☐ Ctrl+X → c로 대화를 압축해 봤는가
• ☐ 테마를 한 번 이상 바꿔 봤는가
• ☐ 상태 바의 모드·토큰 수를 의식적으로 확인했는가

7개 중 5개 이상 체크할 수 있다면, 키보드 중심 워크플로우가 자리 잡기 시작한 겁니다.

내일 예고

내일 5일차에서는 오늘 잠깐 맛본 Plan ↔ Build 모드 전환을 본격적으로 파고듭니다. “먼저 읽고, 계획을 세운 뒤, 실행한다” — 미지의 코드베이스를 처음 마주했을 때 가장 안전하고 빠른 접근법입니다.

---