OpenClaw TUI 터미널 가이드: 1분 만에 터미널에서 AI 연결하기

터미널에서 코딩하다가 AI의 도움이 필요할 때마다 브라우저 창을 여는 건 꽤 번거로운 일이죠. 개발 흐름을 유지하면서 터미널 안에서 바로 AI 에이전트와 소통하고 싶다면 TUI(Terminal UI)가 답이 될 수 있어요.

빠른 시작

Gateway를 시작하세요.

openclaw gateway

TUI를 엽니다.

openclaw tui

메시지를 입력하고 Enter를 누르세요.

Remote Gateway를 사용하는 경우:

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

Gateway에서 패스워드 인증을 사용한다면 --password를 사용하세요.

화면 구성

Header: 연결 URL, 현재 에이전트, 현재 세션 정보가 표시돼요.
Chat log: 사용자 메시지, 어시스턴트 응답, 시스템 알림, 도구 카드가 나타납니다.
Status line: 연결 및 실행 상태(connecting, running, streaming, idle, error)를 보여줘요.
Footer: 연결 상태, 에이전트, 세션, 모델 정보와 함께 think/fast/verbose/reasoning 설정, 토큰 수, deliver 상태가 표시됩니다.
Input: 자동 완성을 지원하는 텍스트 에디터예요.

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

에이전트는 고유한 슬러그(예: main, research)를 가집니다. Gateway가 이 목록을 제공해요.
세션은 현재 에이전트에 속합니다.
세션 키는 agent:<agentId>:<sessionKey> 형식으로 저장돼요.
- /session main이라고 입력하면, TUI는 이를 agent:<currentAgent>:main으로 확장합니다.
- /session agent:other:main이라고 입력하면, 다른 에이전트의 세션으로 명시적으로 전환할 수 있어요.
세션 범위(scope):
- per-sender (기본값): 각 에이전트가 여러 세션을 가집니다.
- global: TUI가 항상 global 세션을 사용합니다 (피커가 비어 있을 수 있어요).
현재 에이전트와 세션은 항상 푸터(footer)에서 확인할 수 있습니다.

전송 및 전달

메시지는 Gateway로 전송되지만, provider로의 전달(delivery)은 기본적으로 꺼져 있어요.
전달 기능을 켜는 방법은 다음과 같습니다:
- /deliver on 입력
- 또는 Settings 패널에서 설정
- 또는 openclaw tui --deliver로 시작

피커 및 오버레이

Model picker: 사용 가능한 모델 목록을 보고 세션 오버라이드를 설정합니다.
Agent picker: 다른 에이전트를 선택합니다.
Session picker: 현재 에이전트의 세션만 보여줍니다.
Settings: deliver 여부, 도구 출력 확장, thinking 노출 여부를 전환할 수 있어요.

키보드 단축키

Enter: 메시지 전송
Esc: 활성화된 실행 중단
Ctrl+C: 입력 내용 지우기 (두 번 누르면 종료)
Ctrl+D: 종료
Ctrl+L: 모델 피커 열기
Ctrl+G: 에이전트 피커 열기
Ctrl+P: 세션 피커 열기
Ctrl+O: 도구 출력 확장 토글
Ctrl+T: thinking 노출 여부 토글 (히스토리를 다시 불러옵니다)

슬래시 명령어

핵심 명령어:

/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>
/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 작업 디렉토리의 새로운 비대화형(non-interactive) 쉘에서 실행됩니다 (지속적인 cd나 환경 변수 유지는 안 돼요).
로컬 쉘 명령어는 환경 변수로 OPENCLAW_SHELL=tui-local을 전달받습니다.
! 하나만 입력하면 일반 메시지로 전송되며, 앞에 공백이 있는 경우 로컬 실행이 트리거되지 않습니다.

도구 출력

도구 호출은 인자(args)와 결과(results)가 포함된 카드로 표시됩니다.
Ctrl+O를 눌러 요약 보기와 확장 보기 사이를 전환할 수 있어요.
도구가 실행되는 동안 부분적인 업데이트 내용이 동일한 카드에 스트리밍됩니다.

터미널 색상

TUI는 어시스턴트의 본문 텍스트를 터미널의 기본 전경색으로 유지하므로, 다크 모드와 라이트 모드 터미널 모두에서 가독성이 좋습니다.
라이트 배경 터미널을 사용하는데 자동 감지가 잘못되었다면, openclaw tui를 실행하기 전에 OPENCLAW_THEME=light를 설정하세요.
원래의 다크 팔레트를 강제로 사용하려면 OPENCLAW_THEME=dark를 설정하면 됩니다.

히스토리 및 스트리밍

연결 시 TUI는 최신 히스토리를 불러옵니다 (기본값 200개 메시지).
스트리밍 응답은 완료될 때까지 실시간으로 업데이트됩니다.
TUI는 더 풍부한 도구 카드를 보여주기 위해 에이전트 도구 이벤트도 모니터링합니다.

연결 상세 정보

TUI는 Gateway에 mode: "tui"로 등록됩니다.
재연결 시 시스템 메시지가 표시되며, 이벤트 간의 공백은 로그에 나타납니다.

옵션

--url <url>: Gateway WebSocket URL (기본값은 설정 파일 또는 ws://127.0.0.1:<port>)
--token <token>: Gateway 토큰 (필요한 경우)
--password <password>: Gateway 패스워드 (필요한 경우)
--session <key>: 세션 키 (기본값: main, 범위가 global인 경우 global)
--deliver: 어시스턴트 응답을 provider에 전달 (기본값 off)
--thinking <level>: 전송 시 thinking 레벨 오버라이드
--timeout-ms <ms>: 에이전트 타임아웃 (ms 단위, 기본값은 agents.defaults.timeoutSeconds)

참고: --url을 직접 설정하면 TUI는 설정 파일이나 환경 변수의 자격 증명을 사용하지 않습니다. --token이나 --password를 명시적으로 전달해야 하며, 자격 증명이 누락되면 에러가 발생합니다.

문제 해결

메시지 전송 후 출력이 없는 경우:

TUI에서 /status를 실행해 Gateway가 연결되어 있는지, idle/busy 상태인지 확인하세요.
Gateway 로그를 확인하세요: openclaw logs --follow.
에이전트가 실행 가능한 상태인지 확인하세요: openclaw status 및 openclaw models status.
채팅 채널에서 메시지를 기다리고 있다면 전달 기능을 활성화하세요 (/deliver on 또는 --deliver).
--history-limit <n>: 불러올 히스토리 개수를 조절해 보세요 (기본값 200).

연결 문제 해결

disconnected: Gateway가 실행 중인지, --url/--token/--password가 정확한지 확인하세요.
피커에 에이전트가 없음: openclaw agents list 명령과 라우팅 설정을 확인하세요.
세션 피커가 비어 있음: global 범위에 있거나 아직 생성된 세션이 없을 수 있습니다.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.