TUI

빠른 시작

Gateway 모드

1. Gateway를 시작합니다.

openclaw gateway

2. TUI를 엽니다.

openclaw tui

3. 메시지를 입력하고 Enter를 누릅니다.

원격 Gateway:

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

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

로컬 모드

Gateway 없이 TUI를 실행합니다.

openclaw chat# oropenclaw tui --local

참고:

• openclaw chat 및 openclaw terminal은 openclaw tui --local의 별칭입니다.
• --local은 --url, --token 또는 --password와 함께 사용할 수 없습니다.
• 로컬 모드는 내장된 에이전트 런타임을 직접 사용합니다. 대부분의 로컬 도구는 작동하지만 Gateway 전용 기능은 사용할 수 없습니다.
• 설정 파일에 작성된 설정이 있으면 openclaw 및 openclaw crestodian도 이 TUI 셸을 사용하며, Crestodian이 로컬 설정 및 복구 채팅 백엔드 역할을 합니다.

보이는 항목

• 헤더: 연결 URL, 현재 에이전트, 현재 세션.
• 채팅 로그: 사용자 메시지, 어시스턴트 응답, 시스템 알림, 도구 카드.
• 상태 줄: 연결/실행 상태(연결 중, 실행 중, 스트리밍 중, 유휴, 오류).
• 푸터: 에이전트 + 세션 + 모델 + 목표 상태 + 생각/빠름/상세/추적/reasoning + 토큰 수 + 전달. tui.footer.showRemoteHost가 활성화되면 원격 Gateway 연결에도 연결 호스트가 표시됩니다.
• 입력: 자동 완성이 있는 텍스트 편집기.

멘탈 모델: 에이전트 + 세션

• 에이전트는 고유한 슬러그입니다(예: main, research). Gateway는 목록을 노출합니다.

• 세션은 현재 에이전트에 속합니다.

• 세션 키는 agent:<agentId>:<sessionKey>로 저장됩니다.

  • /session main을 입력하면 TUI가 이를 agent:<currentAgent>:main으로 확장합니다.
  • /session agent:other:main을 입력하면 해당 에이전트 세션으로 명시적으로 전환합니다.

• 세션 범위:

  • per-sender(기본값): 각 에이전트에 여러 세션이 있습니다.
  • global: TUI는 항상 global 세션을 사용합니다(선택기가 비어 있을 수 있음).

• 현재 에이전트 + 세션은 항상 푸터에 표시됩니다.

• 로컬이 아닌 URL 기반 연결에서 Gateway 호스트를 표시하려면 다음으로 활성화하세요.

  openclaw config set tui.footer.showRemoteHost true

  루프백 및 내장 로컬 연결에는 호스트 레이블이 표시되지 않습니다.

• 세션에 목표가 있으면 푸터에 Pursuing goal, Goal paused (/goal resume) 또는 Goal achieved와 같은 간결한 상태가 표시됩니다.

• --session 없이 시작하면, Gateway 모드 TUI는 해당 세션이 아직 존재하는 경우 동일한 Gateway, 에이전트, 세션 범위에 대해 마지막으로 선택한 세션을 다시 시작합니다. --session, /session, /new 또는 /reset 전달은 계속 명시적입니다.

전송 + 전달

• 메시지는 Gateway로 전송되며, 공급자로의 전달은 기본적으로 꺼져 있습니다.
• TUI는 WebChat과 같은 내부 소스 표면이지, 일반적인 아웃바운드 채널이 아닙니다. 표시되는 응답에 tools.message가 필요한 하네스는 대상 없는 message.send로 활성 TUI 턴을 충족할 수 있습니다. 명시적인 공급자 전달은 여전히 일반 구성 채널을 사용하며 lastChannel로 대체되지 않습니다.
• 전달 켜기:
  • /deliver on
  • 또는 설정 패널
  • 또는 openclaw tui --deliver로 시작

선택기 + 오버레이

• 모델 선택기: 사용 가능한 모델을 나열하고 세션 재정의를 설정합니다.
• 에이전트 선택기: 다른 에이전트를 선택합니다.
• 세션 선택기: 지난 7일 동안 업데이트된 현재 에이전트의 세션을 최대 50개까지 표시합니다. 이전에 알고 있는 오래된 세션으로 이동하려면 /session <key>를 사용하세요.
• 설정: 전달, 도구 출력 확장, 생각 표시 여부를 전환합니다.

키보드 단축키

• Enter: 메시지 보내기
• Esc: 활성 실행 중단
• Ctrl+C: 입력 지우기(종료하려면 두 번 누르기)
• Ctrl+D: 종료
• Ctrl+L: 모델 선택기
• Ctrl+G: 에이전트 선택기
• Ctrl+P: 세션 선택기
• Ctrl+O: 도구 출력 확장 전환
• Ctrl+T: 생각 표시 여부 전환(히스토리 다시 로드)

슬래시 명령

코어:

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

세션 제어:

• /think <off|minimal|low|medium|high>
• /fast <status|on|off>
• /verbose <on|full|off>
• /trace <on|off>
• /reasoning <on|off|stream>
• /usage <off|tokens|full|reset>(reset/inherit/clear/default는 세션 재정의를 지웁니다)
• /goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear
• /elevated <on|off|ask|full>(별칭: /elev)
• /activation <mention|always>
• /deliver <on|off>

세션 수명 주기:

• /new 또는 /reset(세션 재설정)
• /abort(활성 실행 중단)
• /settings
• /exit

로컬 모드 전용:

• /auth [provider]는 TUI 내부에서 공급자 인증/로그인 흐름을 엽니다.

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

로컬 셸 명령

• TUI 호스트에서 로컬 셸 명령을 실행하려면 줄 앞에 !를 붙입니다.
• TUI는 세션당 한 번 로컬 실행 허용 여부를 묻습니다. 거부하면 해당 세션에서 !가 비활성화된 상태로 유지됩니다.
• 명령은 TUI 작업 디렉터리에서 새로운 비대화형 셸로 실행됩니다(영구적인 cd/env 없음).
• 로컬 셸 명령은 환경에서 OPENCLAW_SHELL=tui-local을 받습니다.
• 단독 !는 일반 메시지로 전송되며, 앞의 공백은 로컬 실행을 트리거하지 않습니다.

로컬 TUI에서 설정 복구

현재 설정이 이미 검증을 통과하고, 동일한 머신에서 내장 에이전트가 이를 검사하고 문서와 비교하며 실행 중인 Gateway에 의존하지 않고 드리프트를 복구하도록 돕고 싶을 때 로컬 모드를 사용하세요.

openclaw config validate가 이미 실패하는 경우 먼저 openclaw configure 또는 openclaw doctor --fix로 시작하세요. openclaw chat은 잘못된 설정 가드를 우회하지 않습니다.

일반적인 루프:

1. 로컬 모드를 시작합니다.

openclaw chat

2. 에이전트에게 확인할 내용을 요청합니다. 예:

Compare my gateway auth config with the docs and suggest the smallest fix.

3. 정확한 증거 및 검증을 위해 로컬 셸 명령을 사용합니다.

!openclaw config file!openclaw docs gateway auth token secretref!openclaw config validate!openclaw doctor

4. openclaw config set 또는 openclaw configure로 좁은 변경을 적용한 다음 !openclaw config validate를 다시 실행합니다.
5. Doctor가 자동 마이그레이션 또는 복구를 권장하면 이를 검토하고 !openclaw doctor --fix를 실행합니다.

팁:

• openclaw.json을 직접 편집하는 것보다 openclaw config set 또는 openclaw configure를 선호하세요.
• openclaw docs "<query>"는 동일한 머신에서 라이브 문서 인덱스를 검색합니다.
• openclaw config validate --json은 구조화된 스키마와 SecretRef/해결 가능성 오류가 필요할 때 유용합니다.

도구 출력

• 도구 호출은 인수 + 결과가 포함된 카드로 표시됩니다.
• Ctrl+O는 접힌 보기와 확장된 보기 사이를 전환합니다.
• 도구가 실행되는 동안 부분 업데이트가 동일한 카드로 스트리밍됩니다.

터미널 색상

• TUI는 어시스턴트 본문 텍스트를 터미널의 기본 전경색으로 유지하여 어두운 터미널과 밝은 터미널 모두에서 읽기 쉽게 합니다.
• 터미널이 밝은 배경을 사용하고 자동 감지가 잘못된 경우 openclaw tui를 실행하기 전에 OPENCLAW_THEME=light를 설정하세요.
• 대신 원래의 어두운 팔레트를 강제로 사용하려면 OPENCLAW_THEME=dark를 설정하세요.

히스토리 + 스트리밍

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

연결 세부 정보

• TUI는 Gateway에 mode: "tui"로 등록됩니다.
• 재연결은 시스템 메시지를 표시하며, 이벤트 공백은 로그에 표시됩니다.

옵션

• --local: 로컬 내장 에이전트 런타임에 대해 실행
• --url <url>: Gateway WebSocket URL(기본값은 설정 또는 ws://127.0.0.1:<port>)
• --token <token>: Gateway 토큰(필요한 경우)
• --password <password>: Gateway 비밀번호(필요한 경우)
• --session <key>: 세션 키(기본값: main, 범위가 전역이면 global)
• --deliver: 어시스턴트 응답을 공급자에게 전달(기본값 꺼짐)
• --thinking <level>: 전송에 사용할 생각 수준 재정의
• --message <text>: 연결 후 초기 메시지 보내기
• --timeout-ms <ms>: 에이전트 제한 시간(ms)(기본값은 agents.defaults.timeoutSeconds)
• --history-limit <n>: 로드할 히스토리 항목(기본값 200)

문제 해결

메시지를 보낸 후 출력이 없음:

• TUI에서 /status를 실행하여 Gateway가 연결되어 있고 유휴/사용 중인지 확인합니다.
• Gateway 로그를 확인합니다: openclaw logs --follow.
• 에이전트가 실행될 수 있는지 확인합니다: openclaw status 및 openclaw models status.
• 채팅 채널에 메시지가 표시되길 기대하는 경우 전달을 활성화하세요(/deliver on 또는 --deliver).

연결 문제 해결

• disconnected: Gateway가 실행 중이고 --url/--token/--password가 올바른지 확인하세요.
• 선택기에 에이전트 없음: openclaw agents list와 라우팅 설정을 확인하세요.
• 빈 세션 선택기: 전역 범위에 있거나 아직 세션이 없을 수 있습니다.

관련 항목

• Control UI — 웹 기반 제어 인터페이스
• 설정 — openclaw.json 검사, 검증 및 편집
• Doctor — 안내형 복구 및 마이그레이션 검사
• CLI 참조 — 전체 CLI 명령 참조