오퍼레이터 채팅 어시스턴트

오퍼레이터 채팅 어시스턴트는 모든 대시보드 페이지 위에 오버레이되는 플로팅 멀티탭 패널입니다. 뷰포트 상단에서 슬라이드 다운되어 현재 라우트에 관계없이 항상 사용할 수 있으므로, 오퍼레이터와 대화하거나, 내장 터미널에서 빠른 상태 명령을 실행하거나, 현재 작업 중인 페이지를 벗어나지 않고 코딩 에이전트 세션을 시작할 수 있습니다. 대시보드 레이아웃의 일부로 제공되며, 열고 닫을 수 있고 Esc로 닫을 수 있습니다.

이 페이지에서는 세 가지 탭 유형(채팅, 터미널, 코드), 채팅 입력창에서 실행할 수 있는 슬래시 명령어, 내장 터미널의 내장 명령, 분할 및 팝아웃 레이아웃, 색상 테마 및 화면 설정을 설명합니다. 브라우저를 페어링하고 대시보드를 처음 여는 방법은 대시보드 실행을 참고하세요. 에이전트와 대화하는 방법에 대한 안내는 에이전트와 채팅하기를 참고하세요.

탭

어시스턴트는 단일 창 위에 있는 탭 스트립입니다. 각 탭은 세 가지 종류 중 하나이며, + 버튼(선택 창이 열림)을 클릭하거나 슬래시 명령어로 새 탭을 만들 수 있습니다. 스트립은 내용이 넘칠 경우 수평으로 스크롤되며, 설정 및 닫기 컨트롤은 오른쪽에 고정됩니다.

탭	아이콘	설명
Chat	message	WebSocket 세션을 통해 오퍼레이터와 나누는 실시간 대화
Terminal	terminal	xterm.js 기반 내장 터미널 — 가능한 경우 실제 PTY, API 명령 폴백 지원
Code	code	Revka MCP 데몬에 연결된 CLI 코딩 에이전트 세션 (Claude Code, Codex, OpenCode, Gemini)

패널을 처음 열면 두 개의 탭이 시작됩니다: 안정적인 operator-main 세션에 바인딩된 Chat 탭 하나와 Terminal 탭 하나입니다. 열린 탭, 활성 탭, 화면 설정은 localStorage에 저장되므로 패널을 다시 열어도 이전 상태가 유지됩니다.

탭 이름 변경, 닫기, 복원

• 이름 변경: 채팅 탭 제목을 더블클릭하여 이름을 변경합니다. Enter 키를 누르거나 다른 곳을 클릭하면 저장되고, Esc로 취소됩니다. 새 이름은 PUT /api/sessions/{id}로 세션 백엔드에 저장됩니다.
• 닫기: 마우스를 올리면 나타나는 ×로 탭을 닫습니다. 채팅 탭을 닫으면 해당 세션이 아카이브(DELETE /api/sessions/{id})되고 로컬에 기록되어 다시 나타나지 않습니다. 마지막 탭을 닫으면 새 채팅 탭이 열립니다.
• 복원: 패널을 열 때 자동으로 복원됩니다. 최근 대시보드 세션 목록을 조회하여 메시지가 있고 아카이브되지 않은 세션(최대 12개)의 채팅 탭을 복원하므로, 진행 중인 대화가 페이지 새로고침 후에도 유지됩니다.

GET /api/sessions
Authorization: Bearer <token>

참고

채팅 탭은 화면에 표시 중이거나 실시간 작업이 진행 중일 때만 마운트됩니다. 응답이 스트리밍 중인 탭에서 다른 탭으로 전환하면, 해당 탭은 턴이 완료될 때까지 백그라운드에서 마운트 상태를 유지하여 청크가 손실되지 않도록 하며, 턴이 완료되면 언마운트됩니다.

채팅 탭

채팅 탭은 오퍼레이터와의 완전한 대화 창입니다. 탭의 세션 ID를 키로 하는 게이트웨이 채팅 WebSocket을 통해 연결됩니다.

ws[s]://<host><base>/ws/chat?session_id=<session-id>&token=<bearer>

연결 시 revka.v1 서브프로토콜을 협상합니다. 브라우저에서 new WebSocket()에 Authorization 헤더를 설정할 수 없기 때문에, bearer 토큰은 ?token= 쿼리 파라미터로 전달됩니다. 현재 라우트의 페이지 컨텍스트는 각 메시지와 함께 전송되어 오퍼레이터가 페이지별 지침을 받을 수 있습니다. 프레임별 프로토콜(message, steer, stop, 스트리밍 chunk/thinking/done 및 모든 오류 코드)에 대한 자세한 내용은 실시간: WebSocket, SSE & Live Canvas를 참고하세요.

채팅 탭 기능:

• 마크다운 렌더링 — 어시스턴트 응답은 GitHub Flavored Markdown으로 렌더링되며, 사용자가 입력한 메시지는 원문 그대로 표시됩니다.
• 스트리밍 — 오퍼레이터의 응답이 실시간으로 스트리밍되며, 응답 중에는 스윕 바와 상태 표시줄이 표시됩니다.
• 액티비티 카드 — 도구 호출과 그 결과가 스트림 내에 컴팩트한 카드 형태로 인라인으로 표시됩니다.
• 대기열 vs. 조종 — 턴이 진행 중인 동안 입력창 옆의 토글로 다음 메시지를 대기열에 추가(현재 턴이 완료된 후 전송)하거나, 현재 턴을 조종(다음 오퍼레이터 경계에서 적용되는 중간 메모)할 수 있습니다. 조종은 텍스트 전용이며, 첨부 파일이 준비된 상태에서는 비활성화됩니다.
• 중지 — 중지 버튼으로 진행 중인 턴을 취소합니다.
• 최신으로 이동 — 자동 스크롤이 새 출력을 따라가며, 위로 스크롤하면 일시정지되고 최신으로 이동 버튼이 표시됩니다.
• 복사 — 모든 메시지에 복사 버튼이 있습니다.

첨부 파일

다음 메시지에 첨부할 파일을 클립 아이콘 버튼, 입력창으로의 파일 드래그 앤 드롭, 또는 클립보드에서 이미지 붙여넣기로 준비합니다. 각 파일은 활성 세션에 업로드되며 이름과 크기가 표시된 칩으로 나타납니다.

POST /api/sessions/{session_id}/attachments
Authorization: Bearer <token>
Content-Type: multipart/form-data

{
  "file_id": "att_...",
  "filename": "screenshot.png",
  "size": 184320,
  "mime": "image/png",
  "session_id": "...",
  "created_at": "2026-06-18T..."
}

반환된 file_id는 WebSocket 페이로드의 attachments 배열에 담겨 다음 메시지와 함께 전송됩니다. 게이트웨이는 개별 파일 크기를 25 MiB로 제한합니다. 이미지는 비전 지원 프로바이더에 전달되며, 텍스트 파일은 프롬프트에 인라인으로 삽입됩니다(매우 큰 경우 잘림 처리). 인라인 삽입 규칙은 실시간을 참고하세요.

터미널 탭

터미널 탭은 xterm.js 기반의 실제 터미널입니다. 열릴 때 게이트웨이 터미널 WebSocket을 통해 PTY에 연결을 시도합니다.

ws[s]://<host><base>/ws/terminal?session_id=<id>&token=<bearer>&cols=<n>&rows=<n>

PTY가 연결되면 로그인 셸, 완전한 키 입력 전달, 창 크기 변경 지원, 클릭 가능한 링크를 사용할 수 있습니다. 패널은 터미널의 측정된 열과 행을 기반으로 PTY 크기를 미리 설정하여 첫 렌더링이 컨테이너와 일치하도록 합니다. PTY 프로토콜, 지원 CLI 도구, MCP 자동 주입에 대한 내용은 실시간: WebSocket, SSE & Live Canvas를 참고하세요.

API 명령 모드

PTY 모듈이 비활성화된 플랫폼이나 연결 시간이 초과된 경우 등 PTY WebSocket을 사용할 수 없을 때, 터미널은 API 명령 모드로 폴백됩니다. 이 모드는 셸이 아니라 읽기 전용 게이트웨이 엔드포인트를 호출하고 JSON 결과를 출력하는 소형 내장 명령 실행기입니다. ❯ 프롬프트에서 명령을 입력하세요.

명령	호출	표시 내용
status	GET /api/status	런타임 상태 (프로바이더, 모델, 상태)
cost	GET /api/cost	비용 요약
agents	GET /api/agents	등록된 에이전트
config	GET /api/config	현재 설정
sessions	GET /api/sessions	활성 세션
health	GET /api/health	상태 스냅샷
integrations	GET /api/integrations	인테그레이션 카탈로그
clear	—	터미널 지우기
help	—	명령 목록 출력

help를 입력하면 언제든지 목록을 출력할 수 있습니다. 알 수 없는 명령을 입력하면 오류와 함께 help로 안내합니다. API 명령 모드에서는 기본 줄 편집(Backspace, 현재 줄 취소 Ctrl+C, 화면 지우기 Ctrl+L)을 지원합니다.

참고

터미널은 활성 어시스턴트 색상 테마(색상 테마 참고)에 따라 스타일이 적용되며, 폰트 크기와 커서 깜박임은 패널의 화면 설정을 따릅니다.

코드 탭

코드 탭은 CLI 코딩 에이전트를 터미널에서 실행하며, 공유 Revka MCP 데몬에 연결되어 에이전트가 Revka 도구에 액세스할 수 있습니다. 설정 화면과 실행 화면으로 구성됩니다.

설정 화면에서 도구와 저장소 루트를 선택한 후 세션을 시작합니다.

도구	비고
Claude Code (claude)	PTY에서 실행
Codex (codex)	PTY에서 실행
OpenCode (opencode)	PTY에서 실행
Gemini CLI (gemini)	PTY에서 실행
Revka Operator (operator)	PTY 아님 — 탭이 오퍼레이터 컨텍스트의 채팅 탭으로 전환됨

설정 화면은 데몬을 먼저 조회하여 상태 표시줄(Revka MCP: ready / checking… / not running)을 표시합니다.

GET /api/mcp/discovery
Authorization: Bearer <token>

PTY 도구를 시작하면 패널이 MCP 세션을 열고 터미널을 연결합니다.

POST /api/mcp/session
Authorization: Bearer <token>
Content-Type: application/json

{ "cwd": "/path/to/repo", "label": "Claude Code · repo" }

반환된 session_id와 token은 터미널 WebSocket(/ws/terminal?tool=<tool>&cwd=<repo>&mcp_session=<id>&mcp_token=<tok>)에 전달되며, 두 번째 WebSocket은 실시간 도구 진행 이벤트를 구독합니다.

ws[s]://<host><base>/ws/mcp/events?session_id=<mcp-session>&mcp_token=<tok>&token=<bearer>

이 진행 이벤트는 터미널 위에 상태 카드 스트립(도구 이름, 진행 상황, 상대적 타임스탬프)으로 렌더링되어 에이전트의 도구 호출 진행을 확인할 수 있습니다. 최근에 사용한 저장소 루트는 빠른 재사용을 위해 기억됩니다. 세션 수명 주기 및 이벤트 페이로드 스키마는 실시간: WebSocket, SSE & Live Canvas 및 MCP 프록시 & 디스커버리 API를 참고하세요.

팁

Revka Operator를 선택하면 터미널이 실행되지 않고, 탭이 오퍼레이터 코딩 컨텍스트로 범위가 설정된 채팅 대화로 전환됩니다. 외부 CLI를 구동하는 대신 오퍼레이터가 자체 도구를 통해 변경 작업을 수행하도록 할 때 사용합니다.

슬래시 명령어

채팅 입력창에서 /를 입력하면 입력하면서 필터링되는 슬래시 명령어 메뉴가 열립니다. 화살표 키로 이동하고, Tab 또는 Enter로 선택하며, Esc로 닫습니다. 인수가 필요한 명령은 /<name> 로 미리 입력되어 인수를 바로 입력할 수 있으며, 인수가 없는 명령은 즉시 실행됩니다.

명령	별칭	인수	동작
/help	/?	—	사용 가능한 명령 목록을 인라인으로 출력
/clear	/cls	—	스크롤백 지우기 (세션 연결 유지)
/new	—	—	새 탭 메뉴 열기
/chat	—	—	새 채팅 탭 열기
/terminal	/term	—	새 터미널 탭 열기
/code	—	—	새 코드 탭 열기
/attach	/file	—	OS 파일 선택기를 열어 파일 첨부
/theme	—	<dark|light|oled|system>	UI 테마 전환
/lang	/language	<en|zh|tr|ko>	UI 언어 전환
/close	—	—	활성 탭 닫기

/theme dark
/lang ko
/clear

/clear는 로컬 스크롤백만 지우며, 세션이나 저장된 대화 기록은 삭제하지 않습니다. /lang은 언어 선택을 런타임 설정에 저장합니다.

참고

/architect 명령은 워크플로우 에디터의 Architect 채팅 패널 내에서만 사용할 수 있으며, 대시보드 어시스턴트에서는 사용할 수 없습니다. 이 명령이 작동하려면 열린 워크플로우가 필요합니다. 워크플로우, 에디터 & 실행을 참고하세요.

레이아웃

어시스턴트는 뷰포트 상단에서 페이지 위로 슬라이드 다운되어 뒷 페이지를 어둡게 처리하는 팝아웃 패널입니다. 패널 바깥쪽을 클릭하거나 Esc를 눌러 닫을 수 있습니다. 높이를 조절할 수 있으며(화면 설정 참고), 반투명하게 설정하면 아래 페이지가 투영되어 워크플로우 에디터나 캔버스와 함께 채팅할 때 유용합니다.

분할 채팅

활성 탭이 채팅 탭일 때 액션 클러스터에 분할 버튼이 나타납니다. 처음 클릭하면 현재 탭 옆에 새 채팅 탭이 생성되고, 이후 클릭할 때마다 분할 방향이 전환됩니다.

• 좌우 분할 (세로 분할) — 두 채팅이 좌우로 배치됩니다.
• 상하 분할 (가로 분할) — 두 채팅이 위아래로 배치됩니다.

별도의 ×로 분할을 해제합니다. 분할은 채팅 탭 두 개에서만 의미가 있으며, 터미널이나 코드 탭으로 전환하면 분할이 숨겨지고 돌아오면 복원됩니다. 두 개의 오퍼레이터 대화, 또는 하나의 대화와 하나의 참고 스레드를 동시에 표시할 때 사용합니다.

색상 테마

터미널과 채팅은 설정 패널에서 선택하고 localStorage(revka-assistant-config)에 저장된 네 가지 색상 테마 중 하나를 사용합니다. 기본값은 Revka입니다.

테마	느낌
Matrix	어두운 배경에 초록색, 부드러운 글로우
Amber	따뜻한 앰버/오렌지 색상, 부드러운 글로우
Revka	쿨 블루 (기본값)
Minimal	중성 회색, 글로우 없음

테마는 메시지 색상, 커서 색상, 글로우 액센트, 내장 터미널의 테마에 적용됩니다. 대시보드의 라이트/다크 테마(/theme 명령 또는 헤더 토글로 변경)와는 독립적으로 작동하며, 업로드된 UI 스킨과도 별개입니다. 로그, 감사, 진단, 페어링 & 스킨 페이지를 참고하세요.

화면 설정

기어 아이콘으로 설정 패널을 열어 어시스턴트의 외관을 조정할 수 있습니다. 이 설정도 localStorage에 저장됩니다.

설정	범위 / 값	기본값	설명
Color Scheme	Matrix, Amber, Revka, Minimal	Revka	액센트 및 터미널 테마
Font Size	10–20 px	13 px	스크롤백 및 터미널 폰트 크기
Cursor Blink	on / off	on	입력창 및 터미널 커서 깜박임
Panel Height	25–90 %	60 %	뷰포트 대비 패널 높이 비율
Panel Opacity	50–100 %	100 %	패널 전체 불투명도; 100% 미만이면 아래 페이지가 투영됨

주의

모바일 Safari가 포커스 시 자동으로 확대되는 것을 방지하기 위해, Font Size 설정에 관계없이 입력창의 유효 폰트 크기는 최소 16 px으로 제한됩니다. 선택한 크기는 위의 메시지 스크롤백에는 그대로 적용됩니다.

관련 페이지

에이전트와 채팅하기 대시보드에서 오퍼레이터와 대화하는 방법을 안내합니다.

대시보드 실행 게이트웨이를 시작하고, 기기를 페어링하고, 대시보드를 엽니다.

실시간: WebSocket, SSE & Live Canvas 탭 뒤에서 동작하는 채팅, 터미널, MCP 이벤트 WebSocket 프로토콜.

Cron, 세션 & 첨부 파일 API 세션 목록 조회, 이름 변경, 삭제, 첨부 파일 업로드 엔드포인트.

MCP 프록시 & 디스커버리 API 코드 탭에서 사용하는 데몬 디스커버리 및 MCP 세션.

로그, 감사, 진단, 페어링 & 스킨 어시스턴트의 색상 테마와는 별개로 적용되는 UI 스킨.