TUI (Terminal UI)

빠른 시작

  1. Gateway를 시작합니다.
openclaw gateway
  1. TUI를 엽니다.
openclaw tui
  1. 메시지를 입력하고 Enter를 누릅니다.

원격 Gateway:

openclaw tui --url ws://<host>:<port> --token <gateway-token>

Gateway가 비밀번호 인증을 사용하는 경우 --password를 사용하세요.

표시되는 내용

  • 헤더: 연결 URL, 현재 agent, 현재 세션.
  • 채팅 로그: 사용자 메시지, assistant 응답, 시스템 알림, tool 카드.
  • 상태 줄: 연결/실행 상태 (연결 중, 실행 중, 스트리밍 중, 유휴, 오류).
  • 푸터: 연결 상태 + agent + 세션 + 모델 + think/verbose/reasoning + 토큰 수 + deliver.
  • 입력: 자동 완성이 있는 텍스트 편집기.

멘탈 모델: agent + 세션

  • Agent는 고유한 slug입니다 (예: main, research). Gateway가 목록을 노출합니다.
  • 세션은 현재 agent에 속합니다.
  • 세션 키는 agent:<agentId>:<sessionKey>로 저장됩니다.
    • /session main을 입력하면, TUI는 이를 agent:<currentAgent>:main으로 확장합니다.
    • /session agent:other:main을 입력하면, 명시적으로 해당 agent 세션으로 전환됩니다.
  • 세션 범위:
    • per-sender (기본값): 각 agent가 많은 세션을 가집니다.
    • global: TUI는 항상 global 세션을 사용합니다 (picker가 비어 있을 수 있음).
  • 현재 agent + 세션은 항상 푸터에 표시됩니다.

전송 + 전달

  • 메시지는 Gateway로 전송됩니다. provider로의 전달은 기본적으로 꺼져 있습니다.
  • 전달 켜기:
    • /deliver on
    • 또는 Settings 패널
    • 또는 openclaw tui --deliver로 시작

Picker + 오버레이

  • 모델 picker: 사용 가능한 모델을 나열하고 세션 재정의를 설정합니다.
  • Agent picker: 다른 agent를 선택합니다.
  • 세션 picker: 현재 agent에 대한 세션만 표시합니다.
  • Settings: deliver, tool 출력 확장 및 thinking 가시성을 토글합니다.

키보드 단축키

  • Enter: 메시지 전송
  • Esc: 활성 실행 중단
  • Ctrl+C: 입력 지우기 (두 번 누르면 종료)
  • Ctrl+D: 종료
  • Ctrl+L: 모델 picker
  • Ctrl+G: agent picker
  • Ctrl+P: 세션 picker
  • Ctrl+O: tool 출력 확장 토글
  • Ctrl+T: thinking 가시성 토글 (히스토리 다시 로드)

슬래시 명령어

핵심:

  • /help
  • /status
  • /agent <id> (또는 /agents)
  • /session <key> (또는 /sessions)
  • /model <provider/model> (또는 /models)

세션 제어:

  • /think <off|minimal|low|medium|high>
  • /verbose <on|full|off>
  • /reasoning <on|off|stream>
  • /usage <off|tokens|full>
  • /elevated <on|off|ask|full> (별칭: /elev)
  • /activation <mention|always>
  • /deliver <on|off>

세션 라이프사이클:

  • /new 또는 /reset (세션 리셋)
  • /abort (활성 실행 중단)
  • /settings
  • /exit

기타 Gateway 슬래시 명령어 (예: /context)는 Gateway로 전달되고 시스템 출력으로 표시됩니다. Slash commands를 참조하세요.

로컬 셸 명령어

  • 줄 앞에 !를 붙여 TUI 호스트에서 로컬 셸 명령어를 실행합니다.
  • TUI는 세션당 한 번 프롬프트하여 로컬 실행을 허용합니다. 거부하면 세션 동안 !가 비활성화됩니다.
  • 명령어는 TUI 작업 디렉토리에서 새롭고 비대화형 셸에서 실행됩니다 (지속적인 cd/env 없음).
  • 단독 !는 일반 메시지로 전송됩니다. 앞에 공백이 있으면 로컬 실행을 트리거하지 않습니다.

Tool 출력

  • Tool 호출은 인수 + 결과가 있는 카드로 표시됩니다.
  • Ctrl+O는 축소/확장 보기 간에 토글합니다.
  • Tool이 실행되는 동안, 부분 업데이트가 동일한 카드로 스트리밍됩니다.

히스토리 + 스트리밍

  • 연결 시, TUI는 최신 히스토리를 로드합니다 (기본값 200개 메시지).
  • 스트리밍 응답은 확정될 때까지 제자리에서 업데이트됩니다.
  • TUI는 더 풍부한 tool 카드를 위해 agent tool 이벤트도 수신합니다.

연결 세부사항

  • TUI는 mode: "tui"로 Gateway에 등록됩니다.
  • 재연결은 시스템 메시지를 표시합니다. 이벤트 간격은 로그에 표시됩니다.

옵션

  • --url <url>: Gateway WebSocket URL (기본값은 config 또는 ws://127.0.0.1:<port>)
  • --token <token>: Gateway token (필요한 경우)
  • --password <password>: Gateway 비밀번호 (필요한 경우)
  • --session <key>: 세션 키 (기본값: main, 또는 범위가 global인 경우 global)
  • --deliver: assistant 응답을 provider에 전달 (기본값 꺼짐)
  • --thinking <level>: 전송 시 thinking 레벨 재정의
  • --timeout-ms <ms>: Agent 타임아웃 (ms) (기본값은 agents.defaults.timeoutSeconds)

문제 해결

메시지 전송 후 출력이 없음:

  • TUI에서 /status를 실행하여 Gateway가 연결되어 있고 유휴/사용 중인지 확인합니다.
  • Gateway 로그를 확인하세요: openclaw logs --follow.
  • Agent가 실행될 수 있는지 확인하세요: openclaw status 및 openclaw models status.
  • 채팅 channel에서 메시지를 기대하는 경우, deliver를 활성화하세요 (/deliver on 또는 --deliver).
  • --history-limit <n>: 로드할 히스토리 항목 수 (기본값 200)

문제 해결

  • disconnected: Gateway가 실행 중이고 --url/--token/--password가 올바른지 확인하세요.
  • Picker에 agent가 없음: openclaw agents list 및 라우팅 설정을 확인하세요.
  • 빈 세션 picker: global 범위에 있거나 아직 세션이 없을 수 있습니다.
← 문서로 돌아가기