Orca Chat UI 사용법, Claude Code·Codex를 채팅으로 쓰기

Orca에서 Claude Code나 Codex를 띄우면 기본 화면은 터미널 TUI다. 설정에서 실험 기능인 Orca Chat UI를 켜면 같은 에이전트를 말풍선, 도구 실행 행, 인라인 diff 카드로 이뤄진 채팅 화면에서 다룰 수 있다. 켜는 것 자체는 토글 두어 개면 끝나지만 “켰는데 왜 그대로지?”에서 막히는 사람이 많아서, 그 지점까지 같이 정리한다.

이 글은 macOS에서 Orca 1.4.215, Claude Code 2.1.283, codex-cli 0.156.0 기준이다. Orca는 9월 25일부터 28일 사이에만 릴리스가 네 번 나갈 만큼 업데이트가 잦아서, 메뉴 문구는 조금씩 달라질 수 있다.

🐋 Orca와 Chat UI의 관계

Orca는 Stably AI가 MIT 라이선스로 공개한 데스크톱 앱이다. 태스크마다 별도의 git worktree를 만들고 그 안에서 에이전트를 하나씩 띄워, 여러 에이전트를 병렬로 돌리고 diff를 비교하는 게 본업이다. GitHub 스타는 8만 개를 넘겼다.

Chat UI는 그 위에 얹히는 화면 계층이다. 에이전트를 새로 구현한 게 아니라 이미 설치된 CLI 세션을 다른 모양으로 보여주는 창이라는 점을 잡고 가면 이후 동작이 헷갈리지 않는다. 그리고 여기엔 두 갈래가 있다.

1. 터미널 기반 Chat UI: 돌아가는 PTY 위에 대화 기록과 입력창을 덧씌운다. 원본은 여전히 터미널이다. Claude, Codex, Grok, OMP 세션이 대상이다.
2. 구조화 네이티브 채팅: 로컬 Claude·Codex 세션 전용이다. 세션 상태를 Orca가 직접 들고 있어서 앱을 재시작해도 탭과 대화가 복원된다. 이미지 붙여넣기, 도구 실행 진행 표시 같은 기능이 이쪽에 몰려 있다.

말로는 감이 잘 안 와서 직접 찍어 봤다. 데모용으로 만든 작은 todo 저장소에서 Claude에게 removeTodo 함수와 테스트를 맡기고, 에이전트 패널 오른쪽 위의 터미널 아이콘으로 보기만 바꿔 가며 캡처한 화면이다. 같은 세션, 같은 응답이다.

왼쪽 TUI는 패널 폭에 맞춰 긴 줄이 꺾이고 한글 자간이 벌어진다. 오른쪽 Chat UI는 같은 출력을 코드 블록, 목록, 인라인 코드로 다시 그리고, 중간에 실행한 명령은 “2 명령을 실행했습니다” 한 줄로 접는다. 스크린샷은 한국어 UI로 설정된 Orca라 메뉴 이름이 이 글의 영문 표기와 조금 다르게 보일 수 있다.

🧰 CLI 설치와 로그인

Orca는 에이전트 CLI를 내장하지 않는다. Claude Code와 Codex를 각자 설치하고 터미널에서 한 번 로그인해 두면, Orca가 ~/.claude와 ~/.codex를 읽어 인증을 그대로 가져다 쓴다. 별도 설정 파일은 없다.

# Orca (macOS, Homebrew)
brew install --cask stablyai/orca/orca

# Claude Code (npm i -g @anthropic-ai/claude-code 도 가능)
curl -fsSL https://claude.ai/install.sh | bash
claude            # 첫 실행 때 브라우저로 로그인

# Codex
npm i -g @openai/codex
codex login

Windows는 GitHub Releases의 orca-windows-setup.exe, Linux는 AppImage나 .deb/.rpm을 받으면 된다. Linux에서는 GNOME 스크린 리더와 이름이 겹치지 않도록 CLI 이름이 orca-ide로 바뀌어 있다.

설치가 끝났으면 버전부터 확인한다.

$ claude --version
2.1.283 (Claude Code)
$ codex --version
codex-cli 0.156.0

Orca를 처음 열면 홈 디렉터리 접근 권한을 묻고, ~/.claude·~/.codex에 있던 터미널 설정을 가져온다. 왼쪽 사이드바의 Add Repo로 로컬 저장소를 하나 추가해 두자.

⚙️ Chat UI 켜기

설정 경로는 Settings → Experimental → Chat UI다. 여기서 순서대로 만진다.

1. Chat UI 토글을 켠다.
2. Default view를 Terminal chat과 Chat UI 중에서 고른다. Chat UI로 두면 새로 여는 에이전트 탭이 처음부터 채팅으로 열린다.
3. Default view를 Chat UI로 고르면 그 아래에 Use updated structured native chat 토글이 새로 나타난다. Claude·Codex를 구조화 채팅으로 쓰려면 이것까지 켠다.
4. 같은 화면의 Resume working chats automatically after a restart를 켜 두면, 업데이트 설치로 앱이 꺼져도 작업 중이던 채팅이 다시 열릴 때 이어진다.

3번 토글이 처음엔 보이지 않는다는 게 첫 번째 함정이다. Default view를 바꿔야 비로소 나타난다.

같은 화면에 Use your shell environment 항목도 있다. 기본값은 켜짐이고, 로그인 셸에서 export한 환경 변수를 구조화 채팅 세션에 그대로 넘긴다. API 키 같은 변수가 에이전트 프로세스까지 넘어가는 게 싫다면 끄고 허용할 변수 이름만 따로 지정하면 된다.

설정이 제대로 저장됐는지는 Orca 데이터 파일에서 바로 확인할 수 있다.

$ grep -o -E '"(experimentalNativeChat|openAgentTabsInChatByDefault)": [a-z]+' \
    ~/Library/Application\ Support/orca/orca-data.json
"openAgentTabsInChatByDefault": true
"experimentalNativeChat": true

Chat UI는 새로 만드는 로컬 세션에만 적용된다. 이미 열려 있던 터미널 세션은 끝까지 터미널로 남는다.

켜 놓고 기존 탭을 들여다보며 “안 되네” 하는 경우가 대부분 이 규칙 때문이다. 새 worktree를 하나 만들어서 확인해야 한다.

💬 새 세션을 채팅으로 열기

저장소 이름 옆의 + 를 눌러 worktree를 만들고, 에이전트 콤보박스에서 Claude Code 또는 Codex를 고른다. Default view를 Chat UI로 해 뒀다면 바로 채팅 화면이 뜨고, 에이전트 패널에서 언제든 터미널 보기로 전환할 수 있다.

입력창에서 /를 치면 슬래시 명령과 설치된 스킬이 한 목록으로 뜬다. 목록은 에이전트별로 다르다. Claude 쪽은 설치된 CLI가 보고하는 설명과 인자 힌트까지 보여준다. Orca가 직접 처리하는 명령은 두 개인데, /clear는 같은 창에서 새 대화를 시작하되 이전 대화를 히스토리에 남기고, /compact는 에이전트에게 컨텍스트를 줄여 달라고 요청한다. 나머지 에이전트 고유 명령은 그대로 CLI로 전달된다.

파일은 왼쪽 파일 트리나 데스크톱에서 입력창으로 끌어다 놓으면 에이전트가 읽을 수 있는 경로로 첨부된다. 클립보드 이미지 붙여넣기는 구조화 Codex 채팅에서 지원하고, 보내기 전에 썸네일로 확인하고 뺄 수 있다.

입력창 위의 모델 pill은 두 에이전트가 동작 방식이 다르다.

• Claude: 모델 목록을 하드코딩하지 않고 그 호스트에 설치된 Claude CLI에서 읽어온다. 새 모델이 나오면 CLI만 업데이트하면 목록에 뜬다.
• Codex: pill에서 모델을 고르면 내부적으로 /model <id>를 보낸다. 그냥 /model만 치면 기존처럼 Codex 자체 선택기가 열린다.

어떤 Claude 모델을 고를지 고민이라면 Claude Opus 4.8 vs Fable 5 비교에 선택 기준을 정리해 뒀다. Fast mode 토글은 에이전트가 지원한다고 보고할 때만 나타난다. Claude 채팅에서는 모델 옆 링이 컨텍스트 사용량을 보여주는데, 눌러 보면 메시지·도구·메모리 파일이 각각 토큰을 얼마나 먹는지까지 나온다.

작업 진행을 따라가는 방식에서 터미널과 차이가 크다. 파일 수정은 인라인 diff 카드로 뜨고, 대화에 나온 파일 경로를 클릭하면 Orca 에디터에서 열린다. 서브에이전트나 백그라운드 셸은 입력창 위 스트립에 개수, 상태, 경과 시간이 모인다. Claude의 TodoWrite와 Codex의 update_plan은 체크리스트로 그려지고, 최신 계획은 입력창 위 접이식 패널에 고정된다.

Codex 쪽도 같은 저장소의 다른 worktree에서 띄워 봤다. addTodo에 마감일 인자를 붙이고 overdueTodos를 만들라고 하면서 계획부터 세우라고 시킨 세션이다.

이 캡처에서는 계획이 본문의 번호 목록으로 찍혔고, 실행한 명령은 “1번 명령 실행”처럼 한 줄로 접혔다. 탭 제목은 첫 프롬프트에서 따 와 자동으로 붙었다. 마지막 줄의 npm test, git diff --check 결과까지 한 화면에 들어오니 터미널을 거슬러 올라가며 로그를 뒤질 일이 줄어든다.

TUI로 한 시간짜리 세션을 돌려 본 사람이면 내가 아까 뭘 시켰는지 찾으려고 스크롤을 한참 거슬러 올라간 적이 있을 것이다. 긴 대화에서는 대화 가장자리에 메시지 레일이 생겨 프롬프트마다 마커가 찍히고, 마커를 누르면 그 턴으로 바로 이동한다. Chat UI로 넘어갈 이유를 하나만 꼽으라면 이것이다.

🔁 터미널 세션과 다른 에이전트로 대화 넘기기

기존 대화를 옮기는 기능은 오른쪽 사이드바 Agents 탭의 Agent Session History에 있다. Claude, Codex, Cursor, Gemini 등 지난 세션이 작업 디렉터리, 브랜치, 모델, 메시지 수와 함께 나열되고, 제목이나 대화 본문으로 검색할 수 있다.

위 화면 오른쪽이 그 패널이다. 세션마다 요약, 에이전트 종류, 메시지 수, 모델 ID가 붙는다. 항목을 펼치거나 오른쪽 ⋯ 메뉴를 열면 아래 동작을 고를 수 있다.

• Resume: 원래 디렉터리에서 새 터미널을 열고 그 에이전트의 resume 명령을 실행한다.
• Resume in New Chat: Claude·Codex 세션을 구조화 채팅으로 이어간다. 기존 터미널 세션을 채팅으로 옮기는 정식 경로가 이것이다.
• Continue in New Session…: 이전 맥락을 요약한 핸드오프 프롬프트로 새 세션을 시작한다. Claude로 하던 작업을 Codex에게 넘기는 것도 이 메뉴다.

마지막 항목은 이름만 봐서는 에이전트를 바꿀 수 있다는 게 전혀 드러나지 않는다. 채팅 화면 우클릭 메뉴에도 Copy, Paste, Move Tab to Split뿐이라 찾기가 어렵다. 이 문제는 9월 22일 GitHub 이슈 #22323으로 올라가 있으니 나중 버전에서는 진입점이 바뀔 수 있다. 터미널에서 찾고 싶다면 orca search로 세션 전문을 검색할 수도 있다.

⚠️ 주의점과 트러블슈팅

첫째는 권한이다. Orca는 새로 실행하는 에이전트에 권한 우회 플래그를 기본으로 채워 넣는다. Claude는 --dangerously-skip-permissions, Codex는 --dangerously-bypass-approvals-and-sandbox가 붙는다. worktree로 분리돼 있다고 해서 에이전트 프로세스가 홈 디렉터리나 네트워크에 못 닿는 건 아니다.

채팅 화면이 편해질수록 무엇을 승인 없이 실행하는지 덜 보게 된다. 처음 쓴다면 Settings → Agents → Agent Permissions에서 Manual로 바꿔 두는 편이 안전하다.

이미 특정 에이전트의 실행 인자를 직접 고쳐 뒀다면 이 전역 스위치는 그 에이전트를 건드리지 않는다. 그런 경우엔 해당 에이전트 설정에서 인자를 직접 정리해야 한다.

둘째, 구조화 채팅은 로컬 세션 한정이다. WSL, SSH, 원격 호스트 세션은 터미널 기반 Chat UI로 동작하고, 네이티브 Windows도 Orca가 프로세스 시작 시각을 읽지 못하면 터미널 채팅으로 되돌아간다. 원격에서 이미지 붙여넣기가 안 된다면 이 때문이다.

셋째, 아직 실험 기능이다. 공식 문서도 OSC 상태 정보를 전부 봐야 할 때는 raw TUI를 쓰라고 권한다. 9월 말 기준 GitHub에 열려 있는 이슈 중 체감이 큰 것은 이 정도다.

1. Chat UI에서 Codex 모델·effort가 바뀌지 않는 버그(9월 22일)
2. 새 Chat UI가 응답이 끝나면 멈춘 것처럼 보이는 버그(9월 17일)
3. 채팅 안에서 Ctrl+F 찾기가 안 되는 문제(9월 28일, 기능 요청)

모델 전환이 먹지 않으면 에이전트 패널에서 터미널 보기로 잠깐 바꿔 /model을 직접 치면 된다. 같은 PTY를 보고 있으니 채팅으로 돌아와도 설정은 유지된다.

넷째, Codex 0.157 이상을 쓴다면 worktree 경로 길이를 신경 써야 한다. 경로가 길면 소켓 오류를 막으려고 백그라운드 데몬이 꺼지고, codex agents나 데몬 기반 resume이 제한된다.

계정을 여러 개 굴린다면 orca account add로 Claude·Codex 관리 계정을 추가해 둘 수 있다. 세션 도중 재로그인 없이 계정을 바꿀 수 있고, 현재 계정의 사용량과 레이트 리밋 근접도는 하단 상태바에 표시된다.

📌 정리

Orca Chat UI를 쓰는 데 필요한 건 CLI 로그인 한 번과 Settings → Experimental → Chat UI의 토글 두 개가 전부다. 다만 적용 대상은 새로 만드는 로컬 세션뿐이고, 구조화 채팅 토글은 Default view를 Chat UI로 바꿔야 나타난다. 기존 대화는 Agent Session History의 Resume in New Chat으로 옮기고, 다른 에이전트로 넘길 땐 Continue in New Session… 메뉴를 쓴다.

편해진 만큼 권한 우회 플래그가 기본값이라는 사실은 잊기 쉽다. 채팅 화면을 켜기 전에 Agent Permissions부터 한 번 확인하자.