한국어
문서
TUI

TUI

OpenCode 터미널 사용자 인터페이스 사용하기.

OpenCode는 LLM과 함께 프로젝트를 작업할 수 있는 대화형 터미널 인터페이스, 즉 TUI를 제공합니다.

OpenCode를 실행하면 현재 디렉터리에 대한 TUI가 시작됩니다.

opencode

또는 특정 작업 디렉터리에 대해 시작할 수도 있습니다.

opencode /path/to/project

TUI에 들어가면 메시지로 프롬프트를 입력할 수 있습니다.

Give me a quick summary of the codebase.

파일 참조

@를 사용해 메시지에서 파일을 참조할 수 있습니다. 이 기능은 현재 작업 디렉터리에서 퍼지 파일 검색을 수행합니다.

팁: @를 사용해 메시지에서 파일을 참조할 수도 있습니다.

How is auth handled in @packages/functions/src/api/index.ts?

해당 파일의 내용이 대화에 자동으로 추가됩니다.

설정된 참조도 @ 자동완성에 표시됩니다. @alias를 입력하면 참조 루트가 컨텍스트로 추가되고, @alias/를 입력하면 해당 참조 내부의 파일이 자동완성됩니다.

Compare our setup with @docs/README.md

Bash 명령어

메시지를 !로 시작하면 셸 명령어를 실행합니다.

!ls -la

명령어의 출력은 도구 결과로 대화에 추가됩니다.

명령어

OpenCode TUI를 사용할 때 / 다음에 명령어 이름을 입력하면 동작을 빠르게 실행할 수 있습니다. 예를 들어:

/help

대부분의 명령어에는 ctrl+x를 기본 리더 키로 사용하는 키보드 단축키도 있습니다. 자세히 보기.

다음은 사용 가능한 모든 슬래시 명령어입니다:

connect

OpenCode에 프로바이더를 추가합니다. 사용 가능한 프로바이더 중에서 선택하고 해당 API 키를 추가할 수 있습니다.

/connect

compact

현재 세션을 압축합니다. 별칭: /summarize

/compact

키 바인딩: ctrl+x c

details

도구 실행 세부 정보 표시를 토글합니다.

/details

editor

메시지 작성을 위해 외부 편집기를 엽니다. EDITOR 환경 변수에 설정된 편집기를 사용합니다. 자세히 보기.

/editor

키 바인딩: ctrl+x e

exit

OpenCode를 종료합니다. 별칭: /quit, /q

/exit

키 바인딩: ctrl+x q

export

현재 대화를 Markdown으로 내보내고 기본 편집기에서 엽니다. EDITOR 환경 변수에 설정된 편집기를 사용합니다. 자세히 보기.

/export

키 바인딩: ctrl+x x

help

도움말 대화 상자를 표시합니다.

/help

init

AGENTS.md를 생성하거나 업데이트하기 위한 가이드 설정입니다. 자세히 보기.

/init

models

사용 가능한 모델을 나열합니다.

/models

키 바인딩: ctrl+x m

new

새 세션을 시작합니다. 별칭: /clear

/new

키 바인딩: ctrl+x n

redo

이전에 취소한 메시지를 다시 실행합니다. /undo를 사용한 후에만 사용할 수 있습니다.

팁: 모든 파일 변경 사항도 복원됩니다.

내부적으로 이 기능은 Git을 사용해 파일 변경 사항을 관리합니다. 따라서 프로젝트는 Git 저장소여야 합니다.

/redo

키 바인딩: ctrl+x r

sessions

세션을 나열하고 전환합니다. 별칭: /resume, /continue

/sessions

키 바인딩: ctrl+x l

share

현재 세션을 공유합니다. 자세히 보기.

/share

themes

사용 가능한 테마를 나열합니다.

/themes

키 바인딩: ctrl+x t

thinking

대화에서 사고/추론 블록의 표시 여부를 토글합니다. 활성화하면 확장된 사고를 지원하는 모델의 추론 과정을 볼 수 있습니다.

참고: 이 명령어는 사고 블록이 표시되는지 여부만 제어합니다. 모델의 추론 기능을 활성화하거나 비활성화하지는 않습니다. 실제 추론 기능을 토글하려면 ctrl+t를 사용해 모델 변형을 순환하세요.

/thinking

undo

대화에서 마지막 메시지를 취소합니다. 가장 최근의 사용자 메시지, 그 이후의 모든 응답, 그리고 모든 파일 변경 사항을 제거합니다.

팁: 적용된 모든 파일 변경 사항도 되돌려집니다.

내부적으로 이 기능은 Git을 사용해 파일 변경 사항을 관리합니다. 따라서 프로젝트는 Git 저장소여야 합니다.

/undo

키 바인딩: ctrl+x u

unshare

현재 세션의 공유를 해제합니다. 자세히 보기.

/unshare

편집기 설정

/editor와 /export 명령어 모두 EDITOR 환경 변수에 지정된 편집기를 사용합니다.

Linux/macOS

# Example for nano or vim
export EDITOR=nano
export EDITOR=vim
 
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
export EDITOR="code --wait"

영구적으로 적용하려면 셸 프로필에 다음을 추가하세요. ~/.bashrc, ~/.zshrc 등.

Windows (CMD)

set EDITOR=notepad
 
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
set EDITOR=code --wait

영구적으로 적용하려면 시스템 속성 > 환경 변수를 사용하세요.

Windows (PowerShell)

$env:EDITOR = "notepad"
 
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
$env:EDITOR = "code --wait"

영구적으로 적용하려면 PowerShell 프로필에 다음을 추가하세요.

인기 있는 편집기 옵션은 다음과 같습니다:

  • code - Visual Studio Code
  • cursor - Cursor
  • windsurf - Windsurf
  • nvim - Neovim 편집기
  • vim - Vim 편집기
  • nano - Nano 편집기
  • notepad - Windows 메모장
  • subl - Sublime Text

참고: VS Code 같은 일부 편집기는 --wait 플래그와 함께 시작해야 합니다.

일부 편집기는 차단 모드로 실행하기 위해 명령줄 인수가 필요합니다. --wait 플래그는 편집기 프로세스가 닫힐 때까지 차단되도록 만듭니다.

설정

tui.json(또는 tui.jsonc)을 통해 TUI 동작을 사용자 지정할 수 있습니다.

tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}

이것은 서버/런타임 동작을 설정하는 opencode.json과는 별개입니다.

keybinds는 내장 기본값과 병합되므로, 변경하려는 단축키만 설정하면 됩니다.

옵션

  • theme - UI 테마를 설정합니다. 자세히 보기 .
  • keybinds - 키보드 단축키를 사용자 지정합니다. 자세히 보기 .
  • leader_timeout - OpenCode가 리더 키 입력 후 대기하는 시간을 제어합니다. 기본값은 2000 입니다.
  • scroll_acceleration.enabled - 부드럽고 자연스러운 스크롤을 위한 macOS 스타일 스크롤 가속을 활성화합니다. 활성화하면 빠른 스크롤 제스처에서는 스크롤 속도가 증가하고, 느린 동작에서는 정밀함을 유지합니다. 이 설정은 scroll_speed보다 우선하며, 활성화 시 이를 재정의합니다.
  • scroll_speed - 스크롤 명령어를 사용할 때 TUI가 스크롤하는 속도를 제어합니다(최솟값: 0.001 , 소수 값 지원). 기본값은 3 입니다. 참고: scroll_acceleration.enabled가 true로 설정되어 있으면 무시됩니다.
  • diff_style - diff 렌더링을 제어합니다. "auto"는 터미널 너비에 맞춰 적응하고, "stacked"는 항상 단일 열 레이아웃을 표시합니다.
  • mouse - TUI에서 마우스 캡처를 활성화하거나 비활성화합니다(기본값: true ). 비활성화하면 터미널의 기본 마우스 선택/스크롤 동작이 유지됩니다.
  • attention - TUI 데스크톱 알림과 사운드를 설정합니다. 기본적으로 비활성화되어 있습니다.

OPENCODE_TUI_CONFIG를 사용해 사용자 지정 TUI 설정 경로를 로드할 수 있습니다.

Attention

TUI는 질문, 권한, 세션 오류, 완료된 세션에 대해 주의를 요청할 수 있습니다. attention.enabled로 활성화하세요. 내장 이벤트는 트리거될 때 사운드를 재생하며, 서브에이전트가 아닌 이벤트는 터미널이 흐려졌을 때만 데스크톱 알림을 요청합니다.

  • enabled - 모든 주의 알림과 사운드를 활성화합니다. 기본값은 false 입니다.
  • notifications - 주의가 활성화되었을 때 터미널을 통한 데스크톱 알림을 허용합니다. 기본값은 true 입니다.
  • sound - 주의가 활성화되었을 때 주의 사운드를 허용합니다. 기본값은 true 입니다.
  • volume - 기본 사운드 볼륨으로 0부터 1까지입니다. 기본값은 0.4 입니다.
  • sound_pack - 사용할 사운드 팩 ID입니다. 기본값은 opencode.default 입니다.
  • sounds - default , question , permission , error , done , 또는 subagent_done 에 대한 사운드 파일을 재정의합니다. 경로는 절대 경로, file:// URL, 또는 tui.json 기준 상대 경로일 수 있습니다.

사용자 지정

명령 팔레트(ctrl+p)를 사용해 TUI 보기의 다양한 측면을 사용자 지정할 수 있습니다. 이러한 설정은 재시작 후에도 유지됩니다.

사용자 이름 표시

채팅 메시지에 사용자 이름이 표시되는지 여부를 토글합니다. 다음을 통해 접근하세요:

  • 명령 팔레트: "username" 또는 "hide username"을 검색
  • 설정은 자동으로 유지되며 TUI 세션 간에 기억됩니다
Windows (WSL)CLI