전체 문서 목록
ORCA 완전 가이드 · 2026-11-04 기준

Orca — 여러 AI 코딩 에이전트를
한 앱에서 동시에 부리는 개발 환경

Orca는 AI에게 코딩 일을 여러 개 동시에 맡기고, 그 결과를 한곳에서 확인하는 작업장 프로그램입니다. Stably AI가 만들었고, 무료로 쓸 수 있습니다. 홈페이지는 스스로를 ADE(Agent Development Environment — AI 에이전트를 위한 개발 환경)라고 부르며, 표어는 “Ship 100x with the agent IDE”(에이전트 개발 도구로 100배 빠르게 내보내라)입니다.

무료 · 오픈소스macOS · Windows · LinuxiOS · Android 앱Y Combinator(유명 스타트업 투자사) 투자GitHub ★ 114.5k(개발자 인기 지표)
아주 쉽게 말하면 AI 코딩 도우미를 “직원”이라고 생각해 보세요. 직원 한 명에게 일을 시키면 끝날 때까지 기다려야 합니다. 여러 명에게 동시에 시키면 빠르지만, 모두가 같은 책상에서 같은 서류를 고치면 엉망이 됩니다. Orca는 직원마다 책상(워크트리)을 따로 마련해 주고, 누가 일하는 중이고 누가 질문을 기다리는지 한 화면에서 보여 주며, 끝난 결과를 꼼꼼히 검토해 합치는 사무실입니다.
이 가이드를 읽는 법 Orca는 원래 코드를 다룰 줄 아는 사람을 위한 도구입니다(코딩을 대신해 주는 노코드 도구가 아닙니다). 그래서 이 가이드는 두 층으로 되어 있습니다. 본문만 읽어도 “무엇이고, 왜 필요하고, 어떻게 쓰는지”를 이해할 수 있게 썼고, 설정 값·명령어·오류 처리 같은 세부는 🔧 개발자용 참고 상자에 접어 두었습니다. 처음 읽을 때는 접힌 상자를 건너뛰고, 각 장 맨 위의 🚩 처음이라면 이것만 안내를 따라가세요. 모르는 말은 바로 아래 용어표에서 찾을 수 있습니다. 더 짧게 보려면 한눈에 보기이나 필수판을, 처음부터 따라 하려면 활용편을 보세요.

먼저 알아 두면 좋은 용어

가이드 전체에서 자주 나오는 말입니다. 먼저 굵게 표시한 8개만 알아도 대부분 따라갈 수 있습니다. 각 장에서도 처음 나올 때 괄호로 다시 풀이합니다.

용어쉬운 풀이
⭐ AI 코딩 에이전트사람 대신 코드를 읽고, 고치고, 명령을 실행하는 AI 프로그램. 예: Claude Code, Codex, Cursor CLI, Gemini.
⭐ 터미널 · 셸글자로 명령을 입력해 컴퓨터를 다루는 창. 대부분의 코딩 에이전트는 터미널 안에서 돌아갑니다.
⭐ git · 저장소(repo)코드의 변경 이력을 기록하는 도구와, 그 이력이 담긴 프로젝트 폴더.
⭐ 커밋“여기까지 저장” 하고 이력에 남기는 한 번의 기록.
⭐ 브랜치이력의 갈래. 원본(main)을 건드리지 않고 따로 작업하기 위한 줄기.
⭐ 워크트리한 저장소의 브랜치를 별도 폴더에 하나 더 꺼내 놓은 것. 폴더가 다르니 여러 작업이 서로 섞이지 않습니다. Orca의 기본 작업 단위.
⭐ diff바뀌기 전과 후의 차이. 지운 줄은 빨강, 더한 줄은 초록으로 보입니다.
⭐ PR (Pull Request)“내 브랜치의 변경을 원본에 합쳐 주세요” 하고 리뷰를 요청하는 것. GitLab에서는 MR.
용어 24개 더 보기 — 읽다가 모르는 말이 나오면 여기서 찾으세요
용어쉬운 풀이
ADEAgent Development Environment. 사람이 직접 코딩하는 IDE와 달리, 여러 에이전트를 지휘·감독하는 데 맞춘 개발 환경.
IDE · 에디터코드를 쓰고 고치는 프로그램. 예: VS Code.
CLICommand Line Interface. 터미널에서 명령어로 쓰는 프로그램. Orca에도 orca라는 CLI가 있습니다.
체크아웃특정 브랜치의 파일을 폴더에 꺼내 놓은 상태.
스테이징다음 커밋에 넣을 변경을 골라 담아 두는 단계.
푸시 · 원격(remote)내 컴퓨터의 커밋을 GitHub 같은 서버 저장소로 올리는 것과, 그 서버 저장소.
CI · 체크PR을 올리면 서버가 자동으로 돌리는 테스트·검사.
이슈 · 티켓할 일이나 버그를 적어 둔 카드. GitHub Issues, Linear, Jira 등.
SSH다른 컴퓨터(서버)에 안전하게 접속해 명령을 실행하는 방법.
페어링두 기기(예: 데스크톱과 폰)를 서로 믿을 수 있게 연결해 두는 것.
프롬프트에이전트에게 보내는 지시문.
세션에이전트 하나가 실행되어 대화·작업하는 한 번의 흐름.
패인 · 분할앱 화면을 여러 칸으로 나눈 것과 그 한 칸.
데몬화면 없이 뒤에서 계속 도는 프로그램. Orca는 이것으로 앱을 꺼도 에이전트를 살려 둡니다.
스킬에이전트에게 특정 도구 사용법을 알려 주는 안내 문서 묶음.
MCPModel Context Protocol. AI 에이전트가 외부 도구에 연결하는 표준 방식.
실험 기능 실험설정 → Experimental에서 켜야 쓸 수 있는, 아직 다듬는 중인 기능.
GitHub · GitLab코드를 올려 두고 여러 사람이 함께 검토하는 웹사이트. PR과 이슈가 여기에 있습니다.
런타임지금 켜져서 일하고 있는 Orca 프로그램 본체. 다른 컴퓨터에서 돌 수도 있습니다.
토큰① AI 사용량을 세는 단위, ② 비밀번호 대신 쓰는 출입증 문자열. 문맥에 따라 다릅니다.
환경 변수프로그램이 실행될 때 함께 받는 설정 메모(이름=값). 예: DO_NOT_TRACK=1.
localhost“내 컴퓨터 자신”을 가리키는 주소. 개발 중인 웹 화면을 열 때 씁니다.
Workspace(워크스페이스)Orca 화면에서 워크트리를 부르는 다른 이름. 이 가이드에서는 “워크트리”로 통일합니다.
<이름> 표기명령어 예시의 <repoId>처럼 꺾쇠로 감싼 부분은 “직접 바꿔 넣는 칸”입니다.

Orca 한 장 그림

🙂 나 지시 · 리뷰 Orca 앱 워크트리 A로그인 기능 작업 · 자기 폴더 워크트리 B결제 버그 고치기 워크트리 C대시보드 만들기 Claude Code작업 중 Codex질문 대기 — 나를 부름 Gemini완료 — 리뷰 기다림 명령 창 · 편집기 · 브라우저 · 변경 비교 — 모두 워크트리마다 따로 GitHub 등코드 보관·검토 사이트 원격 서버 · 폰다른 컴퓨터·휴대폰
🟠 작업 중🩷 질문 대기(나를 부름)🟢 완료
내가 지시하면(파란 점) 각 워크트리의 에이전트가 따로 일하고, 상태 점(작업 중·질문 대기·완료)이 한 화면에 보입니다. 결과는 리뷰를 거쳐 GitHub로 나가고, 원격 서버나 휴대폰에서도 이어서 볼 수 있습니다.

왜 이런 도구가 필요한가

한 문장으로 말하면 “AI 여러 명이 한 책상에서 일하면 서로의 일을 망치기 때문”입니다. 지금 개발자들은 보통 코드 편집 프로그램(IDE, 예: VS Code)을 쓰거나, AI 에이전트를 터미널 창에 하나씩 띄워 씁니다. 아래 표는 같은 일을 이 두 방법과 Orca로 할 때의 차이입니다.

기존 에디터(IDE)에이전트를 터미널에서 직접 실행Orca (ADE)
전제사람 한 명이 직접 타이핑터미널 창 하나에 에이전트 하나여러 에이전트가 동시에 일함
동시 작업브랜치를 바꿔 가며 하나씩같은 폴더에서 돌리면 서로 덮어씀작업마다 워크트리를 따로 만들어 충돌 없음
상태 파악—창을 하나씩 열어 봐야 함작업 중·질문 대기·완료를 한눈에, 알림까지
결과 검토diff 보기직접 git 명령줄마다 코멘트 → 묶어서 에이전트에게 다시 보냄
범위파일 편집에이전트 실행워크트리·리뷰·브라우저·원격·모바일·자동화 전체

Orca가 맞는 경우

같은 버그를 에이전트 셋에게 동시에 시켜 가장 좋은 답을 고르고 싶을 때 · AI가 만든 코드를 진지하게 리뷰하고 싶을 때 · 이미 Claude Code·Codex·Cursor CLI를 쓰고 있어 한곳에서 지휘하고 싶을 때 · 에이전트를 내 컴퓨터가 아닌 다른 컴퓨터(원격 서버·가상 컴퓨터)에서 돌리고 싶을 때

Orca가 아닌 것

AI 모델이 아닙니다(쓰던 Claude·Codex 구독을 가져와 씀) · git을 대체하지 않습니다(모든 워크트리는 진짜 git 워크트리) · 호스팅 서버 상품이 아닙니다(기본은 내 컴퓨터, 원격은 내가 가진 기계) · 코드를 모르는 사람용 노코드 도구가 아닙니다

하루 작업의 기본 순환

① 워크트리 만들기작업 이름 · 어디서 시작할지② 에이전트 실행③ 리뷰 · 배포

1단계 — 작업 공간 만들기. 할 일 하나마다 워크트리를 만듭니다. 이름을 적고, 어느 버전에서 시작할지 고르고, 필요하면 할 일 카드(이슈)를 연결합니다. 생성은 뒤에서 진행되므로 기다리지 않아도 됩니다. → 2장

① 워크트리 만들기② 에이전트 실행채팅으로 지시 · 화면으로 확인③ 리뷰 · 배포

2단계 — 에이전트에게 맡기기. 워크트리 안에서 Claude Code·Codex 등을 띄우고 일을 지시합니다. 다른 워크트리에서도 동시에 다른 에이전트가 일합니다. 질문이 오면 알림이 뜨고, 결과 화면은 내장 브라우저로 바로 확인합니다. → 3장, 4장

① 워크트리 만들기② 에이전트 실행③ 리뷰 · 배포바뀐 곳에 메모 → AI가 고침 → 합치기 요청

3단계 — 검토하고 내보내기. AI가 바꾼 부분(diff)을 한 줄씩 보며 메모를 달고, 메모를 한꺼번에 AI에게 돌려보내 고치게 합니다(초록 화살표: 수정 요청이 도는 길). 만족하면 저장 지점을 만들고(커밋) 서버에 올려(푸시) 합쳐 달라는 요청(PR)까지 앱 안에서 끝냅니다. → 6장

이 가이드의 구성

한눈에 정리
  • Orca는 AI 코딩 에이전트 여러 개를 워크트리별로 나눠 동시에 돌리고 지휘하는 무료·오픈소스 데스크톱 앱입니다.
  • 기본 순환은 워크트리 만들기 → 에이전트에게 맡기기 → 리뷰하고 내보내기입니다.
  • 모델이나 호스팅 서비스가 아니라, 내가 쓰던 에이전트와 git을 그대로 쓰는 “작업장”입니다.

출처: onorca.dev 홈, onorca.dev/docs (What is Orca?)

CHAPTER 01

시작하기 — Orca란 무엇이고 어떻게 설치·설정하나

Orca는 여러 AI 코딩 에이전트를 한 화면에서 나란히 돌리는 데스크톱 앱입니다. 이 장에서는 Orca가 어떤 도구인지, 설치와 첫 실행, 세 에이전트를 동시에 경주시키는 첫 세션, 알림·설정·개인정보, 그리고 문제가 생겼을 때 고치는 방법까지 한 번에 훑습니다.

이 장에서 배우는 것
  • Orca가 무엇이고 누구를 위한 도구인지, 그리고 무엇이 아닌지
  • macOS·Windows·Linux 설치, 첫 실행, 업데이트(안정판·RC) 받는 법
  • 에이전트를 어디서 돌릴지 고르는 4가지 방식(로컬·SSH·원격 Orca 서버·Cloud VM) — 처음엔 로컬만 알면 됩니다
  • 빈 앱에서 5분 안에 에이전트 3개를 병렬로 돌리는 첫 세션
  • Agents 피드(Activity)와 알림·벨·소리
  • 설정(Settings) 화면 19개 전체 지도 — 처음엔 3개만 보면 됩니다
  • 텔레메트리: 수집하는 것과 절대 수집하지 않는 것, 끄는 법
  • 자주 생기는 문제와 GitHub 오류(요청 한도·인증·권한) 해결법
처음이라면 이것만

1. Orca란? → 2. 설치(각 탭 첫 줄만) → 4. 첫 3-에이전트 세션(시작 전 준비물부터, 화면 그림을 따라 누르기) → 6. 알림 순서로 읽으면 충분합니다.

건너뛰어도 되는 곳: 3절 실행 방식의 원격 방식(SSH·원격 서버·Cloud VM), 7절 설정 중 General·Agents·Notifications 외의 탭, 9·10절(문제가 생겼을 때 개발자가 보는 참고). “🔧 개발자용 참고” 상자는 모두 접어 두고 읽어도 됩니다.

1. Orca란?

Orca는 여러 AI 코딩 에이전트를 나란히 실행하는 데스크톱 앱, ADE(에이전트용 개발 환경 — 코드 편집·실행·검토를 에이전트와 함께 한곳에서 하는 프로그램)입니다. AI 코딩 에이전트(말로 시키면 스스로 코드를 고치는 AI 프로그램)를 여러 개 동시에 부리는 “작업 지휘실”이라고 보면 됩니다. 핵심은 “작업 하나 = 독립된 작업 공간 하나”라는 점입니다. 작업마다 다음 세 가지가 따로 주어집니다.

자기만의 워크트리(git worktree)

같은 저장소(프로젝트 파일과 변경 기록을 담은 폴더)를 폴더만 하나 더 만들어 다른 브랜치로 꺼내 둔 사본입니다. 에이전트끼리 서로의 파일을 덮어쓰지 않습니다.

자기만의 에이전트 터미널

Claude Code, Codex, Cursor CLI 같은 에이전트가 그 워크트리 안에서 실행됩니다. 터미널(글자로 명령을 입력하는 검은 창)에서 돌아갑니다.

자기만의 브라우저 탭

작업별로 웹 화면을 따로 띄워 결과를 확인할 수 있습니다.

쉬운 말로 풀면

git(코드 변경 이력을 저장·관리하는 도구)은 코드의 “저장 기록장”입니다. 브랜치(branch)(원래 코드에서 갈라져 나온 별도의 작업 줄기)는 “원본을 건드리지 않고 따로 고쳐 보는 갈림길”이고, 워크트리(worktree)(한 저장소의 브랜치를 별도 폴더에 동시에 꺼내 두는 git 기능)는 그 갈림길마다 책상을 하나씩 더 놓아 주는 것이라고 생각하면 됩니다. 책상이 따로 있으니 세 명(에이전트)이 동시에 일해도 서류가 섞이지 않습니다. 그래서 작업을 바꿀 때마다 변경을 잠시 치워 두는 stash(고치던 것을 임시 보관함에 넣기)나 브랜치를 이리저리 바꾸는 번거로움이 없습니다.

저장소(repo) 기준 브랜치: origin/main 워크트리: fix-login 브랜치 1 워크트리: fix-login-2 브랜치 2 워크트리: fix-login-3 브랜치 3 Claude Code 터미널 + 브라우저 작업 중 Codex 터미널 + 브라우저 작업 중 Cursor CLI 터미널 + 브라우저 작업 중
Orca의 기본 그림: 저장소 하나에서 작업마다 워크트리가 갈라지고, 각 워크트리에 에이전트 터미널과 브라우저 탭이 붙습니다. 메인 창 왼쪽 사이드바에는 워크트리 목록이, 오른쪽에는 에이전트 터미널과 diff(변경 비교) 화면이 분할 창으로 놓입니다.

언제 Orca를 쓰면 좋은가

  • 같은 버그를 에이전트 셋에게 동시에 시켜 보고 가장 잘한 쪽을 고르고 싶을 때
  • AI가 만든 diff(파일이 어떻게 바뀌었는지 줄 단위로 보여 주는 비교 결과)를 내보내기 전에 꼼꼼히 검토하고 싶을 때
  • 이미 Claude Code, Codex, Cursor CLI 요금을 내고 있고, 이들을 한곳에서 지휘하고 싶을 때
  • 에이전트를 다른 컴퓨터에서 돌리고 싶을 때 — SSH(다른 컴퓨터에 암호화된 통로로 접속하는 방법), 직접 운영하는 Orca 서버, 필요할 때만 켜는 VM(클라우드에 빌려 쓰는 가상 컴퓨터) — 그러면서도 화면은 그대로 쓰고 싶을 때

누구를 위한 도구인가

Orca는 이미 코드를 직업으로 쓰는 사람이 AI를 “대체재”가 아니라 “지렛대”로 쓰도록 설계됐습니다. diff를 읽고, 커밋(변경 내용을 하나의 저장 단위로 기록하는 것)을 신경 쓰고, 워크트리를 깔끔하게 관리하는 사람을 전제로 합니다. 코드를 몰라도 되는 노코드(no-code) 도구를 찾는다면 Orca는 그런 도구가 아닙니다.

Orca가 아닌 것
  • AI 모델이 아닙니다. 이미 쓰는 에이전트를 실행할 뿐입니다. Claude, Codex, OpenCode 구독은 본인 것을 가져옵니다.
  • git을 대체하지 않습니다. 모든 워크트리는 진짜 git worktree입니다. 언제든 터미널에서 그 폴더로 들어가(cd(폴더 이동 명령)) 평범한 git 명령을 써도 됩니다.
  • 서버를 빌려주는 서비스가 아닙니다. VPS(월세로 빌리는 인터넷 서버 컴퓨터) 같은 상품을 팔지 않습니다. 기본은 내 컴퓨터에서 돌고, 다른 컴퓨터를 쓰더라도 내가 관리하는 기기·클라우드 계정(SSH 대상, 직접 운영하는 Orca 서버, Cloud VM/워크트리별 환경)을 씁니다.
다음 순서로 읽으세요

설치 → 첫 3-에이전트 세션(공식 문서가 “가장 중요한 페이지”라고 부르는 부분) → 노트북 밖에서 돌리고 싶어지면 실행 방식(Ways to run).

2. 설치

Orca는 보통 프로그램처럼 다운로드 → 더블클릭 → 설치하면 끝입니다. 공식 사이트의 Send download link(다운로드 링크 보내기)로 내 메일에 링크를 보내 두고, 설치할 컴퓨터에서 열 수도 있습니다. 내 운영체제 탭의 첫 줄만 읽으면 됩니다.

① 다운로드 내 OS에 맞는 파일 받기 ② 더블클릭 설치 파일 열기 ③ 설치·실행 “정말 열까요?” → 열기
세 단계면 설치가 끝납니다. 업데이트도 기본으로 자동입니다.

다운로드 → 더블클릭 → 설치. Apple Silicon(M1 이후 칩)용과 Intel용 중 내 Mac에 맞는 것을 받습니다. 첫 실행 때 macOS가 “정말 열까요?” 하고 물으면 열기를 누르면 됩니다.

Homebrew 설치·서명·공증

Homebrew로 설치 — Homebrew(macOS에서 명령 한 줄로 프로그램을 설치·업데이트하는 도구) cask로도 배포되며, 안정판이 나올 때마다 자동으로 버전이 올라갑니다.

brew install --cask stablyai/orca/orca
brew upgrade --cask orca   # 새 안정판으로 업데이트
Homebrew는 안정판만

cask는 stable(안정) 채널만 따라갑니다. RC 빌드가 필요하면 GitHub Releases 링크나 앱 안의 Check for Updates 방식(아래 “업데이트”)을 쓰세요.

플랫폼 메모: 앱은 서명(signed)·공증(notarized)(애플이 “출처가 확인된 앱”이라고 도장을 찍어 준 것)되어 있지만, 첫 실행 때 macOS가 “정말 열까요?” 하고 물을 수 있습니다. Electron(웹 기술로 만든 데스크톱 앱의 틀) 기반 앱에서는 정상적인 일입니다.

다운로드 → 더블클릭 → 설치. 설치 프로그램(installer)을 받아 실행합니다.

Windows 기본 셸·orca 명령
  • 기본 셸(터미널 안에서 명령을 받아 실행하는 프로그램)은 Settings → Terminal에서 PowerShell 또는 CMD로 정할 수 있습니다. 대부분은 PowerShell을 원합니다.
  • 함께 들어 있는 orca 명령은 네이티브 프로그램이라 Visual C++ Redistributable(별도 실행 라이브러리) 없이 동작합니다. 설치 프로그램이 PATH(컴퓨터가 명령 프로그램을 찾아보는 폴더 목록)에 추가해 줍니다.

다운로드 → 더블클릭(또는 설치) → 실행. 자동 업데이트를 원하면 AppImage(설치 없이 파일 하나로 실행되는 형식)를 고르세요.

Linux 패키지 형식·CLI 이름

AppImage, .deb, .rpm 세 가지가 있습니다.

형식업데이트 방식
AppImageOrca가 스스로 업데이트합니다. 자동 업데이트를 원하면 이것을 고르세요.
.deb / .rpm새 버전이 있다고 알려 주고, 설치에 쓸 패키지 관리자 명령을 보여 줍니다. 그 명령을 실행하기 전에 Orca를 종료하세요.
Linux에서는 CLI 이름이 다릅니다

Linux의 명령줄 도구 이름은 orca가 아니라 orca-ide입니다. GNOME의 화면 낭독기 “Orca”와 이름이 겹치지 않게 하기 위해서입니다.

예전 버전은 GitHub Releases 페이지에서 언제든 받을 수 있습니다. 지금 업데이트가 마음에 안 들면 이전 버전으로 돌아가도 됩니다.

되돌릴 때 데이터 형식

Orca는 되돌아가도 워크트리 데이터를 강제로 낮은 버전 형식으로 바꾸지(force-downgrade) 않습니다.

첫 실행 때 일어나는 일

① 홈 폴더 접근 권한 요청 — 저장소(repo)를 추가할 수 있도록 홈 폴더(내 사용자 이름으로 된 기본 폴더) 접근을 물어봅니다. 허용하면 됩니다.

② 기존 설정 가져오기 제안 — ~/.claude, ~/.codex, Ghostty 터미널 설정이 있으면 가져올지 물어봅니다. (~는 내 홈 폴더라는 뜻입니다.) 처음 쓰는 사람은 가져올 것이 없으니 넘어가면 됩니다.

③ 빈 시작 화면 — 아무것도 없는 랜딩 화면이 나오고, 여기서 첫 저장소를 추가합니다.

Orca

사이드바: (비어 있음)   Add Repo

업데이트: 안정판과 RC

Orca는 기본적으로 자동 업데이트되며 stable(안정) 채널을 따라갑니다. 초보자는 아무것도 바꾸지 않아도 됩니다. 안정판은 검증을 거친 버전이고, RC(release candidate, 출시 후보 — 새 기능이 먼저 들어간 시험판)는 거의 매일 나오기도 합니다.

RC·사전 출시판 받는 법

RC 채널을 “항상 받기”로 고정하는 앱 내 설정은 없습니다. 대신 Check for Updates 버튼(Settings → General → Updates, 또는 앱/Help 메뉴)을 보조 키와 함께 누르면 받을 빌드가 달라집니다.

클릭 방법효과
Shift+클릭최신 RC 사전 출시판(prerelease)까지 포함해 확인
Cmd+클릭 (macOS) / Ctrl+클릭 (Windows·Linux)성능(perf) 태그가 붙은 최신 사전 출시판
Option+클릭 (macOS 전용)내 컴퓨터에 있는 macOS 빌드 중 Orca 호환성 검사를 통과한 것을 골라 사용. 실패하면 “Could Not Use Local Build”가 뜨고 Choose Another Build(다른 빌드 고르기)를 누를 수 있습니다.

어떤 빌드든 GitHub Releases 페이지에서 직접 받을 수도 있습니다.

3. 실행 방식(Ways to run Orca)

초보자는 “① 로컬”만 알면 됩니다

설치한 내 컴퓨터에서 그대로 돌리는 것이 로컬이고, 대부분의 사람에게 기본입니다. 나머지 세 방식은 “노트북 밖에서 돌리고 싶어질 때” 돌아와 읽으세요.

모든 워크트리는 “어딘가”에서 돌아갑니다. 그 어딘가는 눈앞의 컴퓨터일 수도, 이미 가진 서버일 수도, 늘 켜져 있는 공용 서버일 수도, 그 작업 하나만을 위해 새로 띄운 클라우드 VM(인터넷 회사에서 빌려 쓰는 가상 컴퓨터)일 수도 있습니다.

비유로 보면

원격 방식은 회사에 늘 켜져 있는 PC를 집에서 원격 조종하는 것과 비슷합니다. 내 눈앞에는 화면만 있고, 실제 파일과 일하는 프로그램(에이전트)은 멀리 있는 컴퓨터에서 돌아갑니다. 내 노트북을 덮어도 회사 PC는 계속 일합니다.

화면은 어디? (내가 보는 곳) 파일·에이전트는 어디? (일하는 곳) ① 로컬 내 컴퓨터 같은 내 컴퓨터한 대에서 전부 ② SSH 내 노트북편집기·diff·화면 SSH로 접속한 다른 컴퓨터에이전트·워크트리 ③ 원격Orca 서버 노트북·브라우저·휴대폰화면 역할만 늘 켜 둔 Orca 서버 컴퓨터프로젝트·터미널·에이전트 전부 ④ Cloud VM 내 Orca 화면 작업마다 새로 띄운 환경내 클라우드 계정에 빌린 새 컴퓨터
왼쪽은 내가 눈으로 보는 곳, 오른쪽은 실제 파일과 에이전트가 일하는 곳입니다. 로컬만 두 쪽이 같은 컴퓨터입니다.

한 줄로 정리하면: 내가 보는 화면과 실제로 일하는 컴퓨터가 같은 곳이면 로컬, 다른 곳이면 원격 방식입니다. 한 번 설치한 Orca에서 네 방식을 섞어 쓸 수 있고, 원격 방식은 언제나 내가 관리하는 기기·클라우드 계정을 씁니다(Orca가 서버를 빌려주지 않음).

Orca를 설치하고, 프로젝트를 열고, 워크트리를 만듭니다. 에이전트·터미널·브라우저가 화면(UI)과 같은 컴퓨터에서 돌아갑니다. 사이드바의 “Local Mac” 아래 카드 하나하나가 자기 에이전트와 브랜치를 가진 워크트리입니다.

대부분의 사람에게 기본 경로입니다. 아래 “첫 3-에이전트 세션”을 따라 해 보세요.

한 줄 요약: 화면은 내 노트북, 일은 SSH로 접속한 다른 컴퓨터가 합니다. 워크트리를 만들 때 Run on(어디서 실행할지)에서 그 컴퓨터를 고르기만 하면 됩니다.

SSH 대상 설정 자세히

성능 좋은 Mac mini, Linux VPS, GPU 서버, SSH가 되는 클라우드 샌드박스 등 SSH로 접속되는 어떤 호스트든 지정할 수 있습니다. 워크트리를 만들 때 Run on에서 그 호스트를 고르면, 에이전트와 git worktree는 원격에서 돌고 편집기·diff·UI는 노트북에 남습니다.

잘 맞는 경우: 원격에 이미 저장소·도구·자격 증명(로그인 정보)이 있고, 노트북의 Orca 하나로 여러 서버를 부리고 싶을 때.

  1. 호스트 추가Settings → SSH에 호스트를 등록합니다.
  2. 연결 테스트저장소 워크트리를 쓰려면 그 호스트에 git이 설치돼 있어야 합니다.
  3. Run on에서 선택워크트리를 만들며 SSH 대상을 고릅니다. 입력하면 바로 걸러 주는 목록에 준비된 호스트가 나오고, 연결은 됐지만 이 프로젝트용 설정이 아직 안 된 호스트는 “setup-needed”(설정 필요) 줄로 보이며 선택할 수 없습니다.

SSH 워크트리는 VS Code Remote-SSH로 열 수 있고, SFTP가 허용되면 원격 폴더를 내려받을 수 있으며, 원격에서 터미널용 네이티브 모듈을 빌드하지 못해도 파일·git 작업은 계속 쓸 수 있습니다. 첫 연결 때 Orca가 그 호스트에 자체 관리 서버(managed server)를 설치하므로, Node 버전이 다르거나 빌드 도구가 없어도 연결이 막히지 않습니다.

한 줄 요약: “회사의 늘 켜진 PC를 집에서 원격 조종”하는 방식입니다. 한 기기에서 Orca를 계속 켜 두고, 노트북·브라우저·휴대폰은 화면 역할만 합니다.

원격 Orca 서버 설정 자세히

안 쓰는 노트북, Mac mini, 집 서버, 클라우드 VPS, 팀 서버 등 내가 관리하는 기기에서 Orca를 계속 켜 두고, 노트북·브라우저·휴대폰을 그 런타임(에이전트가 실제로 도는 실행 환경)에 “페어링(pairing, 짝 맺기)”합니다. 프로젝트·워크트리·터미널·에이전트 프로세스는 서버가 소유하고, 클라이언트(접속해서 보는 쪽 기기)는 화면 역할만 합니다.

잘 맞는 경우

  • 노트북이 잠들어도 에이전트가 계속 돌아야 할 때
  • 모바일에서 같은 세션에 다시 붙고 싶을 때
  • 자동화나 백엔드가 안정적인 호스트에서 세션을 시작해야 할 때

가장 쉬운 설정: 두 컴퓨터 모두에 Orca와 Tailscale(내 기기들끼리 안전한 사설 네트워크를 만들어 주는 서비스)을 설치합니다.

  1. 서버 쪽Settings → Remote Orca Servers → Advertise this app as a server → New Link에서 Tailscale 주소를 고르고 접속 링크(access link)를 만듭니다.
  2. 클라이언트 쪽Add Server를 누르고 그 링크를 붙여 넣습니다.

화면 없는(headless(모니터 없이 돌아가는)) Linux 서버나 서비스로 관리되는 VM이라면 대신 orca serve를 씁니다.

orca serve --pairing-address <접속 가능한 tailscale IP 또는 호스트 이름>

SSH와 원격 Orca 서버 비교

SSH 워크트리원격 Orca 서버
런타임 주인노트북의 Orca원격 기기(Orca 데스크톱 또는 orca serve)
연결이 끊기면에이전트는 호스트에서 계속 돌고, 노트북이 다시 붙음세션 상태 전체가 서버에 있음
여러 클라이언트노트북 하나가 호스트를 조종노트북·웹·모바일·자동화가 같은 런타임을 공유
보통 설정SSH config 가져오기, Run on 선택서버 앱을 공유하거나 orca serve 실행 후 URL로 페어링

Experimental 한 줄 요약: 작업(워크트리)마다 깨끗한 새 컴퓨터를 빌려 쓰고, 끝나면 버리는 방식입니다. 아직 실험 기능이라 초보자는 건너뛰세요.

Cloud VM 레시피 설정 자세히

각 워크트리가 자기만의 환경(클라우드 샌드박스(격리된 실험 공간), VM, 로컬 Docker(프로그램을 상자에 담아 따로 돌리는 도구) 컨테이너)을 필요할 때 띄울 수 있습니다. 환경은 저장소에 커밋된 레시피(orca.yaml + 수명 주기 스크립트)로 정의합니다. 만들면(create) 켜지고, suspend/resume/destroy(일시정지/재개/삭제)로 정리합니다. Orca는 얇은 포장일 뿐이라 제공자 계정·이미지·요금은 모두 내 것입니다.

제품 화면에서는 Settings → Experimental의 Cloud VM이라는 이름으로 보입니다. 레시피가 만드는 것은 여전히 “워크트리별 환경”(문서상 이름: per-workspace environment)입니다.

현재 사람들이 연결하는 제공자: Vercel Sandbox, Fly, Modal, 일반 SSH 호스트, 로컬 Docker. 연결 방식은 두 가지입니다 — Orca server(레시피가 orca serve를 띄우고 페어링 URL을 돌려줌) 또는 SSH(레시피가 접속 정보를 돌려주면 Orca가 접속).

잘 맞는 경우: 작업마다 깔끔한 격리, 쓰고 버리는 컴퓨팅, 모든 에이전트가 똑같은 표준 환경에서 시작하길 원할 때.

1. 켜기 — Settings → Experimental에서 Cloud VM을 켭니다. 그 화면에 짧은 “Create a Cloud VM” 안내와 레시피/런타임 조작 버튼이 있습니다.

2. 스킬 설치 — 필요하면 Cloud VM / per-workspace environment 스킬을 설치하거나 업데이트합니다.

3. 에이전트에게 부탁 — 아무 워크트리에서 에이전트에게 이렇게 말합니다.

Use the orca-per-workspace-env skill to set up a per-workspace environment for this repo.

4. 스킬이 안내 — 사전 준비 → 기본 스냅샷 → 에이전트 인증 → orca.yaml 레시피 → doctor(진단) 검증 순서로 진행합니다.

5. 사용 — Recipes에 레시피가 나타나면 워크트리를 만들며 Run on에서 그것을 고릅니다.

레시피가 목록에 안 보인다면

워크트리 생성 화면에 레시피가 나오려면 environmentRecipes 항목이 프로젝트 기본 체크아웃(primary checkout)의 orca.yaml에 있어야 합니다. 기능 브랜치에만 있으면 안 됩니다. 단, 스크립트를 다듬는 동안 doctor와 실제 프로비저닝은 어느 브랜치에서든 돌릴 수 있습니다.

BYO 클라우드 — Orca VPS가 아님

Cloud VM은 Orca가 호스팅하는 VPS를 주지 않습니다. 제공자는 직접 가져오고(BYO, Bring Your Own) 그 제공자에게 비용을 냅니다. Orca는 내 create/suspend/resume/destroy 스크립트를 실행하고, 스크립트가 출력한 페어링 URL이나 SSH 정보로 접속할 뿐입니다.

네 방식 비교표·고르는 기준(원격을 쓸 때)
Orca 화면(UI) 편집기·diff·사이드바 ① 로컬 내 데스크톱 일상 코딩 ② SSH 대상 이미 있는 서버 UI는 노트북에 ③ 원격 Orca 서버 늘 켜진 Orca 모바일·자동화 공유 ④ Cloud VM 작업마다 새 컴퓨터 쓰고 버림
한 번 설치한 Orca에서 네 가지 방식을 섞어 쓸 수 있습니다. 예: 간단한 수정은 로컬, GPU 서버는 SSH, CI(코드를 올릴 때마다 자동으로 검사하는 시스템)처럼 격리가 필요한 작업은 Cloud VM 레시피.
방식파일과 에이전트가 사는 곳기기 주인잘 맞는 용도
Local(로컬)내 데스크톱나일상 코딩, 빠른 반복
SSH target(SSH 대상)SSH로 접속하는 원격 호스트(다른 컴퓨터)나(또는 팀)개발용 서버, GPU 호스트, 상시 켜진 VPS(빌려 쓰는 인터넷 서버)
Remote Orca Server(원격 Orca 서버)Orca 데스크톱 또는 orca serve가 돌아가는 기기나(또는 팀)오래 유지되는 공유 런타임(에이전트가 실제로 도는 실행 환경), 모바일, 자동화
Cloud VM / 워크트리별 환경워크트리마다 쓰고 버리는 VM·샌드박스(바깥과 격리된 안전한 실험 공간)내 클라우드 계정(제공자는 직접 준비)격리된, 일회성 에이전트 컴퓨팅
Orca는 서버를 팔지 않습니다

Orca는 서버를 빌려주는 상품(관리형 VPS 호스팅)을 판매하지 않습니다. 원격 방식은 언제나 내가 관리하는 기기와 클라우드 계정을 씁니다.

어떻게 고를까

로컬에 머물기

노트북이 충분히 빠르고 에이전트 작업이 짧을 때.

SSH

이미 VPS(빌려 쓰는 서버)나 개발 서버가 있고, 두 번째 Orca를 설치하지 않고 거기서 에이전트를 돌리고 싶을 때.

원격 Orca 서버

모바일·브라우저·자동화가 함께 쓰는 상시 켜진 Orca 런타임 하나가 필요할 때.

Cloud VM

작업마다 레시피로 정의된 새 샌드박스를 받고, 워크트리가 사라지면 같이 사라지게 하고 싶을 때.

4. 첫 3-에이전트 세션

시작 전 준비물 — 이 둘이 없으면 1단계에서 막힙니다
  1. AI 코딩 에이전트 1개 설치·로그인. Orca는 AI 모델을 주지 않고, 내가 이미 쓰는 에이전트(Claude Code, Codex 등)를 돌립니다 — 그 에이전트의 구독(대부분 유료)은 직접 준비해야 합니다. 에이전트를 설치한 뒤 아무 터미널에서 한 번 로그인해 두면, Orca가 그 로그인 정보를 자동으로 가져다 씁니다. 아래 예시처럼 세 종류를 비교하려면 각 에이전트마다 이 준비가 필요합니다.
  2. git 저장소 폴더 1개. 1단계에서 고를 “프로젝트 폴더”는 git으로 관리되는 폴더(저장소)여야 합니다 — Orca의 워크트리는 모두 진짜 git 워크트리이기 때문입니다. 그런 폴더가 없다면 팀의 개발자에게 쓸 저장소를 받아 내 컴퓨터에 받아 두거나(clone(서버의 저장소를 내 컴퓨터로 복사해 오기)), 저장소 주소(clone URL)로 추가하는 방법을 물어보세요.

공식 문서가 “가장 중요한 페이지”라고 부르는 흐름입니다. 빈 앱에서 시작해 5분 안에 같은 작업을 에이전트 셋에게 동시에 시켜 보고, 그중 가장 잘한 것으로 PR(Pull Request — “내 변경을 원본에 합쳐 주세요”라는 요청서)을 냅니다. 아래 그림에서 빨간 테두리가 깜빡이는 곳을 차례로 누르면 됩니다.

1. 저장소 추가 — Add Repo 누르기: 사이드바의 Add Repo를 누르고 내 컴퓨터에 있는 프로젝트 폴더를 고릅니다.

Orca 사이드바 Add Repo 저장소 추가 (아직 아무것도 없음) 빈 시작 화면
화면 흉내 — 빨간 테두리가 깜빡이는 곳을 누릅니다. (실제 모양은 버전에 따라 조금 다를 수 있습니다.)

Orca는 그 폴더의 git 상태를 읽고 기본 브랜치를 기준 브랜치(base ref(저장소의 기본 기준 — 보통 서버에 있는 원본 줄기 origin/main))로 잡습니다. 새 워크트리는 기본적으로 여기서 갈라져 나옵니다. 기준 브랜치는 나중에 저장소 설정에서 바꿀 수 있습니다.

2. 워크트리 만들기 — + 누르고 이름 적기: 저장소 이름 옆 +를 누르고 작업 이름을 적습니다(예: fix-login-race). 비워 두면 Orca가 해양 생물 이름을 붙여 줍니다.

Orca 사이드바 📁 my-app + 새 워크트리 작업 이름 fix-login-race 출발점 origin/main ▾ 에이전트 Claude Code (기본 선택) ▾
화면 흉내 — 빨간 테두리가 깜빡이는 곳을 누릅니다. (실제 모양은 버전에 따라 조금 다를 수 있습니다.)
  • 화면에는 Workspace(워크스페이스 — 워크트리와 같은 것)라는 말도 나옵니다. 원클릭 Workspace 실행기(launcher)가 열리고, 기본 에이전트가 미리 선택돼 있습니다(Settings → Agents에서 변경). 빈 터미널만 열 수도 있습니다.
  • 출발점(start-from ref(이 새 워크트리가 갈라져 나오는 지점))은 보통 그대로 둡니다. 대개 기준 브랜치와 같은 기본값 origin/main은 “인터넷 서버(GitHub 등)에 있는 원본 줄기”라는 뜻입니다. 원하면 다른 브랜치나 커밋에서 시작해도 됩니다.
워크트리가 만들어지는 곳·고정

Orca가 관리 폴더 아래에 진짜 git worktree를 만들고, 브랜치를 체크아웃(그 브랜치 내용을 폴더에 꺼내 놓기)해 엽니다. 고정(pinned)한 워크트리는 사이드바에서 눈에 띄게 표시되어 자주 쓰는 것을 놓치지 않습니다.

3. 에이전트 고르기 — 선택 상자에서 고르기: 새 워크트리에 터미널이 열리고 에이전트 선택 상자가 보입니다. Claude Code, Codex, Cursor CLI 등을 고르면 됩니다.

Orca 사이드바 📁 my-app fix-login-race 터미널 — fix-login-race 에이전트 고르기: Claude Code ▾ Claude Code Codex Cursor CLI 고르면 바로 실행
화면 흉내 — 빨간 테두리가 깜빡이는 곳을 누릅니다. (실제 모양은 버전에 따라 조금 다를 수 있습니다.)

Orca가 올바른 작업 폴더에서 그 에이전트의 CLI(글자 명령으로 쓰는 프로그램)를 실행하고, 내 구독 자격 증명(내가 이미 결제·로그인한 계정 정보)을 넘겨줍니다. 그래서 시작 전 준비물 ①대로 터미널에서 한 번 로그인해 두었다면 Orca 안에서 따로 로그인할 필요가 없습니다.

4. 세 에이전트 경주 — 사이드바에 워크트리 3개: 2~3단계를 두 번 더 반복해 워크트리를 셋으로 만들고, 세 곳에 똑같은 부탁(프롬프트)을 붙여 넣습니다.

Orca 사이드바 📁 my-app fix-login-raceClaude Code fix-login-race-2Codex fix-login-race-3Cursor CLI Claude Code 에게: “로그인 버그를 고쳐 줘 …” Codex 에게: “로그인 버그를 고쳐 줘 …” Cursor CLI 에게: “로그인 버그를 고쳐 줘 …” 같은 부탁(프롬프트)을 세 곳에 붙여 넣기
화면 흉내 — 빨간 테두리가 깜빡이는 곳을 누릅니다. (실제 모양은 버전에 따라 조금 다를 수 있습니다.)

브랜치 셋, diff 셋, 프롬프트 하나. 이제 일하게 둡니다.

5. 창을 셋으로 나누기 — 탭을 가장자리로 끌기: 워크트리의 탭을 다른 창(pane)의 오른쪽이나 아래쪽 가장자리로 끌어다 놓으면 화면이 분할됩니다.

Orca 사이드바 📁 my-app fix-login-race fix-login-race-2 fix-login-race-3 Claude Code작업 중… Codex작업 중… Cursor CLI작업 중… 탭을 끌어 가장자리에 놓기
화면 흉내 — 빨간 테두리가 깜빡이는 곳을 누릅니다. (실제 모양은 버전에 따라 조금 다를 수 있습니다.)

세 에이전트가 일하는 모습을 동시에 지켜볼 수 있습니다.

6. 승자 고르기 → diff 검토 → 내보내기: 에이전트들이 멈추면 각 워크트리의 diff 화면을 엽니다. Annotate AI Diff로 줄마다 의견을 달아 가장 잘한 에이전트에게 돌려보내고, 다 되면 Commit(저장)과 Push(내 컴퓨터의 저장 기록을 인터넷 서버에 올리기)를 Orca 안에서 바로 합니다.

코드를 못 읽어도 “가장 잘한 것” 고르는 법
  • 결과 화면 비교 — 워크트리마다 있는 브라우저 탭에서 결과를 직접 눌러 보고, 내가 부탁한 대로 동작하는 쪽을 고릅니다.
  • 바뀐 줄 수 — diff 화면 위쪽 작은 표시(칩)에 더한 줄·지운 줄 수가 나옵니다. 결과가 비슷하면 덜 바꾼 쪽이 검토하기 쉽습니다.
  • 자동 검사 통과 여부 — PR을 올린 뒤 Checks 패널에서 검사(CI)가 통과했는지 봅니다. 셋의 결론이 같으면 아마 정답입니다.

자세한 검토 순서는 6장 레시피: AI diff를 줄 단위로 리뷰하기를 보세요.

Orca 사이드바 📁 my-app fix-login-race ✓ fix-login-race-2 🗑 fix-login-race-3 🗑 변경 비교(diff) — fix-login-race - 옛 줄 (지워진 부분) + 새 줄 (더해진 부분) + 새 줄 Annotate AI Diff 줄마다 의견 달기 Commit Push 저장 → 서버에 올리기
화면 흉내 — 빨간 테두리가 깜빡이는 곳을 누릅니다. (실제 모양은 버전에 따라 조금 다를 수 있습니다.)

나머지 두 워크트리는 클릭 한 번으로 지울 수 있고, 그 브랜치도 함께 지워집니다.

저장소 추가add 워크트리worktree 에이전트agent 창 분할split 변경 검토diff 내보내기ship 폴더 고르기 작업용 책상 AI에게 일 시키기 나란히 보기 바뀐 줄 확인 커밋·push·PR
이 흐름(저장소 추가 → 워크트리 → 에이전트 → 창 분할 → 변경 검토 → 내보내기)이 Orca의 전부입니다. 나머지 기능은 모두 이 단계 중 하나를 더 깊이 다룬 것입니다.

레시피: 같은 작업으로 에이전트 셋 경주시키기

같은 작업을 여러 에이전트에게 병렬로 시키는 것은 Orca의 “필살기”입니다. 정리하면 다음과 같습니다.

  1. 같은 출발점에서 워크트리 3개같은 출발점(start-from ref)에서 fix-bug, fix-bug-2, fix-bug-3을 만듭니다.
  2. 서로 다른 에이전트각각 Claude Code, Codex, Cursor CLI를 띄웁니다.
  3. 같은 프롬프트세 곳에 똑같이 붙여 넣습니다.
  4. 창 분할탭을 가장자리로 끌어 일하는 모습을 함께 봅니다.
  5. diff 검토끝나면 각 diff를 보고, 승자에게 Annotate AI Diff를 씁니다. 승자는 결과 화면·바뀐 줄 수·검사 통과로 고릅니다(위 4절 6단계의 “고르는 법” 참고).
  6. 승자에서 PR이긴 워크트리에서 커밋·push·PR 열기.
  7. 패자 정리나머지 둘을 삭제합니다. 클릭 한 번이면 워크트리와 브랜치가 함께 지워집니다.
같은 프롬프트 Claude Code Codex Cursor CLI 셋이 일치 → 아마 정답 하나씩 다시 시킬 때보다 시간이 덜 듦 셋이 갈림 → 어려운 지점 발견 의견 차이 자체가 신호
왜 효과가 있나: 에이전트마다 실수하는 방식이 다릅니다. 동시에 시키면 하나씩 차례로 다시 시키는 것보다 비용(특히 기다리는 시간)이 덜 들고, 의견 차이를 “신호”로 드러냅니다.

5. Agents 피드(Activity)

사이드바의 Agents 항목을 누르면 모든 워크트리의 에이전트 소식을 대화 묶음(thread) 형태로 보여 주는 피드(새 소식이 위아래로 쌓이는 목록 — SNS 타임라인 같은 것)가 열립니다. 자리를 비웠다 돌아와서 “무엇이 끝났고 누가 나를 기다리나”를 한곳에서 확인하고, 처리할 순서를 고르게(triage) 해 줍니다.

Orca — Agents 피드(화면 흉내)
🔍 필터 (Cmd/Ctrl+F) Agents 3 📌 fix-login-race · Claude Code — 실행 중 실행 중인 에이전트는 맨 위에 고정 ⏸ fix-login-race-2 · Codex — 막힘(blocked): 질문에 답을 기다림 “이 파일도 고칠까요?” … (최근 응답 미리보기) ✓ fix-login-race-3 · Cursor CLI — 한 차례 끝남(idle) “로그인 오류를 고쳤습니다…” (최근 응답 미리보기) + 새 워크트리 생성: add-dark-mode

줄을 누르면 그 워크트리로 바로 이동합니다. 숫자 배지는 마지막으로 본 뒤 새로 온 소식 수입니다.

  • 기본으로 켜져 있습니다. 마지막으로 본 뒤 새 사건이 오면 읽지 않음 배지가 붙습니다.
  • 항목을 클릭하면 해당 워크트리와 창(pane)으로 바로 이동합니다 — 시스템 알림을 눌렀을 때와 같은 동작입니다.
  • Cmd+F(macOS) / Ctrl+F(Windows·Linux)로 피드 필터에 커서를 옮깁니다. 단, 내장 터미널에 포커스가 있으면 그 단축키는 터미널이 가져갑니다.
  • 피드 머리글에는 현재 적용된 필터가 표시됩니다.
  • 에이전트 줄을 오른쪽 클릭하면 동작 메뉴가 나옵니다. Cmd(Windows·Linux는 Ctrl)을 누른 채 여러 줄을 고르면 한 동작을 한꺼번에 적용할 수 있고, 동작 후에도 Activity 화면에 그대로 머뭅니다.
피드에 나오는 것
  • 에이전트가 한 차례(turn)를 마침 — 쉬는 중(idle)이거나 질문에 막힘(blocked)
  • 새 워크트리 생성
  • 입력을 오래 기다려 “막힘”으로 올라온 에이전트
  • 에이전트의 가장 최근 응답 짧은 미리보기 — 스레드를 하나하나 열지 않고 훑어볼 수 있음

스레드는 상태별로 묶이며, 실행 중인 에이전트는 맨 위에 고정됩니다.

알림과의 관계

Agents 피드는 머리글 벨이나 시스템 알림을 대체하지 않습니다. 그것들은 에이전트 완료 때 계속 울립니다. 피드는 자리를 비웠다 돌아왔을 때 “무엇이 바뀌었나”를 워크트리마다 스크롤하지 않고 한 번에 훑는 따라잡기용 화면입니다.

6. 알림과 받은 편지함(Notifications & Inbox)

Orca는 그냥 터미널이 아니라 에이전트를 돌리기 때문에, 에이전트가 진짜로 끝났는지 잠시 멈춘 건지 구분할 수 있습니다. 알림은 이 신호를 이용합니다. 에이전트 셋을 걸어 두고 자리를 비웠다가, 첫 번째가 끝나면 돌아오면 됩니다.

작업 중 working 끝남(쉬는 중) idle 시스템 알림 소리(연달아 끝나도 생략 안 됨) 워크트리 옆 작은 표시(칩) 머리글 벨(읽지 않음 모음) macOS Dock 아이콘 배지
에이전트가 working → idle로 바뀌면 여러 경로로 알려 줍니다. 각 경로는 설정에서 따로 끌 수 있습니다.
기능설명
Agent-finished pings(완료 알림)에이전트가 작업 중 → 쉬는 중으로 바뀌면 시스템 알림·소리·워크트리 칩(사이드바 워크트리 이름 옆에 붙는 작은 꼬리표 모양 표시)이 나갑니다. 한 에이전트가 끝난 직후 다른 에이전트가 끝나도 완료음은 빠지지 않고 울립니다.
Persistent bell(상시 벨)머리글 벨에 모든 워크트리의 읽지 않은 알림이 모입니다. 알림을 누르면 해당 워크트리·창으로 이동합니다.
Dock 배지 (macOS)같은 읽지 않음 개수가 Dock 아이콘에도 표시되어 Orca를 앞으로 꺼내지 않아도 알 수 있습니다. 해당 워크트리를 방문하면 사라집니다.
Mark unread(읽지 않음으로 표시)알림을 오른쪽 클릭해 다시 읽지 않음으로 만듭니다. 일단 확인했지만 나중에 다시 보고 싶을 때 씁니다.
Tuning(세부 조정)Settings → Notifications에서 종류별(system, sound, chip-only)로 끌 수 있습니다.

알림을 띄울 기기 고르기, 알림 소리 바꾸기, 채팅 화면에서의 예외 동작은 아래 접힌 상자에 있습니다.

기기별 알림 · 사용자 소리 · 채팅 화면 예외
기능설명
구조화된 채팅(structured chat)의 경우구조화된 채팅(검은 터미널 대신 메신저처럼 말풍선으로 주고받는 채팅 화면)의 업데이트된 버전에서 한 차례(turn(내 메시지 하나에 에이전트가 일하고 답하는 한 차례))가 성공하면 시스템 알림이나 소리 대신 그 탭과 워크트리에 읽지 않음 표시만 붙습니다. 실패하거나 취소된 차례는 읽지 않음 표시를 붙이지 않습니다.
Per-machine(기기별)Settings → Notifications → Machines에서 이 컴퓨터에 알림을 띄울 기기(이 컴퓨터, SSH 대상, 페어링된 Orca 서버)를 고릅니다. 페어링된 서버의 스위치는 그 서버를 거쳐 닿는 작업까지 포함합니다. 끈 기기는 “제외 목록”으로 저장되므로 나중에 추가한 기기는 기본으로 알림이 옵니다. 이 스위치는 이 컴퓨터의 데스크톱 알림에만 영향을 주며 휴대폰 푸시는 그대로입니다.
Custom sounds(사용자 소리)종류별로 데스크톱 알림 소리를 고릅니다 — 디스크의 아무 오디오 파일이나 Orca 내장 소리. 메일·Slack 소리와 구분하고 싶을 때 유용합니다. 지원 형식: MP3, WAV, OGG, M4A, AAC, FLAC. 한 파일이 전달되는 모든 데스크톱 알림에 적용됩니다. 사용자 소리를 쓰면 같은 화면에서 재생 음량도 정할 수 있습니다.

7. 설정(Settings) 전체 지도

처음엔 General · Agents · Notifications만 보세요

설정 화면은 19개나 되지만, 처음에 손댈 일은 거의 이 세 곳뿐입니다. 나머지는 아래 “🔧 개발자용 참고” 상자에 모두 접어 두었습니다. 어떤 설정이든 Cmd+,(macOS)를 누르고 키워드를 입력하면 검색할 수 있습니다.

기본·모양 General 일반 Appearance 모양·언어 Shortcuts 단축키 Terminal 터미널 에이전트·채팅 Agents 에이전트 Chat 채팅 Quick Commands 빠른 명령 Browser 브라우저 Artifacts 공유 파일 연결 Git git·GitHub Repository 저장소별 Integrations 외부 서비스 SSH 원격 접속 원격 서버 Remote Orca Servers 알림·음성 Notifications 알림 Voice 음성 받아쓰기 고급 떠 있는 공간 Floating Workspace Plugins 플러그인 Experimental 실험 기능 = 처음엔 이 3개만 (General · Agents · Notifications)
설정 탭 19개를 용도별 다섯 묶음으로 나눈 지도입니다. 빨간 테두리가 깜빡이는 세 곳이 초보자 필수입니다. (묶음은 이 가이드가 이해를 돕기 위해 나눈 것으로, 실제 화면의 순서와는 다릅니다.)

초보자 필수 3개

General(일반) — 앱 전체에 걸친 기본 동작. 초보자가 볼 것: Updates(업데이트 확인·설치), UI zoom(화면 글자 크기 배율), Default new-worktree name(새 워크트리 기본 이름).

General 항목 전체
항목설명
Orca CLI함께 들어 있는 명령줄 도구를 셸과 에이전트가 쓸 수 있게 등록합니다.
Updates업데이트 확인·설치. Check for Updates의 보조 키 클릭: Shift+클릭 = 최신 RC 포함 / Cmd+클릭(macOS)·Ctrl+클릭(Windows·Linux) = 최신 perf 태그 사전 출시판 / Option+클릭(macOS만) = 호환성 검사를 통과한 로컬 macOS 빌드 선택. 실패 시 “Could Not Use Local Build”와 Choose Another Build.
Open in menu워크트리의 “Open in”(다른 앱으로 열기) 메뉴에 나올 앱을 고릅니다. VS Code / Insiders는 SSH 워크트리를 Remote SSH로 열 수 있고, 다른 편집기는 로컬 경로로만 엽니다.
UI zoom설치본별 화면 배율.
Default new-worktree name새 워크트리 기본 이름: 사용자 접두어 또는 해양 생물 이름.
Editor Word Wrap파일 편집기의 기본 줄 바꿈(기본 켜짐). 파일 탭의 ⋯ 메뉴나 Alt+Z로 전환. Diff Word Wrap과는 별개입니다.
Reuse a preview tab when browsing files기본 켜짐. 파일을 한 번 클릭하면 현재 미리보기 탭을 바꿔치기합니다. 끄면 한 번 클릭한 파일마다 새 탭이 열립니다.
Collapse Unchanged Regions단일 파일 diff에서 바뀌지 않은 긴 구간을 접고 주변 몇 줄만 보여 줍니다. 필요하면 펼칠 수 있고, “View all changes”(전체 변경 보기)는 자기만의 접힘 배치를 따로 유지합니다.

Agents(에이전트) — 가장 항목이 많은 화면입니다. 초보자가 볼 것: Installed agents(내 컴퓨터에서 찾은 에이전트 켜고 끄기), 새 워크트리에 미리 선택될 기본 에이전트, Agent permissions(에이전트가 일할 때 매번 나에게 허락을 받을지 — Manual은 매번 승인, Auto는 일상적인 동작만 스스로 승인, Yolo는 묻지 않음), Account lists(쓰는 AI 계정 목록).

Agents 항목 전체
항목설명
Installed agents감지된 CLI 목록. 켜고 끌 수 있으며, 끄면 실행 메뉴에 원하는 CLI만 보입니다.
Per-agent launch defaults에이전트별 실행 파일 경로·이름 지정, 기본 Command·Arguments(와 환경 변수) 편집. 구조화된 네이티브 채팅도 같은 명령·인자를 씁니다. 이 실행 설정은 워크트리가 돌아가는 호스트에서 편집되므로, 원격·SSH 워크트리는 그 기기의 설정을 씁니다.
Agent permissions새 터미널·구조화 채팅 세션의 권한 모드: Manual(매번 승인), Auto(일상적 동작은 에이전트가 스스로 승인 — Claude, Claude Agent Teams, Codex 지원), Yolo(묻지 않음). Auto를 고르면 지원하지 않는 에이전트용으로 Other agents에서 Manual 또는 Yolo를 정합니다. 기존 채팅은 현재 모드를 유지하고, 사용자 지정 실행 인자를 쓰는 에이전트는 그 인자를 프리셋으로 바꾸기 전까지 그대로입니다.
Trust the folder when Orca starts an agent기본 켜짐. Orca가 실행하는 에이전트(오케스트레이션 작업자, 자동화, 휴대폰에서 시작한 에이전트 포함)가 “이 폴더를 신뢰하나요?” 질문을 건너뜁니다. 끄면 각 에이전트 자신의 신뢰 질문이 그대로 나옵니다.
Share Codex history across accounts기본 켜짐. Orca가 관리하는 계정의 기록이 시스템 기본 계정으로 돌아갔을 때 ~/.codex에도 보입니다. 끄면 새 공유만 멈추고 기존 기록은 지우지 않습니다. 오래된 SSH·WSL 호스트는 업데이트해야 이 설정이 나타납니다.
Run each Codex terminal on its own server기본 켜짐. Codex 탭의 상태 표시와 탭 닫기가 정확하게 동작하도록 합니다. 끄면 Codex의 공용 서버와 그 에이전트 개요 화면을 씁니다. 새 터미널부터 적용. 직접 시작한 Codex가 서버를 공유하면 Warn when a Codex tab shares a server 알림이 뜹니다.
Account listsClaude, Codex, OpenCode, Devin, Antigravity, GLM Coding Plan 계정 목록. Linux에서 암호화하지 못한 저장 자격 증명은 경고로 표시됩니다. Claude 계정마다 설정 폴더가 따로 있으며, 기본 브라우저가 이미 다른 Claude 이메일로 로그인돼 있으면 계정 추가 시 Copy sign-in link(로그인 링크 복사)를 제안합니다. Antigravity 계정 줄은 채팅 런타임 설치 상태를 보여 주고 그 호스트에 설치·제거할 수 있습니다.
OpenCode Go session cookieGo 요청 한도를 보려면 __Host-console_session을 포함한 opencode.ai의 전체 Cookie 헤더를 붙여 넣습니다. 인증 쿠키 하나만으로는 부족합니다.
Startup hooks에이전트별 시작 훅(시작할 때 자동으로 실행할 동작).
Agent status hooksOrca에 working / waiting / done 상태를 표시. 앱을 재시작하지 않아도 바로 적용됩니다(Windows WSL 훅 중계 포함). CLI: orca agent hooks on|off|status.
Keep computer awakeOn(계속 깨어 있음), Agent(에이전트가 일하는 동안만), Off. 데스크톱 상태 표시줄의 Caffeinate(커피 아이콘)도 같은 조작입니다. 페어링된 웹 클라이언트에서는 숨겨집니다.
Skill freshnessAgents 화면과 스킬 카드는 전체 상태를 보여 주지만, 사이드바는 조치가 필요한 스킬(Update available, Needs attention / review)에만 배지를 답니다. 정상·로딩 중·선택 사항 미설치는 조용합니다. 대화상자의 Update로 전역 스킬을 백그라운드에서(터미널 없이) 갱신하고, 진행 상황은 상태 표시줄에 나옵니다. 대화상자를 닫아도 작업은 취소되지 않습니다.

Notifications(알림) — 자세한 내용은 위 “6. 알림” 절.

  • Agent-finished(에이전트 완료): 시스템 알림, 소리, 칩(워크트리 옆 작은 표시) 각각 켜고 끄기
  • 종류별 사용자 지정 데스크톱 알림 소리
  • Machines: 이 컴퓨터에 알림을 띄울 기기(이 컴퓨터, SSH 대상, 페어링된 Orca 서버). 페어링된 서버 스위치는 그 서버를 거친 작업까지 포함하고, 새로 추가한 기기는 알림이 옵니다.
  • PR check failures(PR 검사 실패)
  • Update available(업데이트 있음)
나머지 설정 탭 16개 전체

이 가이드의 다른 장에서 해당 기능을 자세히 다룹니다.

Appearance(모양) — 테마·글꼴·상태 표시줄·언어.

항목설명
Theme, accent color, density테마, 강조색, 화면 밀도. 설치한 플러그인이 앱·터미널 테마를 테마 선택기에 추가할 수 있고, 앱 테마가 터미널 색까지 함께 제공하기도 합니다.
Font familyUI 글꼴. 편집기 글꼴은 선택 사항으로, 비워 두면 터미널 글꼴을 따르고 값을 넣으면 파일 편집기와 diff에만 적용됩니다.
Editor minimap편집기 오른쪽 축소 지도 켜기/끄기.
Status bar toggles상태 표시줄 항목 켜기/끄기. 여기에 Resource Manager(CPU·메모리·세션, 데몬 조작, 워크트리 디스크 검사)가 있습니다. 프로젝트가 페어링된 Orca 서버에 있으면 그 서버의 프로세스를 서버 이름 아래에 보여 줍니다.
Usage percentages상태 표시줄 목록(roster)에 AI 제공자 한도를 “사용한 %” 또는 “남은 %”로 표시. 목록은 이제 기본이 짧은 Compact 보기이며(이미 고른 적이 있으면 유지), 같은 선택기에서 Detailed도 고를 수 있습니다.
App IconDock과 창 전환기에 보이는 아이콘: Classic, Watercolor, Blue 중 선택.
Language인터페이스 언어: System(OS를 따름), English, 中文(简体), 繁體中文, 한국어, 日本語, Español, Deutsch, Русский, Türkçe. 설정 검색은 각 언어의 “언어”라는 단어(语言 / 語言 / 언어 / 言語 / Idioma)로도 찾아 주므로, 화면이 아직 영어여도 “언어”로 검색할 수 있습니다.

Chat(채팅) — 기본 실행 화면을 Chat(채팅 UI)으로 할지 CLI(터미널)로 할지와 에이전트별 예외를 정합니다(Agents 화면에서도 가능). 새로 설치하면 기본은 Terminal이고, 기존 실행 설정은 유지됩니다.

항목설명
Behavior에이전트가 일하는 동안 후속 메시지를 대기열에 쌓을지, 사용량 한도에 걸린 채팅이 한도가 풀리면 자동으로 이어갈지 정합니다. 새 세션의 권한 기본값은 Agents 화면에서 정하며, 이미 있는 채팅은 자기 모드를 유지합니다.
Agents지원 에이전트마다 Chat 또는 CLI 선택. 이 데스크톱에서 시작하는 모든 경우(CLI, 오케스트레이션, 휴대폰에서 중계된 실행 포함)에 적용됩니다. Antigravity의 채팅 런타임이 없으면 그 줄에 Install이 보이고, Remove는 실행 중인 채팅을 멈추고 런타임을 지우되 채팅 기록은 남깁니다.
Appearance채팅 글꼴(미리보기와 설치된 글꼴 추천 포함), 본문 크기·코드 크기(px), 너비, 대비. Match terminal interface를 켜면 채팅 전체가 터미널의 글꼴·색을 쓰고, 나중에 터미널 테마를 바꿔도 따라갑니다. 켜져 있는 동안 글꼴·크기 조절은 비활성화됩니다. Reset chat appearance로 기본값 복원.
Inline visuals에이전트가 답변 안에 차트·다이어그램·목업을 보여 주도록 허용. 새로 시작하는 채팅에 적용됩니다.
Chat naming새 채팅은 기본적으로 자기 에이전트와 계정으로 이름을 만듭니다. Advanced에서 이름 짓기용 에이전트를 따로 고를 수 있고, 예전에 저장한 이름 짓기 명령·인자도 계속 동작합니다.

Git — 브랜치 기준점과 GitHub 사용량.

항목설명
Default base ref resolver기본 base ref(새 워크트리의 출발점)를 정하는 방식.
Commit signing커밋 서명 옵션.
Editor for external git tools외부 git 도구가 쓸 편집기.
Auto-Rename Branch From WorkOrca가 만든 생물 이름 브랜치를, 에이전트가 일을 시작한 뒤 작업 내용에 맞게 이름을 바꿉니다.
GitHub API Budget로컬 gh CLI 기준으로 남은 REST(core)·Search·GraphQL 할당량. PR 검사나 Tasks가 갱신을 멈췄을 때 유용합니다. 숫자는 괜찮은데 GitHub가 실제 호출을 막는다면 아래 “GitHub 오류” 절을 보세요.

Terminal(터미널)

항목설명
Font, theme, cursor style, padding글꼴, 테마, 커서 모양, 여백.
Ghostty importGhostty 터미널 설정 가져오기.
Warp theme importImport themes from Warp(OS별 Warp 테마 폴더를 자동으로 찾음) 또는 Import from YAML(Warp 형식 테마 파일이 든 아무 폴더)로 Warp YAML 테마를 가져옵니다.
JIS Yen (¥) to Backslash (\)macOS 일본어 키보드에서 ¥ 키를 백슬래시로.
Default shell새 로컬 터미널 탭의 기본 셸. 비우면 시스템 기본값. Windows에서는 가능한 경우 PowerShell, Command Prompt, WSL도 고를 수 있습니다.
Shell argumentsUnix 사용자 지정 기본 셸의 인자(Default shell → Advanced). -l(기본, 로그인 셸) 또는 Custom args를 골라 한 줄에 하나씩 입력. 빈 목록이면 인자를 넘기지 않습니다.
Running terminal limit컴퓨터별 동시 실행 터미널 한도(Advanced). 기본은 시스템 터미널 한도의 절반(최대 4096), 시스템 한도를 못 읽으면 256. 바꿔도 이미 열린 터미널은 닫히지 않습니다. 업데이트 후에는 새 터미널을 열어야 새 터미널 호스트를 씁니다. 오래된 원격 서버는 업데이트해야 한도를 바꿀 수 있습니다.
Allow TUI Clipboard Writes (OSC 52)기본 켜짐. Zellij, tmux, Neovim, fzf, Grok 같은 터미널 화면 프로그램이 PTY(가상 터미널)를 통해 — SSH 너머에서도 — 시스템 클립보드에 쓸 수 있게 합니다. 예전처럼 막아 두고 싶으면 끕니다.

Quick Commands(빠른 명령)

  • 저장해 둔 터미널 명령과 에이전트 프롬프트 프리셋. 범위는 전체(Global) 또는 프로젝트별. 줄마다 명령 본문 복사 버튼이 있습니다.
  • 범위 필터로 목록을 검토·편집합니다. 같은 목록이 모바일 앱과 동기화됩니다.
  • 원격·다중 호스트 환경에서는 명령을 소유한 Orca 호스트별로 묶어 보여 줍니다(Saved on). 호스트 소유는 Global/Project 범위, 그리고 명령이 실행되는 곳과는 별개입니다.

Browser(브라우저) — 워크트리별 내장 브라우저.

항목설명
Profiles브라우저 프로필(로그인 상태 등을 분리 보관).
Default Zoom새로 여는 브라우저 탭의 확대 수준. 탭마다 Cmd+휠(macOS)로 바꾼 값은 따로 기억됩니다.
Design Mode defaults디자인 모드 기본값.
Devtools opt-in개발자 도구 사용 선택.
Remote server workspaces페어링된 런타임의 새 브라우저 페이지를 This device(이 데스크톱에서 그림) 또는 Server (streamed)(서버에서 그려 스트리밍)로. 트래픽은 항상 원격 서버를 거치며, 새 페이지에만 적용됩니다.
Browse through SSH workspace hosts브라우저 트래픽과 DNS를 각 워크트리의 SSH 호스트를 통해 보냅니다. 끄면 이 기기에서 직접 접속합니다.
Link Routing터미널·마크다운·편집기의 http(s) 링크를 Orca 브라우저로 열지 시스템 브라우저로 열지. 하위 옵션 Hold Shift…를 쓰면 한 번의 클릭에 한해 반대로 동작합니다(⇧⌘-클릭 / Shift+Ctrl+클릭).
Terminal URL clicks터미널 URL을 그냥 클릭했을 때 동작 메뉴를 열지, 바로 열지, 보조 키가 필요한지. 가운데 클릭 동작은 따로 설정합니다.
Show terminal link actions기본 켜짐. 터미널 링크를 그냥 클릭하면 작은 동작 팝오버가 열립니다. 끄면 ⌘-클릭 / Ctrl-클릭해야 열립니다.
Default Search Engine주소창이나 새 탭 검색창에 URL이 아닌 글을 입력했을 때 쓸 검색 엔진.

Artifacts(공유 파일) — HTML/Markdown을 공개 링크로 공유.

항목설명
Orca account공유 파일을 게시·관리하려면 로그인(Orca Relay와 같은 계정 계열).
Allow publishing public artifact links기본 꺼짐. 기기 전체에 걸린 관문입니다. 켜면 나·에이전트·이 기기의 orca CLI가 최대 10 MiB의 HTML/Markdown을 올리고 공개 보기 링크를 만들 수 있습니다. 꺼도 이미 만든 링크는 지워지지 않습니다.
Show Artifacts / sidebar shortcutArtifacts 목록을 열어 계정 소유 링크를 검색·미리보기·복사·삭제.
Ask Before Deleting Artifacts공개 링크를 끊기 전에 확인을 받는 선택 옵션.
공유 방법열려 있는 로컬 HTML 페이지나 마크다운 편집기에서 Share as artifact, 또는 orca artifacts … 명령.

Integrations(외부 서비스 연동)

항목설명
GitHub OAuthGitHub 로그인 연동.
Linear API tokenLinear(이슈 관리 서비스) 토큰.
JiraCloud(이메일 + API 토큰) 또는 자체 설치 Server/Data Center(PAT 또는 사용자 이름/비밀번호).
Bitbucket CloudEmail & API token(기본) 또는 Access token으로 연결. Orca가 저장 전에 자격 증명을 확인합니다. ORCA_BITBUCKET_* 환경 변수가 있으면 그것이 우선이며 Connect / Disconnect 버튼이 숨겨집니다. 저장한 자격 증명은 이 기기에만 남으므로, 원격 Orca 서버에서는 서버에 환경 변수를 설정하세요.
MiniMaxMiniMax 세션 쿠키(platform.minimax.io/console/usage에서)를 붙여 넣어 MiniMax CLI의 로컬 사용량·한도 추적을 켭니다. 선택 사항인 group ID와 usage models 칸은 쿠키에서 고른 기본값을 덮어씁니다.
MCP serversMCP 서버 설정. 저장소의 MCP 설정은 그것을 고른 호스트에 남습니다.

Voice(음성 받아쓰기)

항목설명
Enable Voice Dictation마이크 권한이 필요합니다(macOS는 개인정보 보호 및 보안 설정이 열릴 수 있음).
Microphone받아쓰기에 쓸 입력 장치. 기본은 시스템 마이크이고, 헤드셋처럼 특정 장치를 고를 수 있습니다. 고른 마이크가 빠지거나 없으면 시스템 기본으로 돌아가고 방해하지 않는 안내를 띄웁니다.
Dictation modeToggle(단축키로 시작/정지) 또는 Hold(단축키를 누르고 있는 동안 말하기).
Speech Model기기 안에서 도는 모델을 내려받아 쓰거나, API 키를 붙여 넣고 OpenAI 클라우드 모델을 씁니다(아래 표).
Listening… 표시듣는 동안 Listening… 알약 모양 표시에 Stop 버튼이 나옵니다. Toggle 모드에서는 툴팁에 받아쓰기 단축키도 보입니다.
음성 모델특징
Parakeet TDT v3 (권장)여러 유럽 언어, 오프라인
Parakeet TDT v2영어, 더 빠름
Zipformer 계열중국어+영어 이중 언어 스트리밍, 영어/중국어 스트리밍, Zipformer Streaming KO(한국어)
Paraformer Bilingual중국어 방언 + 영어
Parakeet TDT-CTC JA일본어
SenseVoice중국어/영어/일본어/한국어/광둥어, 언어 자동 감지
Whisper Tiny90개 이상 언어, 정확도 낮음
GPT-4o mini / GPT-4o Transcribe클라우드. 같은 화면에 OpenAI 키 필요

SSH

  • SSH 워크트리, 대상 호스트, 암호문(passphrase), 기본 신원 파일(identity file), 여러 호스트 일괄 관리. 여러 호스트를 골라 한 번에 Test 또는 Remove할 수 있고, OpenSSH 설정 목록에서 지운 호스트는 Restore removed hosts를 누르기 전까지 지워진 채로 남습니다.
  • Advanced: 프록시 / 점프 호스트, Reuse SSH connection for faster setup(시스템 OpenSSH 다중화로 빠른 연결, 기본 켜짐), 호스트별 Allow this host's orca CLI to control Orca(그 호스트의 orca CLI가 Orca를 조작하도록 허용).
  • Managed servers: Orca가 빈 SSH 호스트에 자체 서버를 설치·실행하고 최신으로 유지합니다. 버전과 터미널을 보고 Update, Roll back(되돌리기), Recover(복구), Stop… / Forget…(중지/잊기)를 할 수 있습니다. 모든 SSH 호스트는 이 관리 서버 위에서 돌며, 예전의 Runtime 선택기는 없어졌습니다. 관리 서버가 돌 수 없는 호스트는 이유를 보여 주고 연결하지 않습니다.
  • Kerberos 호스트: OpenSSH 설정의 GSSAPIAuthentication이 시스템 OpenSSH 인증을 결정합니다.

Remote Orca Servers(원격 Orca 서버)

  • 원격 Orca 런타임과 페어링·연결하는 서버 목록. Add server로 접속 링크 붙여 넣기, SSH 호스트에 설치, Cloud VM 설정 중 하나를 고릅니다. 줄마다 상태가 보이고 덜 쓰는 동작은 ⋯ 메뉴에 있습니다.
  • 이 데스크톱 앱을 서버로 알리고(advertise), 취소 가능한 접속 링크를 만듭니다.
  • 페어링된 모바일에 보일 이 데스크톱의 Machine name. 비우면 감지된 컴퓨터 이름을 씁니다.
  • Advanced: 서버를 거치는 프로젝트·터미널·제공자 확인에 쓸 기본 런타임 선택.

Shortcuts(단축키) — 전체 키맵이 있고 모든 단축키를 다시 지정할 수 있습니다.

동작macOSWindows / Linux비고
Close all editor tabs(편집기 탭 모두 닫기)Cmd+Option+WCtrl+Alt+W
다음/이전 탭(모든 종류)Cmd+Shift+] / [Ctrl+Shift+] / [새 설치 기본값
같은 종류 다음/이전 탭Cmd+Option+] / [(Ctrl 계열)새 설치 기본값
직전에 쓴 탭Ctrl+Tab새 설치 기본값
Add Review Note(검토 메모 추가)Cmd+Shift+ACtrl+Shift+A변경 가능
Delete workspace(워크트리 삭제)Cmd+Shift+BackspaceCtrl+Shift+Backspace지울 사이드바 워크트리 위에 마우스를 올려 두고 누름. 그래도 확인을 묻습니다.
Toggle Sleeping Workspaces지정 안 됨사이드바의 잠든 워크트리 필터를 바로 켜고 끄고 싶으면 지정
Toggle Child Workspaces지정 안 됨상위 워크트리의 하위(children) 보이기/숨기기 — “N children” 칩 클릭과 같음. 마우스 아래 워크트리, 없으면 활성 워크트리 대상
Toggle Workspace Board지정 안 됨Workspace Board 열기/닫기. 기존 workspace.openBoard 지정도 계속 동작
Send Review Notes to Agent지정 안 됨지정하면 마우스 없이 활성 워크트리의 diff 메모 보내기 메뉴를 엶

기존 설치본은 직접 바꾼 단축키를 ~/.orca/keybindings.json에 그대로 유지합니다.

Repository(저장소별)

항목설명
Base ref and hooks저장소별 base ref와 훅.
Auto-run commands워크트리를 만들 때 자동으로 실행할 명령.
Repo icons사이드바 저장소 아이콘: 아이콘, 검색 가능한 전체 이모지, 업로드한 이미지, 웹사이트 파비콘, GitHub 아바타 중 선택 후 프리셋 또는 직접 입력한 hex 배지 색.
Source Control AI overrides커밋 메시지, PR 내용, 브랜치 이름을 만드는 AI 설정을 저장소별로 덮어쓰기.
Worktree Shared Pathsgit이 무시하는(gitignored) 경로를 기본 체크아웃에서 새 워크트리마다 만들어 줍니다(macOS는 가능하면 APFS 복제 복사, 아니면 심볼릭 링크). 저장소에 커밋된 orca.yaml의 worktree.sharedDirectories 및 .worktreeinclude와 함께 쓰입니다.

Floating Workspace(떠 있는 워크트리) — 특정 저장소 워크트리에 묶이지 않은 터미널·브라우저·마크다운 탭을 위한 전역 공간.

항목설명
Enable Floating Workspace기능 켜기.
Terminal Directory새 floating 터미널 탭의 시작 폴더(~ = 홈).
Toggle Button Location전환 버튼이 나타날 위치. 키보드 단축키는 버튼 위치와 상관없이 동작합니다.

Plugins(플러그인)

  • Settings → Plugins, 상태 표시줄 버튼, 또는 텍스트 입력칸 밖에서 Cmd+Shift+X / Ctrl+Shift+X로 엽니다. 카탈로그를 둘러보고, 분류나 설치 상태로 거르고, 설치한 플러그인을 켜고 끕니다.
  • 플러그인은 테마, 아이콘 테마, 구문 강조, 사용자 지정 편집기 등 여러 기능을 추가합니다. git 마켓플레이스 소스를 추가하고 설치된 버전을 관리할 수도 있습니다.
  • 플러그인 시스템은 기본 켜짐. 설치(orca://plugins 링크 포함)하면 검토 화면이 열립니다.
코드를 실행하는 플러그인 주의

코드를 실행하는 플러그인은 설치 전에 동의를 받으며, 승인하면 내 컴퓨터 전체에 접근할 수 있습니다. 믿을 수 있는 플러그인만 설치하세요. 플러그인 작업자는 이 컴퓨터에서 돌고, SSH 워크트리 동작은 여전히 Orca를 거칩니다.

Experimental(실험 기능) 안정화 전 — 동작이 바뀔 수 있음

항목설명
Activity PageSlack 같은 워크트리 피드로 에이전트 사건을 보여 줌.
Compact 워크트리 cards레이아웃이 실험 단계인 동안 사이드바 카드의 중복된 둘째 줄을 숨김.
Agent hibernation쉬고 있는 백그라운드 에이전트를 일시정지하고 다시 열면 자동 재개.
Agent DashboardNeeds You / Working / Done(선택적으로 Idle) 칸반 보드. 검색과 프로젝트·워크트리·PR 필터, 창 안 또는 별도 창으로 열기. “Show idle agents”는 여기가 아니라 대시보드 보드 설정에 있습니다.
Browser extensions재시작 후 로컬 브라우저 프로필에서 Chrome 웹 스토어 확장 사용.
Cloud VM저장소가 소유하는 필요 시 환경(클라우드 샌드박스, VM, 로컬 Docker)의 설정 조작과 워크트리 Run on 대상을 표시. 설정 안내와 레시피 설치가 이 토글 아래에 있습니다(위 “실행 방식 ④”).

8. 개인정보와 텔레메트리

텔레메트리(telemetry)(프로그램이 사용 통계를 개발사로 보내는 것)는 정식 배포된(packaged) Orca 빌드가 보내는 익명 사용 통계입니다. 핵심만 먼저 보면 다음과 같습니다. 끄고 싶다면 앱 설정에서 스위치 하나만 끄면 됩니다.

익명

내 기기에 저장된 무작위 ID로만 구분합니다. 계정, 이메일, IP 주소, 사용자 이름은 수집하지 않습니다.

내용 없음

파일 내용, 프롬프트, 에이전트 출력, 터미널 출력, 저장소 이름, 브랜치 이름, URL, 경로, 커밋 메시지를 절대 보내지 않습니다.

끄는 법

Settings → Privacy에서 “Share anonymous usage data”(익명 사용 데이터 공유)를 끄면 됩니다. 개발자용 방법(환경 변수)도 있습니다 — 아래 “끄는 법” 탭.

내 컴퓨터 머무는 것 코드·프롬프트·출력 경로·저장소·브랜치 URL·커밋 메시지 오류 원문·위치 기록 (로컬 진단 파일) 나가는 것 정해진 선택지 값 버전 문자열 익명 로컬 ID OS·CPU·채널 PostHog Cloud 미국 지역 서버
UI에 입력한 자유 문장은 어떤 것도 기기를 떠나지 않습니다. 전송되는 모든 값은 고정된 선택지(enum(“claude-code / codex …”처럼 미리 정해 둔 목록 중 하나)), 버전 문자열, 익명 로컬 ID 중 하나입니다. PostHog는 통계를 받아 주는 회사입니다.

모든 사건에 함께 붙는 정보: Orca 버전, 운영체제(darwin / win32 / linux 등), CPU 구조, 대략적인 OS 릴리스 문자열, 배포 채널(stable 또는 rc), 익명 로컬 ID. 호스트 이름·사용자 이름·IP는 없습니다.

분류기록하는 것기록하지 않는 것
Lifecycle(생애 주기)앱이 열린 시점 — 일·주·월간 활성 사용자 추정용
Repos and workspaces저장소 추가·워크트리 생성 시점과 방법(폴더 선택 vs 클론 URL, 명령 팔레트 vs 끌어놓기 등)저장소 이름, URL, 경로, 브랜치 이름, 자유 입력 글
Agents에이전트 시작 시점, 종류(claude-code, codex, gemini 등 고정 목록), 어디서 실행했는지프롬프트, 모델 세부, 에이전트 출력
Agent errors대략적인 오류 분류와 관련 에이전트 종류오류 원문, 스택 트레이스(오류가 프로그램 어디서 났는지 줄줄이 적은 기록)(사건별 세부는 내 기기의 로컬 진단 파일에만 남고, 내가 직접 진단 묶음을 공유할 때만 전달)
Settings허용 목록에 있는 소수의 기능 플래그·UX 설정을 바꾼 시점, 어떤 설정이 바뀌었는지, 참/거짓형인지 선택형인지자유 입력 설정의 실제 값
Privacy controls텔레메트리를 켜거나 끈 시점 — 동의 화면이 제대로 동작하는지 집계로 확인하기 위해
  • 파일 경로, 저장소 이름, 브랜치 이름, URL, 커밋 메시지, 현재 작업 폴더
  • 에이전트 프롬프트, 응답, 터미널 내용
  • 오류 원문이나 스택 프레임 (사건별 오류 맥락은 로컬 진단 파일에만 있고, 직접 진단 묶음을 공유할 때만 전달)
  • 사용자 계정 정보 (Orca에는 계정 시스템이 없음)
  • IP 주소, 정밀한 위치 — 요청에서 얻는 지리 정보는 국가뿐
  • 익명 ID에 연결된 공급사 쪽 사용자 프로필

초보자는 앱 설정에서 끄기만 하면 됩니다. Settings → Privacy에서 “Share anonymous usage data”(익명 사용 데이터 공유)를 끕니다. 즉시 적용되고 계속 유지됩니다.

환경 변수로 끄기

방법은 모두 세 가지이며 하나만 해도 충분하고 함께 써도 됩니다. 나머지 두 가지는 환경 변수(프로그램을 실행할 때 컴퓨터가 함께 건네주는 “설정 쪽지”. 터미널이나 시스템 설정에서 정함)를 쓰는 방법입니다.

  1. 앱에서Settings → Privacy에서 “Share anonymous usage data”를 끕니다.
  2. DO_NOT_TRACK=1업계 공통 환경 변수. 그 실행 동안 전송을 막습니다. 변수를 지우면 다음 실행 때 저장된 설정으로 돌아갑니다.
  3. ORCA_TELEMETRY_DISABLED=1Orca 전용 차단 스위치. 동작은 DO_NOT_TRACK과 같습니다.

이 두 환경 변수 중 하나가 설정돼 있으면 앱 설정과 상관없이 항상 꺼집니다.

공급사PostHog Cloud, 미국 리전(미국에 있는 데이터 센터)
보관 기간PostHog Cloud 요금제의 기본값(그들 요금 페이지 기준). Orca가 따로 정한 보관 기간은 없음
접근 권한소수의 Orca 관리자만 프로젝트 멤버

9. 문제 해결과 자주 묻는 질문

개발자용 참고 — 처음엔 건너뛰세요

문제가 생겼을 때 돌아와서 보는 절입니다. 아래 표에서 증상을 찾아 한 줄 해결책을 먼저 보고, 자세한 방법은 “🔧 개발자용 참고”를 펼치세요.

증상한 줄 해결책
에이전트가 시작되지 않아요Orca 밖에서 그 에이전트가 실행되는지 먼저 확인하고, 탭의 Restart를 누릅니다.
Codex가 “path must be shorter than SUN_LEN”Orca를 v1.4.212 이상으로 업데이트합니다.
어떤 프로필 사본을 쓸지 물어봐요보통 Use SQLite (Recommended)를 고릅니다.
diff 화면이 이상하거나 멈춰 있어요diff 도구 막대의 새로고침 아이콘을 누릅니다.
워크트리 만들기가 실패해요서버의 최신 내용을 받아 오거나(git fetch origin) 다른 이름을 씁니다.
Orca CLI가 “command not found”Settings → General → Orca CLI에서 등록합니다.
SSH는 되는데 원격 터미널이 안 돼요설정의 SSH 호스트·관리 서버 화면에서 이유를 확인합니다.
SSH로 “Download Folder”가 안 돼요폴더 전송(SFTP)이 막힌 것 — 파일 하나씩 받거나 터미널로 받습니다.
“Open in VS Code”가 비활성SSH 워크트리에서, VS Code로 지정해 엽니다.
Kerberos 로그인 실패Kerberos 로그인 티켓과 SSH 설정을 확인합니다.
browser_no_tab 오류그 워크트리에 브라우저 탭을 먼저 엽니다.
느리거나 메모리를 많이 써요안 쓰는 워크트리와 브라우저 탭을 닫습니다.
GitHub PR 패널·검사 오류아래 “10. GitHub 오류 해결”을 봅니다.
증상별 자세한 해결 방법
에이전트가 시작되지 않아요
  1. Orca 밖의 일반 터미널에서 그 에이전트 CLI를 실행해 봅니다. 거기서도 실패하면 CLI 설치와 로그인을 확인하세요. Orca에서만 실패하면 아래를 봅니다.
  2. 그 CLI가 Orca가 보는 PATH(컴퓨터가 명령 프로그램을 찾아보는 폴더 목록)에 있는지 Settings → Agents에서 확인합니다.
  3. 탭의 Restart 칩을 눌러 봅니다.
Codex가 “path must be shorter than SUN_LEN”이라고 해요

Orca를 v1.4.212 이상으로 업데이트하세요. Codex 0.157 이상은 Orca가 관리하는 계정 홈에서 백그라운드 데몬의 소켓 경로가 너무 길면 이 오류가 날 수 있습니다. 이제 Orca가 해당 홈을 자동으로 조정하므로 계정을 옮기거나 시스템 ~/.codex/config.toml을 고칠 필요가 없습니다.

Orca가 어떤 프로필 사본을 쓸지 물어봐요

프로필의 JSON 사본과 SQLite 사본이 둘 다 읽히는데 내용이 다르면, 각각 마지막으로 저장된 시각을 보여 줍니다. Use SQLite (Recommended) 또는 Use JSON을 고르면 그 사본을 유지하고 Orca가 적용 후 재시작합니다. 사본을 먼저 살펴봐야 하면 Quit을 고르세요. 다른 프로필 복구 오류는 별도의 명령 안내가 나올 수 있습니다.

diff 화면이 이상하거나 멈춰 있어요
  • diff 도구 막대의 새로고침 아이콘을 누르면 Orca가 워크트리를 다시 읽습니다.
  • 외부에서 한 git 작업(rebase, reset)이 새로고침 사이에 끼어들 수 있습니다.
워크트리 만들기가 실패해요
  • start-from ref를 아직 가져오지(fetch) 않았을 수 있습니다. 저장소에서 터미널을 열고 git fetch origin을 실행하세요.
  • 대상 폴더에 이미 그 브랜치의 워크트리가 있을 수 있습니다. 지우거나 새 브랜치 이름을 고르세요.
Orca CLI가 “command not found”라고 해요

Settings → General → Orca CLI에서 CLI를 등록하세요. macOS에서는 ~/.local/bin에 실행 연결 파일(shim)을 설치하므로, 그 폴더가 셸의 PATH에 있어야 합니다. Windows에서는 orca가 설치 프로그램이 PATH에 추가하는 네이티브 프로그램입니다.

SSH는 연결되는데 원격 터미널이 안 돼요
  • Orca가 호스트에 자체 관리 서버를 설치하므로 Node 버전 불일치나 빌드 도구 부족으로는 더 이상 연결이 막히지 않습니다. Settings → SSH Hosts에서 그 호스트가 어떤 서버를 쓰는지 보고, Settings → Managed servers에서 update / roll back / recover 할 수 있습니다.
  • 관리 서버가 돌 수 없는 호스트는 더 이상 예전 SSH 런타임으로 대체되지 않습니다. Settings → SSH Hosts가 이유를 설명하고 연결은 그 이유와 함께 실패합니다. 그 호스트에 계속 연결하려면 이전 버전 Orca를 쓰세요.
  • v1.4.224에서 넘어온 터미널은 입출력은 되지만 orca CLI가 없습니다. orca 명령이 필요하면 같은 호스트에 새 터미널을 여세요.
SSH로 파일은 되는데 “Download Folder”가 안 돼요

폴더 내려받기에는 재귀 SFTP 전송이 필요합니다. 시스템 SSH만 쓰는 연결에서도 파일 하나 내려받기는 될 수 있습니다. 대안으로 터미널에서 tar/scp를 쓰세요.

“Open in VS Code”가 비활성이거나 Local only라고 나와요
  • 원격 Orca 서버 런타임이 아니라 SSH 워크트리를 쓰세요.
  • Open-in 명령을 Cursor나 인자가 여러 개인 셸 명령이 아니라 VS Code / Insiders로 지정하세요.
  • 호스트를 지웠다면 SSH 대상을 새로고침하세요.
Kerberos 로그인이 실패해요
  • klist에 그 호스트 영역(realm)의 유효한 티켓이 보이는지 확인합니다.
  • OpenSSH 설정의 해당 Host에 GSSAPIAuthentication yes가 있는지 확인한 뒤, Settings → SSH에서 대상을 다시 가져오거나 다시 테스트합니다.
브라우저가 browser_no_tab이라고 해요

현재 워크트리에 열린 탭이 없다는 뜻입니다. orca tab create --url ...로 열거나, 브라우저 창을 직접 열어 이동하세요.

느리거나 메모리를 많이 써요
  • 지금 쓰지 않는 워크트리는 닫으세요. 워크트리마다 파일 감시자(file watcher)가 계속 살아 있습니다.
  • 브라우저 탭이 많은 분할 레이아웃이 RAM을 가장 많이 씁니다. 필요 없는 브라우저는 닫으세요.
GitHub PR 패널 / 검사 / Tasks 오류

요청 한도, 잘못된 gh 인증, 부족한 권한 범위, 저장소 접근 문제는 모두 Source Control과 PR Checks 패널에 나타납니다. 전체 표는 다음 절 “GitHub 오류”를 보세요. 터미널에서는 gh가 되는데 Orca가 GitHub CLI가 없다고 한다면, PATH에 있는 gh 실행기 하나가 멈춰 있을 가능성이 큽니다. Orca는 멈춘 실행기를 지나쳐 버전 확인을 통과하는 사본을 찾아 쓰며, CLI가 없다고 보고하지 않습니다.

gh auth status -h github.com
gh api user
gh api rate_limit --jq '.resources.core'
로그 보기

Help → Open Logs로 Orca 로그 폴더를 엽니다. 버그를 신고할 때 첨부하세요.

문제 신고
  • Help → Send Feedback(앱 안) — 스크린샷을 붙여 넣거나 끌어 놓거나 이미지 파일을 고르면, 보내기 전에 미리보기가 보입니다. 재현이 어려운 버그는 로그도 첨부하세요.
  • GitHub Issues — 버그·기능 요청
  • Discord — 실시간 도움

10. GitHub 오류 해결

개발자용 참고 — 처음엔 건너뛰세요

GitHub(코드를 인터넷에 올려 두고 함께 작업하는 서비스)와 연결해 PR을 쓰다가 문제가 생겼을 때 보는 절입니다.

한 줄 요약: PR 상태·검사·이슈가 갱신되지 않으면 원인은 거의 항상 GitHub 로그인(인증), 권한, 요청 한도이지 Orca 고장이 아닙니다. 가장 흔한 것은 요청 한도 — 한 계정이 한 시간에 GitHub에 물어볼 수 있는 횟수를 여러 도구가 나눠 쓰다가 다 써 버리는 경우이며, 기다리면 풀립니다.

Orca 창들 터미널의 gh gh 쓰는 에이전트 자동 검사(CI) 확장·다른 앱 한 계정의 시간당 예산 모두가 같이 줄어듦 다 쓰면 → 거절(403) Orca는 잠시 gh 호출 중단 (과부하 차단 장치)
여러 도구가 한 계정의 예산을 나눠 쓰기 때문에, Orca를 안 써도 다른 도구 때문에 PR 패널이 막힐 수 있습니다. HTTP 403(서버가 “허락할 수 없음”이라고 돌려주는 거절 번호)을 받으면 Orca는 잠시 GitHub에 묻는 것을 멈춥니다 — 이것을 circuit breaker(누전 차단기처럼 문제가 생기면 잠깐 끊어 두는 장치)라고 합니다.
GitHub 오류 분류표·명령·대처법 전체

Orca는 내 컴퓨터(또는 원격 Orca 호스트)의 GitHub CLI(gh)를 통해 GitHub와 대화합니다. PR 상태, 검사(checks), 이슈, Tasks가 갱신되지 않으면 원인은 거의 항상 GitHub 인증, 권한, API 요청 한도이지 PR 패널 자체의 고장이 아닙니다.

빠른 분류표

보이는 메시지가능성 높은 원인먼저 해 볼 것
“GitHub is rate-limiting requests” / “rate limit exceeded (core)”내 사용자의 GitHub REST(core) 할당량 소진재설정까지 기다리기, 추가 gh/에이전트/Orca 사용 중단, Settings → Git → GitHub API Budget 확인
“GitHub authentication is unavailable” / gh 인증 요구gh 미로그인, 만료된 토큰, 잘못된 GITHUB_TOKENgh auth status 후 gh auth login
“GitHub did not allow access” / HTTP 403(한도 아님)권한 범위(scope) 부족 또는 저장소 접근 불가repo(필요하면 조직 SSO 포함)로 재인증, 브라우저에서 PR이 열리는지 확인
“repository is unavailable” / HTTP 404잘못된 remote, 접근 권한 없는 비공개 저장소, 이름 바뀐 저장소git remote -v와 브라우저 접근 확인
“GitHub is unreachable” / 시간 초과네트워크, 프록시, VPN, GitHub 장애githubstatus.com 확인, VPN 끄고 재시도
“GitHub CLI is unavailable”Orca가 쓰는 PATH에 gh 없음gh 설치 후 Orca 재시작

요청 한도(rate limit) — 가장 흔함

GitHub는 로그인한 사용자마다 한 시간짜리 공유 예산을 줍니다. 그 계정을 쓰는 모든 도구가 같은 예산을 나눠 씁니다: Orca, 터미널의 gh, gh를 부르는 Claude/Codex/Grok 에이전트, CI 스크립트, 브라우저 확장, 다른 앱.

버킷(예산 종류)담당하는 것보통 한도(로그인 시)
REST (core)대부분의 PR/이슈/API 호출(gh pr view, 검사 메타데이터, 여러 REST 엔드포인트)5,000 / 시간
GraphQLProject/Tasks와 일부 풍부한 PR 조회5,000 포인트 / 시간
Search검색 기반 목록30 / 분

주 버킷이 바닥나면 GitHub는 “API rate limit exceeded” 같은 메시지와 함께 HTTP 403을 돌려줍니다. Orca는 이를 “rate-limited”로 분류하고, 가능하면 마지막으로 알던 PR 상태를 유지하며, 짧은 시간 동안 gh 호출을 더 띄우지 않아 한 번의 한도 초과가 연쇄 실패로 번지지 않게 합니다.

설정은 “괜찮다”는데 PR 패널은 막혀 있다면

Settings → Git → GitHub API Budget은 GitHub의 특수 rate_limit 엔드포인트를 읽습니다. 이 조회는 한도 계산에서 빠져 있어서, 같은 사용자의 실제 REST 호출이 이미 remaining: 0인데도 남은 양이 있다고 보여 줄 때가 있습니다. 서로 다를 때는 이 순서로 믿으세요.

  1. PR / Checks 패널의 오류(실제 요청이 실패한 것)
  2. 터미널에서 한 실제 CLI 확인(아래)
  3. 설정의 예산 숫자(유용하지만 조회 전용)

또 GitHub API Budget을 Accounts의 Claude / Codex / Grok 사용량과 헷갈리지 마세요. 그것들은 AI 제공자 한도이지 GitHub REST 할당량이 아닙니다.

터미널에서 한도 확인하기

# 조회(할당량을 쓰지 않음; 실제보다 건강해 보일 수 있음)
gh api rate_limit --jq '.resources | {core, graphql, search}'
# 실제 REST 호출 — PR 갱신이 의존하는 것
gh api user -i 2>&1 | head -40

gh api user가 “API rate limit exceeded”와 X-Ratelimit-Remaining: 0으로 403을 돌려주면, 그 계정은 X-Ratelimit-Reset(Unix 초 단위 시각)까지 REST가 막힌 상태입니다.

주로 할당량을 태우는 것
  • Orca 창이나 electron-dev 빌드를 여러 개 동시에 열어 둠(각자 PR/Tasks를 갱신할 수 있음)
  • gh를 자동으로 돌리는 에이전트(PR/이슈 배정, 검사 폴링, 대량 GraphQL)
  • PR 패널 갱신과 함께 무거운 Tasks / 여러 저장소 동시 처리
  • 같은 GitHub 사용자 토큰을 쓰는 다른 앱
대처법
  • 오류나 X-Ratelimit-Reset에 나온 시간당 재설정까지 기다립니다.
  • 동시에 도는 GitHub 클라이언트를 줄입니다 — 여분의 Orca를 끄고 대량 gh 자동화를 멈춥니다.
  • 한도에 걸린 동안 PR 패널 새로고침을 연타하지 마세요. Orca가 이미 물러나 있습니다.
  • 스크립트는 GraphQL을 묶어서 쓰고, 개인 계정으로 큰 집합을 PR 하나씩 REST로 반복 조회하지 마세요.
  • 재설정 후에도 PR 갱신이 실패하면 인증을 다시 확인합니다(아래).

인증 문제

Orca는 그 호스트에서 gh가 쓰는 인증을 그대로 물려받습니다.

gh auth status -h github.com
gh api user --jq '{login, id}'

정상: 로그인됨, 토큰 유효, gh api user가 내 login을 돌려줌.

셸 프로필(~/.bash_profile, ~/.zshrc 등)에 export GITHUB_TOKEN=$(gh auth token)처럼 내보내 두면, gh는 키체인보다 이 값을 우선합니다. 오래되거나 잘못된 환경 변수 토큰은 헷갈리는 인증·한도 동작을 만듭니다. 지우고 다시 로그인하세요.

unset GITHUB_TOKEN GH_TOKEN
gh auth logout -h github.com
gh auth login -h github.com

gh auth status가 토큰을 유효하지 않다고 보여 줄 수 있습니다. gh auth login(또는 gh auth refresh)을 실행하고 Orca를 재시작해 새 자격 증명을 읽게 하세요.

조직의 비공개 저장소는 토큰에 SSO 승인이 필요할 수 있습니다. GitHub 토큰 설정에서 조직의 SSO 승인 링크를 열고 다시 시도하세요.

GitHub 인증은 호스트마다 따로입니다. 노트북에서 로그인해도 원격 기기의 gh는 로그인되지 않습니다. 그 호스트에 SSH로 들어가 gh auth login을 하거나, 그 환경의 원격 서버 GitHub 예산 화면을 쓰세요.

권한과 저장소 오류

증상의미
“rate limit” 없는 HTTP 403토큰 권한 범위가 부족하거나 그 자원을 볼 수 없음
HTTP 404 / “could not resolve to a Repository”저장소가 없거나, 이름이 바뀌었거나, 이 토큰으로는 보이지 않음
“resource not accessible by integration”앱/토큰 종류가 그 동작을 할 수 없음
  • gh api user와 같은 사용자로 로그인한 브라우저에서 PR/저장소가 열리는지 확인합니다.
  • repo(그리고 그 기능을 쓰면 read:org / project)를 포함한 classic 권한 범위로 재인증합니다.
  • GitHub Enterprise라면 그 호스트 이름으로 gh 인증이 됐는지 확인합니다(gh auth login --hostname …).
네트워크와 GitHub 장애

시간 초과, “could not resolve host”, “GitHub is unreachable”은 연결 문제입니다.

  • GitHub Status 확인
  • VPN / 회사 프록시 없이 시도
  • 원격 호스트라면 api.github.com으로 나가는 HTTPS가 되는지 확인
GitHub CLI가 없다고 할 때
  • gh 설치
  • 일반 터미널에서 which gh가 되는지 확인
  • Orca를 완전히 종료 후 다시 열기(PATH를 맞추기 위해)
  • Windows는 Orca가 실행되는 환경(WSL인지 네이티브인지)과 같은 곳에 설치

GitHub가 실패할 때 Orca의 동작

상황Orca의 대응
요청 한도 / 장애PR·Checks 패널이 화면을 비우지 않고, 마지막으로 알던 상태 + 짧은 배너를 보여 줍니다.
확실한 인증 / 권한 실패로그인이나 접근 권한을 고치라는 명확한 빈 화면 안내나 배너가 나옵니다.
Circuit breaker(회로 차단기)주 버킷 한도 403을 받은 뒤, 그 버킷(core, search, graphql)에 대해 잠시 새 gh 실행을 거절합니다. 앱이 계속 반응하도록, 그리고 구멍을 더 깊이 파지 않도록 하기 위해서입니다.

Orca에서 GitHub API Budget 보기

  • Settings → Git → GitHub API Budget: GitHub 조회 기준 REST / Search / GraphQL 남은 양
  • 한도가 풀릴 때까지 기다린 뒤 새로고침
  • 원격 Orca 서버에서는 서버가 소유한 gh 신원에 대해 원격 고급(advanced) 예산 화면을 쓰세요. 로컬 설정은 데스크톱 클라이언트 것만 보여 줍니다.
그래도 안 되면
  1. Orca가 쓰는 같은 기기·사용자에서 gh pr view나 gh api user로 한 번 재현합니다.
  2. Help → Open Logs로 로그를 모읍니다.
  3. 분류된 오류 문구(비밀값 제외), 가린(redacted) gh auth status 출력, 터미널 gh도 똑같이 실패하는지를 적어 GitHub Issues에 올립니다.
한눈에 정리
  • Orca는 작업마다 워크트리·에이전트 터미널·브라우저 탭을 따로 주는 ADE(에이전트용 개발 환경)입니다. AI 에이전트의 구독은 직접 준비합니다.
  • 설치는 다운로드 → 더블클릭 → 설치. macOS·Windows·Linux를 지원합니다.
  • 실행 위치는 로컬 · SSH · 원격 Orca 서버 · Cloud VM(실험) 네 가지지만, 초보자는 화면과 일하는 곳이 같은 “로컬”만 알면 됩니다.
  • 첫 세션 전에 에이전트 1개 설치·로그인과 git 저장소 폴더를 준비합니다. 흐름은 저장소 추가 → 워크트리 → 에이전트 → 창 분할 → 변경 검토 → 내보내기입니다.
  • 같은 부탁을 에이전트 셋에게 시키고, 결과 화면·바뀐 줄 수·검사 통과로 승자를 고릅니다. 셋이 일치하면 아마 정답, 갈리면 어려운 지점이라는 신호입니다.
  • Agents 피드는 자리 비운 뒤의 따라잡기 화면이고, 에이전트가 끝나면 시스템 알림·소리·칩·벨·Dock 배지로 알려 줍니다.
  • 설정은 Cmd+,(macOS)로 열어 검색하며, 처음엔 General·Agents·Notifications만 보면 됩니다.
  • 텔레메트리는 익명이고 내용·경로를 보내지 않으며, Settings → Privacy에서 끕니다.

출처: onorca.dev/docs (What is Orca?), /docs/install, /docs/first-session, /docs/ways-to-run, /docs/recipes/parallel-agents, /docs/activity, /docs/notifications, /docs/settings, /docs/telemetry, /docs/troubleshooting, /docs/github-errors

CHAPTER 02

Orca의 핵심 모델 — 워크트리·세션·화면 배치·복원·빠른 이동

Orca는 "작업 하나 = 폴더 하나(워크트리)"라는 생각 위에 세워져 있습니다. 이 장에서는 그 바탕이 되는 git 워크트리부터, 에이전트 세션의 상태 표시, 탭과 화면 분할, 앱을 껐다 켜도 그대로 돌아오는 세션 복원, 그리고 키보드로 순식간에 이동하는 검색창까지 Orca의 뼈대를 차례로 살펴봅니다.

이 장에서 배우는 것
  • 브랜치·체크아웃·워크트리가 무엇이고, 왜 Orca가 "작업마다 폴더를 따로" 쓰는지
  • 워크트리의 일생(만들기 → 작업 → 검토 → 내보내기 → 정리)과 생성 대화상자의 모든 옵션
  • gitignore된 파일을 새 워크트리에 채워 넣는 세 가지 방법(Shared Paths · orca.yaml · .worktreeinclude)
  • 사이드바 정리·필터·다중 선택, 정리 도구와 보존 브랜치, 여러 저장소 묶음
  • 에이전트 상태 표시, 에이전트 대시보드, 실행 기본값(권한 생략 플래그)과 Restart 칩
  • 탭·분할 화면, 세션 복원(데몬), Cmd-P · Cmd-J(macOS) · + 검색창
처음이라면 이것만 처음엔 건너뛰어도 되는 것: "🔧 개발자용 참고"로 접힌 상자(필터 목록, 설정 파일, 세부 규칙), 「공유 경로」, 「정리 도구와 보존 브랜치」, 「여러 저장소 묶음」 절, 「빠른 이동」의 세부 동작(절 머리에 ⏭ 표시).

먼저 알아 둘 것 — 브랜치·체크아웃·워크트리

Orca의 모든 것은 git(파일이 바뀐 기록을 저장하고 되돌리거나 합칠 수 있게 해 주는 버전 관리 도구)의 워크트리라는 기능 위에 있습니다. git을 처음 들어도 괜찮도록 세 단어부터 풀어 보겠습니다.

저장소(repo)

프로젝트 파일과 그 변경 기록 전체를 담은 상자입니다. 보통 컴퓨터의 폴더 하나로 보입니다.

브랜치(branch)

기록의 "갈래"입니다. main이라는 큰 줄기에서 feature/login 같은 가지를 뻗어, 원본을 건드리지 않고 따로 고쳐 볼 수 있습니다.

체크아웃(checkout)

어떤 브랜치의 파일들을 실제 폴더에 "꺼내 놓는" 일입니다. 폴더 안 파일은 지금 체크아웃된 브랜치의 모습입니다.

워크트리(worktree)

같은 저장소를 폴더 여러 개에 동시에 체크아웃하는 git 기능입니다. 폴더마다 다른 브랜치가 꺼내져 있습니다.

쉽게 비유하면 보통 방식은 책상 하나에서 숙제를 바꿔 가며 하는 것과 같습니다. 수학을 하다 국어로 바꾸려면 수학 책을 치워야(stash) 하죠. 워크트리는 숙제마다 책상을 따로 주는 것입니다. 수학 책상과 국어 책상이 나란히 있으니 치울 필요도 없고, 두 사람(두 에이전트)이 동시에 앉아도 서로의 공책을 건드리지 않습니다.
📁 my-app/ 폴더는 하나뿐 지금은 한 브랜치만 꺼내짐 main feature/login fix/bug-12 바꿀 때마다 ① 하던 일 치우기(stash) ② 다른 브랜치 체크아웃 에이전트 둘이면 서로 충돌!
전통적인 방식: 폴더 하나에 브랜치를 번갈아 꺼냅니다. 한 번에 한 작업만 가능하고, 두 에이전트가 같은 파일을 동시에 고치면 엉킵니다.
저장소 기록(.git) 기록은 하나를 공유 📁 my-app-login/ 브랜치 feature/login 🤖 Claude 📁 my-app-bug12/ 브랜치 fix/bug-12 🤖 Codex 📁 my-app-docs/ 브랜치 docs/readme 🤖 Gemini
워크트리 방식: 기록은 하나를 공유하지만 작업마다 디스크 위 폴더가 따로 있습니다. 에이전트 셋이 동시에 일해도 서로의 파일을 밟지 않습니다.

Orca는 워크트리 중심(worktree-native)으로 설계되었습니다. 한 체크아웃에서 브랜치를 바꾸고 stash(하던 변경을 잠시 치워 두기)하는 대신, 모든 기능 개발이나 버그 수정마다 git worktree로 저장소의 디스크 사본을 따로 만듭니다. 이것이 여러 에이전트를 병렬로 돌려도 안전한 이유입니다 — 에이전트끼리 서로의 파일을 건드리지 않습니다.

워크트리 모델 — 기준점·출발점·삭제

이 절에는 ref라는 말이 자주 나옵니다. ref(기록의 한 지점을 가리키는 이름표)는 "main", "feature/login"처럼 사람이 읽을 수 있는 이름을 기록 위의 한 점에 붙여 둔 것입니다. origin(내 컴퓨터가 아닌, 팀이 함께 쓰는 서버 쪽 저장소)이 앞에 붙으면 "서버에 있는 것"이라는 뜻입니다.

origin/main= 기준 브랜치(base ref) — 서버에 있는 원본 줄기 출발점(start-from ref) 여기서 갈라짐 워크트리 = 자기 브랜치·파일·터미널 = 저장 시점(커밋) 하나 = 기준 브랜치의 기록 줄 = 워크트리 자기 브랜치
● 하나하나가 저장 시점(커밋)입니다. 저장소마다 기준 브랜치(base ref, 보통 origin/main)가 있고, 워크트리는 출발점(start-from ref)에서 갈라져 자기 브랜치를 가집니다.
요소뜻
기준 브랜치 (base ref)저장소마다 하나. 보통 origin/main(서버에 있는 원본 줄기)입니다.
출발점 (start-from ref)워크트리마다 하나. 새 브랜치가 어디서 갈라져 나올지 정합니다.
워크트리 자신의 것자기만의 브랜치, 디스크 위 파일, 자기 에이전트 터미널을 가집니다.

보통은 출발점 = 기준 브랜치입니다(가장 빠른 기본 경로). 검토 중인 다른 작업(PR) 위에 이어서 쌓을 때만 출발점을 다른 브랜치로 고릅니다.

삭제할 때 일어나는 일

  • 워크트리를 삭제하면 폴더와 브랜치를 함께 지웁니다(확인 창이 먼저 뜹니다).
  • 체크아웃 제거는 git이 직접 처리하므로, 지우는 동안에도 채팅이나 파일 작업이 멈추지 않습니다.
  • git이 체크아웃 제거를 끝내지 못하면 워크트리가 목록에 그대로 남아 다시 시도할 수 있습니다. 실패 종류가 허용하면 Force Delete(강제 삭제)를 제안합니다.
  • 합쳐지지 않은 커밋이 있을지 몰라 git이 로컬 브랜치를 남겨 두면, Orca가 검토 단계를 제안할 수 있습니다 — 아래 보존 브랜치 참고.
Force Delete 버튼의 화살표 메뉴

Force Delete는 버튼과 화살표 메뉴가 붙은 분할 버튼입니다. 화살표 메뉴의 Always force delete(항상 강제 삭제)를 고르면 앞으로의 모든 삭제에 이 선택을 기억합니다.

Always force delete는 신중하게한 번 켜면 이후 모든 워크트리 삭제에 강제 삭제가 기억되어 적용됩니다.

워크트리의 일생 — 기능 하나가 태어나서 정리되기까지

① Create — 만들기

작업 이름을 정하고, 출발점(start-from)을 고르고, 원하면 GitHub · Linear · Jira · GitLab 항목을 연결합니다.

② Work — 작업

에이전트 터미널, 편집기 탭, 브라우저 탭, 터미널 창이 모두 이 워크트리 범위 안에서 열립니다.

③ Review — 검토

출발점과 비교한 diff(변경점) 보기, Annotate AI Diff(AI가 만든 변경에 메모 달기), Attribution(누가 어떤 줄을 썼는지)으로 확인합니다.

④ Ship — 내보내기

커밋(commit, 변경 저장), 푸시(push, 서버로 올리기), PR(Pull Request — 내 변경을 main에 합쳐 달라는 요청) 열기, 자동 검사(checks) 기다리기까지 모두 Orca 안에서 합니다.

⑤ Archive or delete — 보관 또는 삭제

클릭 한 번으로 워크트리와 브랜치를 함께 지웁니다.

워크트리 만들기 — 백그라운드 생성과 출발점

생성은 뒤에서 조용히 진행됩니다

Create 제출대화상자 즉시 닫힘 최신 기록 받기git fetch · 백그라운드 새 폴더 만들기git worktree add 시작 화면 열림에이전트 / 셸
제출하면 창은 바로 닫히고, 무거운 git 작업은 뒤에서 돕니다. 그동안 다른 워크트리를 계속 쓸 수 있습니다.
  • Create Worktree 대화상자를 제출하면 창이 즉시 닫히고, git fetch(서버에서 최신 기록 받기)와 git worktree add(새 폴더 만들기)는 뒤에서 계속됩니다.
  • 새 워크트리는 사이드바에 진행 줄과 함께 나타나고, 그 워크트리 탭에는 체크아웃이 끝날 때까지 실시간 설정 상태가 보입니다. 끝나면 고른 시작 화면이 열립니다.
  • 에이전트를 고르면 그 에이전트가 첫 탭으로 실행되고, Blank Terminal(빈 터미널)을 고르면 평범한 셸이 열립니다.
  • 생성 중에도 다른 워크트리로 옮겨 가거나, 진행을 지켜보거나, 탭 안 패널에서 취소할 수 있습니다.
  • 큰 저장소에서도 빠르며, 뒤에서 생성이 끝나도 지금 보고 있는 워크트리에서 억지로 끌려가지 않습니다.
  • 실패하면 패널에 오류와 Retry(다시 시도) 버튼이 뜹니다.

출발점 고르기 — Branch from

New Workspace(새 워크스페이스 — 워크스페이스는 워크트리와 같은 것) 작성 창의 Branch from(어디서 갈라질지) 컨트롤로 출발점을 정합니다.

기준 브랜치(base ref)

가장 빠른 기본 경로입니다. 보통은 이것을 고릅니다.

다른 로컬 브랜치

내 컴퓨터에 있는 다른 브랜치. 검토 중인 PR 위에 작업을 "쌓아 올릴" 때 유용합니다.

특정 커밋 SHA

SHA(커밋마다 붙는 긴 고유 번호)로 기록의 한 지점을 콕 집어 그곳에서 출발합니다.

기존 원격 브랜치

Orca가 받아와(fetch) 체크아웃해 줍니다.

생성 대화상자 — Project · Run on · 에이전트 · 연결 · 이름

꼭 정할 것은 두 가지뿐이름(무슨 일을 할지)과 에이전트(누구에게 시킬지)만 신경 쓰면 됩니다. Project(어느 프로젝트)와 Run on(어느 컴퓨터에서)은 일할 장소를 고르는 칸이고, 이슈 연결과 Advanced 칸은 선택 사항입니다. 브랜치 이름은 비워 두면 작업 이름에서 자동으로 만들어집니다.
Create Workspace
Name: 로그인 버그 고치기 :rocket: 🔗 Jira / GitHub 연결
Project ▾ 입력해서 거르기… + Add a new project (항상 맨 아래)
Run on ▾ 로컬 · SSH 호스트 · 레시피 + Add host
Agent ▾ Claude Code Set as default
▸ Advanced — Branch name: feature/my-branch · Parent workspace
  • Name — 작업 이름. 여기에 GitHub·Jira 같은 이슈 주소를 붙여 연결할 수도 있습니다. 이모지도 넣을 수 있습니다.
  • Agent — 일할 에이전트. Set as default로 다음부터 기본값으로 정할 수 있습니다.
  • Project · Run on — 글자를 쳐서 고르는 목록. 프로젝트가 없으면 맨 아래 Add a new project로 추가합니다.
  • Advanced — 브랜치 이름을 직접 정하거나 부모 워크트리를 고를 때만 엽니다.
각 칸의 세부 동작 (원격 호스트, 연결, 이모지, 브랜치 이름 규칙)

Project와 Run on(어디서 실행할지)은 입력하면 바로 걸러지는 콤보 상자입니다.

  • 글자를 쳐서 목록을 거르고, Enter로 지금 강조 표시된 줄을 확정합니다.
  • Project 목록 맨 아래에는 늘 Add a new project(새 프로젝트 추가)가 고정되어 있어, 프로젝트가 하나도 없어도 막다른 길이 되지 않습니다.
  • Run on은 준비된 호스트와 레시피, 그리고 그 컴퓨터에 아직 프로젝트 설정이 필요한 호스트까지 보여 줍니다.
  • 설정이 필요한 호스트에서는 생성 창을 떠나지 않고 Set project location(프로젝트 위치 지정)을 골라, 기존 체크아웃/폴더를 찾아 고르거나 그 호스트에 Git 저장소를 복제(clone)할 수 있습니다. 준비되면 Orca가 그 위치를 자동 선택하므로 계속 만들면 됩니다.
  • 연결이 끊긴 SSH(암호화된 통로로 다른 컴퓨터에 접속하는 방법)/원격 호스트는 실행 대상으로 고르지 않고도 Connect(연결)만 할 수 있습니다.
  • Add host(호스트 추가)는 SSH나 Remote Orca Server 대상을 위해 항상 고정되어 있습니다. 자세한 실행 방식은 "Ways to run Orca" 문서를 참고하세요.
  • Agent 선택기(접힌 상태든 펼친 상태든)에서 Set as default로 고른 에이전트를 기본값으로 정할 수 있습니다. Blank Terminal도 기본값이 될 수 있습니다.
  • 이름 칸에서 GitHub PR, Linear 이슈, GitLab MR, Jira 이슈를 연결합니다. Jira는 URL을 붙여 넣거나 Jira 모드에서 검색합니다.
  • 연결된 이슈는 워크트리 카드에 표시됩니다(Jira 항목 목록 문서 참고). 나중에 Edit Worktree Details에서 리뷰·작업을 더 붙일 수 있습니다.
  • 워크트리 이름 칸에 Slack식 단축 코드(:rocket:)를 치면 제안 팝업에서 이모지를 고를 수 있습니다.
  • 같은 선택기가 사이드바에서 더블클릭으로 이름 바꿀 때, Edit Worktree Details에서, Worktree Jump Palette(Cmd-J, macOS)에서도 동작합니다.
  • 화면에 보이는 이름은 이모지를 그대로 유지하지만, git 브랜치 이름을 만들 때는 알려진 이모지를 읽을 수 있는 코드로 바꿉니다(예: 🚀 → rocket).
  • Jump Palette 검색은 이모지 이름 워크트리를 이 코드 조각으로 찾아 줍니다.
  • 기본적으로 브랜치 이름은 입력한 워크트리 이름에서, 또는 연결된 GitHub PR · Linear/Jira 이슈 · GitLab MR에서 만들어집니다.
  • 직접 정하려면 Advanced(고급) 펼침 영역을 열고 Branch name 칸(예시 글씨 feature/my-branch)에 입력합니다.
  • 직접 입력한 워크트리 이름은 Auto-Rename Branch From Work(작업 내용으로 브랜치 자동 이름 변경)가 켜져 있어도 브랜치에 그대로 쓰입니다. 자동 변경은 Orca가 만든 이름만 바꿉니다.
  • Linear 이슈에서 만들면, Linear가 제공하는 그 이슈의 브랜치 이름(Linear 화면에서 제안하는 것과 같은 이름)을 씁니다. 이슈 제목을 그대로 줄여 이름으로 만드는 방식이 아닙니다.
  • Branch name 칸은 직접 입력한 이름이나 base 브랜치로 만들 때만 보입니다. 추적 중인 작업 항목에 묶이면 브랜치는 그 항목에서 정해지고(연결된 GitHub PR은 제출 순간 브랜치를 다시 확인), 입력해도 무시될 칸이라 아예 숨깁니다.
  • 같은 펼침 영역에서 같은 저장소의 활성 워크트리를 Parent workspace(부모 워크트리)로 고를 수 있습니다. 이건 Orca 사이드바에서 안쪽으로 묶어 보여 주기만 할 뿐, git 기록이나 브랜치는 바꾸지 않습니다. 보관된 워크트리나 순환(서로가 서로의 부모)이 생기는 선택은 제외됩니다.

새 워크트리에 빠진 파일 채우기 — 공유 경로

⏭ 처음엔 건너뛰어도 됩니다 — 새 워크트리에서 "파일이 없다"는 오류가 날 때 돌아와 읽으세요.

새 워크트리는 깨끗한 체크아웃입니다. 기록에 저장되는 파일만 꺼내지므로, gitignore된(.gitignore 목록에 적혀 git이 기록하지 않는) 파일은 따라오지 않습니다. 대표적인 세 가지가 빠집니다.

  • 의존성(프로그램이 돌아가는 데 필요한 남이 만든 부품 묶음, 예: node_modules) — 크고, 언제든 다시 받을 수 있습니다.
  • 캐시(빠르게 하려고 미리 만들어 둔 임시 결과물, 예: .cache) — 역시 크고, 다시 만들 수 있습니다.
  • 로컬 비밀값(비밀번호·접속 열쇠를 적은 개인 설정 파일, 예: .env) — 작고, 다시 만들기 번거롭습니다.
쉽게 비유하면새 책상(워크트리)을 받았는데 서랍이 비어 있는 상황입니다. 두꺼운 공용 사전(의존성·캐시)은 책상마다 한 권씩 사지 않고 옆 책상 것을 같이 봅니다(공유). 반면 개인 열쇠(.env)는 책상마다 복사본을 하나씩 넣어 둡니다(복사). Orca는 이 두 가지 방법으로 빈 서랍을 채웁니다.
📁 주 체크아웃 node_modules/.cache/.env 📁 새 워크트리 node_modules/ 🔗.cache/ 🔗.env 📄(자기 사본) 공유(바로가기) — orca.yaml · Shared Paths 복사 — .worktreeinclude
공용 사전처럼 크고 다시 만들 수 있는 폴더는 "공유", 개인 열쇠처럼 워크트리마다 따로 가져야 할 설정 파일은 "복사"합니다.

설정하는 곳은 세 군데입니다 — 나만 쓰는 Settings → Repository(설정 → 저장소)의 Shared Paths, 팀이 함께 쓰는 orca.yaml 파일(공유), 그리고 .worktreeinclude 파일(복사). 정확한 적는 법은 아래 접힌 상자에 있습니다.

세 방법의 설정 위치·조건·예시 파일

어디서: 저장소별로 Settings → Repository(설정 → 저장소). 사용자 개인 설정입니다.

동작: 적은 경로를 주 체크아웃에서 새 워크트리마다 만들어 넣습니다. macOS에서는 가능하면 APFS 복제 복사(clone-copy: 디스크 공간을 거의 쓰지 않는 사본), 안 되면 심볼릭 링크(실제 파일 대신 원본 위치를 가리키는 바로가기)를 씁니다.

어디서: 저장소 루트의 orca.yaml 안 worktree.sharedDirectories. 저장소에 커밋되어 팀이 함께 씁니다.

동작: gitignore된 폴더를 같은 방식으로 공유합니다(복사가 아니라 링크/공유). node_modules나 .cache처럼 크고 다시 만들 수 있는 폴더에 씁니다.

조건: 항목은 주 체크아웃에 폴더로 존재하고 gitignore되어 있어야 합니다. git이 추적하는 경로나 없는 경로는 건너뜁니다.

# orca.yaml (repo root)
worktree:
  sharedDirectories:
    - node_modules
    - .cache

어디서: 저장소 루트의 .worktreeinclude 파일.

동작: gitignore된 파일·폴더를 새 워크트리마다 복사합니다(링크가 아님). 그래서 워크트리마다 자기 사본을 따로 가집니다. 흔한 예: .env, .vscode/ 아래 로컬 설정.

  • 빈 줄과 # 주석을 쓸 수 있습니다.
  • 지금은 글자 그대로의 경로만 지원합니다. 와일드카드(glob, 예: *.env)와 부정(!)은 경고와 함께 건너뜁니다.
  • 추적 중이거나, 없거나, gitignore되지 않은 경로는 복사하지 않습니다.
# .worktreeinclude (repo root)
.env
.env.local
.vscode/settings.json
세 방법이 겹칠 때orca.yaml의 공유 폴더는 사용자별 Worktree Shared Paths 목록에 더해질 뿐 대체하지 않습니다. 이미 공유·링크된 경로는 .worktreeinclude로 다시 복사하지 않습니다.

사이드바 — 워크트리를 정리하고 찾기

Sidebar
🔍 Search (Cmd-J) · 필터 입력 · ⚙ 2
my-app
📌 결제 리팩터링
? 로그인 버그 🚀
문서 정리 2 children
main
api-server
캐시 실험

기본으로 사이드바는 프로젝트별로 워크트리를 묶습니다. 맨 위 줄이 프로젝트(git 저장소 하나 또는 관련 묶음)이고, 펼치면 작업 중인 워크트리가 나옵니다.

  • 머리 부분에 전역 검색과 별개인 자체 필터 입력이 있어 사이드바 안에서 목록을 좁힐 수 있습니다.
  • 맨 위 Search 버튼은 Worktree Jump Palette(Cmd-J, macOS)를 엽니다 — 키보드를 잘 안 쓰는 사람을 위한 클릭 버전입니다.
  • 상태 표시줄에 에이전트 활동이 보이고, 읽지 않은 워크트리는 배지 대신 굵은 글씨로 표시됩니다.
  • 왼쪽 사이드바를 열어 두었는지 재시작 후에도 기억하며, 다른 클라이언트에서 원격 워크트리를 드러내도 내 사이드바 묶음이 펼쳐지지 않습니다.

카드 다루기 — 자주 쓰는 것

하고 싶은 일방법
오래 걸리는 작업을 위에 고정워크트리를 프로젝트 맨 위에 pin(고정)
보관 · 잠재우기 · 삭제워크트리 우클릭 → archive / sleep / delete
여러 개 선택Cmd(Linux/Windows는 Ctrl)+클릭으로 하나씩 추가, Shift+클릭으로 연속 범위. 선택된 것 중 하나를 우클릭하면 모두에 적용
이름 바로 바꾸기제목을 더블클릭. 카드의 다른 곳을 더블클릭하면 전체 편집 창이 열림

목록을 좁히는 필터(잠든 것·자동으로 만든 것 숨기기 등)와 부모 아래 묶이는 자식 워크트리, 그 밖의 카드 조작은 아래 접힌 상자에 있습니다.

필터 메뉴 · 그 밖의 카드 조작 · 자식 워크트리

필터 메뉴

머리의 필터 메뉴에는 Show 영역(하위 메뉴 Hosts and projects: 호스트·프로젝트 범위)과, 그 아래 "숨기기" 토글들이 있습니다.

숨기기 항목설명
Sleeping workspaces잠든(활성 패널이 닫힌) 워크트리. 단, 프로젝트의 진입점/메인 워크트리는 이 필터에서도 보여 프로젝트 줄이 사라지지 않습니다.
Except default branchHide sleeping이 켜져 있을 때만 보이는 하위 옵션. 기본 브랜치 워크트리는 잠든 것 숨기기에서 제외합니다.
Default branch workspaces메인 체크아웃 줄.
Automation-created workspaces자동화가 만든 워크트리.
CLI-created workspacesorca worktree create로 만든 것. 카드에 마우스를 올리면 Orca CLI 출처 정보가 보입니다.
Other-client workspaces공유 Remote Orca Server에 다른 연결 기기가 만든 워크트리가 있을 때 나타납니다. 켜면 이 기기에서 만든 것만 보입니다. 빈 Cmd-J(macOS) 최근 목록과 숫자 단축키도 같은 필터를 따르지만, 검색어를 치면 숨은 줄도 찾아집니다.
Detached HEAD workspacesDetached HEAD(브랜치 이름표 없이 특정 저장 시점 하나에 그대로 서 있는 상태) — 브랜치가 아니라 특정 커밋 위에 있는 체크아웃.

필터 버튼에 켜진 필터 개수가 표시되고, Clear는 켜진 필터만 초기화합니다. 이 필터로만 숨겨진 워크트리는 텍스트 검색이나 Jump Palette에 검색어를 치면 여전히 찾을 수 있습니다(Jump Palette에는 Tab으로 여는 자체 호스트/프로젝트 필터도 있습니다).

그 밖의 카드 조작

하고 싶은 일방법
키보드로 삭제 시작워크트리나 폴더 워크스페이스에 마우스를 올리고 macOS Cmd-Shift-Backspace, Windows/Linux Ctrl-Shift-Backspace (확인 창은 그대로 뜹니다)
저장소 줄 순서 바꾸기드래그. 줄 위/아래로 끌면 순서 변경, 안쪽으로 넣는 영역은 넓고 안정적. Esc로 취소
이름 복사워크트리 하나 우클릭 → Copy Worktree Name. Orca가 워크트리 지정에 쓰는 정식 이름을 복사(사용자 이름 → 브랜치 → 폴더 순으로 대체)하므로 폴더 워크스페이스나 이름을 지운 경우에도 동작
연결된 작업 여러 개Edit Worktree Details → Linked work. GitHub·GitLab·Linear·Jira URL을 붙이거나 연결된 서비스를 검색. Reviews(PR/MR)와 Issues & tasks로 나뉘고 개수가 보이며 카드에 쌓여 표시. 링크는 그 워크트리의 저장소 것이어야 함
끊긴 SSH 다시 연결호스트 연결이 끊긴 SSH 워크트리는 카드 제목 줄에 재연결 컨트롤이 나올 수 있음(SSH worktrees 문서)

직접 바꾼 이름은 워크트리 브랜치가 바뀌어도 유지됩니다. 사용자 이름을 지우면 다시 브랜치에서 자동으로 이름을 따옵니다. Orca가 만든 이름은 계속 브랜치를 따라갑니다.

자식 워크트리(중첩)

  • 오케스트레이션이나 부모를 지정한 worktree create로 생긴 자식이 있으면, 부모 아래 N children 칩이 보입니다. 클릭하면 자식을 보이거나 숨깁니다.
  • 키보드로 같은 일을 하려면 Settings → Shortcuts에서 Toggle Child Workspaces에 키를 지정합니다. 마우스 아래 워크트리(없으면 활성 워크트리)에 칩과 똑같이 작동합니다.
  • 우클릭 메뉴에 Sleep with Descendants (N)와 Delete with Descendants…가 생길 수 있습니다.
    • Sleep with descendants: 선택한 워크트리와 같은 프로젝트·저장소·호스트 안의 검증된 모든 자식의 활성 패널을 닫습니다. 살아 있는 터미널이나 브라우저 탭이 있는 것만 대상입니다.
    • Delete with descendants: 원래 있던 연쇄 삭제를 명시적으로 보여 주고 백그라운드에서 실행하므로 확인 창이 Orca의 나머지를 막지 않습니다.
    • 오래된 계보 링크, 순환, 호스트나 저장소 경계를 넘는 자식은 제외됩니다.

정리 도구와 보존 브랜치

⏭ 처음엔 건너뛰어도 됩니다 — 워크트리가 많이 쌓여 한꺼번에 지울 때 읽으세요.

Resource Manager → Clean up workspaces

여러 워크트리를 지우기 전에 전체를 훑어보고 싶을 때 씁니다. 목록에는 로컬 워크트리, 메인 워크트리, 폴더 워크스페이스, 연결이 끊긴 SSH 호스트의 워크트리가 포함됩니다.

  • 폴더 워크스페이스와 프로젝트 그룹은 내부 ID 대신 저장된 표시 이름(예: Documentation → Release notes)으로 보이며, 재시작 후 세션을 복구해도 마찬가지입니다.
  • 검색·필터·정렬로 각 워크트리의 상태, 최근 활동, 크기, Git 상태, 연결된 리뷰를 확인한 뒤 지울 것을 고릅니다.

보존 브랜치 (Preserved branches)

일괄 삭제다중 선택 / 정리 도구 폴더는 모두 삭제복구되지 않음 미병합 의심 브랜치git이 삭제 거부 → 보존 Review N Branches남은 브랜치 검토 고른 것만 강제 삭제나머지는 저장소에 남음
폴더는 지워지지만, 합쳐지지 않은 커밋이 있을 수 있는 브랜치는 남겨 두고 검토 기회를 줍니다.

사이드바 다중 선택이나 Resource Manager 정리로 일괄 삭제해도 디스크 폴더는 지워집니다. 그런데 git이 "합쳐지지 않은 커밋이 있을 수 있다"며 로컬 브랜치 삭제를 거부하면, Orca는 그 브랜치를 남기고 Review N Branches 같은 알림(화면 구석에 잠깐 뜨는 메시지)을 띄웁니다. 열면 남은 브랜치 목록이 나와 일부만 강제 삭제할 수 있습니다. 선택하지 않은 브랜치는 저장소에 남고, 워크트리 폴더는 복원되지 않습니다.

여러 저장소 묶음과 폴더 워크스페이스

⏭ 처음엔 건너뛰어도 됩니다 — 저장소 여러 개를 한 번에 다룰 때만 필요합니다.

Git 저장소 여러 개가 든 상위 폴더를 추가하면, 고른 저장소를 따로따로 가져오거나 하나의 프로젝트 그룹으로 묶을 수 있습니다.

📦 프로젝트 그룹: company/ + repo: web repo: api 📁 폴더 워크스페이스 상위 폴더 수준에서 동작 작업 출처: repo api
폴더 워크스페이스는 상위 폴더에 놓이지만, 이슈·PR 같은 작업 출처는 아래 저장소 하나에 묶입니다.
  • 각 프로젝트 그룹에는 폴더 워크스페이스 흐름이 있습니다. 상위 폴더 수준에 있는 워크트리 비슷한 항목으로, 작업 출처(GitHub/GitLab/Linear/Jira)를 아래 저장소 중 하나에 묶어 둡니다. 그래서 사이드바에서 형제들과 함께 묶여 있어도 기능별 작업 화면이 올바른 저장소에 붙어 있습니다.
  • 만드는 법: 사이드바의 그룹 머리 줄에 마우스를 올리고 +(툴팁 "Create workspace for group")를 누릅니다. Create Folder Workspace 창에서 작업 출처가 될 프로젝트를 고르고, 이름을 짓고, 원하면 이슈나 PR을 연결해 제출합니다. 그룹 아래 일반 워크트리 옆에 나타납니다.
  • 프로젝트 그룹을 지울 때 포함된 프로젝트(저장소 등록)까지 함께 제거하는 체크박스가 있어, 더는 안 쓰는 묶음을 확인 한 번으로 정리할 수 있습니다.

평범한 git 명령도 그대로

Orca가 만든 워크트리는 특별한 것이 아니라 진짜 git 워크트리입니다. 그래서 개발자가 터미널에서 git 명령을 직접 쳐도 문제없고, Orca는 다음에 화면을 새로 고칠 때 그 변화를 알아채 사이드바와 화면에 반영합니다. git 명령을 몰라도 Orca 화면만으로 쓸 수 있으니, 이 절은 "섞어 써도 괜찮다"는 것만 알면 됩니다.

⌨️ 터미널에서 직접 $ git status $ git worktree add … $ git worktree remove … 🖥️ Orca 화면 사이드바 목록·상태가 맞춰짐 직접 만든 워크트리 → "외부" 표시 직접 지운 워크트리 → 목록 정리 다음 새로 고침 때 알아챔
같은 워크트리를 터미널에서 git 명령으로 바꿔도, Orca는 다음 새로 고침 때 알아채고 자기 화면을 맞춥니다.

직접 만든 워크트리는 처음엔 "외부" 것으로 숨겨질 수 있고, 사이드바의 hidden worktrees 카드에서 보이게 할 수 있습니다. 세부 설정은 아래에 접어 두었습니다.

직접 만든(외부) 워크트리 다루기와 출처별 설정
  • Orca 워크트리는 모두 진짜 git 워크트리입니다. 터미널을 열어 git status, git rebase, git cherry-pick(뒤의 둘은 기록을 옮기거나 골라 담는 개발자용 명령) 등 무엇이든 쓸 수 있고, Orca는 다음 화면 갱신 때 변경을 알아챕니다.
  • 직접 git worktree add로 만든 워크트리는 Orca에 보이게 하기 전까지 외부 것으로 남습니다. 저장소가 이를 숨기면 사이드바에 hidden worktrees 카드가 나옵니다. 클릭해 Non-Orca worktrees를 열고 원하는 것에 Show를 고르세요.
  • Settings → General → Workspace에서 외부 워크트리 출처(Claude Code 워크트리, GSD 워크트리, 기타 위치, 직접 추가한 절대 경로 위치)의 전역 기본값을 정합니다. 이 기본값은 그 호스트의 현재·미래 워크트리에 적용되며, 새로 추가한 전역 사용자 루트는 숨김으로 시작합니다.
  • 프로젝트의 Non-Orca worktrees 창에서는 출처별로 그 프로젝트만 따로 설정하거나 전역 설정으로 되돌리고, 숨은 워크트리를 검색해 하나씩 되살릴 수 있습니다.
  • CLI에서 git worktree remove를 해도 Orca가 다음에 그 저장소를 새로 고칠 때 알아채고 자기 상태를 정리합니다.

에이전트 세션과 상태 표시

에이전트 세션이란 워크트리 하나 안의 터미널 하나에서 도는 CLI 에이전트 하나입니다. CLI(마우스 대신 글자 명령으로 쓰는 프로그램) 에이전트는 Claude Code·Codex처럼 터미널 창 안에서 일하는 AI 도우미를 말합니다. Orca는 그 일생을 추적해서, 탭마다 들어가 보지 않아도 어떤 세션이 일하고 어떤 세션이 쉬는지 알려 줍니다. 모든 워크트리 카드 안에 상태 기호가 바로 보입니다.

작업 중Spinner ? 나를 기다림권한·입력 필요 완료초록 점 · ✓ 막힘·실패중단 포함 쉬는 중오래 조용함 표시 없음평범한 셸
에이전트 탭과 워크트리 줄은 같은 상태 기호를 씁니다.
기호뜻
Spinner(돌아가는 원)작업 중
? 주황 물음표나를 기다림(권한 요청 / 입력 필요). 사이드바 "Needs You" 개수도 같은 기호
초록 체크(대시보드) 또는 초록 점(사이드바)완료 / 조용히 활성
빨간 점막힘, 중단됨, 실패
회색 점쉬는 중(idle) — 끝난 뒤 오래 조용한 상태
표시 없음평범한 셸 — Orca가 아는 에이전트 CLI가 아님
시간 순서로 보면작업 중(돌아가는 원) → 끝나면 초록 + 🔔 끝남 알림 → 오래 두면 회색(쉬는 중 — 대시보드는 약 30분 조용하면 Idle 칸). 원문은 끝남 알림이 울리는 순간도 "idle"이라고 부르지만, 이 가이드는 그 순간을 "끝남", 오래 조용한 상태만 "쉬는 중"이라고 부릅니다.

Orca는 이 상태를 어떻게 알까요? 에이전트가 일하는 동안 "나 지금 일해요", "끝났어요" 하고 신호를 보내기 때문입니다. Claude Code, Codex 등 여러 에이전트가 이 신호를 내보냅니다.

신호의 정체와 정확한 감지 규칙
  • 상태는 터미널의 OSC 제목 신호(프로그램이 터미널 창 제목을 바꾸며 보내는 신호)와 에이전트 훅(hook — 에이전트가 정해진 순간마다 바깥에 알려 주는 연결 지점)으로 감지합니다.
  • 작업 중에는 OSC 제목이 바뀌며 상태가 갱신되고, 터미널 출력은 검색·복사가 되며 Ghostty 테마로 꾸며집니다.
  • 정확한 감지 규칙은 Orca CLI의 terminal wait --for tui-idle 명령 설명을 보세요.
상태 표시가 안 보이면그 세션의 에이전트 CLI를 Orca가 인식하지 못한 것입니다. 실행 파일 이름을 손으로 치지 말고 에이전트 콤보 상자로 시작하세요.

세션의 일생

🤖 Launch실행콤보 상자에서 고름 Work작업 중 끝남 🔔초록 · 끝남 알림 오래 두면 회색 Exit종료(정상·충돌) Restart Restart 칩 한 번 → 같은 에이전트를 같은 폴더에서 다시 시작 ? 권한·입력이 필요하면주황 ? (나를 기다림)
실행 → 작업(돌아가는 원) → 끝남(초록, 🔔 끝남 알림 — 오래 두면 회색 "쉬는 중") → 종료(Restart 칩). Restart 칩을 누르면 다시 작업으로 돌아옵니다. 작업 도중 나를 기다릴 때는 주황 ?가 뜹니다.
Launch — 실행

콤보 상자에서 에이전트를 고르면 Orca가 CLI를 띄웁니다.

Work — 작업

에이전트가 보내는 신호로 상태 기호가 바뀝니다. 터미널 출력은 검색·복사가 됩니다.

끝남 (원문: Idle)

Orca가 "작업 중 → 조용해짐"으로 바뀌는 순간을 감지해 agent-finished(에이전트 끝남) 알림을 보냅니다. 그대로 오래 두면 회색 "쉬는 중"으로 보입니다.

Exit — 종료

에이전트 프로그램이 끝나면 탭에 Restart 칩이 나타납니다.

Restart 칩

에이전트가 끝나면(정상 종료든 충돌이든) 탭에 Restart 칩이 뜹니다. 한 번 누르면 같은 에이전트를 같은 작업 폴더에서 다시 살립니다.

Codex 계정 유지

Codex의 Restart 칩은 현재 계정도 유지합니다(Hot-swap Codex accounts 문서 참고).

에이전트 대시보드 실험 기능

Settings → Experimental → Agent Dashboard(설정 → 실험 기능)를 켜면 왼쪽 사이드바에 Agent Dashboard 항목이 생깁니다. 모든 워크트리의 에이전트를 칸반(열마다 카드를 놓는 게시판) 형태로 보여 줍니다.

? Needs You
🤖 로그인 버그"파일 삭제를 허락할까요?"
Working
🤖 결제 리팩터링my-app · 3분
🤖 API 문서api-server · 1분 · SSH host · openclaw
Done
🤖 README 정리docs · 12분 · PR Open
Idle (기본 숨김)
🤖 캐시 실험30분 이상 조용함

네 개의 열

  • Needs You — 권한이나 질문에 답을 기다림
  • Working — 실행 중
  • Done — 끝났지만 아직 검토하고 싶을 수 있는 세션
  • Idle — 약 30분 동안 완료를 알리지 않은 조용한 에이전트. 보드에서 기본 숨김입니다. 보이려면 보드 설정(톱니바퀴)에서 Show idle agents를 켭니다 — 전역 Experimental 설정이 아니라 창 안/팝아웃 화면의 톱니바퀴입니다. 창 안과 팝아웃은 서로 동기화됩니다.

카드를 누르면 그 에이전트의 터미널이 바로 열립니다. 카드에 무엇이 표시되는지, 검색·필터와 별도 창으로 여는 법은 아래에 접어 두었습니다.

카드 구성 · 검색·필터·열기 방식
  • 머리: 에이전트 아이콘, 세션 대화 이름(직접 바꾼 이름 → 생성된 제목 → AI Vault/에이전트 세션 제목 → 없으면 워크트리 이름), 상태 기호
  • 미리보기: 가능하면 마지막 사용자/에이전트 메시지, 없으면 작업 요약
  • 바닥: 프로젝트 아이콘, 워크트리 이름(머리에 세션 이름이 이미 있을 때), 경과 시간, 캐시된 리뷰 상태(있으면). 워크트리 상태는 툴바 필터에만 있고 카드에는 워크트리별 상태 점이 더는 없습니다.
  • Needs You 카드는 주황빛(대기 중인 질문 요약 표시 가능), Done 카드는 초록빛, 나머지는 중립 — 색이 있으면 "여기 보세요"라는 뜻입니다.
  • 카드를 클릭하면 그 에이전트의 실시간 터미널이 열리거나 앞으로 옵니다. 연결된 Remote Orca Server의 에이전트도 되며, 미리보기는 그것을 돌리는 호스트에서 가져옵니다.
  • SSH 워크트리와 연결된 Remote Orca Server 카드에는 호스트 배지가 붙습니다. 마우스를 올리거나 초점을 주면 저장된 호스트 이름(예: SSH host · openclaw, Remote Orca host · Build Mac)이 보입니다. 로컬 워크트리에는 없습니다.
  • 중첩된 Codex/Claude 하위 에이전트(subagent)는 부모 줄 아래 펼칠 수 있는 자식으로 나올 수 있습니다.
  • Open as: 사이드바 옆 창 안 보드(In-window) 또는 별도 창(Pop-out)
  • Search: 워크트리·프로젝트·에이전트 이름. 검색어나 필터가 있으면 결과 개수가 보임
  • Filter: Project, Workspace status(워크트리 상태), PR / MR status(Open, Draft, Merged, Closed, No review) 다중 선택
  • 하나씩 지울 수 있는 필터 칩과 Clear all filters
  • Settings → Shortcuts에서 Toggle Agent Dashboard에 단축키를 지정할 수 있습니다. 기본 키는 없고, 터미널·편집기·브라우저 탭에 초점이 있어도 동작합니다.

실험 보드를 꺼 두어도 워크트리 카드에는 같은 기호로 에이전트 줄이 인라인 표시됩니다.

실행 기본값 — 에이전트가 허락을 묻는가

에이전트는 파일을 고치거나 명령을 실행하기 전에 "이거 해도 될까요?" 하고 사람에게 물을 수 있습니다. Orca는 기본으로 묻지 않게 해서 에이전트를 띄웁니다. 매번 허락 창이 떠서 흐름이 끊기지 않게 하려는 것이고, 그래도 되는 이유로 워크트리 자체가 안전 울타리라는 점을 듭니다 — 에이전트는 자기 작업 폴더에서 일하고, 그 결과(변경점)는 합치기 전에 사람이 골라 담거나 버릴 수 있습니다.

묻는 모드 (Manual) 도구를 쓸 때마다 사람에게 확인 🤖 에이전트 "해도 될까요?" 사람이 승인해야 진행 ? 사이드바에 주황 ? 가 자주 뜸 안전하지만 자리를 비우면 멈춤 묻지 않는 모드 (Yolo · 기본) 확인 없이 스스로 진행 울타리 = 이 작업의 워크트리(폴더) 🤖 에이전트 고치고실행하고 결과는 합치기 전에 사람이 골라 담거나 버릴 수 있음
왼쪽은 매번 허락을 묻는 방식, 오른쪽은 Orca의 기본값인 묻지 않는 방식입니다. 오른쪽에서 Orca가 기대는 안전장치는 "작업마다 폴더가 따로"라는 워크트리 구조입니다.

"묻지 않게"는 에이전트를 켤 때 권한 생략 플래그(프로그램을 켤 때 뒤에 붙이는 옵션 글자. 여기서는 "확인 절차를 건너뛰어라"라는 뜻)를 미리 붙여 두는 방식으로 이루어집니다. 이 기본값은 Settings → Agents(설정 → 에이전트)의 Agent permissions(에이전트 권한)에서 바꿀 수 있습니다 — 플래그가 붙은 지금 상태가 Yolo(묻지 않음)이고, Manual(매번 묻기)로 바꾸면 허락 창이 돌아옵니다. 그 사이의 Auto는 지원하는 에이전트(Claude, Claude Agent Teams, Codex)가 일상적인 동작만 스스로 승인하는 모드입니다.

주의 — 에이전트가 묻지 않고 실행합니다기본 상태에서는 에이전트가 파일 수정·명령 실행을 확인 없이 합니다. Codex의 플래그는 이름대로 승인 절차와 샌드박스(프로그램이 하는 일을 가둬 두는 격리 공간)를 모두 건너뜁니다. 워크트리가 작업 폴더를 분리해 주긴 하지만, 원하지 않으면 위의 설정에서 Manual로 바꾸세요.
에이전트별 기본 플래그와 실행 인자 직접 고치기
에이전트기본으로 붙는 플래그
Claude--dangerously-skip-permissions
Codex--dangerously-bypass-approvals-and-sandbox
Gemini (Cursor · Crush · Kimi · Rovo Dev · Hermes · GitHub Copilot · Command Code도 같음)--yolo
그 밖의 에이전트선택기의 각 에이전트에 해당하는 같은 성격의 플래그
  • 에이전트 하나만 바꾸려면 Settings → Agents에서 그 에이전트 줄을 펼치고 launch arguments(실행 인자)를 고칩니다. Orca가 이 변경을 기억해 이후 실행마다 적용하고, 옆의 Reset 버튼은 원래 플래그로 되돌립니다.
  • Agent permissions에서 Manual·Auto·Yolo를 고르면 새 터미널 세션과 구조화된 채팅 세션에 적용됩니다. 이미 열려 있는 채팅은 자기 모드를 유지합니다.
  • Auto를 고르면 Auto를 지원하지 않는 에이전트에 쓸 Manual 또는 Yolo를 Other agents에서 따로 정합니다.
  • 실행 인자를 직접 고쳐 둔 에이전트는 전체 권한 설정을 바꿔도 그대로 둡니다(직접 넣은 명령이 지워지지 않도록). 그 인자를 미리 준비된 값(preset)으로 바꿔야 전체 설정을 따릅니다.

탭·창·분할 레이아웃

Orca의 창 시스템은 여러 에이전트가 일하는 모습을 맥락을 잃지 않고 지켜보도록 만들어졌습니다. 탭은 탭 그룹(창, pane)에 모이고, 창은 쪼개져 레이아웃이 됩니다.

🤖 에이전트 터미널$ claude ± Diff 보기+ 추가된 줄 − 지운 줄 🌐 브라우저 탭localhost:3000 경계 위치는 워크트리별로 저장 (pinned boundaries)
왼쪽엔 에이전트 터미널, 오른쪽 위엔 diff, 오른쪽 아래엔 브라우저 — 분할은 중첩됩니다. 분홍 조각은 탭을 창 가장자리로 끌어다 놓는 모습입니다.

탭 하나에는 한 가지가 담깁니다: 터미널, 편집기 버퍼, 브라우저, diff, PR.

  • 그룹 안에서 탭을 위아래로 끌어 순서를 바꿉니다.
  • 다른 그룹 위로 끌면 그쪽으로 옮겨집니다.
  • 터미널·편집기·브라우저 탭 우클릭 → Copy Tab ID: 그 탭을 가리키는 고정 참조(예: orcaTabId: abc123)를 복사합니다. 에이전트에게 "정확히 이 탭"을 알려 줄 때 편합니다. 비활성·고정 탭에서도 되고, 탭 이름을 바꾸거나 활성화하거나 닫지 않습니다.
  • 활성 워크트리의 편집기 파일 탭을 모두 닫기: macOS Cmd+Option+W, Windows/Linux Ctrl+Alt+W.
  • 활성 탭 색 막대가 어느 창에 초점이 있는지 알려 줍니다.
  • 탭 어디든 마우스를 올리면 전체 제목과 그 아래 아이콘·프로그램 줄이 나옵니다. 옆 탭으로 옮기면 짧은 미끄럼 효과와 함께 바로 그 카드가 보여, 잘린 제목도 쉽게 알아볼 수 있습니다.

탭을 창의 가장자리로 끌어다 놓으면 분할됩니다.

  • 오른쪽 가장자리 — 좌/우로 나눔(horizontal split)
  • 아래쪽 가장자리 — 위/아래로 나눔(vertical split)
  • 분할은 중첩됩니다. 어떤 탭 종류든(에이전트 터미널, diff, 브라우저, 편집기, PR 보기) 한 창 트리 안에 함께 있을 수 있습니다.
  • 터미널 탭은 탭 안에서도 나눌 수 있습니다. 터미널 탭 메뉴의 Split terminal right / Split terminal down, 또는 활성 터미널 창 머리의 분할 버튼(오른쪽 분할)을 씁니다.
  • 고정된 경계(Pinned boundaries): 경계선은 놓은 자리에 머뭅니다. 창 크기를 바꿔도 레이아웃이 뒤섞이지 않고, 경계 위치는 워크트리별로 저장됩니다.

새로 설치했을 때의 기본 단축키입니다.

동작macOSLinux / Windows
다음 / 이전 탭 (모든 종류)Cmd+Shift+] / Cmd+Shift+[Ctrl+Shift+] / Ctrl+Shift+[
다음 / 이전 탭 (같은 종류)Cmd+Option+] / Cmd+Option+[Ctrl+Alt+] / Ctrl+Alt+[
직전에 쓴 탭Ctrl+TabCtrl+Tab

Settings → Shortcuts에서 바꿀 수 있습니다. 기존 설치는 사용자 지정 값을 ~/.orca/keybindings.json에 유지합니다.

워크트리마다 자기 탭 레이아웃을 가집니다. 워크트리를 바꾸면 창 트리 전체가 통째로 바뀌고, 브라우저 탭·터미널·diff가 두고 간 모습 그대로 다시 나타납니다.

세션 복원 — 껐다 켜도 그대로

Orca를 닫았다가 다시 열면 작업 공간 전체가 되살아납니다. 어떤 브랜치에서 어떤 에이전트를 돌리고 있었는지 기억하는 건 사용자가 아니라 Orca의 일입니다.

비결은 데몬(화면 없이 뒤에서 계속 도는 프로그램)입니다. 데몬을 앱을 꺼도 뒤에서 터미널을 붙잡고 있는 관리인이라고 생각하면 됩니다. 에이전트가 일하는 터미널은 앱 창이 아니라 이 관리인이 쥐고 있어서, 창을 닫아도 일이 멈추지 않습니다. 다만 관리인도 컴퓨터 안에 사는 프로그램이라, 컴퓨터 자체가 꺼지면 함께 꺼집니다.

Orca 앱 창닫아도(macOS Cmd-Q) 괜찮음 데몬 (관리인)뒤에서 터미널을 붙잡고 있음 🤖 Claude Code 🤖 Codex 재연결 💻 컴퓨터 — 재부팅·OS 업데이트·시스템 멈춤·전원 끊김이면 데몬도 꺼짐 그래도 화면 배치와 마지막 출력 기록은 돌아옴. 에이전트만 다시 실행
에이전트 터미널은 앱이 아니라 데몬이 붙잡고 있어서, 앱 창을 닫아도 에이전트는 계속 일합니다.

복원되는 것

  • 열린 워크트리 — 사이드바에 열려 있던 모든 워크트리
  • 탭과 분할 — 워크트리별 창 배치(중첩 분할 포함)와 초점이 있던 탭
  • 실행 중인 에이전트 — 데몬(관리인)이 터미널을 쥐고 있으므로 앱 창을 닫아도 Claude Code·Codex 등이 작업 도중 죽지 않습니다. 다음 실행 때 새로 띄우지 않고 살아 있던 그 에이전트에 그대로 다시 연결합니다.
  • 터미널 스크롤백(위로 굴려 다시 볼 수 있는 지난 출력) — 각 터미널의 출력 기록. Orca가 닫혀 있던 동안 나온 출력도 포함
  • 초점 워크트리와 탭 — 닫을 때 보던 화면으로 열림

복원되지 않는 것

  • 데몬은 컴퓨터와 운명을 같이합니다. 재부팅, OS 업데이트, 커널 패닉(운영체제가 심각한 오류로 갑자기 멈추는 일), 강제 전원 끄기처럼 기계 전체가 꺼지면 실행 중인 에이전트는 모두 끝납니다. 다음 실행 때 워크트리·탭·분할·마지막 스크롤백은 돌아오지만 에이전트 프로세스는 없습니다. 아무 탭에서 에이전트를 다시 실행해 이어 가세요.
  • Orca가 닫혀 있는 동안 데몬이 충돌해도 그 데몬이 붙잡던 세션은 같은 결과가 됩니다. 레이아웃과 스크롤백은 여전히 복원됩니다.
개발자용 용어 — PTY와 warm-reattach

데몬이 쥐고 있는 것은 각 에이전트의 PTY(가상 터미널 — 프로그램이 터미널 화면과 주고받는 통로)입니다. 다음 실행 때 살아 있던 프로세스에 그대로 다시 붙는 동작을 warm-reattach라고 부릅니다.

언제 복원이 일어나나 — 상황별로 보기

데몬 살아남음 → 에이전트 계속 실행. Cmd-Q(macOS)는 평소의 종료 방법이며, 에이전트는 뒤에서 계속 일합니다.

데몬 살아남음. 업데이트 설치를 위해 Orca가 다시 켜져도 에이전트는 영향받지 않습니다.

데몬 살아남음. Orca 자체가 충돌해도 데몬이 세션을 살려 두고, 다음 실행 때 다시 붙습니다.

데몬 죽음 → 에이전트 사라짐, 레이아웃은 복원. 노트북 재시작, OS 업데이트, 커널 패닉, 강제 전원 끄기. 워크트리·탭·분할·마지막으로 저장된 스크롤백은 돌아옵니다.

깨끗하게 새로 시작하고 싶다면복원은 매번 실행할 때마다 일어나며, "새 세션으로 열기" 같은 모드는 없습니다 — Orca는 항상 복원합니다. 그러니 종료 전에 워크트리를 직접 닫으세요. 닫은 워크트리는 닫힌 채로 남습니다.

빠른 이동 — Cmd-P · + 검색창 · Cmd-J

⏭ 처음엔 아래 표만 보고 건너뛰어도 됩니다 — 탭 안의 세부 동작은 워크트리가 많아졌을 때 읽으세요.

워크트리가 몇 개를 넘으면 "어디로 가지?"가 병목이 됩니다. Orca는 키보드 중심 이동 도구를 제공합니다. 이 절의 Cmd 단축키는 원문에 macOS 키로만 나옵니다. 단축키는 모두 Settings → Shortcuts에서 바꿀 수 있습니다.

검색창이 세 개라 헷갈리기 쉽습니다. 무엇을 찾느냐로 고르면 됩니다.

검색창무엇을 찾나언제 쓰나
Cmd-P(macOS) Quick Open지금 워크트리 안의 파일"그 파일 어디 있더라?" — 파일 이름 조각으로 바로 열 때
탭 줄의 +열린 탭·파일·웹 주소·에이전트, 그리고 웹 검색새 탭을 열면서 무엇을 띄울지 한 칸에서 정할 때
Cmd-J(macOS) Jump Palette모든 워크트리와 모든 탭다른 작업(워크트리)으로 건너가거나, 나를 기다리는 에이전트를 찾을 때
Quick Open — 현재 워크트리
auth log
login.ts …/src/auth/
auth-log.md docs/
gitignore된 파일 (두 번째로)
.env ./
  • 현재 워크트리 안의 파일 검색입니다. 조각을 입력하면 최근 사용 + 일치 점수로 순위를 매기고, 고른 파일을 새 편집기 탭에 엽니다.
  • 여러 단어 검색어는 경로의 여러 부분에 걸쳐 맞춰지고, 위치(줄 등)를 가리키는 결과는 파일을 그 위치에서 엽니다.
  • 도중에 버린 검색은 취소되어 오래된 결과가 목록에 끼어들지 않습니다.
  • 결과 줄은 파일 이름이 앞에 오고, 공간이 좁으면 상위 폴더 경로를 줄입니다(마우스를 올리면 전체 경로).
  • gitignore된 파일도 결과에 나옵니다. 추적 파일 결과 다음 두 번째 단계로 나오므로, 자주 여는 빌드 결과물이나 env 파일에 닿으면서도 목록 위쪽을 어지럽히지 않습니다.
+ 새 탭
Search open tabs, files, URLs, agents…
📄 login.ts 이미 열린 탭
🌐 localhost:3000/login 방문 기록
🔎 "react 로그인 예제" 웹 검색
  • 탭 줄의 +는 열린 탭·파일·URL·에이전트를 한 칸에서 찾습니다(예시 글씨: Search open tabs, files, URLs, agents…).
  • 파일 줄은 Quick Open처럼 파일 이름이 앞에 옵니다. 이미 열린 편집기 탭과 맞으면 중복 파일 결과 대신 그 탭을 우선해 두 번째 사본을 열지 않습니다.
  • 이 워크트리의 브라우저 방문 기록도 검색합니다. 일치 정도와 최근 방문 순으로 URL·페이지 제목 제안이 나옵니다.
  • 경로나 URL 대신 검색어를 치면 워크트리 브라우저에서 Default Search Engine(기본 검색 엔진)으로 엽니다. 한 단어면 파일 결과가 먼저, 여러 단어 문장이면 검색 줄이 위로 올라갑니다.
  • 검색어 앞에 ?를 붙이면 파일·탭 맞추기를 건너뛰고 바로 검색합니다.
Worktree Jump Palette
repo/worktree Tab: 호스트·프로젝트 필터
Recent Chats & Terminals
? 로그인 버그 · Claude ⌘1
README 정리 · Codex ⌘2
결제 리팩터링 ⌘3 See more
Recent Worktrees
my-app / 캐시 실험

모든 워크트리와 모든 탭을 한 번에 검색해 이동합니다. 빈 입력칸의 예시 글씨는 repo/worktree — 어느 쪽 반쪽만 쳐도 걸러집니다. 입력을 시작하면 사이드바 필터로 숨겨진 것도 포함해 보관되지 않은 모든 워크트리를 찾습니다. :rocket: 같은 이모지 코드도 이름 짓기와 같은 제안 팝업을 씁니다.

Tab을 누르면 호스트·프로젝트 필터 메뉴가 열립니다. 고른 것은 하나씩 지울 수 있는 칩으로 보이고, 팔레트를 닫으면 필터가 지워져 다음엔 전체 범위로 열립니다.

Jump Palette는 아무것도 입력하지 않으면 최근 에이전트 세션(나를 기다리는 것부터)을 보여 주고, 입력을 시작하면 모든 워크트리와 탭을 찾습니다. 결과가 어떤 순서로 나오는지는 아래에 접어 두었습니다.

Jump Palette 결과 구성과 순서 규칙
Recent Chats & Terminals (빈 검색어일 때)
  • 활동 순으로 최근 에이전트/터미널 세션을 최대 6개: 나를 기다림 → 완료 → 쉬는 중 순서.
  • 지금 보고 있는 쉬는 탭은 빼서 목록이 "할 일" 위주로 유지됩니다. 단, 현재 탭이라도 작업 중·나를 기다림·읽지 않은 활동이 있으면 나옵니다.
  • 탭 줄과 같은 실시간 배지(돌아가는 원, 물음표, 종, 체크)를 씁니다.
  • 더 있으면 See more로 전체 목록을 펼칩니다. 숫자 단축키 macOS Cmd-1~Cmd-6, Windows/Linux Ctrl-1~Ctrl-6로 첫 줄들에 바로 갑니다.
  • 팔레트를 여는 순간 구성과 순서가 고정되어 커서 아래에서 줄이 뒤섞이지 않습니다.
Recent Worktrees

빈 검색어의 다음 구역. 마지막으로 초점을 준 순서이며, 훑어보기 좋게 개수가 제한됩니다.

Projects와 repo groups

사이드바 구역 이름으로 바로 이동할 수 있습니다.

저장소별 모든 워크트리 (입력 시작 후)

캐시된 GitHub PR 제목·번호(#123), GitLab MR 제목·번호(!123)로도 워크트리를 찾습니다 — 그 리뷰 정보가 이미 받아져 있을 때.

모든 열린 탭
  • 현재 워크트리 것이 먼저, 그다음 전체.
  • 탭 제목·내용에 맞는 것이 워크트리·브랜치·저장소 이름에만 맞는 것보다 앞섭니다. 비슷하면 최근에 쓴 탭이 앞.
  • 터미널·브라우저·시뮬레이터 줄은 저장소와 워크트리를 작은 위치 칩으로 합쳐 보여 주고, 긴 보조 경로는 앞쪽을 줄여 파일 이름과 맞은 끝부분이 보이게 합니다.
  • 마지막 활성 시점(얼마 전인지)을 아는 경우 표시합니다.
  • terminal, simulator 같은 종류 별칭으로도 찾을 수 있지만 줄 이름에는 붙지 않습니다.
섞어 보여 주기와 더 보기
  • 검색어가 탭과 워크트리 둘 다에 맞으면 각 구역 미리보기를 번갈아 보여 줘 한쪽이 묻히지 않게 합니다.
  • 구역에 더 있으면 N more 줄의 See more로 20개씩 더 펼칩니다. 검색어를 바꾸면 펼친 구역이 초기화됩니다.
  • 한 구역만 나오는 결과는 상한이 있는 전체 목록을 보여 줍니다.
열기와 새로 만들기
  • Enter로 이동, 워크트리에서 Shift-Enter는 현재 창을 바꾸지 않고 새 분할로 엽니다.
  • 검색어가 기존 워크트리와 맞지 않으면 그 글자를 이름으로 하는 Create worktree 줄을 제안합니다. 실제 결과가 있으면 그것이 먼저 선택되어 있어 Enter는 여전히 이동합니다.

실전 — 워크트리 10개를 오가기

워크트리 10개는 버거운 양입니다. Jump Palette + Restart 칩 + 에이전트 상태 기호가 바로 이 규모를 위해 만들어졌습니다. 아래는 10개를 띄워 둔 사이드바를 흉내 낸 것입니다 — 어디부터 가야 할지 기호만 보고 정할 수 있습니다.

Sidebar — 워크트리 10개
my-app
? 로그인 버그 ① 먼저
? 결제 화면 ① 먼저
검색 개선
알림 설정
README 정리 ② 검토
아이콘 교체 ② 검토
api-server
캐시 실험 ③ Restart
로그 정리
속도 측정
문서 번역
기호할 일
? 주황 ?나를 기다림 — 가장 먼저 갑니다
돌아가는 원일하는 중 — 그냥 둡니다
초록 점끝났거나 조용히 활성 — 결과를 검토합니다
빨간 점막힘·실패 — 필요하면 Restart 칩으로 다시 띄웁니다
회색 점끝난 뒤 오래 조용함(쉬는 중) — 필요할 때 살펴봅니다

기호의 뜻은 상태 표시 표와 같습니다.

  1. Cmd-J(macOS)로 팔레트 열기작업 이름 조각을 입력합니다. Enter는 이동, Shift-Enter는 화면을 나눠 열기. 목록이 크면 Tab으로 호스트·프로젝트를 거릅니다.
  2. 사이드바 훑기입력이 필요한 워크트리(주황 ?)부터 먼저 갑니다.
  3. Restart 칩으로 되살리기각 워크트리에서 끝난 에이전트를 다시 띄웁니다. 노트북이 잠든 뒤 한꺼번에 재개할 때 좋습니다.
  4. 종 알림 비우기계속 남아 있는 종(🔔) 아이콘으로 "agent finished"(에이전트 끝남) 알림을 하나씩 처리합니다. 알림을 클릭하면 그 워크트리로 이동합니다.
위생 관리병합된 워크트리는 과감하게 지우세요. 클릭 한 번이면 워크트리와 브랜치가 함께 사라집니다. 병합된 워크트리가 수십 개 쌓이면 팔레트만 느려집니다.
한눈에 정리
  • 워크트리 = 같은 저장소를 작업마다 다른 폴더에 꺼내 둔 것. 에이전트끼리 파일을 밟지 않아 병렬 작업이 안전합니다.
  • 일생: Create → Work → Review → Ship → Archive/Delete. 생성은 백그라운드, 출발점은 보통 기준 브랜치(base ref), 필요하면 로컬 브랜치·커밋·원격 브랜치.
  • gitignore된 파일은 Shared Paths·orca.yaml(공유) / .worktreeinclude(복사)로 채웁니다.
  • 사이드바: 프로젝트별 묶음, 숨기기 필터, 고정·다중 선택·자식 칩. 일괄 삭제 시 미병합 브랜치는 보존 후 검토.
  • 상태 기호: 돌아가는 원(작업) · 주황 ?(나를 기다림) · 초록(완료) · 빨강(실패) · 회색(쉬는 중). 끝나면 초록 → 오래 두면 회색. 대시보드는 실험 기능.
  • 에이전트는 묻지 않는 모드(Yolo, 권한 생략 플래그)가 기본 — 원치 않으면 Settings → Agents의 Agent permissions에서 Manual(매번 묻기)로.
  • 탭은 끌어서 분할, 레이아웃은 워크트리별 저장. 데몬 덕에 앱을 꺼도 에이전트는 계속, 재부팅 땐 레이아웃만 복원.
  • Cmd-P 파일, + 탭·파일·URL·웹 검색, Cmd-J 워크트리·탭 이동(macOS 키).

출처: onorca.dev/docs/model/worktrees · onorca.dev/docs/model/agents-sessions · onorca.dev/docs/model/tabs-panes-splits · onorca.dev/docs/model/session-restore · onorca.dev/docs/model/quick-open · onorca.dev/docs/recipes/jump-worktrees

CHAPTER 03

에이전트와 터미널 — 지원 에이전트, 채팅 UI, 기록, 사용량

Orca의 심장은 “코딩 에이전트를 터미널에서 돌리는 일”입니다. 이 장에서는 코딩 에이전트와 터미널이 무엇인지부터 시작해, Orca가 어떤 에이전트를 지원하고, 그 에이전트와 대화하는 두 가지 화면(터미널·채팅), 지난 대화 다시 열기, 쉬는 에이전트 재우기, 사용량 확인, 그리고 터미널의 모든 기능을 차례로 살펴봅니다.

이 장에서 배우는 것
  • 코딩 에이전트·터미널·CLI가 무엇이고, Orca가 둘을 어떻게 이어 주는지
  • Orca가 기본으로 지원하는 40여 개 에이전트와 통합 수준의 차이, 권한(Yolo/Manual) 기본값
  • Claude Code·Codex·Cursor CLI·GLM-5.2 각각의 설정과 특이사항, 계정 바꿔 끼우기(hot-swap)
  • 네이티브 채팅 UI(Chat UI)의 작성창·대기열·되감기·모델 선택 등 세부 기능
  • 에이전트 세션 기록(Agent Session History), 휴면(hibernation), 훅·메모리, 사용량·한도 추적
  • 터미널: 링크 동작, 검색, 테마, 기본 셸, 단축키, 플로팅 터미널, Quick Commands
처음이라면 이것만

에이전트별 특이사항, 계정 바꿔 끼우기, 사용량 공급자별 방식, 터미널 세부 설정은 필요할 때 찾아 읽으면 됩니다. 🔧 표시가 붙은 접힌 상자는 개발자용 참고라 처음엔 건너뛰어도 됩니다.

코딩 에이전트와 터미널, 먼저 쉽게 알기

한 줄 비유 터미널은 컴퓨터에게 글자로 명령을 내리는 “채팅창”이고, 코딩 에이전트는 그 채팅창 안에 들어와 앉은 “AI 개발 도우미”입니다. 여러분이 “로그인 버튼 고쳐 줘”라고 쓰면, 에이전트가 직접 파일을 열어 보고, 고치고, 테스트 명령을 실행합니다.

터미널(Terminal)이란

마우스로 아이콘을 누르는 대신, npm test처럼 글자로 명령을 입력해 컴퓨터를 움직이는 창입니다. 명령을 받아 실행해 주는 프로그램을 셸(shell)(터미널 안에서 명령을 알아듣고 실행하는 프로그램. zsh, bash, PowerShell 등)이라 부릅니다. 이렇게 글자 명령으로 쓰는 프로그램을 CLI(Command Line Interface — 버튼 화면 없이 글자 명령으로 쓰는 프로그램)라고 합니다.

코딩 에이전트(Coding Agent)란

Claude Code, Codex 같은 AI가 들어 있는 CLI 프로그램입니다. 일반 챗봇과 달리 내 컴퓨터의 코드를 읽고, 파일을 고치고, 명령을 실행할 수 있습니다. 대부분 터미널 안에서 돌아가는 글자 화면, 즉 TUI(Terminal User Interface — 터미널 안에 글자로 그린 화면)를 갖고 있습니다.

나 할 일을 말함 Orca 워크트리(작업용 복사본) · 탭 · 상태 표시 · 기록 · 사용량 터미널 탭 셸이 명령을 실행 $ claude ▍ 에이전트 CLI Claude Code, Codex … 파일 읽기·수정·실행 AI 모델 회사 서버(계정)
Orca는 에이전트를 “터미널 안에서 실행하는 프로세스”로 띄웁니다. 그 위에 상태 점, 기록, 사용량 같은 편의 기능을 얹어 줍니다.
핵심: Orca는 어떤 CLI 에이전트와도 함께 씁니다 Orca의 에이전트 선택 상자(agent combobox)는 결국 “터미널에 프로세스 하나를 띄우는” 일을 합니다. 그래서 목록에 없는 CLI 에이전트도 터미널에서 직접 실행하면 쓸 수 있습니다. 아래 표의 에이전트들은 여기에 더해 한 번 클릭으로 실행·설정되도록 미리 준비되어 있고, 일부는 더 깊은 기능(훅·상태·사용량·계정 전환)까지 지원합니다.

지원 에이전트 한눈에 보기

Orca의 기본 에이전트 선택기(built-in agent picker)에는 40여 개 에이전트가 미리 들어 있고, 모두 한 번 클릭으로 실행·설정됩니다. 그중 Orca 기능을 가장 많이 함께 쓰는 것은 깊은 통합이 붙은 아래 네 가지입니다. 어느 것을 고를지 모르겠다면 이 넷 중에서 시작하세요.

에이전트Orca에서 되는 것만든 곳
Claude Code깊은 통합 사용량 계정 전환, 훅, 계정별 폴더Anthropic
Codex깊은 통합 사용량 계정 전환OpenAI
Muse Code깊은 통합 훅 상태, 사용량 세션 기록Meta
Cursor CLI깊은 통합Cursor

표에 쓰인 표시의 뜻은 다음과 같습니다.

깊은 통합

사용량, 계정 전환, 훅 등 여러 기능을 깊이 연결한 에이전트(Claude Code, Codex, Muse Code, Cursor CLI).

자동 설정 Auto-setup

선택기에서 고르면 Orca가 알아서 실행 준비를 해 줍니다.

훅 · 상태

에이전트가 “작업 중 / 입력 대기 / 완료”를 Orca에 알려 탭·사이드바에 상태 점이 뜹니다.

네이티브 채팅

터미널 대신 Orca의 구조화된 채팅 화면으로 대화할 수 있습니다.

사용량

상태 표시줄에 사용량·한도까지 남은 정도를 보여 줍니다.

세션 기록 · 재개

지난 대화를 목록에서 찾아 그대로 이어갈 수 있습니다.

전체 목록 펼치기 — 기본 선택기의 에이전트 41개 (검색·필터)

기본 선택기에 들어 있는 에이전트 전체입니다. 이름으로 검색하거나 기능별로 걸러 볼 수 있습니다. 표에 나오는 낯선 이름 풀이:

  • 감독 작업자(supervised workers): 에이전트가 거느리는 작업자를 Orca가 함께 관리·표시해 준다는 뜻입니다.
  • 백그라운드 도우미를 행으로 표시: 에이전트가 뒤에서 돌리는 보조 작업이 목록에 한 줄씩 보인다는 뜻입니다.
  • 작업 공간 신뢰(workspace trust): Qoder CLI 행에 붙은 지원 항목 이름입니다. 원문에는 이름만 나옵니다.
  • dsh-tui 프로필: DeepSeek Harness를 실행할 때 Orca가 쓰는 실행 설정(profile)의 이름입니다. tui는 터미널 안 글자 화면(TUI)을 뜻합니다.
  • acli, traecli, qwen: 각각 Rovo Dev, Trae, Qwen Code를 찾거나 실행할 때 쓰는 실행 파일 이름입니다.
에이전트Orca에서 되는 것 (Notes)만든 곳
Claude Code깊은 통합 사용량 계정 전환(hot-swap), 훅, 계정별 폴더Anthropic
Claude Agent Teams기본은 꺼져 있음. Settings → Agents에서 켜면 orca claude-teams로 실행되고, 팀원(teammate)마다 Orca의 네이티브 패널이 하나씩 생깁니다Anthropic
Codex깊은 통합 사용량 계정 전환(hot-swap)OpenAI
Muse Code깊은 통합 훅 상태, 사용량 세션 기록Meta
Grok자동 설정, 네이티브 채팅(구조화)xAI
GitHub Copilot CLI자동 설정GitHub
OpenCode자동 설정, 상태, 계정 프로필, 네이티브 채팅(구조화). OpenCode 2 베타도 지원OpenCode
Pi자동 설정, 훅 상태, 네이티브 채팅(구조화). 백그라운드 도우미를 행으로 표시Pi
ZCode자동 설정, 훅 상태, 세션 재개, 사용량, 감독 작업자. 터미널 UI가 있는 zcode 빌드를 설치해야 함ZCode
DeepSeek Harness자동 설정, 훅 상태, 질문(questions), 세션 재개. dsh-tui 프로필로 실행DeepSeek
OMP자동 설정, 훅 상태, 네이티브 채팅(구조화). 백그라운드 도우미를 행으로 표시OMP
Prime Agent자동 설정, 훅 상태, 세션 기록Prime Intellect
Gemini자동 설정Google
Antigravity자동 설정, 훅 상태, 계정. 로컬 감독 작업자. IDE·2.0에서 하던 대화를 새 CLI 대화로 이어갈 수 있음Google
Ante자동 설정, 상태Ante
Aider자동 설정Aider
Goose자동 설정Block
Amp자동 설정Amp
Kilocode자동 설정Kilo
Kiro자동 설정, 상태, 세션 기록Kiro
Charm Crush자동 설정Charm
Auggie자동 설정Augment
Autohand자동 설정Autohand
Cline자동 설정Cline
CodeBuddy자동 설정, 훅 상태, 세션 기록. 설치: npm install -g @tencent-ai/codebuddy-codeCodeBuddy
Codebuff자동 설정Codebuff
Freebuff자동 설정, 상태Freebuff
Command Code자동 설정, 상태Command Code
Continue자동 설정Continue
Cursor CLI깊은 통합Cursor
Devin자동 설정, 계정 프로필Devin
Droid (Factory)자동 설정, 훅 상태Factory
Kimi자동 설정Moonshot
Mistral Vibe자동 설정Mistral
MiniMax자동 설정, 사용량 추적, 한도(rate-limit) 추적MiniMax
Qoder CLI자동 설정, 훅 상태, 작업 공간 신뢰(workspace trust), 세션 재개, 감독 작업자. Qoder CLI CN 포함Qoder
Qwen Code설치된 qwen 실행 파일로 자동 설정, 감독 작업자Qwen
Rovo Dev자동 설정. acli를 통해 감지Atlassian
Hermes자동 설정Nous
OpenClaw자동 설정OpenClaw
Traetraecli(TRAE CN CLI)로 자동 설정Trae

권한 기본값 — 왜 “확인 없이” 실행할까

코딩 에이전트는 보통 명령을 실행하기 전에 “이거 실행해도 될까요?”라고 매번 묻습니다. 예를 들어 파일을 지우거나 고치기 전에 “이 파일 지워도 될까요? [예/아니오]” 같은 확인 창을 띄우는 식입니다. Orca는 새로 실행하는 에이전트에 이 확인을 건너뛰는 옵션(flag(프로그램을 실행할 때 명령 뒤에 붙이는 켜기/끄기 스위치. 예: --yolo))을 미리 붙여 둡니다. 이런 “확인 없이 실행” 상태를 흔히 Yolo라고 부릅니다.

“파일 지워도 될까요?” [예] [아니오] — 매번 물음 Manual 매번 확인 일상적인 동작은 에이전트가 스스로 승인 Auto 지원 에이전트만 말풍선 없음 묻지 않고 바로 실행 Yolo 확인 생략 · 터미널 기본값 ← 확인을 많이 함 (느리지만 하나하나 봄) 확인 없이 진행 (빠름) → 세 가지는 Claude·Codex 새 세션에서 선택 · Auto가 없는 에이전트는 Manual/Yolo
권한 모드는 “확인 말풍선이 얼마나 자주 뜨는가”의 차이입니다. Orca는 새 터미널 에이전트를 오른쪽 끝(Yolo)으로 실행합니다.

무엇이 위험할까

확인을 건너뛰면 에이전트가 파일을 고치거나 지우는 셸 명령도 여러분에게 묻지 않고 바로 실행합니다. 잘못된 명령이 있어도 중간에 막을 기회가 없습니다.

그래도 괜찮다고 보는 이유

에이전트는 원본이 아니라 자기 전용 워크트리(버려도 되는 작업용 복사본)에서 일합니다. 결과는 원본에 합치기(병합) 전에 사람이 보고 마음에 드는 것만 골라 담거나 통째로 버릴 수 있습니다.

원본 저장소 main 브랜치(기본 갈래) 에이전트 전용 워크트리 (버려도 되는 작업용 복사본) Yolo로 자유롭게 실험 사람이 검토 골라 담기 · 버리기 → 그 뒤에 병합
이유: 워크트리는 일회용입니다. 에이전트가 자기만의 복사본에서 일하므로 셸 명령마다 다시 확인하지 않아도 되고, 병합 전에 변경분을 골라 담거나(cherry-pick) 버릴 수 있습니다.
용어 풀이 워크트리(worktree)(같은 프로젝트를 다른 폴더에 하나 더 펼쳐 놓은 “연습장”), 브랜치(branch)(프로젝트의 작업 갈래. main은 보통 기본 갈래), 체리픽(cherry-pick)(변경 중 마음에 드는 것만 골라 가져오기), 병합(merge)(작업 결과를 원본 갈래에 합치기).
에이전트별로 미리 붙는 옵션 이름
에이전트미리 채워지는 옵션
Claude--dangerously-skip-permissions
Codex--dangerously-bypass-approvals-and-sandbox
Gemini · Cursor · Crush · Kimi · Rovo Dev · Hermes · GitHub Copilot · Command Code--yolo
그 밖의 에이전트같은 역할을 하는 옵션이 있으면 그것

권한 모드 바꾸기

  1. 전체 전환: Settings → Agents → Agent Permissions따로 손대지 않은(uncustomized) 터미널 에이전트 실행을 Yolo(확인 없이)와 Manual(매번 확인) 사이에서 한 번에 바꿉니다.
  2. Claude·Codex 새 세션의 기본값같은 곳에서 새 Claude·Codex의 터미널 세션과 구조화 채팅 세션 기본값도 정합니다. 이미 열린 채팅은 자기 모드를 그대로 유지합니다.
  3. 한 에이전트만 다시 묻게 하기Settings에서 그 에이전트의 기본 인수(arguments)나 환경 변수(environment)(프로그램이 시작할 때 읽어 가는 이름=값 설정)를 직접 고칩니다.

직접 고친 에이전트 설정은 전체 전환 스위치가 건드리지 않습니다. 구조화 채팅에서는 Manual · Auto · Yolo 세 가지 중 고를 수 있습니다(뒤의 네이티브 채팅 참고).

직접 고친 설정이 보호되는 규칙

어떤 에이전트의 실행 인수나 환경 변수를 이미 직접 바꿔 두었다면, 전체 전환 스위치가 그 명령을 지우지 않도록 Orca는 그 에이전트를 그대로 둡니다. 비어 있지 않은 사용자 값은 “명시적 덮어쓰기”로 취급되어, 이후 권한 모드 일괄 변경(migration)에서도 빠집니다.

에이전트별 특이사항

깊게 통합된 에이전트 셋과, 다른 회사 모델(GLM-5.2)을 끼워 쓰는 방법을 탭으로 나눠 봅니다. 탭마다 설치 → 로그인 → 실행 세 단계만 알면 충분하고, 버전별 예외나 설정 파일 내용은 접힌 참고 상자에 모아 두었습니다.

Claude Code — Anthropic의 에이전트 CLI

Orca가 정식으로 지원하는(first-class) 터미널 에이전트입니다. 어느 계정인지 알아보고 시작하고, 사용량을 보여 주고, 계정을 한 번 클릭으로 바꿔 끼울 수 있습니다.

흐름: 설치 → 한 번 로그인 → Orca에서 고르기. Anthropic 안내대로 설치하고, 아무 터미널에서 한 번 로그인하면 Orca가 내 사용자 폴더(~ 표시가 뜻하는 곳 — macOS라면 /Users/내이름 같은 내 개인 폴더) 안의 Claude 설정을 알아서 읽습니다. 추가 설정은 필요 없습니다. 그다음 워크트리에서 터미널을 열고 에이전트 선택 상자에서 Claude Code를 고르면, 탭에 “작업 중 / 입력 대기 / 완료” 상태 점이 뜹니다.

Claude Code 세부 — 설치 명령, 상태 훅, 사용량, 계정 전환, 서브에이전트

설치 명령: npm i -g @anthropic-ai/claude-code 또는 Anthropic 문서를 따릅니다. 로그인 후 Orca는 ~/.claude를 자동으로 읽습니다.

실행: Orca는 워크트리를 작업 폴더로 삼아 실행하고, 상태 줄 훅(status-line hook)을 함께 넣습니다. 이 훅이 내보내는 OSC 제목 이벤트(터미널 프로그램이 터미널에게 보내는 특수 신호. 여기선 창 제목을 바꾸는 신호)로 Orca가 상태 점(state dots)을 그립니다.

사용량·한도: 로컬 ~/.claude 사용량 상태를 읽어 현재 사용량과 한도에 얼마나 가까운지를 상태 표시줄에 보여 줍니다(사용량 절).

계정 hot-swap: 여러 Claude 계정을 한 번 클릭으로 바꿉니다(Codex와 같은 흐름). Claude 세션이 돌고 있어도 바꿀 수 있는데, 전환이 진행되는 동안에는 인증 갱신이 서로 겹치지 않도록 막아 둡니다. 바꿔도 공유 MCP 서버(에이전트에 도구를 붙여 주는 외부 서버, Model Context Protocol) 로그인은 유지되어 다시 인증할 필요가 없습니다.

서브에이전트와 팀: 백그라운드 서브에이전트와 Agent Teams 팀원이 워크트리 에이전트 목록과 Agent Dashboard에서 리드 에이전트 아래 펼칠 수 있는 하위 행으로 보입니다. 하위 행을 고르면 리드 터미널에 그 대화 기록이 보이고, 부모를 고르면 돌아옵니다. 지금 보이는 기록에는 눈(👁) 표시가 붙습니다. Claude 상태 훅이 있으면 기본으로 켜져 있으며, 리드 터미널을 그대로 보고 싶으면 Settings → Agents → Claude subagent navigation에서 끕니다. 설정을 바꾼 뒤에는 새 Claude 세션을 시작해야 적용됩니다.

훅·메모리: 저장소별 훅과 메모리 파일을 지원하며 훅·메모리 절에서 다룹니다.

Codex — OpenAI의 에이전트 CLI

Orca에서 가장 깊이 통합된 에이전트 중 하나입니다. 사용량을 보거나, 계정을 바꾸거나, 다시 실행해도 어느 계정으로 돌던 것인지가 그대로 이어집니다.

흐름: 설치 → 로그인 → Orca에서 고르기. OpenAI 안내대로 설치하고 아무 터미널에서 로그인하면, Orca가 내 사용자 폴더(~ — 내 개인 폴더) 안의 Codex 로그인 정보를 읽어 계정을 알아봅니다. 선택 상자에서 Codex를 고르면 지금 고른 계정으로 실행되고, Codex가 끝나면 재시작 칩(다시 실행 버튼)이 같은 계정으로 다시 실행해 줍니다.

Codex 세부 — 로그인 폴더·작업 폴더, System default·추가 계정, 0.157 이상 버전 예외, 탭별 서버

Orca는 ~/.codex에서 계정과 자격 증명을 읽고, 실행할 때 워크트리를 작업 폴더(cwd)로 삼아 지금 고른 계정으로 인증을 보냅니다.

System default와 추가 계정

System default는 실제 ~/.codex 로그인(Orca 밖에서 그냥 codex를 쳤을 때 쓰는 그 홈)입니다. Orca가 관리하는 추가 계정은 Orca 계정 데이터 아래 각자의 홈을 가져 자격 증명과 기록(rollouts)이 섞이지 않습니다. 새 Codex 실행은 활성 계정을 따르고, 이미 돌고 있는 세션은 재시작할 때까지 시작할 때의 홈을 유지합니다.

Codex 0.157 이상

  • Orca 관리 계정의 홈 경로가 너무 길어 Codex 백그라운드 데몬 소켓에 못 쓰면, Orca가 그 홈에서 데몬을 꺼서 Codex가 시작되게 합니다. 선택기로 실행하든 Orca 터미널에 codex를 직접 치든 같습니다. 계정 데이터는 그대로이고 시스템 ~/.codex/config.toml은 바꾸지 않습니다.
  • 그런 홈에서는 codex agents와 데몬 기반 resume/continuation을 쓸 수 없습니다. 그래도 path must be shorter than SUN_LEN 오류가 나면 Troubleshooting 문서를 보세요.

Codex 터미널마다 자기 서버

0.157 이상에서는 Orca 터미널의 Codex 탭마다 자기 백그라운드 서버를 기본으로 돌립니다. 탭마다 상태가 정확해지고, 한 탭을 닫아도 다른 탭이 끊기지 않습니다. 새로 연 터미널부터 적용되며, 업데이트 때 이미 열려 있던 터미널은 다시 열 때까지 예전 방식입니다.

  • 대가: 탭별 서버에서는 Codex의 공유 서버 기능(백그라운드 실행, codex agents, Codex 데스크톱 앱이나 IDE에서 연 세션)이 Orca에서 시작한 세션을 보지 못합니다.
  • 공유 서버로 바꾸려면: 새 터미널을 열기 전에 Settings → Agents → Run each Codex terminal on its own server를 끄거나, ORCA_CODEX_ISOLATE=0을 설정합니다(예: 셸 시작 파일에 export ORCA_CODEX_ISOLATE=0). 그러면 Codex의 agents 개요를 다시 쓸 수 있습니다.

직접 시작한 Codex가 공유 서버에 붙으면 그 탭 위쪽에 안내가 뜹니다. Fix를 누르면 공유가 꺼지고, 업데이트 전에 연 탭이라면 대신 새 터미널을 열자고 제안합니다.

Codex 세부 — Task 서브에이전트, 넘겨주기, 재시작 칩, 사용량
  • Task 서브에이전트: Codex가 만든 Task 서브에이전트가 워크트리 에이전트 목록과 Agent Dashboard에서 부모 아래 하위 행으로 보입니다. 꺾쇠(chevron)를 펼쳐 보고, 하위 행을 누르면 부모 터미널로 초점이 갑니다(서브에이전트는 따로 패널을 갖지 않음).
  • Hand Off to Another Agent: 에이전트 터미널 머리글이나 우클릭 메뉴에서 고르면, 같은 또는 다른 CLI로 새 세션을 시작하고 이전 대화 기록이나 수집된 맥락에서 만든 분량이 제한된 인계 프롬프트를 넣어 줍니다. 원래 세션은 그대로이며, codex resume과는 다릅니다.
  • 재시작 칩(restart chip): Codex가 끝나면 이 칩이 같은 계정으로 다시 실행합니다. 중간에 계정을 바꿨고 새 계정으로 재시작하고 싶다면 계정 전환기를 먼저 쓰고 재시작하세요.
  • 사용량: 활성 계정의 로컬 Codex 사용량을 상태 표시줄에 보여 줍니다.
Windows(WSL)에서의 Codex
  • Windows의 Codex도 macOS·Linux처럼 실제 ~/.codex 홈을 씁니다. 업데이트 후 처음 Codex 터미널이 뜰 때 한 번 안내가 나옵니다: Codex가 폴더 신뢰나 명령 승인을 다시 물을 수 있고, Orca 안에서만 추가했던 MCP 서버는 다시 추가해야 합니다. 이미 열려 있던 Codex 터미널은 다시 열 때까지 이전 홈으로 돕니다.
  • Windows에서는 호스트 설치본이나 WSL 배포판(distro)(WSL은 Windows 안에서 리눅스를 돌리는 기능, 배포판은 설치된 리눅스 종류) 중 어디의 Codex를 쓸지 고를 수 있습니다. 계정 전환기에서 WSL Codex 계정을 추가하면, Orca가 배포판 안에 격리된 홈(~/.local/share/orca/codex-accounts/<id>/home)을 만들고, 인증을 읽을 수 있게 호스트에서 \\wsl.localhost\<distro>\... 경로로 연결하며, 실행·hot-swap·한도 조회를 그 배포판을 거쳐 보냅니다.
  • 대상 배포판에 Codex가 없으면 Add account 창이 어느 배포판에 실행 파일이 없는지 알려 주는 메시지와 함께 실패합니다.

Cursor CLI — Cursor의 명령줄 에이전트

선택 상자에서 실행, 상태 점 표시, 끝났을 때 재시작 칩까지 정식으로 지원합니다.

흐름: 설치 → 한 번 로그인 → Orca에서 고르기. Cursor 안내대로 Cursor CLI를 설치하고 한 번 로그인하면 Orca가 설치된 프로그램을 스스로 찾아냅니다. 선택 상자에서 Cursor를 고르면 그 워크트리 안에서 실행되고 탭에 상태 점이 뜹니다.

Cursor CLI 세부 — 감지 방식, 상태 신호

Orca는 PATH(셸이 실행 파일을 찾아보는 폴더 목록)에서 CLI를 찾아냅니다. Cursor의 TUI가 상태 점에 필요한 신호(OSC 상태 이벤트(터미널 프로그램이 터미널에게 보내는 특수 신호))를 보내 줍니다.

모델 선택: Cursor 자체 설정을 따릅니다. Orca는 덮어쓰지 않으니 CLI 안에서 설정하세요.

사용량: 기존 Cursor 로그인으로 플랜 사용량을 상태 표시줄과 Settings → Accounts → Cursor에 보여 줍니다.

GLM-5.2를 Orca에서 쓰기

Orca 워크트리·터미널·리뷰 하네스(에이전트 프로그램) Claude Code · OpenCode · OpenClaw … 기본 모델 GLM-5.2 Z.ai CodePlan 구독 껍데기(하네스)는 그대로 두고, 안의 두뇌(모델)만 바꿔 끼웁니다
GLM-5.2는 새 에이전트가 아니라 하네스 안에 끼우는 모델입니다.

GLM-5.2는 따로 “에이전트”가 있는 게 아니라, 이미 쓰는 에이전트의 두뇌(모델)만 바꿔 끼우는 방식입니다. 이때 바깥 껍데기 프로그램을 하네스(harness)(모델을 감싸 파일 읽기·명령 실행을 맡는 에이전트 프로그램. 예: Claude Code, OpenCode)라고 부릅니다. Claude Code, OpenCode, Cline, Kilo Code, Roo Code, Droid, OpenClaw 등에 GLM-5.2를 설정한 뒤 Orca 선택기에서 그 에이전트를 실행하면 됩니다. Orca는 워크트리·터미널 패널·브라우저 탭·리뷰 흐름·세션 관리를 주고, 모델 접근은 Z.ai CodePlan 구독과 에이전트 설정이 맡습니다.

먼저 필요한 것GLM Coding Plan 접근이 있는 활성 Z.ai CodePlan 구독이 필요합니다. OpenAI 호환 하네스는 Z.ai API 키도 필요합니다. Orca는 GLM 접근을 포함하거나 재판매하지 않습니다. 이 설정은 Z.ai의 최신 모델 가이드를 따르므로, 공급자 쪽 세부 사항은 그 페이지를 확인하세요.

설정 방법은 하네스마다 다릅니다: Claude Code는 설정 파일에 모델 이름 몇 줄을 넣고, OpenCode 등 OpenAI 호환 하네스는 설정 화면에서 주소·키·모델 이름을 입력하고, OpenClaw는 설정 파일에 모델을 직접 추가합니다. 자세한 값은 아래 접힌 상자에 있습니다.

핵심 규칙하네스가 공급자·모델 설정을 저장하는 곳에 GLM-5.2를 설정하고, 그 하네스를 Orca가 올바른 워크트리에서 실행하게 두면 됩니다.
① Claude Code에 GLM-5.2 설정 (settings.json)
  1. ~/.claude/settings.json 열기Claude Code는 여기서 모델 덮어쓰기를 읽습니다.
  2. 아래 env 블록 추가·수정
  3. Orca의 Claude Code 세션 재시작새 환경 변수를 불러오기 위해서입니다.
  4. /status 실행Claude Code 안에서 활성 모델을 확인합니다.
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
  }
}
  • [1m] 접미사는 GLM-5.2의 100만 토큰 문맥(context) 버전을 뜻합니다. 이때 CLAUDE_CODE_AUTO_COMPACT_WINDOW를 1000000으로 두어 Claude Code의 압축(compaction) 창 크기를 맞춥니다.
  • Claude Code가 [1m] 모델이 없다고 하면 Claude Code를 업데이트한 뒤 다시 시도합니다.
  • 코딩 작업에는 Z.ai가 /effort로 effort를 max로 두길 권합니다. Claude Code의 낮은 effort 설정은 GLM-5.2의 high로, xhigh·max·ultracode는 GLM-5.2의 max로 연결됩니다.
② OpenAI 호환 하네스 (OpenCode, Cline, Kilo Code, Roo Code, Droid)

OpenCode, Cline, Kilo Code, Roo Code, Droid처럼 OpenAI 호환 공급자를 지원하는 하네스:

  1. 하네스 설정 열기Orca 안이든 밖이든 상관없습니다.
  2. 공급자 선택OpenAI 호환(OpenAI-compatible) 공급자, 또는 Z.ai 공급자 항목이 있으면 그것을 고릅니다.
  3. Base URLhttps://api.z.ai/api/coding/paas/v4
  4. Z.ai API 키 입력
  5. 사용자 지정 모델 이름glm-5.2
  6. 문맥 창 크기입력란이 있으면 1000000.
  7. 이미지 지원 끄기그 하네스가 이 공급자 경로의 이미지 지원을 명시하지 않는 한 끕니다.

저장한 뒤 Orca 에이전트 선택기에서 실행하면, Orca가 같은 설정의 CLI를 선택한 워크트리에서 돌립니다.

③ OpenClaw에 GLM-5.2 추가 (openclaw.json)

OpenClaw가 공급자 모델 목록에서 GLM-5.2를 바로 고르지 못하면 ~/.openclaw/openclaw.json에 직접 추가합니다.

① models.providers.zai.models에 glm-5.2 추가

{
  "id": "glm-5.2",
  "name": "GLM-5.2",
  "reasoning": true,
  "input": ["text"],
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
  "contextWindow": 1000000,
  "maxTokens": 131072
}

② 기본 주 모델 지정

{ "model": { "primary": "zai/glm-5.2", "fallbacks": ["zai/glm-4.7"] } }

③ agents.defaults.models에 모델 추가

{ "models": { "zai/glm-5.2": { "alias": "GLM" }, "zai/glm-4.7": {} } }

④ 게이트웨이 재시작 — openclaw gateway restart

⑤ 확인 — Orca에서 OpenClaw를 실행하거나 Orca 터미널에서 openclaw tui를 실행해 GLM-5.2가 활성인지 봅니다.

계정 바꿔 끼우기 (Hot-swap Codex · Claude 계정)

AI는 쓴 양을 토큰(AI 사용량을 세는 단위. 글자 조각 하나하나를 셉니다)으로 세고, 계정마다 쓸 수 있는 양에 한도가 있습니다. 그래서 넉넉히 쓰려고 Codex 계정을 여러 개 쓰는 경우가 흔합니다. Orca에서는 다시 로그인하지도, 설정 파일을 고치지도 않고 한 번 클릭으로 활성 계정을 바꿉니다. Claude Code 계정도 데이터 폴더만 ~/.claude로 다를 뿐 똑같이 동작합니다.

원리는 간단합니다. Orca는 “지금 쓸 계정”을 가리키는 표시, 즉 자격 증명 포인터(여러 로그인 정보 중 지금 쓸 계정을 가리키는 화살표 같은 표시)만 옮깁니다. 로그인 정보 자체는 건드리지 않으므로 다시 로그인할 필요가 없습니다.

계정 전환기 System default work ✓ personal 자격 증명 포인터 지금 쓸 계정을 가리킴 새로 실행한 Codex → 지금 활성 계정(work)을 사용 이미 돌던 Codex → 재시작 전까지 원래 계정 유지
전환은 즉시입니다. Orca는 다시 로그인하지 않고 “지금 쓸 계정”을 가리키는 표시(포인터)만 바꿉니다. 이미 돌던 세션은 다시 시작할 때까지 원래 계정을 씁니다.

1단계 · 각 계정에 한 번씩 로그인

터미널에서 각 Codex 계정으로 적어도 한 번 로그인해, 인증 정보가 ~/.codex 아래에 남게 합니다.

2단계 · Settings → Agents → Codex Accounts

Orca가 감지한 계정을 사용량·현재 한도와 함께 모두 보여 줍니다.

3단계 · 친근한 이름 붙이기

각 계정에 “personal”, “work” 같은 이름(label)을 붙입니다.

4단계 · 상태 표시줄의 Codex 칩 클릭

계정 전환기가 열립니다. 계정을 고르면 그 뒤에 실행하는 새 Codex 세션이 그 계정을 씁니다. 이미 돌고 있는 세션은 재시작할 때까지 원래 계정을 씁니다.

System default 행은 Orca 밖 터미널에서 그냥 codex를 쳤을 때 쓰는 원래 로그인입니다.

System default 행과, 설정을 고쳤는데 무시되는 것 같을 때

System default 행

~/.codex에 있는 현재 호스트의 Codex 로그인입니다. Orca에서 추가한 관리 계정은 이 로그인을 다시 쓰지 않고 격리된 홈에서 돕니다. Orca 밖 터미널의 codex와 똑같이 실행하고 싶으면 System default를 고르세요.

설정을 고쳤는데 무시되는 것 같을 때

관리 계정에서는 Orca가 실제 ~/.codex/config.toml의 설정을 활성 실행 홈으로 복사(mirror)합니다. 원본이 없거나, 비었거나(예: 클라우드 동기화가 아직 내려받는 중), 읽을 수 없으면 Accounts에 경고가 뜨고, Codex는 마지막으로 성공한 설정을 계속 씁니다. 배너에 적힌 경로의 파일을 고친 뒤 다시 실행하거나 계정을 다시 고르세요.

규칙과 함정
  • 전환은 즉시입니다 — 활성 자격 증명 포인터만 바꾸고, 다시 인증하지 않습니다.
  • 이미 실행 중인 Codex 프로세스는 재시작할 때까지 현재 계정을 유지합니다.
  • 상태 표시줄 사용량은 현재 활성 계정을 따라갑니다.
  • 재시작 칩은 재시작하는 그 순간의 활성 계정을 씁니다.

네이티브 채팅 UI (Chat UI)

터미널의 글자 화면 대신, 메신저처럼 대화 기록 + 작성창(composer)으로 에이전트와 이야기하는 선택형 화면입니다. 구조화된 대화 기록, 스킬, 모델 선택, 답변 안 그림(inline visuals)을 지원합니다. 아래에서 자주 나오는 턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례)은 대화의 한 차례를 뜻합니다. 같은 부탁을 두 화면에서 하면 이렇게 보입니다.

같은 요청: “로그인 버튼 고쳐 줘” 터미널(CLI) 화면 $ claude > 로그인 버튼 고쳐 줘 · src/login.ts 읽는 중… · src/login.ts 고침 (+6 −2) · 테스트 실행… > ▍ 글자가 위에서 아래로 계속 흘러감 채팅(Chat UI) 화면 로그인 버튼 고쳐 줘 ☑ 계획: ✓원인 ◻수정 ◻테스트 src/login.ts +6 −2 (diff 카드) [모델 ▾] [effort ▾] 메시지 입력… 말풍선·체크리스트·카드로 정리돼 보임
왼쪽은 터미널(CLI) 화면, 오른쪽은 채팅 화면입니다(화면 흉내). 일하는 에이전트는 같고, 보여 주는 방식만 다릅니다.
Claude Chat — 로그인 버그 수정
로그인 버튼이 두 번 눌리는 문제 고쳐 줘 · @src/login.ts
☑ 계획 (에이전트가 만든 할 일 목록)
✓ 원인 찾기   ◻ 수정하기   ◻ 테스트
▸ 생각과 도구 호출 4개 (펼치기)
src/login.ts +6 −2 — 인라인 diff 카드
대기 중 메시지: “끝나면 README도 고쳐 줘” · Steer · 편집 · 삭제
claude-opus ▾effort: high ▾◔ 문맥 42%메시지 입력… / 로 명령, @ 로 파일

에이전트마다 Chat(채팅 화면) 또는 CLI(터미널)를 고릅니다. Chat을 고르면 자격이 되는 새 세션이 Orca의 구조화 네이티브 채팅으로 열립니다. 세션 상태를 Orca가 갖고 있으므로, 앱을 다시 켜도 탭과 대화가 복원됩니다.

  • 구조화 채팅 대상: Claude, Codex, Grok, OpenCode(2.x 포함), Pi, OMP, Antigravity.
  • 설정 위치: Settings → Chat UI 또는 Settings → Agents. 에이전트별로 고르고, 따로 고르지 않은 에이전트를 위한 기본값도 정할 수 있습니다.
  • 새로 설치하면 기본은 Terminal입니다.
  • WSL(Windows 안에서 리눅스를 돌리는 기능)·SSH(다른 컴퓨터에 원격으로 접속해 명령을 내리는 방식) 세션은 터미널을 바탕으로 한 Chat UI를 씁니다.
Chat/CLI 선택의 세부 규칙
  • 구조화 구현이 없는 에이전트와 WSL·SSH 세션은 터미널 기반 Chat UI를 씁니다.
  • 기존 사용자는 원래 실행 설정을, 기존 대화는 원래 화면을 유지합니다.
  • 에이전트별 선택은 데스크톱에서 시작하는 모든 경우(CLI, 오케스트레이션, 휴대폰에서 중계된 실행 포함)에 적용됩니다.
  • 탭 우클릭 메뉴나 Agent Session History에서 지원되는 대화를 채팅↔터미널로 옮길 수 있습니다.
  • 어디서 되나: 내 컴퓨터(macOS·Linux·Windows)와, 짝지은 Orca Server가 맡은 워크트리.
  • 모양: Settings → Chat UI에서 글꼴·크기·폭·대비를 정하고, Match terminal interface로 터미널과 같은 모양을 쓸 수 있습니다.
  • Inline visuals: 켜면 에이전트가 답변 안에 차트·다이어그램·목업을 그립니다.
  • 권한 모드: Manual · Auto · Yolo 중 고릅니다(권한 기본값의 그림 참고).
  • Orca가 재시작돼 끊긴 채팅은 다시 연결될 때 이어서 하자고 제안합니다.
구조화 채팅 세부 — 셸 환경 변수, 실행 명령, Codex Ask, Antigravity, 끊긴 채팅
  • 어디서 되나: 로컬 macOS·Linux·네이티브 Windows의 자격 있는 세션, 그리고 짝지은(paired) Orca Server가 소유한 워크트리. WSL·SSH는 터미널 기반 Chat UI를 계속 쓰고, 구조화 구현이 없는 에이전트는 터미널에 머뭅니다. 기존 터미널 세션은 터미널 세션으로 남습니다.
  • Use your shell environment: 새로 열거나 재개하는 구조화 채팅에 넘길 환경 변수(프로그램이 시작할 때 읽어 가는 이름=값 설정)를 정합니다. 기본으로 켜져 있어 로그인 셸의 export 값을 받습니다. 끄면 PATH(실행 파일을 찾는 폴더 목록), 로캘(언어·지역 설정), SSH_AUTH_SOCK(SSH 로그인 열쇠를 찾는 위치) 같은 기본 셸 변수에 더해 고른 변수 이름만 허용합니다. 터미널 기반 채팅은 계속 터미널 셸을 씁니다.
  • 실행 명령: 구조화 채팅은 Settings → Agents에 저장된 그 에이전트의 Command·Arguments로 실행됩니다.
  • 모양: Settings → Chat UI에서 채팅 글꼴, 글자 크기, 코드 크기, 폭, 대비를 정합니다. Match terminal interface를 켜면 터미널의 글꼴·색(이후 테마 변경 포함)을 따라갑니다.
  • Inline visuals: 같은 화면 설정에서 켜면 에이전트가 답변 안에 차트·다이어그램·목업을 그릴 수 있습니다(데스크톱·휴대폰). 넓게 보려면 그림을 따로 탭으로 열 수 있고, Mermaid 다이어그램은 다크 모드에서 채팅 테마를 따릅니다.
  • 권한 모드: Settings → Agents에서 새 Claude·Codex 터미널·구조화 채팅 세션의 기본값을 Manual · Auto · Yolo 중 고릅니다. Auto는 지원 에이전트가 일상적인 동작을 스스로 승인하게 합니다. Auto를 지원하지 않는 에이전트는 Other agents에서 Manual 또는 Yolo를 고릅니다. 기본값을 바꾸거나 모델을 바꿔도 기존 채팅은 자기 모드를 유지합니다.
  • Codex Ask 모드: Codex가 편집을 요청할 때까지 워크트리 접근을 읽기 전용으로 둡니다. 요청을 승인하면 편집이 진행됩니다. 필요하면 처음부터 Approve for me나 Full access로 시작하세요. 권한 선택은 다음 턴부터 적용되고, 이미 돌고 있는 작업은 시작할 때의 권한을 유지합니다.
  • Antigravity 채팅: 자체 채팅 서버를 씁니다. 채팅을 돌릴 호스트에 서버가 없으면 Providers 행이나 채팅의 설치 카드에서 Install을 누른 뒤, 그 서버의 Google 로그인으로 로그인합니다. 실행 환경(runtime)은 Install을 누른 뒤에만 내려받습니다. 설치된 Providers 행의 Remove로 지우면 그 호스트의 Antigravity 채팅이 멈추지만 기록은 남습니다.
  • 재시작으로 끊긴 채팅: 다시 연결될 때 이어서 하자고 제안합니다. 창을 닫았다가 상태 표시줄의 chats to resume 항목에서 나중에 열 수 있고, 이을 채팅이 없으면 항목이 사라집니다. 직접 닫은 채팅 탭은 오른쪽에 다시 나타나지 않습니다.
보내기 · 멈추기 · 첨부

메시지를 보내거나 진행 중인 턴을 멈춥니다. 호스트(에이전트가 실제로 돌아가는 컴퓨터 — 내 컴퓨터나 짝지은 서버)가 지원하면 파일·이미지를 첨부합니다. 파일 트리나 바탕화면에서 작성창(또는 채팅 화면 아무 곳)으로 끌어다 놓으면 에이전트가 읽을 수 있는 경로로 추가됩니다. 첨부 파일은 파일 이름 알약(pill)으로 보입니다.

이미지 붙여넣기 (Codex)

업데이트된 로컬 Codex 채팅에서는 앱 메뉴나 클립보드로 이미지를 붙여넣습니다. 보내기 전 지울 수 있는 썸네일로 보이고, 눌러서 크게 볼 수 있습니다.

끊겨도 남는 초안

보내지 않은 글과 첨부는 호스트가 복원할 수 있으면 연결이 끊겼다 이어져도 남습니다. 같은 세션이 재연결되는 동안 이미 끝난 대화 기록도 화면에서 지워지지 않습니다(데스크톱·모바일 공통).

@ 파일 고르기

초안에 @를 치면 워크트리 파일을 골라 경로로 넣습니다. 모바일 Chat UI에도 같은 팝오버가 뜹니다.

찾기 · 인용 · 이전 프롬프트

Cmd+F(macOS) / Ctrl+F(Windows·Linux)로 채팅 내 검색. 답변 일부를 선택하고 Add to chat으로 작성창에 인용. 빈 초안에서 ↑/↓로 보냈던 모든 프롬프트를 불러옵니다.

숫자 키로 답하기

에이전트가 번호 선택지가 있는 질문을 하면 숫자 키로 답하고, 다음 질문으로 넘어갑니다.

분할 · 이동

패널 동작으로 Chat UI를 나누거나 다른 패널로 옮겨도 같은 세션이 유지됩니다.

diff 카드 · 링크

에이전트의 파일 수정은 인라인 diff 카드로 보입니다. 대화 속 파일 경로·링크를 누르면 Orca에서 열립니다.

복사

답변 속 코드 상자(펜스 코드 블록(답변 안에 테두리로 따로 묶여 보이는 코드 부분))와 셸 명령은 문법 강조되고 블록마다 Copy code 버튼이 있어 코드만 복사합니다. 데스크톱에서 보낸 메시지에 마우스를 올리면 타임스탬프 옆 버튼으로 복사합니다.

대기열(Queue)과 끼어들기(Steer)

에이전트가 작업 중인 턴 끝나면 대기열을 보냄 새 메시지 작성 작업 중에 보냄 대기 카드 편집·삭제·순서 끌기 Steer(끼어들기) 지금 턴에 바로 넣기 Enter Cmd/Ctrl+Enter
기본값: 작업 중 Enter로 보낸 메시지는 작성창 위 카드로 줄을 섭니다. 턴이 끝나면 전송되며, 그 전에 Steer·편집·삭제할 수 있습니다.
대기열 세부 — 편집, 기본 동작 뒤집기, 모바일
  • 대기 메시지는 에이전트가 질문하는 중에도 그 자리에서 편집할 수 있고, 이미지·스킬·@파일을 포함한 전체 작성창으로 고칩니다. 카드는 끌어서 순서를 바꿉니다. 모바일 작성창 위에도 같은 카드가 보입니다.
  • Cmd+Enter / Ctrl+Enter는 진행 중인 턴에 바로 보냅니다. 기본 동작을 뒤집으려면 Settings → Chat UI → Behavior → Queue follow-ups를 끕니다.
  • 모바일에서는 Send를 길게 눌러 Queue/Steer를 고르고, 짧게 누르면 호스트 설정을 따릅니다. 대기열을 모르는 예전 클라이언트·호스트는 바로 보냅니다.

멈추기 · 전송 상태 · 되감기

Stop진행 중인 턴을 끝냅니다.
Sending…보내는 중. 상대(호스트)가 받았다고 확인할 때까지 이렇게 보입니다.
Not sent보내지 못했음. 이유가 함께 나오고 Retry로 다시 보냅니다.
미확인(unconfirmed)보냈는지 확실치 않을 때, 같은 메시지가 두 번 가는 것을 막으려고 “미확인”으로 둡니다.
Rewind to here대화를 그 메시지 시점으로 되돌리고, 그 메시지를 작성창에 돌려놓아 고쳐 다시 보내게 합니다.
멈추기·전송 상태·되감기 세부
  • Stop은 턴을 끝냅니다. Claude는 백그라운드 명령과 서브에이전트까지 포함한 프로세스를 끝냅니다. Codex가 멈춤 요청을 거부하거나 답하지 않으면 Orca가 끝냅니다.
  • “보내지 않았다”고 표시된 메시지는 Retry를 누르기 전까지 보내지지 않고, Steer로 넣은 메시지는 다시 보내지 않습니다.
  • 나가는 메시지는 호스트가 확인할 때까지 Sending…, 실패하면 이유와 함께 Not sent로 표시됩니다. Orca가 충돌하거나 종료되어 끊긴 답변은 설명 하나와 함께 끝난 턴으로 보입니다. Orca가 끊어야 했던 답변은 이유를 밝히고 Continue를 제안하는데, 먼저 에이전트에게 마지막 단계가 끝났는지 확인하게 합니다.
  • 보내는 도중 Orca나 에이전트가 재시작되면, Orca는 공급자 쪽 대화 기록을 확인해 봅니다. 메시지가 도착한 것이 확인되면 전송 완료로, 도착하지 않은 것이 확인되면 Retry를 엽니다. 어느 쪽인지 알 수 없으면 같은 메시지가 두 번 가지 않도록 미확인(unconfirmed)으로 둡니다.
  • Rewind to here: 보낸 메시지의 마우스 오버 줄에 있는 되돌리기 동작으로, 대화를 그 시점으로 되돌리고 그 메시지를 작성창에 돌려놓아 고쳐 다시 보낼 수 있습니다. 에이전트가 쉬고 있고 기다리는 것이 없어야 하며, Codex는 턴 전체를 되돌립니다.

긴 대화는 생각·도구 호출 묶음이 한 줄로 접히고, 가장자리 메시지 레일로 원하는 턴에 뛸 수 있어 읽기 쉽습니다.

읽기 쉬운 대화 기록 — 도구 행, 접기, 메시지 레일, 이전 기록 불러오기
  • 업데이트된 구조화 Codex 채팅에서는 실행 중인 도구 호출이 실시간 진행을 보여 주고, 끝나면 펼쳐서 명령·결과를 볼 수 있는 작은 행으로 접힙니다.
  • 도구 행은 MCP·웹 검색 작업을 포함해 실제로 한 일을 이름으로 보여 주고(내부 동작 이름 대신), 세션의 다른 작업은 두고 그 행의 작업만 멈출 수 있습니다.
  • 긴 보낸 메시지는 토글 뒤로 접히고, 답변 사이의 생각·도구 호출 묶음은 펼칠 수 있는 한 행으로 접힙니다.
  • 긴 대화에서는 가장자리에 메시지 레일(message rail)이 생겨 사용자 프롬프트마다 표시가 하나씩 붙습니다. 올려 보거나 초점을 주면 미리 보고, 고르면 그 턴으로 뜁니다. 아주 긴 기록은 표본을 뽑아 레일이 짧게 유지됩니다.
  • 위로 스크롤하면 맨 위에 닿기 전에 이전 기록을 미리 불러옵니다. 한 페이지가 실패하면 그 자리의 재시도 버튼을 누릅니다.
같은 대화가 터미널에도 열려 있다면그 터미널이 아직 쓰고 있을 수 있으므로 Chat UI는 겹치는 메시지를 보내지 않습니다. 터미널에서 에이전트를 종료하거나 터미널을 닫은 뒤 채팅에서 보내세요. Claude·Codex는 터미널 에이전트가 끝났음을 Orca가 확인하면 터미널 탭은 열어 둬도 됩니다.
/ 명령과 스킬

/를 치면 명령과 스킬(에이전트가 불러 쓰도록 저장해 둔 작업 지침 묶음) 목록이 열립니다.

/clear

같은 패널에서 새 대화를 시작합니다. 이전 대화는 기록에 남습니다.

/compact

에이전트에게 지금까지의 대화 분량(문맥(에이전트가 한 번에 기억하며 참고하는 대화·파일 내용))을 줄여 달라고 해 계속 작업하게 합니다.

모델·옵션 알약

작성창 아래 알약에서 모델과 생각 수준(effort(에이전트가 답하기 전에 얼마나 깊이 생각할지 정하는 단계)) 등을 고릅니다.

새 채팅은 가능하면 첫 메시지로 이름이 지어지고, 탭 동작에서 이름을 바꿀 수 있습니다.

슬래시 명령과 스킬 세부
  • 초안 맨 앞이나 공백 뒤에서 /를 치면 슬래시 명령과 발견된 스킬이 묶인 목록 하나가 열립니다. 에이전트가 기대하는 표기를 넣어 줍니다(Claude는 /skill, Codex는 $skill). $는 더 이상 별도 선택기를 열지 않습니다.
  • 문장 중간에서 명령을 고르면 주변 초안을 보내지 않고 그 명령 글자만 완성합니다. 목록은 에이전트별로 다르며 모바일 Chat UI와 공유됩니다. 데스크톱에서 Claude 명령 행은 설치된 CLI가 알려 주는 설명과 인수 힌트를 씁니다.
  • 선택기에서 고른 스킬은 초안에 알약으로 남고, 직접 치거나 붙여넣은 스킬 이름은 일반 글자로 남습니다.
  • 에이전트 고유 명령은 거부하지 않고 그대로 넘깁니다: Claude /init, /review, /help, Codex /goal <objective>. Orca는 자기 대화 명령인 /clear, /compact는 직접 처리합니다.
  • /clear: 같은 패널에서 새 대화를 시작하고 이전 대화는 기록에 남깁니다. /compact: 에이전트에게 현재 대화 문맥을 줄여 달라고 해 계속 작업하게 합니다(Claude, Codex, Grok, OpenCode, OMP 지원). 작업 중에 보낸 /compact는 거부되지 않고 줄을 섭니다.
모델·옵션 알약 세부 — Claude·Codex·Grok, Fast mode, 문맥 링
  • 에이전트가 제공하면 모델과 옵션(생각 수준, Fast mode 등) 알약을 씁니다. 모델이 많으면 Search models… 칸으로 거릅니다.
  • Fast mode는 공급자·모델을 아는 토글로, 활성 에이전트가 지원한다고 알릴 때만 보이며 공급자가 지원하는 경로를 그대로 둡니다.
  • Claude: 모델 목록은 그 호스트에 설치된 Claude CLI에서 가져옵니다(고정 목록 아님). CLI를 업데이트하면 새 모델이 보입니다.
  • Codex: 알약에서 모델을 바로 고르면 /model <id>를 보내고, 그냥 /model은 에이전트 선택기를 엽니다. 속도 선택으로 Ultrafast가 있습니다.
  • Grok: 모델(실행 시 -m, 세션 중 /model)과 추론 effort(실행 시 --reasoning-effort, 세션 중 /effort). 모델 목록은 로그인된 Grok CLI(grok models)에서 조사해 은퇴한 id는 빠집니다. effort 선택지는 모델을 따릅니다: Grok 4.6은 Extra high까지, Grok 4.5는 High까지.
  • 모델 선택기는 에이전트 시작을 기다리지 않습니다. 프로세스 시작 전에도 그 에이전트의 모델·effort 선택지가 보이고 첫 시작에 적용됩니다. 세션이 살아난 뒤 실행 중 턴에만 영향을 주는 알약은 준비될 때까지 비활성이거나 표시가 붙습니다. 실시간 값은 그 탭의 CLI로 갑니다.
  • 문맥 링(ring): 업데이트된 구조화 Claude 채팅에서 모델·effort 옆 링이 문맥 창 사용량을 보여 줍니다. 열면 토큰 수와 메시지·도구·메모리 파일 등이 차지한 공간이 나옵니다. 턴 중에도 갱신되고 채팅을 다시 열어도 남습니다.
  • Codex, Pi, OMP는 로그아웃 상태면 보내기 전에 알려 줍니다(Send는 막지 않음). 실패할 턴을 기다리지 말고 로그인을 고치면 됩니다.
채팅 이름 짓기

새 채팅은 가능하면 첫 메시지로 이름이 지어지고, 아니면 Claude Chat / Codex Chat으로 남습니다. 기본은 그 채팅의 에이전트·계정이 이름을 짓고, Settings → Chat UI → Chat naming → Advanced에서 다른 이름 짓기 에이전트를 고를 수 있습니다. 탭 동작에서 이름을 바꿀 수 있고, 정한 이름은 탭을 닫은 뒤에도 Agent Session History, 휴대폰, 다른 창에 그대로 남습니다.

구조화 채팅은 맡긴 일·뒤에서 도는 일을 메인 턴 동안과 그 뒤에도 보이게 합니다.

  • 백그라운드 작업 띠: 뒤에서 도는 작업 수와 상태가 작성창 근처에 보입니다.
  • 계획 체크리스트: 에이전트가 세운 계획이 체크리스트로 보입니다.
  • 끝나면: 바뀐 파일과 추가/삭제 줄 수 요약이 나오고, 백그라운드에서 끝난 채팅에는 안 읽음 표시가 붙습니다.
작업 따라가기 세부 — 하위 작업, 대기 알림, goal, 활동 행
  • 백그라운드 작업 띠(strip): 작업이 살아 있는 동안 보입니다. 요약에 에이전트·셸·모니터·워크플로 등 작업 수가 나오고, 펼치면 이름·상태 점·경과 시간이 있는 묶음 행이 나옵니다. Claude·Codex 하위 작업은 각자 끝날 때까지 보이며 펼친 화면에 과제와 결과가 있습니다. 에이전트 하위 작업은 사이드바 세션 아래에도 들여쓴 행으로 보입니다.
  • Codex 채팅은 행에서 백그라운드 명령이나 서브에이전트만 멈출 수 있고, Grok 채팅은 뒤에 남겨 둔 명령을 나열·중지할 수 있습니다. Grok도 서브에이전트를 행으로 보여 줍니다.
  • Claude 서브에이전트가 권한 확인을 기다리면 하위 행은 waiting, 부모 세션도 blocked가 아닌 waiting으로 보입니다(CLI 표시와 같음).
  • 구조화 채팅이 턴 중간에 승인·입력을 기다리면, 다른 대기 에이전트처럼 알림을 띄워 계속 지켜보지 않아도 됩니다.
  • Claude TodoWrite와 Codex update_plan은 인라인 체크리스트로 보이고, 최신 계획은 작성창 위 접이식 진행 패널에도 나옵니다.
  • 활성 Codex goal은 작성창 위에 상태와 함께 보이며 일시정지·재개·지우기·펼치기 버튼이 있습니다. /goal을 입력하면 다음 초안을 goal로 보냅니다. goal이 설정·일시정지·막힘·완료·중지·삭제될 때 대화에 행이 생기며, 반복되는 집계 갱신은 중복 행을 만들지 않습니다.
  • 실행 중인 턴은 대화 끝에 활동 행 하나를 가집니다. Thinking은 추론 중이라는 뜻이고, 명령 실행 같은 공급자 활동이 우선 표시됩니다. 끝났거나 중단된 시간은 새로고침·재시작 후에도 남고, Orca가 턴의 끝을 보지 못했으면 추정하지 않고 시간을 생략합니다.
  • 턴이 끝나면 머리글에 바뀐 파일과 추가/삭제 줄 수 요약이 나오고, 펼치면 diff 카드가 보입니다. 답한 승인·질문 카드는 고른 답을 보여 주는 영수증처럼 남습니다.
  • 끝난 턴은 답변만 남기고 접힙니다. 에이전트가 실패를 알리면 계속 실행 중으로 보이지 않고 턴이 끝납니다.
  • 구조화 채팅이 백그라운드에서 성공적으로 끝나면 탭과 워크트리에 안 읽음 표시가 붙습니다. 데스크톱 알림이나 소리는 없습니다(다른 알림 설정은 Notifications & Inbox 문서).
  • 에이전트의 질문: 에이전트가 묻는 것은 질문 카드로 보이고, 카드의 Submit으로 답합니다.
  • 채팅 ↔ 터미널: 탭을 우클릭해 같은 대화를 채팅 화면과 터미널 화면 사이에서 바꿉니다.
  • Hand Off: 다른 에이전트에게 일을 넘깁니다.
  • 한도 후 자동 이어가기: 사용 한도에 걸려 멈춘 채팅을, 한도가 풀리면 Orca가 이어 가게 할 수 있습니다.
질문 카드·화면 옮기기·넘겨주기·자동 이어가기 세부

에이전트의 질문

Claude가 AskUserQuestion(또는 비슷한 구조화 권한·질문 카드)을 띄우면, Chat UI는 접힌 도구 호출이 아니라 질문 카드로 대화에 그려 작성창 쪽에서 답하게 합니다. 카드의 Submit으로 확정합니다. 로컬 패널뿐 아니라 짝지은 Remote Orca Server·헤드리스 호스트에서 도는 에이전트도 마찬가지입니다.

채팅 ↔ 터미널 옮기기

  • 탭을 우클릭해 지원 세션을 Chat UI와 TUI 사이에서 실시간으로 바꿉니다.
  • 탭 우클릭 메뉴나 Agent Session History 행에서 Resume in New Native Chat은 이전 대화를 구조화 채팅으로 열고, Resume in New CLI는 그 대화를 터미널로 갈라(fork) 냅니다. 원래 대화는 그대로입니다.
  • 대화가 구조화 채팅용으로 예약되면 그 세션은 터미널 Resume 대신 채팅을 쓰세요.

넘겨주기와 한도 후 자동 이어가기

  • 채팅 머리글이나 탭 우클릭 메뉴의 Hand Off로 다른 에이전트에게 일을 넘깁니다.
  • Claude·Codex 채팅이 리셋 시각이 알려진 사용 한도에 닿으면, Settings → Chat UI → Behavior → Continue chats automatically when a usage limit resets를 켜서 리셋 후 Orca가 이어가기 메시지를 보내게 할 수 있습니다. 한도 안내의 Don't continue로 그 채팅만 취소합니다.
  • 이 설정은 에이전트를 돌리는 호스트에 속합니다. 닫힌 채팅이나 잠든 워크트리는 다시 열거나 깨울 때까지 기다리고, 24시간보다 오래된 리셋은 직접 이어가야 합니다.

제공 범위

Chat UI는 데스크톱에서 지원되는 로컬·원격(짝지은 서버) 에이전트 세션에 제공됩니다. 모바일 동반 앱도 같은 세션에 채팅식 대화 화면을 재사용합니다.

에이전트 세션 기록 (Agent Session History)

Claude, Codex, Muse Code, Cursor, Gemini 등 에이전트 CLI는 대화 기록(transcript)을 디스크에 파일로 남깁니다. Orca는 이 파일들을 훑어 오른쪽 사이드바의 Agent Session History 패널에 목록으로 보여 줍니다. 지난 세션을 골라 Resume을 누르면, 같은 작업 폴더·같은 세션 ID로 에이전트의 재개 명령을 새 터미널에서 실행합니다. --resume 옵션을 손으로 챙길 필요가 없습니다.

① 에이전트가 기록 저장 대화 파일을 디스크에 ② Orca가 목록화 Agent Session History 검색·정렬 ③ Resume 클릭 ④ 새 터미널에서 이어서 대화 같은 폴더·같은 세션 재개 명령(예: claude --resume <id>)은 Orca가 대신 입력합니다
세션 기록의 한 바퀴. 내가 할 일은 목록에서 고르고 Resume을 누르는 것뿐입니다.
Agents · Agent Session History
12 shown · 47 recent   ⟳
🔍 제목·폴더·브랜치·모델·내용 검색
Workspace Project All  정렬: Last updated ▾
Claude 로그인 버그 수정 · feature/login · 2시간 전
Codex API 테스트 추가 · main · 어제
Gemini README 정리 · docs · 3일 전

패널 열기와 검색

오른쪽 사이드바를 열고 Agents 탭으로 바꾸면 머리글에 “Agent Session History”가 보입니다. 머리글의 12 shown · 47 recent 같은 개수 옆 검색 상자에 입력하면 세션 제목, 작업 폴더, 브랜치, 모델, 대화 미리보기 글로 거릅니다.

연결된 다른 컴퓨터의 기록까지 검색할 수도 있습니다.

다른 컴퓨터까지 검색

연결된 다른 컴퓨터와 짝지은 Orca Server의 색인된 기록도 찾을 수 있습니다. Settings → Session History에서 원하는 컴퓨터에 Search inside sessions를 켜거나 Enable on all computers를 씁니다. 컴퓨터가 꺼져 있거나 색인 권한이 없으면 안내가 뜹니다. 검색 데이터는 각 컴퓨터에 머물고, 색인에 없는 세션도 로컬 패널에서 둘러볼 수 있습니다. 스크립트·터미널에서는 orca search로 같은 색인을 조회합니다.

WorkspaceWorkspace(워크스페이스 — 워크트리와 같은 것): 현재 워크트리의 세션(활성 워크트리 맥락에 따라)
Project활성 Orca 프로젝트로 연결되는 세션
All이 컴퓨터의 모든 에이전트에서 찾은 모든 세션

원격 워크트리에서도 로컬 기록을 둘러볼 수는 있지만, 재개(Resume)는 로컬 워크트리에서만 됩니다. 활성 워크트리가 원격이면 패널이 알려 줍니다.

  • Agents: 목록에 넣을 에이전트를 하나씩 켜고 끕니다. Select all / Clear로 한 번에 바꿉니다.
  • Group: Project, Folder(작업 폴더마다 제목), Agent(CLI마다 제목).
  • Hide empty sessions: 기록된 메시지가 0개인 세션을 숨깁니다.
  • 정렬: 둘러볼 때는 Last updated / Created. 검색할 때는 Most relevant / Newest로 바뀌고, 관련도가 같으면 새 세션이 먼저입니다. 검색 정렬은 둘러보기 정렬과 따로 기억됩니다. 검색이 훑기 한도에 닿으면 결과 아래 Show more로 더 과거까지 찾습니다.
Agents 필터 전체 목록과 규칙
  • Agents: 훑을 CLI를 하나씩 켜고 끕니다 — Claude, Codex, Muse Code, Hermes, Pi, OMP, Prime Agent, Cursor, Gemini, Antigravity, Rovo Dev, Copilot, OpenCode, Grok, OpenClaw, Devin, Droid, Kimi, Kiro, CodeBuddy, ZCode, Qoder. 끈 에이전트는 훑지 않습니다. 머리글의 Select all / Clear로 한 번에 바꾸며, Clear는 아무것도 안 고른 상태로 만들어 원하는 CLI 하나만 켜기 좋습니다. 아무것도 고르지 않으면 No agents selected가 보입니다.

세션 행을 누르면 상세가 열립니다: 작업 폴더, 브랜치, 모델, 메시지 수, First prompt, 최근 대화 턴. First prompt는 펼칠 때 기록 파일에서 잘리지 않은 첫 사용자 메시지를 불러오며(목록 행은 검색용 짧은 미리보기만 가짐), 카드의 Copy로 긴 프롬프트 전체를 복사해 다시 쓸 수 있습니다. 활성화된 세션 행을 워크트리로 끌어다 놓아도 재개됩니다.

Resume그 세션의 작업 폴더에서 새 터미널을 열고, 에이전트별 “이어서 하기” 명령을 대신 입력해 줍니다(명령 예시는 아래 접힌 상자).
Resume in New Native Chat이전 대화가 보이는 새 구조화 채팅 탭으로 엽니다(자격 있는 세션). Claude는 원래 워크트리에서만, Codex는 다른 워크트리에서도 재개됩니다. 폴더 워크트리에서 시작한 채팅은 같은 폴더에서 재개됩니다. 반대로 Resume in New CLI는 구조화 채팅을 터미널로 갈라 냅니다. 둘 다 탭 우클릭 메뉴에도 있습니다. 채팅용으로 예약된 대화는 터미널 Resume을 쓸 수 없습니다.
Copy resume command같은 셸 명령을 클립보드에 복사(외부 터미널용)
Copy session ID / Copy log path스크립트나 버그 보고에 기록 첨부용
Open log / Reveal log원본 기록 파일을 Orca에서 열거나 OS 파일 관리자에서 보여 줌
Open cwd세션의 작업 폴더를 워크트리로 엶
Resume이 실행하는 명령 예시

claude --resume <id>, codex resume <id>, muse resume <session-id>, pi --session <session_file>, prime-agent --resume <path>, cursor-agent --resume <id>, acli rovodev run --restore <id>. Codex는 원래 세션이 CODEX_HOME을 썼다면 그것도 다시 export합니다.

Pi는 세션 파일로 재개Pi는 훅이 알려 준 디스크의 세션 파일(--session <path>)로 재개합니다. 그 파일이 없으면 세션 id가 있어도 그 행의 Resume은 쓸 수 없습니다.
Resume은 로컬 워크트리가 필요합니다Resume은 Orca 화면을 그리는 컴퓨터에서 에이전트 CLI를 실행합니다. 원격 워크트리에 연결돼 있다면 로컬로 돌아오거나, Copy resume command로 복사해 원격에서 직접 실행하세요.

Orca는 각 에이전트가 원래 쓰는 기록 저장소를 읽습니다. 따로 켤 것은 없고, CLI가 기록을 쓰면 다음 훑기 때 패널에 나타납니다. 머리글의 Refresh Session History로 바로 다시 훑습니다.

Codex~/.codex/sessions
Claude~/.claude 기록
Muse Code~/.local/share/muse/sessions
CursorCursor 세션 로그
OpenCode예전 세션 파일 또는 ~/.local/share/opencode/opencode.db
CodeBuddy.codebuddy/projects 아래 프로젝트 기록
ZCode저장된 기록
Qoder~/.qoder/projects 기록

에이전트 휴면 (Agent hibernation) 실험 기능

워크트리를 수십 개 열어 두면 쉬고 있는 에이전트도 쌓입니다. 쉬고 있어도 하나하나가 대화를 메모리에 붙잡은 채 켜져 있어서, 켜 둔 에이전트가 많을수록 컴퓨터 자원(메모리)을 계속 씁니다. (속을 들여다보면 각각이 모델 세션을 쥐고 있는 살아 있는 PTY(프로그램이 진짜 터미널에 연결된 것처럼 느끼게 해 주는 가상 터미널)입니다.) 휴면은 일을 마치고 충분히 오래 손대지 않은 터미널을 조용히 멈췄다가, 다음에 그 워크트리를 열 때 같은 세션을 이어서 되살립니다.

기본은 꺼져 있습니다안전 장치를 다듬는 중이라 Settings → Experimental → Agent hibernation에서 직접 켜야 합니다.
작업 중 완료(done) 입력 대기 아님 손대지 않음 기본 30분 기다림 휴면 💤 PTY 멈춤 자동 재개 워크트리 열 때 키 입력·새 출력·탭 복귀 → 시계 초기화 같은 대화를 그대로 이어감 (claude --resume 등)
휴면의 한 바퀴. 기다리는 시간(Hibernate after)은 에이전트가 일을 마친 시각(마지막 완료 표시)부터 셉니다.

언제 잠드나 — 핵심 세 가지

① 일이 끝났다

에이전트가 마지막 일을 마치고(done), 여러분의 입력을 기다리고 있지도 않습니다.

② 30분 동안 손대지 않았다

끝난 뒤 키 입력도 새 출력도 없이 정해 둔 시간(기본 30분)이 지났습니다.

③ 지금 보고 있지 않다

그 터미널이 지금 열어 둔 워크트리나 화면에 띄운 워크트리에 있지 않습니다.

실제로는 이 셋 말고도 몇 가지 조건(아래 접힌 전체 목록)이 모두 맞아야 잠들고, 하나라도 어긋나면 계속 돕니다. 한 워크트리에 에이전트 패널이 여러 개면 한 덩어리로 함께 잠들어, 반쯤만 멈춘 워크트리는 생기지 않습니다.

휴면 조건 전체 목록 (모두 참이어야 함)
  • 에이전트가 done 상태 — 마지막 턴을 끝냈고 입력을 기다리지 않음
  • 터미널이 활성 워크트리에도, 지금 앞에 터미널을 그리고 있는 워크트리에도 없음
  • 에이전트가 끝난 뒤 키 입력을 받지 않았음
  • 재개 가능한 세션을 가진 에이전트: Claude, Codex, Gemini, Antigravity, OpenCode, Pi, MiMo Code, Droid, Grok, Devin, OMP
  • 설정한 대기 시간(기본 30분) 이상 쉬었음
  • 모바일 세션이 그 터미널을 조종하고 있지 않음
  • 끝나지 않은 오케스트레이션 Dispatch(pending, dispatched, unknown)가 없음 — 실행 환경이 completed, failed, circuit_broken을 확인하면 다시 잘 수 있음
  • 패널에 살아 있는 서브에이전트·팀원 명단이 남아 있지 않음(자식이 붙어 있으면 공급자의 “done”만으로는 부족)

대기 시간 조절 (Hibernate after)

  • 위치: Agent hibernation 토글 아래
  • 기본 30분, 범위 1분 ~ 24시간
  • 에이전트가 일을 마친 시각(마지막 done 갱신)부터 시계가 돌고, 키 입력·새 출력·그 탭으로 돌아오기가 시계를 되돌립니다.
  • 길게 잡으면 덜 멈추지만 메모리 절약이 줄고, 짧게 잡으면 적극적으로 멈추지만 다시 돌아올 때 재개 비용이 듭니다.

수동 재우기 · 찾기

  • 사이드바에서 워크트리를 직접 재울 수 있습니다(중첩 자식이 있으면 Sleep with Descendants). 수동 잠은 끝났거나 중단된 재개 가능 세션 기록을 지우지 않아, 다시 열면 같은 재개 옵션으로 실행됩니다.
  • 사이드바 필터 메뉴에서 잠든 워크트리를 보일지 정합니다. 자주 숨긴다면 Settings → Shortcuts에서 Toggle Sleeping Workspaces에 단축키를 지정하세요.

재개와 한계

  • 잠든 워크트리를 열면 Agent Session History와 같은 재개 옵션(claude --resume <id>, codex resume <id> 등)으로 다시 실행되어 대화·작업 폴더·공급자 세션이 이어집니다. 누를 것은 없습니다 — 터미널을 앞으로 가져오는 과정에서 자동으로 일어납니다.
  • 처음 열 때 기록해 둔 실행 명령·인수·개인 환경 변수를 다시 씁니다.
  • 기록이 지워졌거나 공급자가 세션 ID를 바꾸는 등으로 재개할 수 없으면, 새 프롬프트로 열리고 이전 기록은 세션 기록에 남습니다.
  • 목록의 재개 가능 에이전트만 잠듭니다. Cursor CLI, Hermes, Copilot, Trae 등 재개할 수 없는 터미널은 계속 돕니다.

에이전트 훅과 메모리

훅(hook)과 메모리 파일이란훅은 “어떤 일이 생기면 자동으로 이 명령을 실행해” 하고 걸어 두는 갈고리입니다. 메모리 파일(CLAUDE.md, AGENTS.md)은 에이전트가 매번 시작할 때 읽는 “이 프로젝트 사용 설명서”입니다.

Orca는 Claude Code와 Codex가 이미 쓰는 훅·메모리 규칙을 그대로 읽고 따릅니다. 그중 Orca 안에서 다룰 만한 것은 설정 화면, 파일 탐색기, 탭의 상태 점처럼 눈에 보이는 곳에 꺼내 줍니다.

저장소별 훅

각 저장소의 .claude/, .codex/ 설정을 읽습니다. 이미 있는 훅은 Orca가 그 저장소의 워크트리에서 에이전트를 실행할 때 그대로 돕니다.

워크트리 준비 훅

새 워크트리를 만든 직후 자동으로 돌 명령을 정해 둡니다. 새 작업 폴더에서 매번 손으로 하던 준비 작업을 대신 해 주는 것입니다. 예: pnpm install(프로젝트에 필요한 부품(라이브러리)을 내려받아 설치), direnv allow(그 폴더 전용 설정값을 쓰도록 허락), .env 복원 스크립트(비밀번호·키 같은 설정을 담은 파일을 다시 가져다 놓기). Settings → Repository → Hooks에서 정합니다.

메모리 파일

Claude의 CLAUDE.md, Codex의 AGENTS.md(저장소 루트 또는 하위 폴더)는 에이전트의 것이라 Orca가 손대지 않습니다. 파일 탐색기에 다른 파일처럼 보여 바로 편집할 수 있습니다.

에이전트 상태 훅 (Agent status hooks)

Settings → Agents → Agent status hooks는 작업 중(working)·대기(waiting)·완료(done)를 화면에 알려 주는 Orca 관리 훅을 다룹니다. 탭과 사이드바의 상태 점이 바로 이 훅 덕분에 뜹니다. 끄면 관리 훅을 지우고, 다시 켜면 Orca를 재시작하지 않고 복구합니다.

상태 훅 내부 동작 — CLI 명령, Codex 승인, endpoint 파일
  • 끄면 관리 훅을 지우고 다시 설치하지 않습니다. 다시 켜면 Orca를 재시작하지 않고 복구합니다(Windows의 WSL 훅 중계도 같은 스위치를 따름).
  • CLI로는 orca agent hooks status|on|off --json.
  • Codex 훅은 바뀐 것이 있을 때만 ~/.codex에 써서, Codex가 매번 승인을 다시 묻지 않습니다.
오래 도는 에이전트 훅 실행 (상태 보고) endpoint.env / .cmd {userData}/agent-hooks/ 지금 살아 있는 Orca 서버 매번 다시 읽음 현재 포트로 Orca를 재시작해도 파일이 갱신되므로 “죽은 포트”로 보내는 일이 없음
재시작에도 살아남기: 훅 연결 정보는 POSIX에선 {userData}/agent-hooks/endpoint.env, Windows에선 endpoint.cmd에 저장되고 훅이 불릴 때마다 다시 읽힙니다.

Orca CLI는 에이전트가 스스로 갱신할 수 있는 워크트리 상태(주석) 필드도 제공합니다(Worktree checkpoints 문서).

사용량과 한도 추적 (Usage & rate-limit tracking)

AI 모델은 보통 “5시간에 얼마, 일주일에 얼마”처럼 쓸 수 있는 양(rate limit, 사용 한도(정해진 시간 동안 쓸 수 있는 AI 사용량의 상한))이 정해져 있습니다. Orca는 Claude Code, Codex, Muse Code, Gemini, Antigravity, OpenCode, Kimi Code, MiniMax, Cursor, ZCode, GLM Coding Plan의 사용량을 상태 표시줄에 보여 줘, 에이전트가 멈추기 전에 한도에 얼마나 가까운지 알게 합니다.

5시간 사용 창 쓸수록 막대가 차고, 창이 끝나면(리셋) 다시 비워집니다 80% 0시간 5시간 ⚠ 80% 경고 칩 리셋! 하루·일주일 창도 같은 방식
사용 한도는 “일정 시간 창” 단위로 채워졌다 비워집니다. 상태 표시줄은 리셋까지 남은 시간을 보여 주고, 80%를 넘으면 경고 칩을 띄웁니다(속도·모양은 예시).
Usage 팝오버 (상태 표시줄 클릭) · ⟳
CodexPro · 1시간 후92%
ClaudeMax · 3시간 후81%
Cursor월간 · 12일 후35%
OpenCodenot signed in
Codex · work ▾⚠ Claude 81%Cursor 35%+2

↑ 화면 흉내(숫자는 예시). 가장 빠듯한 한도가 맨 위로 정렬되고, 80%를 넘으면 경고 칩이 뜹니다.

무엇이 보이나

  • 활성 계정 플랜 대비 현재 사용량
  • 5시간·하루·일주일·Claude Fable 주간 창의 리셋까지 남은 시간(해당될 때)
  • 한도의 80%를 넘으면 경고 칩
  • 공급자가 알려 주면 크레딧 잔액 — Claude usage credits, OpenCode Zen 잔액, Codex credits. 잔액을 주지 않는 공급자는 0이 아니라 “사용 불가”로 표시

여러 계정

상태 표시줄은 항상 활성 계정을 반영합니다. 다른 계정은 계정 전환기에서 각자의 사용량과 함께 보입니다.

Usage 팝오버(사용량 명단)

  • 상태 표시줄의 사용량 부분을 누르면 열립니다. 추적되는 모든 공급자를 (아이콘 · 이름 · 플랜 · 가장 빠른 리셋 · 창별 막대) 형태로, 가장 빠듯한 한도부터 보여 줍니다. 머리글의 새로고침으로 로컬 사용량을 다시 읽습니다.
  • Detailed: 모든 창의 막대·이름표·퍼센트 / Compact: 공급자마다 가장 빠듯한 창만
  • Settings → Appearance에서 % used(쓴 비율)와 % remaining(남은 비율) 중 고릅니다.
  • 숫자가 없는 행은 Loading usage…, not signed in, Usage unavailable, No usage data, 또는 공급자별 오류를 보여 줍니다.
  • Claude·Codex 행에서 계정 전환으로 들어갈 수 있고, Manage accounts는 Settings를 엽니다.
좁은 창에서 상태 표시줄이 줄어드는 방식

상태 표시줄을 한 줄로 유지하려고 작은 막대와 이름표를 숨기고 공급자마다 퍼센트 하나만 보입니다. 그래도 좁으면 일부 공급자 칩이 +N 칩으로 묶이고, 누르면 Usage 팝오버에서 전부 봅니다. 80% 이상인 공급자는 가장 늦게 묶입니다. 잔액이 있으면 그 공급자 한도 옆에 보이고, 좁은 Compact 칸에서는 플랜 상한에 닿은 공급자의 쓸 수 있는 잔액이 드러납니다.

숫자는 가능하면 내 컴퓨터에 있는 에이전트 상태를 읽어 가져옵니다. 공급자에 따라 Settings → Accounts에서 따로 계정 연결이 필요할 수 있습니다.

공급자별로 숫자를 가져오는 방법 (OpenCode Go 쿠키, Cursor, GLM 키 등)
공급자방법과 주의
공통가능하면 로컬 에이전트 상태를 읽습니다. 공급자에 따라 Settings에서 따로 계정 설정이 필요할 수 있습니다.
Muse Code로컬 세션 로그로 토큰을 직접 셉니다. 가격 추정은 없습니다.
OpenCode Go콘솔 API에서 가져오며, Settings → Accounts에 __Host-console_session을 포함한 opencode.ai의 전체 Cookie 헤더가 필요합니다. 인증 쿠키만으로는 작업 공간은 찾아도 Go 사용량은 못 가져옵니다.
Cursor컴퓨터의 기존 Cursor 로그인을 읽어 월간 사용량을 상태 표시줄, Usage 팝오버, Settings → Accounts → Cursor에 보여 줍니다. 로그인시켜 주지는 않으니 저장된 세션이 만료되면 cursor-agent login을 실행하세요. 요청이 거부되면 로그인 만료가 아니라 사용량 실패로 표시됩니다.
AntigravityAntigravity 자체 CLI에서 모델 그룹 풀까지 포함한 할당량을 읽습니다. 로그인된 Gemini CLI가 필요 없고, 확인해도 할당량이 줄지 않습니다.
ZCode디스크 기록에서 읽는 세션 기록과 함께 Coding Plan 할당량이 보입니다.
GLM Coding PlanSettings → Accounts → GLM Coding Plan에서 플랜 사이트(Z.AI 또는 Zhipu BigModel)를 고르고 플랜 API 키를 저장해 직접 연결합니다. ZCode CLI 로그인이 필요 없고, 저장한 키가 ZCode CLI 로그인보다 우선합니다. 명단에 다른 공급자처럼 나옵니다.

모바일

동반 앱에서 호스트의 Accounts 화면을 열면 같은 전환기·사용량이 보입니다. Codex가 한도 리셋 크레딧을 얻었으면 그 화면에서 하나를 쓸 수 있습니다(Mobile companion 문서).

예상 비용 (Stats)

Stats 화면은 모델별 예상 비용을 보여 줄 수 있습니다. 실제 청구 금액이 아니니 정확한 지출은 공급자 콘솔을 보세요.

예상 비용 계산 방식

Stats 분석은 알려진 모델 계열(Claude Opus 5.5, Fable 5.1, Codex GPT-5.6, GPT-6 Astra·Sol·Luna 등)의 예상 비용을 보여 줄 수 있습니다. 공급자의 실제 청구가 아니라 로컬 가격표로 계산합니다. • inferred pricing은 Orca가 모델을 추정한 값, Codex의 • excludes unpriced models는 가격 없는 모델을 뺀 값이며 Overview도 부분 합계임을 표시합니다. 정확한 지출은 공급자 콘솔을 보세요.

터미널 — 기본기와 에이전트용 추가 기능

Orca의 터미널은 널리 쓰이는 코드 편집기 VS Code와 같은 터미널 부품에, AI 에이전트 작업에 맞춘 기능을 더한 것입니다. 다른 터미널 앱에서 쓰던 색·글꼴을 가져올 수도 있습니다.

터미널 부품과 Ghostty

VS Code가 쓰는 xterm.js 기반 터미널입니다. 첫 실행 때 Ghostty 테마·글꼴·커서를 가져올 수 있는 Ghostty 스타일 터미널이기도 합니다.

패널과 탭

  • 터미널은 그냥 탭입니다(탭·패널·분할 레이아웃 장 참고). 터미널 패널을 나누면 셸 두 개가 나란히 생깁니다. 탭에 패널이 하나뿐이어도 닫기 버튼이 있습니다.
  • 에이전트 터미널 탭에는 에이전트 정체와 실시간 상태가 보입니다: 작업 중(working), 입력 대기(waiting for input), 완료(completed), 완료됐지만 안 읽음(completed-but-unread).
탭 제목과 패널 되살리기 규칙
  • Claude·Codex는 Orca가 패널을 세션과 연결할 수 있으면 탭 제목에 AI Vault 대화 이름(사용자 제목·스레드 이름)이 보입니다. 직접 바꾼 이름이 항상 우선합니다.
  • 백그라운드로 보낸 터미널은 돌아올 때 중복 탭을 열지 않고 자기 탭에 다시 붙습니다. 종료 직전에 닫은 패널은 다시 켤 때 되살아나지 않고, 패널을 끌어 따로 탭으로 빼도 두 탭에 동시에 보이지 않습니다.
터미널 탭의 상태 표시
Claude · 로그인 버그 수정 — working
Codex · API 테스트 — waiting for input
Gemini · README — completed
Pi · 리팩터링 — completed-but-unread
긴 에이전트 실행 명령 전달 방식 (macOS·Linux)

에이전트 실행 명령

macOS·Linux에서 길거나 여러 줄인 에이전트 실행 명령이 잘리거나 한 줄씩 따로 실행되지 않고 통째로 전달되며, 시작 명령은 진짜 Enter로 제출됩니다. 업데이트 후 연 터미널부터 적용되고, 이미 열린 터미널은 다시 열 때까지 예전 방식입니다.

  • 찾기: Cmd+F / Ctrl+F로 위로 지나간 출력 안에서 글자를 찾고, Esc로 닫습니다.
  • 링크: 터미널 속 링크를 그냥 누르면 바로 열리지 않고 “어디서 열지” 고르는 작은 메뉴(팝오버)가 뜹니다. 내 컴퓨터에서 띄운 웹 페이지 주소(예: localhost(‘이 컴퓨터 자신’을 가리키는 주소)로 시작하는 주소)는 Orca 안 브라우저로도 열 수 있습니다. Cmd/Ctrl-클릭은 바로 엽니다.
  • 우클릭 메뉴: 최근 출력 복사(Copy Context), 세션 번호 복사(Copy Session ID), 꼬인 키 입력 풀기(Reset Terminal).
  • 끌어다 놓기: 파일을 터미널에 놓으면 그 파일 경로가 입력됩니다.
찾기·링크 동작·복사·초기화 세부

찾기 (Search)

Cmd+F / Ctrl+F로 스크롤백(지나간 출력) 안에서 찾습니다. 찾기 막대는 현재 일치 위치와 전체 개수를 보여 주고, 대소문자·정규식·일치 이동을 지원합니다. Cmd+F / Ctrl+F를 다시 누르면 검색어에 초점을 주고 전체 선택하며, Esc로 닫습니다. 초점·닫기 동작은 편집기 검색 막대와 같습니다.

링크 동작 (Link actions)

  • 터미널 링크(HTTP/OSC 8 URL, 파일 경로, 워크트리, 터미널, 작업 핸들)를 그냥 클릭하면 바로 이동하지 않고 작은 동작 팝오버가 열립니다.
  • 로컬 웹 링크와, 자격 있는 SSH 워크트리나 기능이 확인된 짝지은 런타임의 링크는 Orca Browser와 System Browser를 고를 수 있고, 예전 런타임은 시스템 브라우저만 됩니다.
  • 웹 링크에는 Copy link도 있어 숨은 OSC 8 목적지를 포함한 실제 URL을 팝오버를 닫지 않고 복사합니다(파일·워크트리 목적지는 그대로).
  • Cmd-클릭(macOS) / Ctrl-클릭(Windows·Linux)은 여전히 바로 열고, Shift+Cmd / Shift+Ctrl-클릭은 대체 경로로 엽니다.
  • Settings → Browser → Terminal URL clicks에서 URL을 그냥 클릭했을 때 동작 메뉴 열기 / 바로 열기 / 수정키 기다리기 중 고르고, 가운데 버튼 클릭 동작은 따로 정합니다.
  • 미리 볼 수 있는 HTML 파일 링크는 로컬·SSH·짝지은 런타임 워크트리에서 Orca 안에 열리고, 원격 파일 행에는 Download & open with default app도 있습니다. 같은 파일이 형제 워크트리 탭에 이미 열려 있으면 중복으로 열지 않고 그 탭을 활성화합니다(HTML viewers 문서).
  • 팝오버는 Settings → Browser → Show terminal link actions에서 끌 수 있고, 끄면 링크를 열 때 수정키+클릭이 필요합니다.

복사·초기화·끌어다 놓기

  • Copy Context(터미널 우클릭): 그 패널의 최근 기록을 분량 제한 있게 복사합니다. Orca fork를 시작하지 않고 에이전트 출력을 다른 도구에 붙여 넣을 때 씁니다.
  • Copy Session ID(터미널 탭 우클릭): 스크립트·지원 요청·다른 도구용 세션 식별자를 복사합니다.
  • Reset Terminal(터미널 우클릭): 죽은 프로그램이 키보드·마우스 모드를 꼬아 놓았을 때, 셸을 재시작하지 않고 호스트와 패널의 남은 입력 모드를 지웁니다. Shift+Enter나 수정키가 앱에 안 닿을 때 유용합니다. Orca는 프로그램이 죽었다고 “짐작”만으로 모드를 끄지 않으므로, 살아 있는 프로그램은 Ctrl+C 뒤에도 키보드 모드를 유지합니다. SSH 터미널도 로컬처럼 정리합니다.
  • 파일·스크린샷 끌어다 놓기: 파일을 터미널에 놓으면 프롬프트에 경로가 붙습니다. macOS 스크린샷 썸네일은 로컬 Claude Code 터미널이나 새 워크트리 작성창에 놓을 수 있고, Orca가 임시 이미지의 읽을 수 있는 사본을 에이전트에 줘서 실제로 열 수 있게 합니다. 건너뛴 파일이 있으면 이유를 알려 줍니다.
  • TUI 클립보드(OSC 52): Zellij, tmux, Neovim, fzf, Grok 같은 TUI는 OS 클립보드 대신 OSC 52로 복사합니다. Orca는 기본으로 이를 허용해 SSH에서도 로컬처럼 복사됩니다. 스위치: Settings → Terminal → Allow TUI Clipboard Writes (OSC 52).

Settings → Terminal에서 색 테마와 글자 대비를 고릅니다. 다른 터미널 앱(Ghostty, Warp)을 쓰던 사람은 그 앱의 색 테마를 가져올 수 있습니다.

테마·색 대비·Ghostty·Warp 가져오기 세부
  • 테마: Settings → Terminal에서 색 테마를 고릅니다. 인기 테마 묶음이 들어 있고 무엇이든 고쳐 쓸 수 있습니다. Ghostty 색을 가져왔더라도 Orca에서 테마를 고르면 그 테마 색이 적용되며, Ghostty 설정을 지울 필요는 없습니다.
  • 색 대비: Settings → Terminal → Rendering → Color Contrast에서 Automatic(Orca가 글자를 읽기 좋게 유지), Off(테마의 흐린 색·Powerline 색 그대로), Custom(대비 목표 1~21 지정).
  • Ghostty 가져오기: Ghostty 사용자라면 첫 실행 때 테마·글꼴·커서 설정을 가져올 수 있고, 나중에 Settings → Terminal → Import from Ghostty로 다시 실행합니다.
  • Warp 테마 가져오기: Settings → Terminal의 테마 선택기에서 Import themes from Warp를 누르면 OS별 Warp 테마 폴더(macOS ~/.warp/themes, Linux $XDG_DATA_HOME/warp-terminal/themes, Windows %APPDATA%\warp\Warp\data\themes)를 훑어 가져올 YAML 테마를 고르게 합니다. 옆의 Import from YAML은 같은 선택기를 아무 폴더의 Warp 형식 .yaml/.yml 파일로 향하게 합니다. 가져온 테마는 기본 테마와 함께 목록에 나옵니다.

새 터미널 탭이 어떤 셸로 열릴지 Settings → Terminal에서 고릅니다. 비워 두면 컴퓨터의 기본값을 씁니다. Windows에서는 PowerShell, Command Prompt, WSL 중에서 고를 수 있습니다.

기본 셸 세부 — 셸 인수, 시작 파일을 읽는 순서, WSL

Settings → Terminal에서 새 로컬 터미널 탭의 기본 셸을 고릅니다. 비워 두면 시스템 기본값입니다. Windows에서는 PowerShell, Command Prompt, WSL을 고를 수 있고, WSL은 wsl.exe --status가 성공하면 자동으로 나옵니다. 이 설정은 새 로컬 패널에만 적용되고 기존 패널·SSH 셸은 그대로입니다. 탭 막대의 + 드롭다운 하위 메뉴로 기본값을 바꾸지 않고 다른 셸 탭을 한 번만 열 수 있습니다.

Unix 사용자 지정 기본 셸은 Advanced → Shell arguments에서 인수를 정합니다. 기본 -l(로그인 셸)을 두거나, Custom args로 한 줄에 인수 하나씩 넣습니다(예: --rcfile과 그 경로를 따로 두 줄). 목록을 비우면 인수 없이 실행합니다.

zsh (로그인 셸 -l) $ZDOTDIR, 없으면 홈 폴더에서 순서대로 .zshenv .zprofile .zshrc .zlogin bash (로그인 셸 -l) /etc/profile ~/.bash_profile · ~/.bash_login · ~/.profile 중 첫 번째 ~/.bashrc ✕ 스스로는 안 읽음
macOS·Linux 로컬 패널은 기본으로 시스템 셸($SHELL)을 로그인 셸(-l)로 엽니다.
  • bash는 ~/.bashrc를 스스로 읽지 않습니다. PATH나 버전 관리자(nvm, asdf, mise) 설정이 ~/.bashrc에 있다면, bash가 읽는 로그인 파일에서 ~/.bashrc를 불러오세요(대부분 배포판의 기본 ~/.profile이 이미 그렇게 합니다).
  • Orca의 bash 통합 래퍼(wrapper)를 쓸 때는 -l 대신 --rcfile로 bash를 시작하고, 래퍼가 같은 로그인 파일을 읽되 ~/.bashrc를 따로 읽지는 않습니다.
  • 사용자 지정 셸에서는 입력한 인수가 일반 로컬 패널의 기본 -l을 대신합니다. 빈 목록이면 인수가 없으므로, 래퍼 없는 대화형 bash는 로그인 파일 대신 ~/.bashrc를 읽습니다.
  • 터미널 데몬을 쓸 수 없을 때는 Orca의 bash·zsh 통합이 사용자 인수를 무시하고 로그인 시작을 유지할 수 있습니다. 에이전트 실행, 시작 명령, 한 번만 고른 셸은 이 인수 설정을 쓰지 않습니다.
  • WSL 파일 시스템(\\wsl.localhost\...)의 저장소는 wsl.exe -d <distro>로 실행합니다. WSL에서 연 Windows 경로 저장소는 작업 폴더를 /mnt/<drive>/...로 바꾸고 로그인 bash로 들어갑니다. 관리되는 WSL 터미널에는 Orca CLI가 자동으로 제공됩니다.

원문에 macOS 키만 나온 항목은 “(macOS)”로 표시했습니다.

단축키동작
Cmd+T (macOS)현재 워크트리에 새 터미널 탭
Cmd+Alt+T (macOS)기본 에이전트로 새 에이전트 탭. Linux·Windows에서는 기본으로 비어 있으니 Settings → Shortcuts에서 “New agent tab”을 검색해 지정. 지원 에이전트마다 따로 “New agent tab” 동작이 있어 특정 CLI를 바로 띄우는 단축키를 걸 수 있음
Cmd+W (macOS)현재 탭 닫기
Cmd+\ (macOS)오른쪽으로 분할
Cmd+Shift+\ (macOS)아래로 분할
Cmd+F / Ctrl+F지나간 출력에서 찾기
Cmd+Option+A(macOS) / Ctrl+Alt+A(Windows·Linux)플로팅 터미널 토글(아래 참고)

Shift+Enter 같은 조합키도 다른 터미널 앱과 똑같이 에이전트에 전달됩니다.

네이티브 키 입력 (kitty 키보드 프로토콜, JIS 키보드)

네이티브 키 입력

Orca는 kitty 키보드 프로토콜(조합키 입력을 정확히 전달하는 터미널 규약)을 알리므로, 터미널 앱이 진짜 Shift+Enter, Ctrl+Enter 같은 수정키 입력을 받습니다. Ghostty, WezTerm, 원래 터미널과 똑같이 동작합니다. macOS에서는 기본 Auto 모드로 ABC 키보드의 Option/Alt 단축키가 터미널 앱에 닿습니다.

macOS 일본어 JIS 키보드라면 Settings → Terminal → JIS Yen (¥) to Backslash (\)를 켜서 ¥ 키가 터미널에서 백슬래시를 보내게 할 수 있습니다.

플로팅 터미널과 Quick Commands

플로팅 터미널 (Floating terminal)

어느 워크트리·탭에 있든 단축키 한 번이면 화면 위에 떠오르는 공용 터미널 창입니다. 새로 설치하면 기본으로 켜져 있습니다.

  • Cmd+Option+A(macOS) / Ctrl+Alt+A(Linux·Windows)로 토글합니다. 이미 열려 있으면 초점을 주고, 이미 초점이 있으면 닫습니다.
  • 창 가장자리의 떠 있는 버튼을 누르거나, Settings → Terminal → Floating terminal에서 그 버튼을 상태 표시줄로 옮깁니다.
  • 같은 설정에서 시작 작업 폴더를 정합니다(기본 ~).
  • 자기 탭을 따로 가집니다.
플로팅 터미널과 오케스트레이션

오케스트레이션(여러 에이전트에게 일을 나눠 맡기고 진행을 관리하는 기능) 설정도 지원해, 워크트리 패널을 차지하지 않고 백그라운드 실행을 시작할 수 있습니다.

워크트리 A · B · C 어떤 탭을 보고 있든 플로팅 터미널 ~ $ npm run dev ~ $ ▍ ⌘⌥A / Ctrl+Alt+A
워크트리와 상관없이 늘 한 번의 단축키 거리에 있는 셸.

Quick Commands — 자주 쓰는 명령 저장

자주 쓰는 글을 저장해 두고 버튼 한 번으로 다시 쓰는 기능입니다. 예를 들어 “이 변경 사항을 리뷰해 줘” 같은 부탁 문장을 Claude·Codex처럼 실행할 때 프롬프트(지시문)를 받는 에이전트용 재사용 프롬프트로 저장해 두면 매번 다시 쓸 필요가 없습니다. 개발자라면 npm run dev, pnpm test, 프로젝트 준비 스크립트처럼 자주 실행하는 터미널 명령도 저장합니다.

  1. 만들기Settings → Quick Commands 또는 탭 막대의 Add command 버튼에서 만듭니다. 각 명령은 이름(label), 명령 글(command text), 범위(scope)를 가집니다. 범위는 어디서나 보이는 Global, 특정 저장소 워크트리에서만 보이는 Project.
  2. 실행하기워크트리 탭 막대의 Quick Commands 분할 버튼은 새 터미널 탭을 열어 실행하고, 터미널 우클릭 메뉴는 현재 터미널에 명령을 끼워 넣습니다.
  3. 복사하기명령 행(Settings 목록, 탭 막대 메뉴, 모바일 Quick Commands)의 복사 버튼으로 명령 본문을 클립보드에 넣습니다.
탭 막대 · Quick Commands ▾
dev 서버 npm run dev · Project
테스트 pnpm test · Global
리뷰 부탁 프롬프트 에이전트용 · Global
+ Add command

↑ 화면 흉내(이름은 예시). 누르면 새 터미널 탭에서 그 명령이 실행됩니다.

원격 서버와 함께 쓸 때

짝지은 Remote Orca Server(또는 다른 실행 호스트)와 일하면, 선택기가 로컬과 원격 묶음을 호스트 이름표(예: Local Mac, Orca Server)와 함께 나란히 보여 줍니다. Saved on은 명령이 저장된 곳이고, 실행은 여전히 명령을 부른 터미널·워크트리에서 일어납니다 — 그래서 클라이언트에 저장된 명령도 원격 워크트리 안에서 돌릴 수 있습니다. 여러 호스트 Quick Commands를 알리지 않는 예전 서버는 로컬 목록만 보입니다.

한눈에 정리
  • Orca는 어떤 CLI 에이전트든 터미널에서 띄울 수 있고, 40여 개는 한 번 클릭으로 실행·설정됩니다. 가장 깊게 통합된 것은 Claude Code·Codex·Muse Code·Cursor CLI입니다.
  • 에이전트는 “설치 → 한 번 로그인 → Orca 선택 상자에서 고르기” 순서로 씁니다.
  • 워크트리는 버려도 되는 복사본이라 새 실행에는 확인 생략(Yolo)이 미리 켜져 있고, Settings → Agents → Agent Permissions에서 Manual로 바꿀 수 있습니다.
  • Codex·Claude 계정은 다시 로그인하지 않고 바꿔 끼우며, 바꾼 계정은 새 세션부터 쓰입니다.
  • Chat UI는 터미널 대신 메신저 같은 화면으로 에이전트와 대화하게 해 주고, 대기열·끼어들기·되감기·@파일·/ 명령·모델 고르기를 지원합니다.
  • Agent Session History로 지난 대화를 찾아 Resume으로 이어 갈 수 있고, 재개는 로컬 워크트리에서만 됩니다.
  • 휴면(실험 기능)은 일을 마치고 오래(기본 30분) 손대지 않은 에이전트를 멈춰 컴퓨터 자원을 아끼고, 워크트리를 다시 열면 같은 대화로 자동으로 이어 갑니다.
  • 저장소의 훅과 CLAUDE.md/AGENTS.md는 그대로 따르고, 상태 훅 덕분에 탭에 작업 중·대기·완료 점이 뜹니다.
  • 터미널은 찾기, 링크 메뉴, 테마, 기본 셸 고르기를 지원하고, 플로팅 터미널은 단축키 한 번으로 뜨며, Quick Commands로 자주 쓰는 명령·부탁 문장을 저장합니다.

출처: onorca.dev/docs/agents/supported · onorca.dev/docs/agents/claude-code · onorca.dev/docs/agents/codex · onorca.dev/docs/agents/codex-hot-swap · onorca.dev/docs/agents/cursor-cli · onorca.dev/docs/agents/glm-agent · onorca.dev/docs/agents/native-chat · onorca.dev/docs/agents/session-history · onorca.dev/docs/agents/hibernation · onorca.dev/docs/agents/hooks-memory · onorca.dev/docs/agents/usage-tracking · onorca.dev/docs/terminal

CHAPTER 04

워크트리별 내장 브라우저와 디자인 모드

Orca에는 워크트리마다 따로 쓰는 진짜 Chromium 브라우저가 들어 있습니다. 사람은 이 브라우저로 만든 화면을 확인하고, 에이전트는 글자 명령(CLI)으로 같은 브라우저를 조작합니다. 디자인 모드를 켜면 화면의 요소를 클릭하는 것만으로 “이걸 고쳐 줘”를 에이전트에게 전할 수 있습니다.

이 장에서 배우는 것
  • 내장 브라우저의 조작법과 단축키, 워크트리별로 탭이 나뉘는 방식
  • 쿠키 가져오기, Google 로그인 주의점, 브라우저 프로필(Profiles)로 신원 분리하기
  • 작업 폴더가 다른 컴퓨터에 있을 때: 화면은 내 PC에서 그리고, 인터넷 통신은 그 컴퓨터를 거쳐 가는 구조
  • 링크를 어느 브라우저로 열지 정하기, Chrome 확장, 다운로드, 아티팩트 공유, 휴대폰 화면 크기 흉내
  • 디자인 모드: 요소 클릭 → 에이전트 채팅 → 수정 → 화면 자동 새로 고침의 순환, 그리고 UI 버그 고치기 레시피
  • 에이전트가 화면 요소에 번호표를 붙이고 그 번호로 누르는 원리
처음이라면 이것만

원격 컴퓨터에서 작업하지 않는다면 「원격 워크트리」 절은 건너뛰어도 됩니다. 「🔧 개발자용 참고」로 접힌 부분(명령 목록·오류 이름 등)도 처음엔 펼치지 않아도 됩니다.

워크트리마다 하나씩 있는 브라우저

쉽게 말하면 워크트리(worktree)(같은 프로젝트를 여러 폴더로 펼쳐 놓고 폴더마다 다른 작업을 동시에 하게 해 주는 기능)는 “같은 프로젝트의 작업용 복사본 책상”이라고 생각하면 됩니다. Orca는 책상마다 브라우저를 한 대씩 따로 놓아 줍니다. A 책상에서 열어 둔 탭은 B 책상으로 옮겨 가면 보이지 않고, 다시 A로 돌아오면 그대로 남아 있습니다.

이 브라우저는 흉내만 낸 미리보기 창이 아니라 진짜 Chromium(Google Chrome의 바탕이 되는 공개 브라우저 엔진) 창입니다. 주소창, 방문 기록(history), 개발자 도구(DevTools)를 모두 갖추고 Orca의 한 pane(칸)(Orca 화면을 나눈 한 구역. 터미널·편집기·브라우저 등을 칸마다 띄움)에 들어 있습니다. 탭이 워크트리 단위로 묶이기 때문에, 지금 만들고 있는 앱의 화면이 다른 작업의 탭과 섞이지 않습니다.

워크트리 A (feature-login) 탭: localhost:3000/login 탭: API 문서 스크롤 위치·탭 목록 저장 워크트리 B (fix-navbar) 탭: localhost:5173 A의 탭은 여기서 안 보임 워크트리 C (docs) 미리보기: guide.html 탭: 디자인 시안 돌아오면 그대로 복원
워크트리마다 탭 묶음이 따로 있습니다. 워크트리를 바꾸면 그 워크트리의 탭과 스크롤 위치가 되살아납니다.

화면 구성과 조작법

일반 브라우저와 거의 같지만, Orca 안에서 쓰기 좋게 몇 가지가 더해져 있습니다.

워크트리 A · 브라우저 칸
로그인 페이지 (스피커)API 문서+
◀ ▶ ⟳localhost:3000/loginDesign ModeDevTools⋯
(페이지 내용) — 링크에 마우스를 올리면 아래에 목적지 주소가 표시됩니다.
report.pdf · 완료 — 열기 / 폴더에서 보기 / 닫기
  • 주소창(address bar): 방문 기록과 퍼지(fuzzy) URL 자동 완성(철자가 조금 틀려도 비슷한 주소를 찾아 주는 자동 완성)을 지원합니다.
  • 주소가 아닌 글자를 입력하면 Default Search Engine(기본 검색 엔진)으로 검색합니다. 새 탭의 검색창(omnibox — 주소와 검색어를 함께 받는 입력칸)과 같은 엔진입니다.
  • 새 탭(+) 화면의 검색칸에서 검색어 앞에 ?를 붙이면 주소처럼 보이는 글자라도 무조건 검색합니다.
  • 단어를 더블클릭하면 다른 브라우저처럼 그 단어가 선택됩니다.
  • 뒤로 / 앞으로 / 새로 고침 / 중지 버튼이 있습니다. 새로 고침 버튼에 마우스를 올리면 일반 새로 고침 단축키가 보입니다.
  • 새로 고침 버튼을 오른쪽 클릭(또는 길게 누르기)하면 Reload(새로 고침)와 Hard Reload(강력 새로 고침)가 단축키와 함께 나옵니다. Hard Reload는 캐시(한 번 받은 파일을 다시 받지 않으려고 저장해 두는 임시 보관함)를 건너뛰므로, 내 컴퓨터에서 화면 파일(CSS·JS 등 — 웹 페이지의 모양과 동작을 정하는 파일)을 고치며 확인할 때 유용합니다.
단축키 (원문에는 macOS 키만 나옴)동작
Cmd+T (macOS)새 탭 열기(이 워크트리 전용)
Cmd+Option+B (macOS)오른쪽에 화면을 나눠(split) 브라우저 탭 열기. Settings → Keyboard(설정 → 키보드)에서 바꿀 수 있음
Cmd+Shift+T (macOS)마지막으로 닫은 탭 다시 열기
Cmd+F (macOS)페이지 안에서 찾기
  • 소리가 나는 탭에는 스피커 표시가 붙습니다. 그 표시를 누르면 그 탭만 음소거하거나 다시 켭니다.
  • 새 탭은 화면에 보이지 않아도 뒤에서 미리 로드되므로, 전환했을 때 주소·제목·이동 상태가 이미 준비되어 있습니다. 단, 재시작 후 되살린 탭 가운데 아직 보고 있지 않은 탭은 열어 볼 때 로드될 수 있습니다.
  • DevTools(개발자 도구) 버튼으로 현재 페이지를 검사합니다. 도구 창을 칸의 한쪽에 붙이거나(dock), 크기를 조절하거나, 공간이 부족하면 별도 창으로 떼어 낼(pop out) 수 있습니다.
  • 링크에 마우스를 올리거나 포커스를 주면 페이지 아래쪽에 목적지 주소가 표시됩니다.
  • 칸이 좁아지면 부가 도구는 overflow 메뉴(⋯)로 접히고, 이동 버튼·주소창·Cmd+F는 계속 쓸 수 있게 남습니다.
  • 터미널이나 채팅에서 연 링크는 그 링크를 준 칸 옆에 열립니다.
  • 에이전트가 브라우저를 쓰는 중이면 페이지 위에 에이전트 커서와 활동 배지가 나타납니다. 채팅에 있는 브라우저 링크를 누르면 그 페이지로 바로 이동합니다.

새 창·팝업이 열리는 규칙, HTML 미리보기와 브라우저 탭의 전환, 페이지에 포커스가 있을 때의 단축키 동작은 아래 접힌 상자에 있습니다.

새 창 규칙·미리보기 전환·포커스
  • 링크와 스크립트가 연 새 창(window.open)은 Chrome과 같은 규칙을 따릅니다. Chrome이라면 새 탭으로 열렸을 링크나, 페이지의 스크립트(웹 페이지 안에서 돌아가는 작은 프로그램)가 연 탭은 Orca의 새 탭으로 열리고, 그 탭은 원래 탭의 브라우저 프로필을 그대로 씁니다. 이름이 붙은 팝업이나 OAuth(“Google로 로그인”처럼 다른 서비스 계정으로 로그인하는 방식) 팝업은 별도 창으로 열릴 수도 있습니다.
  • HTML 미리보기는 주소창에 문서 경로를 보여 줍니다. 여기에 웹 주소를 입력하면 그 자리에서 브라우저 탭으로 바뀌고, 반대로 브라우저 탭에 워크트리 안 HTML 파일 경로를 입력하면 다시 미리보기로 바뀝니다. 사이에 다른 방문 기록이 없으면 뒤로 버튼으로 이 전환도 되돌릴 수 있습니다.
  • 페이지에 포커스가 있어도 Orca 단축키, 분할 화면 포커스 이동, 마우스의 뒤로/앞으로 버튼은 그대로 작동합니다.

워크트리별 분리(Worktree scoping)

탭은 워크트리별로 걸러져 보입니다. 다른 워크트리로 옮기면 그 워크트리의 브라우저 탭과 스크롤 위치까지 복원됩니다. 탭은 세션(로그인 상태 등)을 유지하며, 쿠키는 버튼 한 번으로 Chrome이나 Edge에서 가져올 수 있습니다(다음 절 참고).

전환 전: 워크트리 A를 고름 브라우저 칸 A의 탭 1: 로그인 페이지 A의 탭 2: API 문서 스크롤 위치 40% 워크트리 B로 전환 전환 후: 워크트리 B를 고름 브라우저 칸 B의 탭: localhost:5173 A의 탭은 숨겨짐(지워지지 않음) B의 스크롤 위치가 되살아남
같은 브라우저 칸이 워크트리를 바꾸면 그 워크트리의 탭과 스크롤 위치로 다시 채워집니다. A로 돌아가면 A의 탭 2개가 그대로 돌아옵니다.

쿠키 가져오기와 Google 로그인

쿠키란?쿠키(cookie)(웹사이트가 브라우저에 저장해 두는 작은 메모. 로그인 상태 등을 기억함)는 “이 사람은 이미 로그인했어요”라는 출입증 같은 것입니다. 평소 쓰던 브라우저의 출입증을 Orca로 옮기면 사이트마다 다시 로그인하지 않아도 됩니다.
평소 쓰던 브라우저Chrome · Edge · Vivaldi · 쿠키 파일 🎫 사이트 A 출입증 🎫 사이트 B 출입증 🎫 Google 출입증 Orca 브라우저 프로필가져오기 할 때 고른 프로필 🎫 사이트 A 출입증 🎫 사이트 B 출입증 Google은 여기서 직접 로그인 출입증 옮기기 ✕ Google은 빠짐
가져오기는 출입증(쿠키)을 Orca 프로필로 옮겨 줍니다. 단, Google 출입증은 옮기지 않으므로 Google은 Orca 안에서 직접 로그인합니다.
  • 어디서: Chrome, Edge, Vivaldi에서, 또는 쿠키 파일에서 가져올 수 있습니다.
  • 어떻게: Settings(설정)나 브라우저 툴바에서 원하는 프로필(아래 「브라우저 프로필」 절 — 쿠키를 따로 보관하는 신원 묶음)로 가져옵니다.
  • 무엇이 바뀌나: 가져온 파일에 들어 있는 도메인(사이트 주소. 예: example.com)의 쿠키만 교체합니다. 같은 프로필에 있던 관계없는 사이트의 로그인은 그대로 남습니다.
Google 쿠키는 가져오지 않습니다 가져오기 메뉴에는 Google logins aren't imported(Google 로그인은 가져오지 않음)라고 표시되고, Sign in to Google directly in Orca(Orca 안에서 Google에 직접 로그인하세요)라고 안내합니다. Google 쿠키를 건너뛴 가져오기가 끝나면, 가져오기를 실행한 호스트(가져오기가 실제로 일어난 컴퓨터) 이름을 알려 주는 별도 경고가 뜹니다. 그 호스트에서 같은 프로필로 Orca 브라우저를 열고 로그인하면 됩니다.
Google 로그인이 예전 계정에 묶여 있을 때 Settings → Browser → Session & Cookies(설정 → 브라우저 → 세션과 쿠키)에서 호스트와 사용 중인 프로필을 고르고 Clear Google cookies…(Google 쿠키 지우기)를 누른 뒤 확인합니다. 그 프로필에서 Google만 로그아웃되고 다른 사이트 쿠키는 남습니다. 오래된 원격 호스트에서는 이 동작이 지원되지 않을 수 있습니다.

USB 보안 키로 로그인하는 사이트에서 키에 계정이 여러 개 있으면, Orca가 계정을 고르는 창을 띄워 줍니다.

USB 보안 키 패스키 세부
USB 보안 키 패스키 사이트가 USB 보안 키에 저장된 “찾을 수 있는(discoverable) 패스키(비밀번호 대신 기기·보안 키로 본인 확인을 하는 로그인 방식)”를 요청했고 키에 계정이 여러 개 있으면, Orca는 로그인을 조용히 취소하지 않고 계정 선택 창을 엽니다. 원하는 계정을 고르거나 요청을 취소하면 됩니다. 운영체제에 저장된 플랫폼 패스키(예: 기기 자체에 저장된 패스키)는 아직 Orca에서 쓸 수 없고, 이 흐름은 외부 FIDO 보안 키(USB 등으로 꽂아 쓰는 표준 인증 장치)용입니다.

원격 워크트리에서 화면 그리기

회사 서버 등 원격 컴퓨터에서 작업하지 않으면 이 절은 건너뛰세요.

왜 필요할까? 작업 폴더가 내 PC가 아니라 다른 컴퓨터(예: 회사 서버)에 있을 때가 있습니다. Orca에서는 이런 작업 공간을 Workspace(워크스페이스 — 워크트리와 같은 것)라고도 부르는데, 이 장에서는 “원격 워크트리”라고 하겠습니다. 이럴 때도 브라우저를 쓸 수 있고, 연결 방식은 두 가지입니다.

  • Remote Orca Server(Orca 원격 서버)와 짝지은(paired) 원격 워크트리 — 다른 컴퓨터에 Orca 서버를 띄워 내 Orca와 짝지은 경우
  • SSH(다른 컴퓨터에 안전하게 접속해 명령을 실행하는 방법) 원격 워크트리

짝지은 원격 서버에서는 기본적으로 화면은 내 PC에서 그리고, 웹사이트와 주고받는 인터넷 통신은 원격 컴퓨터를 거쳐 나갑니다. 그래서 키보드 입력·글자 선택·팝업은 내 PC에서 자연스럽게 동작하면서도, 웹사이트 입장에서는 원격 컴퓨터에서 접속한 것으로 보입니다. 브라우저 툴바의 호스트 표시(통신이 어느 컴퓨터를 거쳐 가는지 보여 주는 표시)로 확인할 수 있습니다.

“인터넷 통신”에 들어가는 것

원격 호스트를 거쳐 나가는 통신은 HTTP(S)(웹 페이지 요청), WebSocket(실시간 연결), DNS(주소를 찾는 일), 루프백(자기 자신 컴퓨터를 가리키는 주소. 예: localhost, 127.0.0.1) 통신입니다. 입력·선택·팝업은 이 기기에서 처리되면서도 페이지의 네트워크 신원(어디서 접속했는지)은 바뀌지 않습니다.

내 PC (This device) 페이지 그리기입력·선택·팝업도 여기서 툴바 호스트 표시 원격 컴퓨터 Remote Orca Server 또는 SSH로 접속한 컴퓨터 인터넷 통신웹 요청·주소 찾기 등 다운로드 저장업로드도 여기 먼저 웹사이트 /localhost 앱원격 컴퓨터의 접속으로 봄 요청응답
기본값(This device): 화면은 내 PC에서 그리고, 인터넷 통신은 원격 컴퓨터를 거쳐 오갑니다. 점이 요청과 응답의 왕복을 나타냅니다.

Settings → Browser → Remote server workspaces(설정 → 브라우저 → 원격 서버 워크트리)에서 This device(이 기기)를 고르면 위 그림처럼 동작합니다(기본값). 입력·선택·팝업이 이 기기에서 자연스럽게 처리됩니다.

다만 이렇게 내 PC에서 그리는 페이지는 내 PC가 켜져 있어야 합니다. 에이전트가 이 페이지를 조작하는데 PC가 꺼지거나 잠들거나 연결이 끊기면 오류가 납니다.

오류 이름

이렇게 그려지는 페이지를 “client-hosted” 페이지라고 합니다. 짝지은 데스크톱이 꺼져 있거나 잠들었거나 연결이 끊기면 browser_host_unavailable 오류가 납니다.

같은 설정에서 Server (streamed)(서버, 스트리밍)를 고르면 페이지가 원격 서버에서 실행되고 화면만 내 PC로 전송됩니다. 내 PC가 연결되어 있지 않아도 돌아가므로, 오래 걸리거나 사람이 지켜보지 않는 자동화에 더 알맞습니다.

설정은 새 페이지에만 적용이미 열려 있는 페이지를 옮기지는 않습니다. 내 PC에서 그리려던 원격 페이지가 시작되지 못하면 Reopen on server(서버에서 다시 열기)를 눌러 마지막 주소로 서버 쪽 새 페이지를 열 수 있습니다. 이때 로그인 상태나 입력 중이던 양식 내용은 다를 수 있습니다.

SSH 원격 워크트리에서는 Browse through SSH workspace hosts(SSH로 접속한 컴퓨터를 거쳐 탐색) 설정이 브라우저의 인터넷 통신(주소 찾기 포함)을 SSH로 접속한 컴퓨터로 보낼지, 이 기기에서 직접 보낼지를 정합니다.

내 PC에서 그리는 원격 페이지에서 받은 다운로드는 원격 컴퓨터에 저장되고, 업로드할 파일도 먼저 그 컴퓨터에 옮겨 놓은 뒤 페이지에 전달됩니다.

터미널(글자로 명령을 입력하는 창), 마크다운 문서, 편집기에서 http(s) 링크를 눌렀을 때 Orca의 워크트리별 브라우저로 열지, 운영체제의 기본 브라우저(system browser)로 열지를 Settings → Browser → Link Routing(설정 → 브라우저 → 링크 라우팅)에서 정합니다.

그 아래 Hold Shift… 토글을 켜면, 보조키를 누른 채 클릭할 때 이번 한 번만 반대쪽 브라우저로 엽니다. 보조키는 macOS에서 ⇧⌘+클릭, Windows/Linux에서 Shift+Ctrl+클릭입니다.

클릭 방법열리는 곳
그냥 클릭Orca 내장 브라우저
보조키+클릭이번 한 번만 시스템 브라우저
클릭 방법열리는 곳
그냥 클릭시스템 브라우저(그대로)
보조키+클릭 (Hold Shift… 토글을 켰을 때)이번 한 번만 Orca 내장 브라우저

원격 워크트리의 터미널 링크도 대개 같은 선택을 쓸 수 있지만, 오래된 버전과 연결된 경우에는 시스템 브라우저로만 열립니다.

원격 터미널 링크의 조건

이 기능을 지원하는지 확인된(capability-verified) 짝지은 런타임(원격 컴퓨터에서 돌아가며 내 Orca와 짝지어진 Orca 실행 프로그램)이나 조건에 맞는 SSH 원격 워크트리는 그 터미널 링크에도 같은 Orca/시스템 브라우저 선택을 제공합니다. 오래된 런타임에서 온 링크는 시스템 브라우저로만 열립니다. 자세한 내용은 Terminal → Link actions 문서를 보세요.

Chrome 확장 실험 기능

Chrome 확장(브라우저에 기능을 덧붙이는 작은 추가 프로그램. 예: 광고 차단기)을 Orca 브라우저에도 설치할 수 있습니다. 아직 실험 기능이라 먼저 켜야 합니다.

① 실험 기능 켜기Settings에서 켜고Orca 다시 시작 ② 웹 스토어Chrome Web Store를Orca 탭에서 열기 ③ Add to OrcaOrca에 추가버튼 누르기 ④ 로컬 프로필내 PC의 브라우저프로필에서만 실행 광고 차단기는 설치돼도 아직 차단은 안 함 · 일부 확장은 작동 안 함
실험 기능을 켜고, Orca 탭에서 웹 스토어를 열어 Add to Orca를 누르면 끝입니다. 확장은 내 PC의 로컬 프로필에서만 돌아갑니다.
  1. 실험 기능 켜기Settings → Experimental → Browser extensions(설정 → 실험 기능 → 브라우저 확장)를 켜고 Orca를 다시 시작합니다.
  2. 웹 스토어 열기Orca 브라우저 탭에서 Chrome Web Store를 엽니다.
  3. 설치확장 페이지에서 Add to Orca(Orca에 추가)를 누릅니다.
제약확장은 로컬 브라우저 프로필에서만 실행됩니다. 광고 차단기는 설치는 되지만 아직 실제로 차단하지는 않습니다. Tampermonkey처럼 작동하지 않는 확장도 있습니다.

다운로드

브라우저에서 받는 파일은 진행 중이거나 막 끝난 동안 툴바 아래 다운로드 선반(shelf)에 표시됩니다. 각 줄에서 할 수 있는 일은 다음과 같습니다.

취소

진행 중인 다운로드 중단

열기

받은 파일 열기

폴더에서 보기

파일이 있는 폴더 열기

닫기(dismiss)

선반에서 그 줄 치우기

원격 페이지에서 받은 파일이 어디에 저장되는지는 위 「원격 워크트리」 절의 SSH 탭을 참고하세요.

아티팩트로 공유(Share as artifact)

워크트리 브라우저로 연 내 컴퓨터의 HTML 파일(웹 페이지 파일)은 툴바의 Share as artifact(아티팩트로 공유)를 눌러, 로그인한 Orca 계정으로 누구나 볼 수 있는 공개 링크를 만들 수 있습니다. 공유 기능을 처음 쓸 때의 사용 동의(opt-in) 절차와, 공유한 것을 관리하는 화면은 마크다운 문서 공유와 같습니다.

📄 내 HTML 파일워크트리 브라우저로 엶 Share as artifact툴바 버튼 · 파일당 10 MiB까지 🔗 공개 링크링크를 받은 누구나 보기 🖼 같은 폴더의 사진HTML이 따로 불러오는 파일 ✕ 함께 올라가지 않음 → 사진까지 한 파일에 담은 HTML로 공유
HTML 파일 하나만 올라갑니다. 그 파일이 옆에 둔 사진 파일 등을 불러 쓰고 있다면, 공유된 링크에서는 그 사진이 보이지 않습니다.
주의
  • 파일 하나당 10 MiB(약 10MB)까지만 공유됩니다.
  • 같은 폴더의 사진 파일 등, HTML이 따로 불러 쓰는 파일은 함께 올라가지 않습니다. 모든 것이 한 파일에 들어 있는 HTML을 공유하세요.
상대 경로·절대 주소와 관련 문서

HTML이 상대 경로(./img/a.png 같은)로 부르는 파일은 업로드되지 않습니다. 모든 것이 한 파일에 들어 있는(self-contained) HTML을 쓰거나 절대 주소(https://…)로 자원을 불러오세요. 관련 설정과 명령은 Settings → Artifacts와 CLI reference → Artifacts 문서에 있습니다.

뷰포트 크기 흉내(Viewport-size emulation)

브라우저 탭에 원하는 뷰포트(웹 페이지가 보이는 화면 영역) 크기를 지정하면, 칸 크기는 그대로 둔 채 휴대폰·태블릿 같은 다른 화면에서 페이지가 어떻게 보이는지 시험할 수 있습니다(반응형 레이아웃(화면 크기에 따라 배치가 바뀌는 웹 디자인) 확인). 흉내 내는 동안 페이지는 진짜 휴대폰 화면인 줄 압니다 — 그래서 실제 휴대폰에서처럼 배치가 바뀝니다.

어떻게 속이나

Orca는 내부적으로 Chrome DevTools Protocol의 기기 흉내(device emulation)를 쓰기 때문에, 페이지도 window.innerWidth와 미디어 쿼리(@media 규칙)에서 흉내 낸 크기를 그대로 받습니다.

칸 크기는 그대로 뷰포트 페이지의 생각 “나는 휴대폰 화면에 떠 있다” → 휴대폰용 배치로 바뀜
칸은 그대로 두고, 탭 안의 페이지에만 다른 화면 크기를 흉내 냅니다.

에이전트에게 맡길 때도 같은 흉내를 명령으로 켤 수 있습니다.

에이전트용 명령
에이전트가 할 때CLI로는 orca set device --name "iPhone 15" 또는 orca viewport --width 390 --height 844 --scale 3 --mobile을 씁니다. 이렇게 해야 터치 입력과 pointer: coarse까지 함께 흉내 냅니다. 새로 고침, goto, 링크 클릭 등 페이지를 다시 불러올 때마다 초기화되므로 이동 후에는 다시 실행해야 합니다.

브라우저 프로필(Browser-use profiles)

프로필은 브라우저를 특정 신원으로 돌리는 기능입니다. 로그인한 사용자, 특정 쿠키 묶음(cookie jar — 출입증 지갑), 직접 정한 user-agent(UA)(브라우저가 사이트에 “나는 어떤 브라우저입니다”라고 알리는 자기소개 문구)를 프로필마다 따로 가질 수 있습니다. 에이전트가 로그인해야 할 때, 특정 로그인 상태에서만 나는 버그를 다시 일으켜 볼 때, 여러 사용자를 흉내 낼 때 쓸모가 있습니다.

프로필 만들기

1. 설정 열기

Settings → Browser → Profiles(설정 → 브라우저 → 프로필)를 엽니다.

2. 추가

Add profile(프로필 추가)을 누르고 이름을 붙입니다.

3. (선택) 초기값 넣기

쿠키, user-agent, 뷰포트 크기를 미리 넣어 둘 수 있습니다.

4. (필요할 때) UA 꾸미기 끄기

Orca 기본 UA는 Chrome처럼 보이게 다듬은 자기소개입니다. 일부 Google 로그인처럼 이 값을 거부하는 사이트용으로는, 꾸미지 않고 Electron(Orca를 만든 바탕 기술) 원래의 UA를 쓰는 프로필을 만듭니다. 기본 프로필은 Cloudflare(많은 웹사이트가 쓰는 보안 서비스)를 쓰는 사이트에서도 잘 열리도록 Chrome처럼 다듬은 UA를 계속 씁니다.

명령으로 만들기

스크립트로 브라우저를 준비할 때는 CLI로도 만들 수 있습니다: orca tab profile create --no-ua-spoof

프로필 쓰기와 분리

브라우저 툴바에서 프로필을 고르면, 다른 것으로 바꿀 때까지 그 칸의 모든 탭이 그 프로필을 씁니다. 에이전트가 내리는 브라우저 명령도 현재 활성 프로필을 그대로 이어받습니다.

프로필 「관리자」 쿠키(출입증)local storage(사이트 저장소)cache(임시 보관함) 프로필 「일반 회원」 쿠키(출입증)local storage(사이트 저장소)cache(임시 보관함) 프로필 「Google용」 UA 꾸미기 끔쿠키·저장소·캐시 별도 각 프로필은 저장 공간(storage partition)이 따로 — 서로 섞이지 않음
프로필마다 쿠키·로컬 저장소·캐시가 분리되어 있어 서로 섞이지 않습니다.

디자인 모드(Design Mode)

디자인 모드는 Orca 브라우저를 “화면을 가리키면 그 부분의 코드로 이어지는” 도구로 바꿉니다. 켜고 나서 화면의 아무 버튼·글상자 같은 요소나 클릭하면, 그 요소의 정보가 에이전트 채팅에 첨부됩니다. 함께 가는 정보는 DOM(웹 페이지를 이루는 부품 구조), 계산된 CSS(그 부품에 실제로 적용된 색·글꼴·간격 같은 모양 값), 그리고 스크린숏입니다.

켜기

브라우저 툴바의 Design Mode 토글을 누릅니다. 마우스 커서가 요소를 고르는 도구(picker)로 바뀌고, 마우스를 올린 요소가 강조 표시됩니다. Annotate page element(페이지 요소에 메모 달기) 동작은 Settings → Shortcuts(설정 → 단축키)에서 원하는 키로 바꿀 수 있는 단축키로도 제공됩니다.

클릭하면 채팅으로 들어가는 것

HTML

그 부품의 코드(outer HTML)와 주변 조금

계산된 CSS

색, 글꼴, 간격 등 실제 적용 값

스크린숏

그 요소만 잘라 낸 이미지

소스 위치

개발 모드 소스 맵(화면 코드가 원래 어느 파일 몇째 줄인지 알려 주는 지도 파일)이 있으면 파일·줄 번호

이것들이 첨부 하나로 묶여 지금 쓰고 있는 에이전트 창에 들어가고, 사용자는 바꾸고 싶은 내용을 글로 적기만 하면 됩니다.

디자인 모드 순환

에이전트가 코드를 고치면 핫 리로드(코드를 고치면 화면이 저절로 새로 고쳐지는 기능)로 브라우저 화면이 바로 바뀝니다. 다시 클릭해 확인하고, 맞을 때까지 반복합니다.

① 요소 클릭Design Mode 켬 ② 채팅에 첨부+ 고칠 내용 입력 ③ 에이전트 수정소스 파일 편집 ④ 핫 리로드화면 저절로 새로 고침 맞을 때까지반복 →맞으면 저장(commit)
클릭 → 첨부 → 수정 → 핫 리로드(화면 자동 새로 고침) → 다시 클릭해 확인. 점이 이 순환을 계속 돕니다.

페이지 메모 모아 보내기(annotation tray)

요소마다 메모를 달아 두었다가 한꺼번에 보낼 수도 있습니다.

  • 메모 트레이에 여러 개의 메모를 쌓아 두었다가 한꺼번에 에이전트에게 보낼 수 있습니다.
  • 메모 위에 마우스를 올리고 Edit(편집)을 누르면 그 자리에서 코멘트나 의도(intent)를 고칠 수 있고, 끝나면 Save(저장) 또는 Cancel(취소)을 누릅니다.
  • Send(보내기)와 Copy(복사)는 기본적으로 메모마다 짧은 요약만 담습니다. 메모에 이미지를 붙여 넣을 수도 있습니다.
  • 페이지 전체 세부 정보까지 보내려면 Send 메뉴에서 Include page details(페이지 세부 정보 포함)를 고릅니다. Orca는 이 선택을 그 브라우저 칸에 기억합니다.
  • 프롬프트가 전달되면 Orca는 보낸 메모를 페이지에서 지웁니다. 전달이 진행되는 동안 새로 추가하거나 고친 메모는 페이지에 남습니다.

레시피: 디자인 모드로 UI 버그 고치기

시작하기 전에이 레시피는 지금 만들고 있는 앱이 내 컴퓨터에서 실행 중이고, 그 화면을 이 브라우저에서 localhost 주소(내 컴퓨터 안에서 실행 중인 앱을 여는 주소. 예: localhost:3000)로 열어 둔 상태를 전제로 합니다. 앱이 실행 중이어야 코드를 고쳤을 때 화면이 저절로 새로 고쳐지는 핫 리로드(코드를 고치면 화면이 저절로 새로 고쳐지는 기능)가 동작합니다. 앱 실행은 에이전트에게 부탁해도 됩니다(예: “앱을 실행하고 열 주소를 알려 줘”).

디자인 모드는 “저 버튼 이상해 보여”에서 “고친 결과를 저장”까지의 과정을 1분 안쪽으로 줄여 줍니다.

1. 페이지 열기

그 워크트리의 브라우저 칸을 열고 버그가 있는 페이지로 이동합니다.

2. 디자인 모드 켜기

툴바의 Design Mode 토글을 켭니다.

3. 문제 요소 클릭

망가진 요소를 클릭합니다. 그 요소가 풍부한 첨부로 에이전트 채팅에 들어갑니다.

4. 원하는 수정 적기

예: “이 padding(안쪽 여백)이 너무 좁아. 위쪽 카드들과 같게 늘려 줘.”

5. 에이전트가 수정

에이전트가 코드를 고치면 핫 리로드(화면 자동 새로 고침)로 브라우저가 바로 바뀝니다.

6. 다시 클릭해 확인

요소를 다시 클릭해 확인합니다. 아직 틀리면 4단계부터 반복합니다.

7. 작업 저장 지점 만들기

맞게 되면 commit(지금까지 바꾼 내용을 기록에 한 덩어리로 저장해, 나중에 돌아올 수 있는 지점을 만드는 일)합니다.

왜 빠를까?

스크린숏을 직접 찍을 필요도, 페이지의 부품 구조(DOM)를 뒤질 필요도, 그 부품을 가리키는 주소(선택자, selector)를 복사할 필요도 없습니다. 에이전트는 사용자가 가리킨 바로 그 요소의 코드(HTML), 실제 모양 값(계산된 CSS), 잘라 낸 이미지를 받습니다. 사람 검토자라도 받고 싶어 할 바로 그 정보입니다.

에이전트가 브라우저를 조작하는 원리

에이전트는 마우스를 쓰지 않습니다. 대신 먼저 페이지를 훑어 누를 수 있는 요소마다 번호표(@e1, @e2 …)를 붙이고, “@e3 눌러”처럼 그 번호로 누르거나 글자를 입력합니다. 사람이 보는 것과 같은 브라우저, 같은 탭이라서, 에이전트가 무엇을 하는지 화면에서 그대로 지켜볼 수 있습니다.

브라우저 화면 (로그인 페이지) 홈 (링크) 이메일 입력칸 로그인 버튼 @e1 @e2 @e3 🤖 에이전트 ① 화면을 훑어 번호표 받기 ② “@e3 눌러!” ③ 무엇이 바뀌었는지 확인
에이전트는 화면 요소에 붙은 번호표(@e1 같은 이름표, ref)를 보고 “3번을 눌러”처럼 조작합니다.
명령·규칙·오류 복구 (에이전트용 세부)

내장 브라우저는 에이전트가 Orca CLI(글자로 명령을 입력해 프로그램을 다루는 방식)로 조작합니다(orca snapshot, orca click, orca fill 등). 기본 요령은 “페이지 하나를 고정하고, 한 번 스냅숏을 찍고, 그다음 행동한다”입니다. 스냅숏은 위 그림의 “화면을 훑어 번호표 받기”에 해당합니다.

① tab currentbrowserPageId 얻기→ --page 로 고정 ② snapshot--interactive컨트롤·링크 목록 ③ ref 고르기 @e1 link "홈"@e2 textbox "이메일"@e3 button "로그인" ④ click @e3result.effects 로바뀐 점 보고 effects 로 충분하면 다시 snapshot 하지 않음 · 필요할 때만 재스냅숏
스냅숏이 화면 요소마다 @e1 같은 이름표(ref)를 붙이고, 에이전트는 그 이름표로 클릭·입력합니다.
orca tab current --json
orca goto --page <browserPageId> --url https://example.com --json
orca snapshot --page <browserPageId> --interactive
orca click --page <browserPageId> --element @e3 --json
방법무엇을 주나
snapshot --interactive컨트롤과 링크만 ref와 함께. 전체 트리의 절반 이하인 경우가 많음. 단, 오류·상태 메시지 같은 페이지 글은 빠짐
--delta저렴한 두 번째 보기(예: 아무 행동 없이 wait 한 뒤). 지난 --delta 이후 바뀐 것만 — “no change”이거나 어느 줄을 무엇으로 바꿀지. 페이지마다 기준(baseline) 하나: 이동, 큰 변화, 다른 옵션의 --delta 호출이면 전체 트리를 다시 주고 기준을 교체
--full전체 트리를 받고 기준을 새로 시작
--selector <css> · --depth <n> · --compact · --urls한 영역만 / 깊이 제한 / 빈 구조 생략 / 링크 주소 추가
exec --command "read" 또는 옵션 없는 snapshot페이지 글 읽기(마크다운으로, 또는 글이 포함된 전체 트리)
screenshot / full-screenshot보이는 화면 / 페이지 전체 PNG를 저장하고 경로 출력. 데스크톱 브라우저에서는 픽셀이 CSS 픽셀이라 그 x/y를 orca mouse에 그대로 쓸 수 있음. --annotate는 컨트롤마다 ref 라벨, --if-changed는 지난번과 같으면 저장 안 함

click, fill, type, keypress, select, check, hover, scroll, goto, back, reload, mouse 등 행동 명령은 페이지가 잠시 안정되기를 기다린 뒤 result.effects로 결과를 알려 줍니다.

  • url/title(바뀌었을 때), newTabs(새 탭과 그 browserPageId), 막히거나 열린 popups, 시작된 downloads, consoleErrors
  • page: "unchanged", 또는 추가·교체된 스냅숏 줄과 ref(full: true면 새 페이지 전체)
  • loading: true: 아직 이동 중 → wait --load load 후 snapshot. page가 없으면 읽지 못한 것 → snapshot. settled: false: 읽을 때 아직 바뀌는 중
  • JavaScript 대화상자를 연 행동은 browser_dialog_opened로 실패합니다.

다시 스냅숏할 때: page.truncated가 true일 때, wait 뒤, 탭 전환 뒤, browser_stale_ref가 났을 때, 결과에 effects가 없을 때(오래된 Orca 또는 서버 호스팅 페이지)만.

fill과 type의 차이: fill은 입력칸의 값 전체를 한 번에 넣습니다(길이 무관). type은 포커스된 요소에 실제 키를 누르듯 입력하므로 minlength/maxlength, 키 처리기, Enter·Tab이 사람이 칠 때처럼 동작합니다. 먼저 orca focus로 포커스를 주고, 페이지가 키 입력에 반응할 때 type을 씁니다. 서버 호스팅 페이지의 특수 입력칸에서 둘 다 안 되면 orca focus 후 orca inserttext --text "..."를 시도합니다.

자주 쓰는 명령 전체 목록
orca goto|back|reload --page <id> [--url <url>] --json
orca snapshot --page <id> --interactive [--delta]
orca snapshot --page <id> --selector main --depth 4
orca screenshot --page <id> [--annotate]
orca full-screenshot --page <id>
orca pdf --page <id> --json
orca click|check|hover|focus --page <id> --element <ref> --json
orca fill --page <id> --element <ref> --value <text> --json
orca type --page <id> --input <text> --json
orca select --page <id> --element <ref> --value <value> --json
orca scroll --page <id> --direction down --amount 1000 --json
orca keypress --page <id> --key Enter --json
orca upload --page <id> --element <ref> --files <paths> --json
orca wait --page <id> --text|--url|--selector|--load ... --json
orca eval --page <id> --expression <js> --json
orca dialog accept [--text <answer>] | dialog dismiss --page <id> --json
orca set device --page <id> --name "iPhone 15" --json
orca viewport --page <id> --width 390 --height 844 --scale 3 --mobile --json
orca tab list | tab create --url <url> [--split right] --json
orca tab switch|close --index <n> --json
orca cookie get | capture start | console --limit 50 | network --limit 50 --page <id> --json
orca exec --page <id> --command "read" | "get text @e3" --json
  • ref(@e1 등)는 snapshot이 붙이며, 한 탭 안에서만 유효하고 페이지 이동이나 탭 전환으로 무효가 됩니다.
  • 한 페이지에 작용하는 명령에는 항상 --page <browserPageId>를 붙입니다. ID는 orca tab current --json의 result.tab.browserPageId나 orca tab create --json의 result.browserPageId에서 얻어 작업 내내 씁니다. tab list, tab current, tab create, open-url은 --page를 받지 않고, tab switch/tab close는 --index나 --page 중 하나만(둘 다 주면 --page 우선). tab current는 고정한 탭이 아니라 지금 라우팅된 탭을 보여 줍니다. 사용자가 특정 탭을 말하면 tab list --json에서 URL·제목으로 찾습니다.
  • --page가 없으면 워크트리의 현재 탭으로 갑니다. 에이전트가 최근 약 20초 안에 명령을 냈다면 사용자가 다른 탭을 골라도 에이전트 탭이 유지되고, 그 뒤에는 사용자가 고른 탭으로 넘어갑니다. tab switch 후에는 새 페이지의 ID를 씁니다.
  • 페이지가 연 팝업 창(로그인·결제 등)은 tab list에 openerBrowserPageId가 붙은 popup-<n>으로 나옵니다. 클릭이 아무 일도 안 한 것 같으면 tab list를 보고 --page popup-<n>으로 조작합니다. 닫히면 원래 페이지에서 계속합니다.
  • 브라우저 명령은 기본적으로 현재 워크트리 대상입니다. --page는 다른 워크트리 페이지에도 닿지만 --worktree <selector>를 함께 주면 그 범위로 제한됩니다. --worktree all은 의도할 때만.
  • tab list는 탭 막대의 모든 탭을 보여 줍니다. 재시작 뒤 사용자가 열지 않은 탭은 loaded: false이고, tab switch나 --page 명령을 쓰면 사용자 화면을 바꾸지 않고 뒤에서 로드됩니다.
  • tab create --split <right|left|down|up>는 탭 대신 호출한 터미널 옆 새 칸에 열고, 포커스는 터미널에 남습니다.
  • 탭은 orca tab list/create/close/switch로, 기기 흉내는 orca set device/orca viewport --mobile로, 업로드는 orca upload로 — exec --command "..."로 하지 않습니다(UI 상태 동기화·터치 입력 때문). 목록에 없는 기능만 orca exec --command "<agent-browser 명령>"(예: "is visible @e3")로 하며, help 명령은 없습니다.
  • upload는 파일 입력칸 또는 파일 선택 창을 여는 버튼을 받습니다(다른 도메인 iframe 포함). 서버 호스팅 페이지에서는 파일 입력칸의 ref를 줍니다.
  • 비동기 변화 뒤에는 고정 시간 대기 대신 wait --text/--url/--selector/--load를 씁니다. --load networkidle은 폴링·웹소켓·스트리밍이 있으면 끝나지 않으니 피합니다.
  • client-hosted 페이지는 데스크톱이 온라인이어야 하므로, 길거나 무인 자동화에는 서버 호스팅 페이지가 낫습니다.
오류뜻과 대처
browser_no_tab탭이 없음 → orca tab create --url <url> --json
browser_stale_refref가 낡음 → 같은 페이지에서 snapshot 후 새 ref로 재시도
browser_element_not_interactable그 요소에 그 명령을 쓸 수 없음(입력칸 아님, 비활성, 읽기 전용, <select> 아님, 파일 선택 창 안 열림 등 — 메시지에 이유) → 재스냅숏 후 맞는 ref. 직접 만든 드롭다운은 클릭 후 옵션 클릭
browser_tab_not_found전환·닫기 전에 orca tab list --json
browser_dialog_open / browser_dialog_openedalert·confirm·prompt가 열림(오류에 내용 인용) → 다른 명령 전에 dialog accept(prompt면 --text, 없으면 기본값) 또는 dialog dismiss. 연 명령이 이미 효과를 냈을 수 있으니 반복 전에 확인
browser_host_unavailable페이지를 그리는 데스크톱이 오프라인 → 다시 켜거나, 데스크톱 세션보다 오래가야 하면 서버 배치로 페이지를 다시 만듦
한눈에 정리
  • 워크트리마다 진짜 Chromium 브라우저가 있고, 탭·스크롤 위치는 워크트리별로 저장·복원됩니다.
  • (macOS) Cmd+T 새 탭, Cmd+Shift+T 닫은 탭 복원, Cmd+F 찾기, Cmd+Option+B 오른쪽 분할 탭. Hard Reload는 캐시를 건너뜁니다.
  • 쿠키는 Chrome·Edge·Vivaldi·파일에서 가져오되 Google 로그인은 Orca 안에서 직접 해야 합니다.
  • 원격 워크트리는 기본적으로 화면은 내 PC, 인터넷 통신은 원격 컴퓨터를 거침. 사람이 지켜보지 않는 자동화엔 Server (streamed).
  • 링크 라우팅·Hold Shift…로 Orca/시스템 브라우저를 고르고, 확장은 실험 기능, 아티팩트 공유는 파일당 10 MiB(약 10MB)·같은 폴더의 사진 등 따로 불러오는 파일은 제외.
  • 프로필은 쿠키·저장소·캐시가 완전히 분리된 신원이며, 에이전트 명령도 활성 프로필을 따릅니다.
  • 디자인 모드: 요소 클릭 → HTML·CSS·스크린숏·소스 위치가 채팅에 첨부 → 에이전트 수정 → 핫 리로드(화면 자동 새로 고침) → 다시 확인 → commit(저장 지점 만들기).
  • 에이전트는 마우스 대신 화면 요소에 번호표를 붙이고, 그 번호표를 보고 누르거나 입력합니다. 같은 브라우저·같은 탭이라 하는 일을 화면에서 지켜볼 수 있습니다.

출처: onorca.dev/docs/browser/overview · onorca.dev/docs/browser/design-mode · onorca.dev/docs/browser/profiles · onorca.dev/docs/recipes/design-mode-fix · 보조: Orca CLI 내장 브라우저 명령 안내(로컬)

CHAPTER 05

파일 편집과 보기 — 에디터, 마크다운, 뷰어, 파일 탐색기

Orca 안에서 파일을 직접 고치고, 문서를 보기 좋게 다듬고, PDF·이미지·영상·표·노트북을 열어 보고, 파일을 찾아 에이전트에게 건네는 방법을 다룹니다.

이 장에서 배우는 것
  • 코드 에디터(Monaco)의 자동 저장, 다른 쪽이 파일을 바꿨을 때의 처리, 단축키, 화면 설정
  • 마크다운 문서 에디터의 슬래시 메뉴·콜아웃·표·목차·리뷰 노트·공유 링크
  • HTML·Mermaid·PDF·이미지·오디오/비디오·CSV·Jupyter 노트북 뷰어
  • 파일 탐색기의 정렬·git 상태 색·오른쪽 클릭 메뉴, 바깥에서 파일을 끌어다 놓는 법
처음이라면 이것만

HTML 미리보기, Jupyter 노트북, 그리고 🔧 표시가 붙은 접힌 상자는 필요할 때 펼쳐 보면 됩니다.

한눈에 보는 편집 영역

Orca의 각 워크트리(에이전트마다 따로 꺼내 주는 프로젝트 폴더의 작업용 복사본)에는 왼쪽에 파일 탐색기, 가운데에 파일을 여는 탭이 있습니다. 파일을 열면 종류에 맞는 화면이 자동으로 열립니다. 코드는 Monaco 에디터, 마크다운 문서는 리치 에디터, PDF·이미지·영상·표·노트북은 전용 뷰어로 열립니다.

쉽게 말하면Orca는 "모든 기능이 다 든 개발 도구(IDE)"보다는 "잘 만든 메모장 + 각종 미리보기 창"에 가깝습니다. 원문도 Orca가 일부러 editor-first, not IDE-first(IDE보다 에디터 우선)라고 말합니다. 그래서 코드의 실수를 찾아 주는 검사 도구(원문 용어로 타입 검사기·린터)는 Orca에 들어 있지 않습니다. 문서의 맞춤법 검사기 같은 이 도구는 터미널(명령을 글자로 입력하는 창)에서 따로 실행하면 됩니다.
파일 탐색기 ▸ docs/ ▸ src/ app.ts (수정됨) README.md design.pdf data.csv app.ts README.md design.pdf 탭 영역 — 파일 종류별로 알맞은 화면이 열림 코드 → Monaco 에디터 (자동 저장) .md(마크다운 문서) → 리치 에디터 PDF·이미지·영상·CSV·노트북·HTML → 전용 뷰어
왼쪽은 실제 디스크와 실시간으로 맞춰지는 파일 탐색기, 오른쪽은 파일마다 다른 화면이 열리는 탭 영역입니다.

코드 에디터(Monaco)와 자동 저장

Orca의 코드 에디터는 Monaco입니다. VS Code(널리 쓰이는 코드 편집 프로그램)가 쓰는 바로 그 편집기라서 VS Code를 써 본 사람은 거의 같은 감각으로 쓸 수 있고, 여기에 Orca만의 몇 가지 조정이 더해졌습니다.

자동 저장과 "디스크에서 바뀜" 배너

무엇인가 — 파일은 저절로 저장됩니다. 다른 곳을 클릭해 에디터에서 벗어날 때, 그리고 잠깐 타이핑을 멈추고 있을 때 저장됩니다. 그래서 다른 편집기에서 흔히 보는 "아직 저장 안 됨" 표시 점이 없습니다. 평소에는 저장 안 된 변경이 생기지 않기 때문입니다.

왜 검사가 필요한가 — Orca에서는 사람과 에이전트가 같은 파일을 만질 수 있습니다. 그래서 Orca는 저장하기 직전에 "이 탭이 마지막으로 파일을 읽거나 저장한 뒤에 디스크의 파일이 바뀌었나?"를 확인합니다.

내가 편집다른 곳 클릭또는 잠깐 멈춤 저장 전 검사 이 탭이 마지막으로 읽거나 쓴 뒤 디스크 파일이 바뀌었나? 아니오 그대로 저장표시 점 없이 조용히 끝 예 자동 저장 멈춤 + 배너 비교 · 다시 불러오기 내 편집 유지 · 직접 골라 덮어쓰기 고를 때까지 내 편집은 탭에 그대로
자동 저장은 디스크가 바뀌지 않았을 때만 진행됩니다. 바뀌었으면 멈추고 사용자에게 고르게 합니다.
1. 평소처럼 편집

파일을 고치고 다른 탭이나 터미널을 클릭하면(또는 잠시 손을 멈추면) 자동 저장됩니다.

2. 그 사이 에이전트가 같은 파일을 수정

탭이 마지막으로 읽거나 쓴 뒤 디스크의 파일이 바뀌었습니다. 다음 저장 직전 Orca가 이를 알아챕니다.

3. 자동 저장 멈춤 + changed-on-disk(디스크에서 바뀜) 배너

배너가 뜨고 자동 저장이 멈춥니다. 내가 친 내용은 탭 안에 그대로 남아 있어 사라지지 않습니다.

4. 네 가지 중 선택
  • compare(비교) — 디스크 쪽 내용과 내 편집을 비교합니다.
  • reload(다시 불러오기) — 디스크 쪽 내용으로 탭을 새로 고칩니다.
  • keep your edits(내 편집 유지) — 탭의 내용을 그대로 둡니다.
  • overwrite(덮어쓰기) — 디스크 쪽 내용을 내 편집으로 바꿉니다. 내가 직접 골라야만 일어납니다.

SSH로 접속한 원격 컴퓨터의 파일을 열 때만 해당하는 내용(같은 경로의 파일이라도 컴퓨터마다 편집 내용을 따로 보관)은 아래 접힌 상자에 있습니다.

호스트별 편집 내용 분리 (SSH 원격 작업)

컴퓨터(호스트)마다 편집 내용을 따로 보관

Orca는 내 컴퓨터(로컬)뿐 아니라 SSH(다른 컴퓨터에 안전하게 접속해 그곳 파일을 쓰는 방법)로 접속한 원격 컴퓨터의 파일도 엽니다. 이때 경로가 똑같은 파일이라도 컴퓨터(호스트)가 다르면 에디터 내용과 Undo(실행 취소) 기록을 따로 보관합니다. 그래서 원격의 /app/main.ts를 열었을 때 로컬 /app/main.ts의 실행 취소 기록이 섞여 나오는 일이 없습니다. 반대로 같은 로컬 파일을 탭 두 개로 열면 두 탭은 하나의 편집 내용 묶음을 함께 씁니다.

로컬 컴퓨터 탭 1: /app/main.ts 탭 2: /app/main.ts 편집 묶음 A내용 + Undo 공유 SSH 원격 컴퓨터 탭 3: /app/main.ts 편집 묶음 B따로 보관 서로 안 섞임
같은 경로라도 컴퓨터가 다르면 편집 내용 묶음이 따로입니다. 같은 로컬 파일의 탭끼리는 한 묶음을 함께 씁니다.

단축키와 변경 보기(Changes view)

멀티 커서·찾기·정의로 이동

단축키 (원문에는 macOS 키만 나옴)하는 일
Cmd+D (macOS)지금 선택한 단어의 다음 같은 단어를 추가로 선택합니다. 여러 번 누르면 커서가 여러 개가 되어 한꺼번에 고칠 수 있습니다(멀티 커서).
Cmd+F (macOS)지금 파일 안에서 찾기. 글자를 선택한 상태로 누르면 그 글자가 검색창에 미리 채워집니다.
Cmd+Shift+F (macOS)워크트리 전체에서 찾기.
Cmd+클릭 (macOS)정의로 이동(go to definition). 예를 들어 코드에 쓰인 어떤 기능의 이름을 Cmd+클릭하면, 그 기능을 처음 만들어 둔(정의한) 곳으로 바로 이동합니다. 그 언어용 확장 기능이 지원하는 경우에만 동작합니다.

Changes view mode — 탭 안에서 바로 "무엇이 바뀌었나" 보기

어느 에디터 탭에서든 Changes view mode(변경 보기 모드)를 켜면, 커서 위치는 그대로 둔 채 그 파일이 "마지막 커밋과 지금 파일"을 비교하는 화면으로 바뀝니다. 커밋은 git(파일의 변경 이력을 기록하는 도구)에 남긴 기록입니다(마지막 커밋을 원문 용어로 HEAD라고 함). 빨간 줄은 지운 줄, 초록 줄은 더한 줄입니다. 한 번 더 켜고 끄면 일반 파일 화면으로 돌아옵니다.

파일 저장과 커밋은 다릅니다파일 저장 = 지금 내용을 디스크에 쓰는 일(앞 절의 자동 저장). 커밋 = 엑셀의 버전 기록처럼 나중에 돌아올 수 있는 지점을 남기는 일. 변경 보기는 자동 저장된 지금 파일을 마지막 커밋과 비교합니다.
회의메모.md — Changes view
1 # 주간 회의 메모
- 2 날짜: 11월 3일
+ 2 날짜: 11월 4일 ◀ n / p : 바뀐 덩어리 사이를 다음 / 이전으로 이동
3 참석: 김, 이, 박
+ 4 결정: 금요일에 배포 ◀ s : 이 변경을 다음 커밋 목록에 올리기(stage)
  • n / p — 다음 / 이전 변경 덩어리(hunk)로 이동
  • s — 그 변경을 stage(다음 커밋에 넣을 목록에 올려 두기)
  • 단축키는 diff 뷰어(두 버전의 차이를 보여 주는 화면, 6장)와 같습니다.
원문 표현

원문: "an in-tab HEAD-vs-working-tree diff". HEAD는 마지막 커밋 상태, working tree(작업 트리)는 아직 커밋하지 않은 변경까지 포함한 지금 디스크의 상태입니다.

화면 설정 — 줄 바꿈·미니맵·글꼴·언어 지원

파일 에디터는 긴 줄을 기본으로 접어서(Word Wrap) 화면 폭 안에 보여 줍니다. 끄고 켜는 방법은 세 가지입니다.

  1. 탭 메뉴에디터 탭의 ⋯ 메뉴에서 Word Wrap 토글
  2. 단축키Alt+Z (VS Code와 같음). Settings → Shortcuts(설정 → 단축키)에서 다른 키로 바꿀 수 있습니다.
  3. 기본값 설정Settings → General → Editor Word Wrap(설정 → 일반 → 에디터 줄 바꿈)
헷갈리기 쉬운 점이 설정은 Diff Word Wrap과 별개입니다. Diff Word Wrap은 변경 비교(diff) 화면에만 적용됩니다.

미니맵은 에디터 오른쪽에 파일 전체를 아주 작게 줄여 보여 주는 세로 띠입니다(VS Code 스타일). 기본으로 꺼져 있고, Settings → Appearance(설정 → 모양)에서 켤 수 있습니다.

기본적으로 에디터와 변경 비교(diff) 화면은 터미널과 같은 글꼴을 씁니다.

  • Settings → Appearance → Editor Font Family(에디터 글꼴)를 비워 두면 터미널 글꼴을 계속 따라갑니다.
  • 글꼴을 지정하면 에디터에만 그 글꼴이 적용됩니다. 메뉴·버튼 같은 화면 글꼴은 따로 유지됩니다.

문법 색칠(코드의 종류별로 글자색을 달리 칠해 읽기 쉽게 하는 기능)은 Monaco가 기본으로 지원하는 언어 전부에 더해 몇 가지 언어를 추가로 지원합니다(목록은 아래 접힌 상자).

Orca는 IDE(모든 기능이 다 든 개발 도구)보다 에디터를 지향하므로, 코드 검사 도구(타입 검사기·린터)는 터미널 창에서 실행합니다.

추가 지원 언어 목록·Nim·Typst 색칠 방식
SolidityTwig 템플릿Quarto .qmdR Markdown .Rmd셸 시작 파일 .bashrc · .zshrc 등NimTypst

Nim과 Typst는 Orca가 공통으로 쓰는 TextMate 문법 계층(shared TextMate grammar layer)으로 색칠합니다. 이 방식 덕분에 아주 긴 한 줄이 있어도 창이 멈추지 않습니다.

마크다운 문서 에디터(리치 에디터)

마크다운(#를 붙이면 제목, -를 붙이면 목록이 되는 식으로, 간단한 기호로 서식을 다는 글 문서 형식. 확장자 .md) 파일은 기본으로 리치 에디터로 열립니다. 기호 대신 완성된 모양(제목은 큰 글씨, 목록은 점)을 보면서 바로 고치는 방식이라 워드 프로그램과 비슷합니다. 슬래시 메뉴, 도구 모음, 이미지·코드 미리보기, 내부 링크 자동완성을 갖추고 있습니다.

  • Cmd+Shift+M (macOS) — 기호가 그대로 보이는 원문(raw) 에디터와 리치 에디터를 언제든 오갑니다.
  • 운영체제의 "다음으로 열기" — Orca는 macOS·Windows·Linux에서 마크다운 파일의 Open With(다음으로 열기) 목록에 자신을 등록합니다. 원래 쓰던 기본 편집기를 바꾸지는 않습니다. 리치 에디터로 열고 싶을 때 그 메뉴에서 Orca를 고르면 됩니다.
큰 파일과 특수 문법
  • 600 KB보다 큰 파일은 타이핑이 느려지지 않도록 원문(raw) 에디터로 먼저 열립니다. 안내 배너에서 Open anyway(그래도 열기)를 누르면 리치 에디터로 열리며, 이 선택은 그 탭을 닫을 때까지 유지됩니다.
  • 리치 에디터가 망가뜨리지 않고 지킬 수 없는 마크다운 문법을 쓴 파일은 원문 에디터에 머뭅니다.
.md 열기 지킬 수 없는 문법?예 → 원문 에디터 600 KB 초과?아니오 → 리치 원문 먼저 + 배너Open anyway → 리치 리치 에디터Cmd-Shift-M로 원문 전환
마크다운 파일이 어떤 에디터로 열리는지 정해지는 흐름.

마크다운 쓰기 도구 — 슬래시 메뉴·콜아웃·링크·검색

슬래시 메뉴와 토글

빈 줄에서 /를 치면 슬래시 메뉴가 열립니다. 넣을 수 있는 것: 제목, 목록, 코드 블록, 콜아웃, 이미지, mermaid 다이어그램, 토글(눌러서 접었다 펴는 블록).

notes.md
/tog▏
/toggle-text — 접히는 메모
/toggle-h1 — 제목 1 모양 토글
/toggle-h2 … /toggle-h5
  • /toggle-text — 접었다 펼 수 있는 메모.
  • /toggle-h1 … /toggle-h5 — 접힌 상태의 요약 줄이 제목(1~5단계)처럼 보이게 합니다.
  • 토글 안에 토글을 넣어도 그 자리에서 바로 고칠 수 있습니다.
  • 토글은 표준 <details> / <summary> 형식으로 저장됩니다. 그래서 Orca 밖에서 미리보기해도 똑같이 접힙니다.

콜아웃 — 색깔 있는 알림 상자

인용문(>로 시작하는 줄)의 첫 줄에 아래 다섯 표시 중 하나를 쓰면, 표시 글자가 그대로 보이는 평범한 인용 대신 아이콘과 제목이 달린 색 상자로 그려집니다(GitHub 방식). 미리보기를 포함해 Orca가 마크다운을 읽기 전용으로 보여 주는 모든 곳에 적용됩니다.

이렇게 쓰면 → 이렇게 보입니다
> [!NOTE]
> 참고할 내용
> [!TIP]
> [!IMPORTANT]
> [!WARNING]
> [!CAUTION]
Note — 참고
Tip — 도움말
Important — 중요
Warning — 경고
Caution — 주의

위키식 링크 — [[를 치면 워크트리 안의 파일 경로가 자동완성되고, 고르면 지금 문서 기준의 상대 경로 링크가 들어갑니다.

회의메모.md
자세한 내용은 [[보고▏
docs/보고서.md
docs/보고서-초안.md

보이는 글자로 검색 — 에디터 안 마크다운 검색은 기호가 아니라 화면에 보이는 글자를 찾습니다.

검색어찾아 주는 제목 (원문에 쓴 방식이 달라도)
Install# Install 로 쓴 제목, <h1>Install</h1> 로 쓴 제목 모두

마크다운 검토·정리 도구 — 리뷰 노트·프런트 매터·표·목차

리뷰 노트(주석) 달기

리치 에디터에서 문서를 검토할 때, 화면에 보이는 글자를 선택하고 바로 메모를 달 수 있습니다. 원문(raw) 화면으로 돌아갈 필요가 없습니다. Orca는 메모를 선택한 원문 위치에 묶어 두므로, 문서를 계속 고쳐도 메모가 제자리에 보입니다.

기획안.md
출시일은 12월 첫째 주로 정했습니다.
📝 리뷰 노트: 날짜 확정됐는지 확인 필요

Add Review Note(리뷰 노트 추가) 단축키: Cmd+Shift+A / Ctrl+Shift+A (기본값, Settings → Shortcuts에서 변경 가능).

프런트 매터

프런트 매터(문서 맨 위 --- 사이에 적는 제목·날짜·태그 같은 정보 묶음. 블로그 글 등에서 많이 씀)는 YAML·TOML(이런 정보를 적는 설정 형식의 이름) 어느 쪽이든 리치 에디터와 미리보기에 기본으로 보입니다.

post.md · More actions (…) → Hide front matter
---
title: 11월 소식지
date: 2026-11-04
---
11월 소식지 — 본문이 여기서 시작합니다…
  • 본문만 보고 싶으면 에디터의 More actions (…) 메뉴 → Hide front matter(프런트 매터 숨기기).
  • 같은 메뉴의 Show front matter로 다시 보입니다.
  • 이 설정은 파일마다 따로입니다. 한 문서에서 숨겨도 다른 문서는 그대로입니다.

표 편집

키동작
Tab / Shift+Tab다음 / 이전 칸. 마지막 칸에서 Tab을 누르면 새 행이 추가됩니다.
Enter아래 칸으로 이동. 마지막 행이면 행을 추가합니다.
완전히 빈 행에서 Backspace그 행을 지웁니다(표에 남은 마지막 행이면 표 전체를 지웁니다).
행에 다른 내용이 있는데 빈 칸에서 Backspace이전 칸으로 이동합니다.
  • Shift+Tab은 목록 항목이나 코드 블록에서 선택한 줄의 들여쓰기를 줄이는 데도 씁니다.
  • 커서가 표 안에 있으면 도구 모음에 행·열 추가/삭제 버튼이 나타납니다.
  • 표 칸을 오른쪽 클릭하면 같은 명령이 메뉴에 나옵니다. Table 하위 메뉴는 표 칸을 오른쪽 클릭했을 때만 나타납니다.

목차(Table of Contents)

긴 문서에서는 에디터 머리줄의 Table of Contents 버튼(나무 모양 아이콘)을 누르면 에디터 왼쪽에 제목 목록이 붙어 열립니다. 제목을 누르면 그 위치로 이동하고, 접기/펼치기로 깊이 들어간 부분도 읽기 쉽게 정리됩니다. 리치 모드와 미리보기 모드에서 쓸 수 있습니다.

업무매뉴얼.md · 🌲 Table of Contents
▾ 1. 시작하기
  1.1 계정 만들기
  1.2 첫 로그인
▸ 2. 자주 묻는 질문
1.1 계정 만들기

← 왼쪽 목차에서 누른 제목으로 본문이 이동합니다.

아티팩트로 공유 — 공개 보기 링크 만들기

에디터 머리줄의 Share as artifact(아티팩트로 공유)는 열린 마크다운 파일을, 로그인한 Orca 계정을 통해 누구나 볼 수 있는 공개 보기 링크로 게시합니다.

① 설정에서 허용Settings → Artifacts기본은 꺼짐 ② Share as artifact마크다운 파일 게시10 MiB(약 10MB)까지 ③ 공개 링크Republish(다시 게시)→ 같은 링크 갱신 ④ 관리·삭제사이드바Artifacts 페이지
허용 설정 → 게시 → (고친 뒤) 다시 게시 → 관리·삭제 순서입니다.
  1. 먼저 허용 설정Settings → Artifacts → Allow publishing public artifact links(공개 아티팩트 링크 게시 허용)를 켭니다. 기본은 꺼짐입니다.
  2. 게시파일 크기는 10 MiB(약 10MB)까지 지원합니다.
  3. 다시 게시(Republish)Orca가 파일과 링크의 연결을 아직 기억하면 같은 링크의 내용이 바뀝니다.
  4. 관리·삭제사이드바 Artifacts 페이지에서 링크를 관리하거나 지웁니다.
일반적인 주의공개 링크이므로, 올리기 전에 남이 봐도 괜찮은 문서인지 한 번 확인하세요.
에이전트·스크립트에서 공유하기

orca artifacts share|update|list|delete 명령으로 같은 일을 할 수 있습니다(CLI 참고 → Artifacts).

파일 종류별 뷰어 고르기

Orca에는 프로젝트 폴더에 흔히 있는 형식을 위한 뷰어(파일을 열어 보는 전용 화면)가 들어 있습니다. 확장자(파일 이름 끝의 .pdf 같은 부분)에 따라 아래처럼 열립니다.

파일 열기확장자 확인 코드·텍스트Monaco 에디터 (자동 저장) .md리치 마크다운 에디터 (Cmd-Shift-M → 원문) .html격리된 브라우저 미리보기 .mmdMermaid 전용 뷰어 (이동·확대) .pdfPDF 뷰어 (확대·글자 선택·위치 기억) .png .jpg .svg .webp .gif이미지 뷰어 + 이미지 비교 .mp3 .wav .mp4 .mov …오디오·비디오 플레이어 (스트리밍) .csv .tsv고칠 수 있는 표 (약 1MB 이상은 보기 전용) .ipynbJupyter 노트북 (셀 실행)
확장자에 따라 열리는 뷰어. 각 뷰어의 자세한 기능은 아래 소절에서 설명합니다.

HTML 미리보기

무엇인가 — .html(웹 페이지 파일)을 Open in Orca Browser(Orca 브라우저에서 열기) 또는 Open Preview to the Side(옆에 미리보기 열기)로 열면, 웹 페이지 모양 그대로 볼 수 있습니다. 내 컴퓨터, SSH로 접속한 컴퓨터, 페어링된 런타임(paired runtime)(내 Orca와 짝지어 연결해 둔 다른 컴퓨터의 Orca 서버. 4장 「원격 워크트리」 참고)에 있는 파일 모두 됩니다.

어떻게 안전하게 보여 주나 — Orca는 문서를 내 컴퓨터의 샌드박스(바깥과 격리된 안전한 상자. 그 안의 페이지가 내 컴퓨터 파일을 마음대로 못 건드림) 브라우저 탭으로 그립니다. 파일과 그 파일이 쓰는 이미지 같은 자료는 Workspace(워크스페이스 — 워크트리와 같은 것)의 파일 연결(Orca가 그 워크트리 폴더의 파일을 읽어 오는 통로)을 통해서만 읽습니다. 그래서 원격 서버의 디자인 문서도 선명하게 보이면서, 내 컴퓨터의 다른 파일은 드러나지 않습니다.

파일이 있는 곳 로컬 / SSH / 페어링 런타임 design.html ./img/logo.png (함께 쓰는 자료) 다른 폴더 → 승인해야 읽음 워크트리 파일 연결 격리된 미리보기 탭 외부 웹 링크 → 확인 후 일반 브라우저 탭 다운로드 → 막힘 허락한 곳의 웹 글꼴 → 표시됨 내 컴퓨터의 다른 파일 → 드러나지 않음 Preview options: 다시 읽기 · 원본 · 경로 복사
파일과 자료는 워크트리 연결로만 읽고, 미리보기 탭은 격리된 상자 안에 갇혀 있습니다.
  • 폴더 권한 — 미리보기가 다른 폴더를 더 읽어야 하면 먼저 묻고, 승인한 폴더만 그 탭에 허용합니다.
  • 외부 링크 — 바깥 웹 주소(HTTP(S)) 링크는 확인을 받은 뒤 일반 Orca 브라우저 탭에서 열립니다.
  • 다운로드 — 문서 미리보기 안에서는 다운로드가 꺼져 있습니다.
웹 글꼴·미리보기 옵션·주소창·페어링 런타임
  • 웹 글꼴 — 내가 허락한 제공자(예: Google Fonts 링크)에서 글꼴을 요청하는 페이지는 대체 글꼴 대신 그 글꼴로 그려집니다.
  • Preview options(미리보기 옵션) — 디스크에서 다시 불러오기, 원본 파일 열기, 전체 경로 또는 워크트리 기준 상대 경로 복사.
  • 문서 칩 = 주소창 — 미리보기의 문서 칩을 고쳐 웹 URL을 넣으면 그 탭이 일반 브라우저 탭이 됩니다. 반대로 브라우저 탭에서 워크트리의 HTML 경로를 넣으면 다시 미리보기가 됩니다. 사이에 다른 페이지 기록이 없으면 뒤로(Back)로 둘 사이를 오갈 수 있습니다.
  • 페어링 런타임 — HTML 파일이 워크트리 안에 있어야 합니다. 아주 오래된 페어링 서버는 이미지 같은 바이너리 자료 없이 문서를 그릴 수 있으니, 원격 이미지가 안 보이면 서버를 업데이트하세요.

Mermaid · PDF · 이미지 · 오디오/비디오

Mermaid(글자로 적으면 순서도·관계도를 그려 주는 다이어그램 언어) 다이어그램은 마크다운 미리보기 안에서 그 자리에 바로 그려집니다. 따로 떨어진 .mmd 파일은 이동(pan)·확대(zoom)가 되는 전용 뷰어로 열립니다.

스크롤, 확대, 글자 선택이 됩니다. 프로젝트 폴더에 함께 넣어 둔 설계 문서를 볼 때 유용합니다.

  • 확대 — 트랙패드 핀치, Ctrl+스크롤, 또는 Cmd/Ctrl + = / - / 0. 마우스 커서 아래 지점을 기준으로 확대됩니다.
  • 확대 비율 기억 — 탭을 바꿔도, Orca를 다시 켜도 유지됩니다.
  • 읽던 위치 기억 — 다른 탭에 갔다 돌아오면(같은 세션 안에서 닫았다 다시 열어도) 페이지와 페이지 중간 위치까지 복원됩니다. 단, 위치는 Orca를 켜 둔 동안만 기억하며 다시 시작하면 지워집니다.

지원 형식: .png .jpg .svg .webp .gif.

Image-diff 모드(이미지 비교)는 같은 이미지 파일의 두 버전을 나란히 놓고 비교합니다.

오디오·비디오 파일은 Orca 안에서 재생·정지 같은 기본 조작 버튼으로 재생됩니다.

.mp3.wav.ogg.m4a.aac.flac.mp4.mov.webm.mkv.avi
  • 스트리밍 — 데스크톱 앱은 로컬·SSH·페어링 서버의 파일을 조금씩 받아 가며 재생하므로, 큰 영상도 파일 전체를 받기 전에 재생이 시작됩니다.
  • Open in Default App(기본 앱으로 열기) — 로컬 파일은 운영체제 기본 플레이어로 열 수 있습니다.
  • 재생할 수 없는 파일 — Orca가 읽을 수 없는 파일은 빈 화면 대신 재생 오류로 표시됩니다.

CSV · TSV 표

.csv·.tsv(쉼표나 탭으로 칸을 나눈 표 데이터 파일. 엑셀에서 내보내기 할 때 자주 생김) 파일은 엑셀처럼 그 자리에서 고칠 수 있는 표로 열립니다.

users.csv · Delimiter: Auto
idnamesite
1Kim▏https://…
2Lee—
  • 칸을 클릭해 고치고, 범위를 선택해 복사/붙여넣기.
  • 행·열 메뉴로 행·열 추가/삭제, Columns(열) 메뉴로 열 순서 바꾸기.
  • 정렬·필터는 보기만 바꿀 뿐 파일 안의 행 순서는 바꾸지 않습니다.
  • 칸 전체가 웹 주소(http(s))면 클릭해서 열립니다.
  • 조절한 열 너비는 보기를 바꾸거나 앱을 다시 켜도 기억됩니다.
  • 파일의 숨은 형식은 그대로 — 엑셀처럼 칸을 고쳐도, 파일이 원래 갖고 있던 저장 형식(눈에 안 보이는 표시 문자, 줄 끝 방식, 따옴표 방식 등)은 바뀌지 않습니다. 기준은 언제나 파일 자체입니다.
  • 구분자 — 칸을 나누는 문자(쉼표·세미콜론·탭)를 자동으로 알아냅니다. Delimiter(구분자) 선택기로 Auto / Comma / Semicolon / Tab을 직접 고를 수 있습니다(세미콜론으로 나뉜 내보내기 파일에 유용).
  • 원문 보기 — 도구 모음에서 글자 그대로의 원문(raw) 보기로 바꿀 수 있습니다.
1 MiB(약 1MB) 이상 파일은 보기 전용큰 파일은 고칠 수 없는 미리보기로 열려 빠르게 보여 줍니다. 표에서 고치려면 파일이 이 크기보다 작아야 하며, 큰 파일은 원문(raw) 보기로 바꿔 고치세요.
보존되는 형식·큰 파일 처리 방식
  • 편집해도 파일의 BOM(파일 맨 앞의 보이지 않는 인코딩 표시), record endings(줄 끝 문자), quoting(따옴표 방식), 마지막 줄바꿈이 그대로 보존됩니다. "The file stays the source of truth" — 파일 자체가 기준입니다.
  • 1 MiB 이상 파일은 읽기 전용 paged preview(나눠 보여 주는 미리보기)로 열립니다. Orca가 파일에 색인을 만든 뒤 화면에 보이는 행·열만 그려서, 파일 전체를 메모리에 올리지 않고도 빠르게 보여 줍니다.
  • 테스트용 데이터(fixture), 내보낸 자료 등 프로젝트에 든 표 데이터를 다룰 때 유용합니다.

Jupyter 노트북

Jupyter 노트북(설명 글과 실행할 수 있는 코드 칸(셀)을 한 문서에 섞어 둔 파일, 확장자 .ipynb)을 열면 설명 글, 코드 셀, 저장된 실행 결과가 그려진 상태로 보입니다. 코드 셀은 클릭해서 고치고, 설명(마크다운) 셀은 더블클릭하거나 Enter로 고칩니다. 고친 내용은 노트북 파일에 저장됩니다.

내 컴퓨터에 있는 Python(데이터 분석에 많이 쓰는 프로그래밍 언어) 노트북은 Orca 안에서 셀을 실행할 수도 있습니다. 실행은 커널(셀을 실제로 실행하는 엔진)이 맡습니다.

매출분석.ipynb · 커널: .venv ▾ · Run All · Interrupt · Restart · Clear All Outputs
## 이번 달 합계 계산
[1] 합계 = 120 + 340
[2] 합계
460 ← 앞 셀에서 만든 값이 그대로 남아 있음
1. 신뢰(trust) 확인

노트북 코드를 실행하기 전에 Orca의 신뢰 확인 창에 동의해야 합니다. 신뢰하기 전까지 Orca는 이 워크트리의 Python을 시작하지 않습니다.

2. 실행할 Python(커널) 고르기

머리줄의 커널 선택기가 가까이 있는 Python 환경을 추천해 줍니다. 필요한 구성 요소가 없으면 Orca가 설치를 제안합니다. 세부 사항은 아래 🔧 상자를 보세요.

3. 셀 실행

Shift+Enter는 실행 후 다음 셀로, Cmd/Ctrl+Enter는 실행 후 그 셀에 머뭅니다. 그래프·결과·오류·실행 번호가 셀과 함께 표시됩니다.

4. 커널 유지와 관리

첫 실행부터 탭을 닫을 때까지 그 노트북용 커널이 살아 있어 셀 사이에 값이 유지됩니다. 머리줄의 Run All(모두 실행), Interrupt(중단), Restart(재시작), Clear All Outputs(결과 모두 지우기)를 씁니다.

실행 가능 범위셀 실행은 내 컴퓨터의 Python 노트북에서만 됩니다. SSH 워크트리의 노트북이나 다른 언어 노트북도 보기와 고치기는 됩니다.
커널 선택·필요 패키지·파일 형식
  • 커널 선택기는 가까운 .venv 또는 .conda 환경을 추천합니다. 다른 Python을 고르거나 찾아볼 수 있고, Orca는 그 노트북에 대한 선택을 기억합니다.
  • Python에 ipykernel과 jupyter_client가 있어야 합니다. ipykernel이 없으면 Orca가 설치를 제안합니다.
  • 선택한 Python이 패키지 설치를 막으면 Create .venv로 워크트리 전용 환경을 만드세요. 설정 대화상자에 진행 상황과 오류가 보입니다.
  • 편집 내용은 nbformat(노트북 파일 형식)을 지키며 저장됩니다.

파일 탐색기

파일 탐색기는 각 워크트리 왼쪽에 있으며 디스크의 파일을 실시간으로 따라갑니다. 만들기·이름 바꾸기·삭제·이동이 모두 실제 파일에 그대로 적용되고, 에이전트처럼 바깥에서 생긴 변경도 바로 나타납니다. 정렬은 폴더 먼저, 그다음 파일이며, 이름 속 숫자를 수로 이해하는 순서(9, 99, 100)입니다.

글자 순 정렬 (Orca가 쓰지 않음) file100.txtfile9.txtfile99.txt 글자 하나씩 비교 → 100이 9보다 앞 Orca: 폴더 먼저 + 숫자 순서 docs/ (폴더)file9.txtfile99.txtfile100.txt 숫자를 수로 인식 → 9, 99, 100
폴더가 먼저, 그다음 파일이 숫자를 이해하는 자연스러운 순서로 정렬됩니다.
정렬이 적용되는 곳·큰 원격 폴더·sparse checkout
  • 정렬 — 같은 순서(natural, numeric-aware)가 SSH, 원격 런타임, Source Control 트리, 폴더 선택 창, 모바일 파일 트리에도 적용됩니다.
  • 큰 원격 폴더 — 업데이트된 SSH·페어링 서버에서는 스크롤하면 항목을 더 불러옵니다. 큰 폴더가 다 안 보이면 호스트 서버를 업데이트하세요.
  • sparse checkout(저장소의 일부 폴더만 골라 꺼내는 git 기능) — 워크트리가 이것을 쓰면 탐색기가 꺼낸 폴더만 보여 줘, 저장소 전체 대신 실제 작업 폴더에 바로 닿습니다.

바깥에서 끌어다 놓기

파일을 놓으면 지금 활성화된 워크트리가 아니라, 마우스 커서가 가리키는 바로 그곳에 떨어집니다. 파일 트리, 프로젝트 사이드바, 에디터, 탭 줄, 또는 커서 아래에 있는 특정 터미널 창.

Finder / Explorer (내 컴퓨터의 파일 창) screenshot.png spec.pdf 에이전트 터미널 > 이 화면의 버그를 고쳐 줘 > /Users/me/Desktop/screenshot.png PNG 놓으면 파일 경로가 입력줄에 붙여넣어짐 SSH라면 먼저 원격으로 올린 뒤 → 원격의 실제 경로
파일을 에이전트 터미널에 놓으면 그 파일의 경로(위치 주소)가 입력줄에 들어갑니다. 에이전트는 그 경로로 파일을 읽습니다.

파일 트리에 놓기

Finder/Explorer에서 끌어 온 파일이 그 폴더로 복사됩니다.

마크다운 에디터에 놓기

이미지를 놓으면 커서 위치에 이미지가 들어갑니다.

에이전트 터미널에 놓기

파일들의 경로가 입력줄에 붙여넣어집니다.

SSH 워크트리

여기서도 됩니다. Orca가 놓기를 마치기 전에 파일을 원격 컴퓨터로 올려 두므로, 에이전트는 원격 디스크의 실제 경로로 파일을 봅니다.

git 상태 색 — 파일 이름 색이 다른 이유

탐색기의 파일 이름은 git(파일의 변경 이력을 기록하는 도구)이 보는 상태에 따라 색이 다릅니다. 색만 봐도 "새로 만든 파일인지, 고친 파일인지"를 알 수 있습니다.

파일 탐색기
▾ docs/
  보고서.md ← 고친 파일
  새메모.md ← 새로 만든 파일
  요약.md ← 다음 커밋에 넣기로 한 파일
  안내.md
▸ 임시파일/ ← 무시하기로 한 폴더

그림의 색은 설명을 위한 예시입니다.

상태뜻 · 왜 생기나
untracked새로 만들어서 git이 아직 기록해 본 적 없는 파일. 에이전트나 내가 새 파일을 만들면 생깁니다.
modified기록된 적 있는 파일을 그 뒤에 고친 상태.
staged고친 내용을 다음 커밋(변경을 하나의 저장 지점으로 기록하는 일)에 넣기로 표시해 둔 상태. 오른쪽 클릭 → stage 등으로 생깁니다.
ignored프로젝트가 "git이 신경 쓰지 않을 파일"로 정해 둔 것. 임시 파일처럼 기록할 필요 없는 파일이 해당합니다.
실제 색은 Orca 화면에서 확인하세요원문에는 상태별로 어떤 색인지가 적혀 있지 않습니다. 실제 색은 Orca의 파일 탐색기에서 파일을 새로 만들거나 고쳐 보며 확인하세요.

오른쪽 클릭 메뉴 — 버리기·올리기·경로 복사·내려받기·찾기

탐색기에서 파일이나 폴더를 오른쪽 클릭하면 자주 쓰는 동작이 모여 있습니다.

보고서.md 오른쪽 클릭
Discard — 고친 내용 버리기
Stage — 다음 커밋 목록에 올리기
Rename — 이름 바꾸기
Copy — 파일 자체 복사
Copy Path — 전체 경로 복사
Copy Relative Path — 상대 경로 복사
Reveal in Finder — Finder에서 보기
Download — 원격 파일만
Find in Folder — 폴더를 눌렀을 때

메뉴의 순서·모양은 설명을 위한 예시입니다.

메뉴설명
discard그 파일에서 고친 내용을 버립니다. 버린다는 것은 고친 내용이 없어진다는 뜻이니, 버려도 되는지 확인하고 누르세요.
stage다음 커밋 목록에 올리기
rename이름 바꾸기
Copy Path전체 경로(파일의 위치 주소) 복사
Copy Relative Path워크트리 기준 상대 경로 복사. 기본 단축키 Cmd+Option+Shift+C / Ctrl+Alt+Shift+C (변경 가능)
Copy파일 한 개를 골랐을 때, 파일 자체를 운영체제 클립보드에 올려 다른 앱에 붙여넣을 수 있게 합니다.
SSH 워크트리에서 Copy

SSH 워크트리에서는 Orca가 원격 파일을 먼저 내 컴퓨터에 임시로 받아 둔 뒤, 그 파일을 클립보드에 넣습니다. 원격 폴더는 Copy 대상에서 제외됩니다.

원격 파일 내려받기

데스크톱 앱에서 원격 파일을 오른쪽 클릭 → Download(내려받기), 원격 폴더는 → Download Folder(폴더 내려받기 — 연결이 폴더 통째 전송을 지원할 때). 운영체제의 저장 위치 선택 창이 열립니다.

어디서Download 메뉴
데스크톱 앱 + 원격(SSH 등) 파일있음 (폴더는 연결이 지원할 때 Download Folder)
웹 버전 Orca쓸 수 없음
로컬 워크트리보이지 않음 (이미 내 컴퓨터에 있으니까요)

Finder / File Explorer에서 보기

탐색기의 파일, Source Control(변경 목록)의 바뀐 파일, 터미널 안의 파일 경로 링크를 오른쪽 클릭하고 Reveal in Finder(macOS) 또는 Reveal in File Explorer(Windows)를 고르면, 운영체제의 파일 창에서 그 파일이 있는 폴더가 열립니다.

폴더 안에서 찾기

방법결과
폴더를 오른쪽 클릭 → Find in Folder(폴더에서 찾기)그 폴더 안만 찾도록 범위가 정해진 검색 화면이 열립니다.
탐색기에서 폴더를 선택하고 Cmd+Shift+F(macOS) / Ctrl+Shift+F(Windows·Linux)

탐색기의 이름 필터는 파일이 아주 많은 워크트리에서도 처음 목록에 없던 파일까지 찾아 줍니다.

아주 큰 워크트리에서의 이름 필터

아주 큰 워크트리가 목록 한도(listing cap)에 닿아도, 탐색기 이름 필터는 로컬 전체 파일 목록을 검색하므로 처음 목록에 없던 파일도 찾을 수 있습니다. 이때는 타이핑하는 동안 아주 잠깐 기다렸다가 검색하고(debounce), 작은 워크트리는 치는 즉시 걸러 줍니다.

다음 단계원하는 파일을 찾았으면 코드 에디터로 고치고, diff 뷰어(6장)로 에이전트나 내가 만든 변경을 검토하세요.
한눈에 정리
  • 코드는 Monaco 에디터로 열리고, 다른 곳을 클릭하거나 잠깐 멈추면 자동 저장됩니다. 그 사이 디스크의 파일이 바뀌었으면 저장을 멈추고 비교/다시 불러오기/유지/덮어쓰기 중 고르게 합니다.
  • (macOS) Cmd+D 다음 같은 단어 선택, Cmd+F 파일 안 찾기, Cmd+Shift+F 전체 찾기, Alt+Z 줄 바꿈. 파일 저장(자동)과 커밋(돌아올 수 있는 기록)은 다릅니다. 변경 보기(Changes view)는 빨강=지운 줄, 초록=더한 줄(n/p/s).
  • 마크다운은 리치 에디터(macOS Cmd+Shift+M로 원문). 600 KB 초과는 원문 먼저. 슬래시 메뉴·토글·콜아웃·[[ 링크·리뷰 노트·프런트 매터·표·목차·공개 링크 공유(설정에서 허용, 10 MiB(약 10MB)까지).
  • HTML은 격리된 미리보기, Mermaid·PDF·이미지·오디오/비디오·CSV(약 1MB 이상은 보기 전용)·Jupyter(신뢰 후 내 컴퓨터의 Python으로 실행) 전용 뷰어.
  • 탐색기는 실시간·숫자 순 정렬, 파일 색은 git 상태(새 파일·고친 파일·커밋 대기·무시). 끌어다 놓으면 커서 아래 대상으로: 트리=복사, 마크다운=이미지 삽입, 터미널=경로 붙여넣기, SSH=올린 뒤 경로.

출처: onorca.dev/docs/editing/monaco · onorca.dev/docs/editing/markdown · onorca.dev/docs/editing/viewers · onorca.dev/docs/editing/file-explorer

CHAPTER 06

리뷰와 배포 — diff 보기부터 PR·이슈 연동까지

에이전트가 코드를 고쳤다면 이제 사람이 꼼꼼히 확인하고, 저장(커밋)하고, 서버로 올리고(푸시), 동료에게 검토를 부탁(PR)할 차례입니다. 이 장은 그 과정을 Orca 안에서 한 번에 끝내는 방법과, GitHub·GitLab·Bitbucket·Jira·Linear 같은 바깥 서비스와 연결하는 방법을 다룹니다.

이 장에서 배우는 것
  • diff·스테이징·커밋·푸시·PR·CI가 각각 무엇이고, 변경 사항이 어떤 길을 따라 이동하는지
  • Diff viewer(차이 보기 화면)의 기능·범위 설정·줄바꿈·파일 트리·단축키
  • Annotate AI Diff로 줄마다 코멘트를 달고 한 번에 묶어 에이전트에게 돌려보내는 리뷰 순환
  • Attribution(작성자 표시)으로 사람이 쓴 줄과 AI가 쓴 줄을 구분하는 법
  • Orca 안에서 커밋·푸시·강제 푸시·Amend·PR 만들기, 그리고 AI 액션 레시피 설정
  • GitHub·GitLab·Bitbucket 등의 리뷰 연동(자동 병합, 스택 PR, 이슈, Actions, Projects)
  • Jira·Linear 이슈를 워크트리와 연결하는 법, AI diff를 줄 단위로 리뷰하는 레시피
처음이라면 이것만

순서대로 보세요.

  1. 먼저 알아 둘 말: diff · 스테이징 · 커밋 · 푸시 · PR · CI — 봉투·사물함 비유와 용어표
  2. Diff viewer — AI가 만든 코드를 제대로 읽는 화면
  3. Annotate AI Diff — 코멘트를 모아 한 번에 돌려보내기
  4. 커밋 · 푸시 · PR 만들기 — Orca를 떠나지 않고 (첫 두 탭)
  5. 레시피: AI diff를 줄 단위로 리뷰하기 — 코드를 몰라도 따라 할 수 있는 확인법 포함

GitHub 세부 기능·Jira·Linear 소절은 회사에서 그 서비스를 쓸 때 읽어도 됩니다. 🔧 표시가 붙은 접힌 상자는 개발자·관리자용이니 처음엔 건너뛰세요.

먼저 알아 둘 말: diff · 스테이징 · 커밋 · 푸시 · PR · CI

이 장에는 git 용어가 많이 나옵니다. 처음 보는 분도 따라올 수 있게 먼저 하나씩 풀어 보겠습니다. 바탕이 되는 말은 세 가지입니다. git(파일을 언제 누가 어떻게 바꿨는지 기록해 두는 도구), 브랜치(같은 프로젝트에서 갈라져 나온 독립된 작업 줄기 — 다른 작업과 섞이지 않음), 워크트리(브랜치 하나를 위한 별도 작업 폴더. Orca는 작업마다 하나씩 만듭니다).

학교 숙제로 비유하면
  • diff(차이) — 어제 원고와 오늘 원고를 나란히 놓고 빨간 펜(지운 부분)과 초록 펜(새로 쓴 부분)으로 표시한 것입니다.
  • 스테이징(staging) — 고친 것 중 “이번에 낼 부분”만 골라 봉투에 넣어 두는 것입니다. 명령으로는 git add입니다.
  • 커밋(commit) — 봉투를 봉하고 “무엇을 고쳤는지” 메모(커밋 메시지)를 붙여 내 서랍에 보관하는 것입니다. 아직 내 컴퓨터 안에만 있습니다.
  • 푸시(push) — 서랍 속 봉투를 학교 사물함(원격 저장소, 보통 origin이라 부르는 GitHub 같은 서버)에 갖다 넣는 것입니다.
  • PR(풀 리퀘스트) / MR(머지 리퀘스트) — “제 작업 좀 봐 주시고 괜찮으면 본 원고(main 브랜치)에 합쳐 주세요” 하는 검토 요청서입니다. GitHub·Bitbucket은 PR, GitLab은 MR이라고 부릅니다. 이 장에서는 둘을 묶어 호스팅 리뷰(hosted review)라고도 합니다.
  • CI(지속적 통합) / 체크(checks) — 요청서를 내면 자동 채점기가 돌아 테스트·검사를 해 주는 것입니다. GitHub에서는 GitHub Actions, GitLab에서는 파이프라인(pipeline)이 이 일을 합니다.
  • 머지(merge, 병합) — 검토가 끝난 작업을 본 원고에 합치는 것입니다.
작업 폴더 고친 파일(unstaged) 새 파일(untracked) 스테이징 이번에 낼 부분 (staged) 커밋 내 컴퓨터의 기록 메시지 + 변경 묶음 원격(origin) GitHub · GitLab … 브랜치가 올라감 PR / MR 검토 · CI 체크 → 머지 Stage Commit Push Create PR Orca에서는 이 모든 단계를 Diff viewer 옆 커밋 패널과 사이드바의 Source Control 패널에서 처리합니다 diff는 “작업 폴더 + 스테이징”에 있는 변경을 시작 지점(start-from ref)과 비교해 보여 줍니다
변경 하나가 작업 폴더 → 스테이징 → 커밋 → 원격 → PR로 이동하는 길. 노란 점이 변경 하나라고 생각하면 됩니다.

여기에 몇 가지 용어를 더 알아 두면 뒤가 편합니다.

용어쉬운 뜻
GitHub · GitLab · Bitbucket코드를 올려 두고 여러 사람이 함께 검토하는 웹사이트. 위 그림의 “원격(학교 사물함)”이 바로 이런 곳입니다. Azure DevOps·Gitea도 같은 종류의 서비스입니다.
이슈(issue)할 일·버그 신고를 적은 카드. 엑셀 할 일 목록의 한 줄이라고 생각하면 됩니다. GitHub·Jira·Linear 모두 이슈를 다룹니다.
칸반(kanban) 보드“할 일 · 하는 중 · 끝남” 같은 칸에 포스트잇을 붙여 두고 칸에서 칸으로 옮기는 보드.
토큰(token)비밀번호 대신 쓰는 출입증 문자열. 서비스 설정 화면에서 만들어 Orca에 붙여 넣으면, Orca가 그 출입증으로 대신 들어갑니다. 필요 없어지면 언제든 폐기할 수 있습니다.
ref / start-from ref“어느 시점의 코드”를 가리키는 이름표(브랜치 이름, 커밋 번호 등). start-from ref는 워크트리를 만들 때 출발점으로 삼은 지점입니다.
base 브랜치PR이 최종적으로 합쳐질 대상 브랜치(보통 main).
hunk(헝크)diff 안에서 붙어 있는 변경 덩어리 하나. 파일 하나에 여러 hunk가 있을 수 있습니다.
upstream내 로컬 브랜치와 짝을 이루는 원격 브랜치. 처음 푸시할 때 정해집니다.
merge base(분기점)내 브랜치와 base 브랜치가 갈라진 지점.
rebase · amend · squash이미 만든 커밋 기록을 다시 쓰는 방법들(다른 지점 위로 옮기기 / 마지막 커밋 고치기 / 여러 커밋 합치기). 기록이 바뀌므로 원격과 어긋날 수 있습니다.
병합 충돌(merge conflict)두 쪽이 같은 줄을 다르게 고쳐서 git이 어느 쪽을 택할지 모르는 상태.
pre-commit hook커밋 직전에 저장소가 자동으로 돌리는 검사(코드 모양·실수 자동 검사). 실패하면 커밋이 막힙니다.

Diff viewer — AI가 만든 코드를 제대로 읽는 화면

무엇인가. Orca의 Diff viewer(차이 보기 화면)는 AI가 만든 코드를 “슬쩍 훑어보는” 용도가 아니라 진지하게 리뷰하도록 설계되었습니다. 모든 워크트리에는 자기 start-from ref와 비교한 diff가 기본으로 들어 있습니다.

왜 필요한가. 에이전트는 빠르게 많은 줄을 바꿉니다. 무엇이 바뀌었는지 정확히 보지 않고 커밋하면 버그도 함께 배포됩니다.

Diff toolbar 비교 대상: start-from ref ▾ (커밋 · 브랜치 · base ref) ⋯ actions 파일 트리 ▾ src/ ● api.ts ● memo.ts ▸ static/ README.md ↔ 크기 조절 손잡이 @@ hunk 1 @@ 12- const limit = 10 12+ const limit = config.pageSize ?? 10 13 return list(limit) ⋯ 바뀌지 않은 40줄 접힘(Collapse unchanged regions) @@ hunk 2 @@ 58+ export function clear() { … } + 분홍 막대 = AI가 쓴 줄(Attribution) 초록 + = 코멘트 달기
Diff viewer 화면을 단순하게 그린 예시. 왼쪽 파일 트리, 오른쪽 hunk, 거터(줄 번호 옆 여백)의 표시들.

기능 목록

합친 diff (Combined diff)

스테이징된 것, 스테이징 안 된 것, git이 아직 추적하지 않는 새 파일(untracked)까지 모두 한 화면에 모아 보여 줍니다.

줄 번호

바뀌기 전·후 양쪽 줄 번호를 표시하며, 켜고 끌 수 있습니다.

이미지 diff

이미지 같은 바이너리 파일(글자가 아닌 파일)은 side-by-side(나란히), swipe(밀어서 비교), onion-skin(반투명 겹치기) 세 가지 방식으로 비교합니다.

HTML 미리보기

HTML 파일이면 눈 모양 아이콘을 눌러 옆 화면에서 웹페이지 모습으로 미리 봅니다.

눈 아이콘이 나오는 조건

View all/합친 diff에서, 작업 폴더에 아직 남아 있는 HTML 부분에는 항상 보이는 “파일 열기” 버튼 옆에 Open Preview to the Side(눈 모양 아이콘, 옆에 미리보기 열기)가 나타납니다. 누르면 작업 폴더의 HTML을 옆 브라우저 분할 화면에서 엽니다. 삭제된 HTML이나 커밋만 보여 주는 합친 화면에는 눈 아이콘이 없습니다.

병합 충돌 UI

충돌이 나면 3방향 보기(three-way view: 내 쪽 · 상대 쪽 · 결과)로 보여 주고, 그 자리에서 해결할 수 있습니다. 그림 보기

hunk·줄 단위 스테이징

git add -p(변경을 조각조각 골라 스테이징하는 명령)와 같은 일을 눈으로 보며 클릭으로 합니다.

Show Whitespace

공백·탭 같은 보이지 않는 문자를 드러냅니다. diff viewer의 actions 메뉴에서 켜고 끕니다.

Collapse unchanged regions

파일 diff에서 바뀌지 않은 긴 구간을 접어 바뀐 줄만 눈에 들어오게 합니다. diff editor actions 메뉴에서 켜며, 기본값은 꺼짐입니다.

비교 범위 바꾸기 (Scoping)

기본으로는 워크트리의 start-from ref와 비교합니다. diff 툴바에서 비교 대상을 아무 커밋, 아무 브랜치, 또는 base ref로 바꿀 수 있습니다. 예를 들어 “마지막 커밋 이후 바뀐 것만” 보고 싶을 때 유용합니다.

Word wrap (자동 줄바꿈)

켜면 긴 줄이 그 자리에서 접혀 내려가서 가로 스크롤 없이 위에서 아래로 읽을 수 있습니다. 기본값은 꺼짐입니다. 합친 diff에서는 왼쪽 파일 트리를 접었다 펴고 너비를 바꿀 수 있습니다.

줄바꿈 켜는 곳 · 파일 트리 조작 상세
  • diff editor 머리글의 ⋯ actions 메뉴에서 Word Wrap을 토글하거나,
  • Settings → General → Diff Word Wrap(설정 → 일반 → diff 줄바꿈)에서 전체 기본값을 정합니다.
두 스위치는 같은 설정입니다에디터에서 토글하면 모든 곳에서 함께 바뀝니다. 또 “바뀌지 않은 구간 접기”와 “줄바꿈”은 파일 diff에만 적용됩니다. 합친 diff는 자체 파일 트리와 hunk 조작 도구를 따로 씁니다.

파일 트리

합친 diff는 hunk 옆에 접었다 펼 수 있는 파일 트리를 보여 줄 수 있습니다.

  • 트리의 크기 조절 손잡이를 끌거나, 손잡이에 포커스를 두고 화살표 키로 너비를 바꿉니다. Shift를 같이 누르면 한 번에 더 많이 움직입니다.
  • 정한 너비는 앱을 껐다 켜도 기억됩니다.
  • 트리 숨기기/보이기는 합친 diff 툴바에서 합니다.

단축키

j / k — 다음 / 이전 바뀐 파일
n / p — 다음 / 이전 hunk
F7 / Shift+F7 — 현재 에디터의 다음 / 이전 변경
s — 커서가 있는 hunk 스테이징
c — 코멘트 시작(Annotate AI Diff)

Annotate AI Diff — 코멘트를 모아 한 번에 돌려보내기

무엇인가. Annotate AI Diff는 에이전트가 만든 코드를 위한 Orca의 줄 단위 리뷰 순환입니다. AI가 만든 hunk의 아무 줄에나 코멘트를 남긴 뒤, 그 코멘트들을 한 묶음(batch)으로 에이전트에게 보내 고치게 합니다. 줄 번호를 복사해 붙이거나 다른 창으로 오갈 필요가 없습니다.

① 리뷰 diff를 j / k로 훑기 ② 코멘트 c 로 줄에 메모 고정 ③ Send to agent 코멘트를 한 프롬프트로 ④ 에이전트 수정 한 번 생각, 한 번 고침 재리뷰 Resolve
리뷰 → 코멘트 → 묶어 보내기 → 에이전트 수정 → 다시 리뷰. 깨끗해질 때까지 돕니다.

코멘트 남기기

  1. 줄 위에 마우스를 올립니다거터(줄 번호 옆 여백)에 +가 나타납니다. 여러 줄에 달고 싶으면 이웃한 줄들을 끌어서 고르거나, Shift를 누른 채 선택을 넓힙니다. Orca는 선택 범위를 그 hunk 안으로 제한하고, 고른 줄 범위를 라벨로 붙입니다.
  2. +를 클릭합니다또는 커서를 그 줄에 두고 c를 누릅니다.
  3. 의견을 씁니다마크다운(제목·목록·코드 표시 같은 간단한 서식 문법)을 쓸 수 있습니다.
  4. 저장하거나 취소합니다Enter 또는 Cmd/Ctrl+Enter로 저장, Shift+Enter로 줄바꿈, Esc로 취소합니다.

코멘트는 정확히 그 줄에 고정(pin)됩니다. 코드가 수정되어 diff 위치가 밀려도 Orca가 추적해서 코멘트가 그 줄을 따라갑니다.

src/memo.ts — Annotate AI Diff
+ 12 const limit = config.pageSize ?? 10L12
💬 나: pageSize가 0이면 어떻게 되나요? 0일 때도 10으로 처리해 주세요.Resolve
+ 58–61 export function clear() { … }L58–61
💬 나: 이 함수는 어디서도 쓰이지 않습니다. 필요 없으면 지워 주세요.Resolve
미해결 코멘트 2개Send to agent ▾

묶음 보내기 (Send the batch)

리뷰를 다 했으면 diff 맨 위의 Send to agent(에이전트에게 보내기)를 누릅니다. Orca가 모든 코멘트를 줄 위치와 함께 하나의 프롬프트로 엮은 뒤, 그 워크트리에서 쓸 수 있는 에이전트 목록이 담긴 Send notes to 메뉴를 엽니다. 수정을 맡길 에이전트를 고르거나, 같은 메뉴에서 새 에이전트를 시작할 수 있습니다.

단축키를 직접 정해야 합니다Send Review Notes to Agent 동작은 다른 단축키 조합과 부딪치지 않도록 기본으로 단축키가 비어 있습니다. Settings → Shortcuts(설정 → 단축키)에서 지정하면 키보드로 보내기 메뉴를 열 수 있고, 에디터에 포커스가 있을 때도 동작합니다.

왜 묶어서 보내나요?

하나씩 보내면에이전트가 코멘트 하나 고치고, 다음 코멘트에 맞춰 또 바꾸고… 이리저리 흔들립니다.
묶어서 보내면피드백이 일관됩니다. 한 번 생각하고, 한 번에 고치므로 원하는 결과가 나올 확률이 훨씬 높습니다.

답하기 · 해결 처리 · 재리뷰

  • 에이전트가 고친 뒤에도 코멘트는 그 자리에 고정되어 남습니다. 고쳐졌는지 확인하는 체크리스트로 쓰면 됩니다.
  • Resolve(해결)를 누르면 그 코멘트 스레드가 접힙니다.
  • 해결하지 않은 코멘트는 Send를 다시 누를 때 다음 묶음에 포함됩니다.

Attribution — 이 줄은 사람이 썼나, AI가 썼나

무엇인가. Orca는 에이전트가 건드리는 것을 본 모든 줄에 “출처(provenance)”를 기록합니다. 그래서 diff를 읽을 때 어떤 줄은 사람이, 어떤 줄은 AI가 썼는지 한눈에 알 수 있습니다.

1. 에이전트가 파일을 씀 에이전트 도구로 쓴 범위를 Orca가 기록 AI 줄 2. diff에 표시 AI가 만든 줄은 거터에 은은한 표시가 붙음 + const x = … 3. 사람이 그 위를 고침 사람이 덧고친 줄은 다시 “사람”으로 바뀜 사람 줄 이 기록은 Orca 안에만 있고 git 커밋에는 들어가지 않습니다
Attribution(작성자 표시)이 붙고 바뀌는 과정.

왜 중요한가

  • PR 중에서 어느 부분을 더 꼼꼼히 봐야 하는지 알 수 있습니다.
  • 보안·규정 준수 감사에서 AI가 쓴 코드와 사람이 쓴 코드를 나눠 볼 수 있습니다.
  • 방금 내 손으로 쓴 코드는 다시 읽지 않아도 되니 리뷰가 빨라집니다.
범위: Orca 로컬 전용Attribution은 Orca 안에서만 유지되며 git에 커밋되지 않습니다. 계속 남겨 두고 싶다면 diff 툴바에서 diff 메타데이터를 내보내기(export) 하세요.

커밋 · 푸시 · PR 만들기 — Orca를 떠나지 않고

Orca 안에서 커밋하고, 푸시하고, 리뷰(PR)까지 열 수 있습니다. 커밋 패널은 Diff viewer 바로 옆에 있으며, 가장 흔한 흐름인 리뷰 → 스테이징 → 커밋 → 푸시 → 다음 일에 맞춰 설계되어 있습니다.

  1. 스테이징diff에서 hunk 단위 또는 파일 단위로 스테이징합니다.
  2. 커밋 메시지 쓰기아래 패널에 직접 쓰거나, 스테이징한 변경을 바탕으로 Orca가 초안을 써 주길 원하면 Generate with AI(AI로 생성)를 누릅니다.
  3. CommitmacOS는 Cmd+Enter, Windows/Linux는 Ctrl+Enter. 단, 포커스가 Source Control에 있고 주 버튼이 Commit일 때 동작합니다.

저장소에 있는 pre-commit hook(커밋 직전에 코드 모양·실수를 자동으로 검사하는 장치)은 평소처럼 실행됩니다. hook이 실패하면 Orca가 그 출력을 그 자리에 보여 줍니다.

Fix with AI — 커밋이 실패했을 때실패 상세 화면에서 Fix with AI(AI로 고치기)를 누르면, 현재 워크트리에서 기본 에이전트가 시작되고 hook 출력·시도한 커밋 메시지·스테이징된 파일 목록을 넘겨받습니다. 에이전트는 고치라는 프롬프트만 받습니다. hook을 우회하거나, 커밋·푸시하거나, 리뷰를 열라는 요청은 받지 않습니다.

Push는 워크트리의 브랜치를 origin(원격, 학교 사물함)으로 올립니다. 처음 푸시할 때는 upstream(내 브랜치와 짝을 이루는 원격 브랜치)도 함께 정합니다. 브랜치가 원격보다 뒤처져 있으면 Orca는 몰래 강제 푸시하지 않습니다.

봉투·사물함 비유로 이어 보면일반 Push는 사물함에 이미 들어 있는 봉투 줄의 맨 끝에 새 봉투를 이어 붙이는 일입니다. 그런데 rebase·amend·squash로 이미 낸 봉투를 뜯어 고쳐 다시 봉하면, 사물함에는 옛날 사본이 남아 있어 내 서랍과 끝이 맞지 않습니다. 이어 붙일 자리가 없으니 일반 Push로는 올라가지 않고, 사물함 내용을 바꿔 끼우는 강제 푸시가 필요해집니다. 아래 단계를 넘겨 보세요.
내 컴퓨터(내 서랍) 원격(학교 사물함) A B C D A B C PushD 원격 끝(C) 뒤에 새 봉투 D를 그대로 이어 붙이면 됩니다. ① 평소: 이어 붙이기
A·B·C = 커밋(봉투). 평소에는 원격 끝 뒤에 이어 붙이기만 합니다.
내 컴퓨터(내 서랍) 원격(학교 사물함) A B C′ A B C 고쳐 다시 봉한 봉투옛날 사본 마지막 봉투 C를 뜯어 고쳐 다시 봉하면(C′) 내 서랍과 사물함의 끝이 서로 달라집니다. ② amend 뒤: 기록이 갈라짐
amend(마지막 커밋 고치기)·rebase·squash는 이미 만든 기록을 다시 씁니다.
내 컴퓨터(내 서랍) 원격(학교 사물함) A B C′ A B C ✕Push 거절 사물함 끝의 C가 내 서랍 기록에 없으니 “이어 붙이기”가 안 됩니다. Orca는 여기서 몰래 덮어쓰지 않습니다. ③ 일반 Push: 실패
일반 Push는 이어 붙일 수 없을 때 실패하며, Orca가 대신 강제 푸시로 바꿔 실행하는 일은 없습니다.
내 컴퓨터(내 서랍) 원격(학교 사물함) A B C′ A B C′ 확인: 끝이 C 그대로? → 예→ C′로 덮어씀 사물함 끝이 “내가 마지막으로 본 그대로(C)”인지 먼저 확인하고, 맞을 때만 C를 C′로 바꿉니다. ④ Force push with lease: 조건부 덮어쓰기
그래서 Source Control 패널에 Force push with lease가 별도 버튼으로 나타납니다.
내 컴퓨터(내 서랍) 원격(학교 사물함) A B C′ A B C D 확인: 끝이 C 그대로? → 아니오(D)중단동료가 올린 봉투 사물함 끝이 내가 본 C가 아니라 동료의 D로 바뀌었으면 푸시를 멈춥니다. 동료의 D는 지워지지 않습니다. ⑤ 그 사이 동료가 올렸다면: 중단
“내가 본 그대로일 때만” 조건 덕분에 남의 작업을 덮어쓰지 않습니다.

정리하면, rebase·amend·squash로 기록을 다시 써서 원격에는 내 로컬 커밋의 옛날 사본만 있는 상황이면 Source Control 패널이 Force push with lease(조건부 강제 푸시)를 따로 떨어진 버튼으로 보여 줍니다. 일반 Push가 실패했을 때 대신 쓰이는 일은 절대 없습니다.

  • 버튼 라벨에 바뀌게 될 커밋 개수와 upstream 브랜치 이름이 표시되어, 무엇이 바뀌는지 정확히 알 수 있습니다.
  • --force-with-lease를 쓰므로, 내가 알고 있는 원격 상태가 오래된 것이면 푸시가 중단됩니다. 그 사이 다른 사람이 올린 커밋을 덮어쓰지 않습니다.

브랜치를 푸시한 뒤에는 Source Control 패널의 호스팅 리뷰 동작으로 PR(또는 MR)을 만듭니다. 만들기 전에 base 브랜치·제목·설명·초안(draft) 여부를 확인하세요.

  • Bitbucket Cloud도 같은 작성 화면에서 PR을 만들 수 있습니다. Bitbucket Cloud에는 초안 PR이 없어서 Draft 항목이 숨겨집니다.
  • GitHub에서 고른 base에 이미 열린 PR이 있으면 Stack this PR above #N(#N 위에 이 PR 쌓기)을 고를 수 있습니다(아래 스택 PR 참고).

PR 제목·설명은 AI가 초안을 써 줄 수 있고, 만드는 도중 문제가 생기면 이유와 Fix with AI 버튼이 담긴 안내가 나옵니다.

Create PR 때 AI 초안 · 실패 요약 · OMP 상세
  • 이미 푸시된 브랜치에서 Create PR을 누르면, 자리표시 제목과 빈 본문을 보내는 대신 설정된 생성 에이전트가 제목과 설명 초안을 먼저 쓴 뒤 제출합니다. 내가 고른 Draft 선택은 에이전트가 다른 값을 돌려줘도 그대로 유지됩니다.
  • Create PR 과정에서 Orca가 후속 커밋을 해야 하는데 그 커밋이 실패하면(hook 거부, 커밋할 수 없는 작업 폴더 상태 등), 대화상자가 hook 출력과 다음 단계 버튼을 담은 상세 실패 요약을 보여 줍니다. 아무 설명 없이 패널로 튕겨 내지 않습니다. 요약에서 Fix with AI로 에이전트에게 맡기거나, 직접 해결하고 다시 실행하세요.
  • 리뷰 만들기 대화상자의 Generate pull request details with AI(AI로 PR 내용 생성)는 브랜치 diff와 커밋을 바탕으로 제목·설명·초안 여부를 써 줍니다. 생성된 글은 짧고 쉬운(ELI5) “문제/해결” 단락과, 연결된 이슈 안내(GitHub 이슈가 붙어 있으면 Fixes와 Refs 중 무엇을 쓸지)를 목표로 합니다. Orca는 내가 고른 base 브랜치를 유지하고, 빈 설명은 거부하며, 빈 본문이 나가지 않도록 분명한 오류를 보여 줘 다시 시도할 수 있게 합니다. 만들기 전에 각 칸을 꼭 검토하세요.
  • OMP(Orca가 지원하는 에이전트 프로그램 중 하나)가 선택된 액션 에이전트라면 Source Control AI가 이 생성 동작들을 OMP로 실행할 수 있습니다.

Amend(마지막 커밋 고치기)는 명시적으로만 합니다: Commit → Amend. 이미 푸시된 커밋은 사용자가 확인하지 않으면 Orca가 amend하지 않습니다.

왜 확인을 받나요?푸시된 커밋을 고치면 원격과 기록이 어긋나서, 나중에 강제 푸시가 필요해집니다.

Source Control 패널

사이드바의 Source Control(소스 관리) 패널은 지금 보고 있는 화면을 떠나지 않고 같은 동작을 할 수 있게 해 줍니다. 파일을 스테이징하거나 변경을 버리고(discard), 커밋 메시지를 쓰고, Commit · Push · Pull · Sync를 한 번 클릭으로 실행합니다.

Push · Pull · Sync를 봉투·사물함으로
  • Push(푸시) — 내 서랍의 봉투를 학교 사물함(원격)으로 갖다 넣기.
  • Pull(풀) — 사물함에 있는 봉투(다른 사람이나 다른 컴퓨터가 넣은 것)를 내 서랍으로 가져오기.
  • Sync(싱크) — 가져오기와 올리기를 함께 하기. 양쪽에 다 새 봉투가 있을 때 씁니다.
  • upstream — 내 서랍과 짝으로 정해진 사물함 칸. 처음 Push할 때 정해집니다.
Source Control
feature/memo-paging
→ main
+128 −34
M src/memo.ts우클릭: Copy Path / Copy Relative Path
A tests/memo.test.tsStage · Discard
커밋 메시지… Generate with AICommit

맨 위 줄에는 지금 브랜치와 합칠 대상(branch → base)이, 그 옆 작은 칩에는 늘어난/줄어든 줄 수가 보입니다.

Source Control 패널 세부 동작 (경로 표시 · Stage all · 칩 · 복사)
  • 경로에 한글 같은 비ASCII 문자가 있어도 UTF-8로 제대로 표시됩니다.
  • Stage all은 바뀐 파일 목록이 화면에서 잘려(개수 제한) 보이더라도 모든 변경을 스테이징합니다. 호스트가 전체 경로를 직접 찾아내기 때문입니다.
  • 브랜치 정보 줄(맨 위): 현재 브랜치(또는 detached HEAD — 브랜치가 아닌 특정 커밋에 서 있는 상태)를 위에, 비교 base를 아래에(branch → base) 쌓아 보여 줍니다. 그래서 Create PR이나 원격 동작 중에도 어느 브랜치에 있는지 가려지지 않습니다.
  • 쓸 수 있는 merge base가 있으면 작은 칩이 그 분기점 대비 추가/삭제된 줄 수 합계를 보여 줍니다. 스테이징/비스테이징을 따로 더한 값이 아니라 범위 diff 하나로 계산합니다.
  • 칩에 마우스를 올리면, 호스트가 나눈 값을 제공할 때 Code breakdown이 보입니다: Source(소스), Tests(테스트), Generated(자동 생성, 0이 아닐 때만). 내용 분석이 아니라 경로 기준 추정입니다.
  • 긴 브랜치 이름은 칩을 가리지 않도록 잘려 보입니다.
  • 바뀐 파일을 우클릭하면 Copy Path / Copy Relative Path(워크트리 루트 기준 상대 경로)를 쓸 수 있습니다.

패널 맨 아래 주 버튼은 상태에 따라 바뀌어서, 다음에 할 일이 항상 클릭 한 번 거리에 있습니다.

Stage Files스테이징 안 된 변경이 있을 때
1단계 — 고친 파일이 있으면 먼저 스테이징을 권합니다.
Commit스테이징이 끝났을 때
2단계 — 스테이징이 끝나면 커밋으로 바뀝니다.
Push로컬이 앞섬Pull원격이 앞섬Sync양쪽 다 바뀜
3단계 — 커밋 후에는 브랜치가 upstream과 어떤 관계인지에 따라 Push / Pull / Sync 중 하나가 됩니다.

충돌이 났을 때

병합 충돌(두 쪽이 같은 줄을 다르게 고쳐서 git이 어느 쪽을 택할지 모르는 상태)이 생기면 Diff viewer가 3방향 보기로 보여 주고 그 자리에서 해결할 수 있습니다.

내 쪽 limit = 20 내가 고친 줄 상대 쪽 limit = 50 다른 쪽이 같은 줄을 고침 같은 줄, 다른 값 git은 어느 쪽을 택할지 모름 결과 어느 쪽을 남길지 그 자리에서 정함 Review conflicts직접 확인 Resolve with AI에이전트에게 맡기기 Abort merge / rebase하던 병합 그만두기
병합 충돌 3방향 보기: 내 쪽 · 상대 쪽 · 결과. 아래는 Source Control에 나오는 버튼들입니다(줄 내용은 설명용 예시).

merge·rebase·cherry-pick(다른 브랜치의 커밋 하나만 가져오기)·revert(커밋 되돌리기) 후 충돌이 남으면, Source Control은 Review conflicts(충돌 검토) 옆에 Resolve with AI(AI로 해결)를 보여 줍니다. 충돌 묶음을 에이전트에게 넘기거나, 직접 확인한 뒤 진행하면 됩니다. 진행 중인 merge나 rebase를 그만두고 싶다면 Source Control의 Abort merge 또는 Abort rebase를 쓰세요.

저장소별 AI 액션 레시피 (Action recipes)

“Generate with AI”처럼 AI가 움직이는 버튼들이 어떤 지시문으로 어떤 에이전트를 부를지 바꾸는 설정입니다. 기본값 그대로 써도 되므로 처음에는 건너뛰어도 됩니다.

Action recipes 상세 — 편집 위치 · 템플릿 변수 · 저장소별 덮어쓰기

Generate with AI, Generate pull request details with AI, Fix with AI, Resolve with AI는 모두 Source Control AI 액션입니다. 각각 액션 레시피가 뒤에 붙어 있어서, 버튼을 누를 때 어떤 에이전트를, 어떤 CLI 인자로, 어떤 프롬프트 템플릿으로 실행할지 정합니다.

  • 편집 위치: Settings → Git & Source Control → Action recipes. 전역 기본값으로 하거나 현재 저장소에만 적용할 수 있습니다.
  • Model(모델)과 Effort(노력 수준)는 전용 칸에서 고릅니다. 예전에 Arguments(인자)에 저장해 둔 모델·effort 플래그는 자동으로 이 칸들로 옮겨집니다.
쓰는 곳템플릿 변수
커밋 메시지{basePrompt} {branch} {stagedFiles} {stagedPatch} {linkedIssue}
PR 내용(위 변수에 더해){baseBranch} {currentTitle} {currentBody} {commitSummary} {changedFiles} {patch}
{linkedIssue} 주의워크트리에 연결된 GitHub 이슈 번호로 바뀌며, 연결된 것이 없으면 빈 값이 됩니다(Linear/GitLab만 쓰는 워크트리도 빈 값). 그래서 그냥 Fixes #{linkedIssue}라고 쓰면 연결이 없을 때 Fixes #가 되어 버립니다. “연결된 이슈가 있으면 Fixes 줄을 넣어라”처럼 지시하는 문장으로 쓰는 편이 좋습니다.

어떤 저장소가 한 액션에 자기만의 레시피를 갖고 있으면, 전역 기본값을 저장해도 그 저장소 레시피는 바뀌지 않습니다. 설정 화면에 Repository overrides(저장소별 덮어쓰기) 안내가 나타나 어떤 저장소가 무엇(에이전트, CLI 인자, 명령 템플릿)을 다르게 쓰는지 알려 주고, Review 링크로 그 저장소 설정으로 바로 가서 덮어쓰기를 수정하거나 지울 수 있습니다.

호스팅 리뷰 · 이슈 · Actions (GitHub · GitLab · Bitbucket 외)

GitHub(코드를 올려 두고 함께 검토하는 웹사이트)·GitLab·Bitbucket 같은 서비스에서 하는 코드 검토를 호스팅 리뷰라고 합니다. Orca에서는 이것이 워크트리에 기본으로 딸린 기능입니다. 워크트리를 그 PR/MR과 연결하고, 리뷰 상태를 화면 안에 보여 주며, 앱을 떠나지 않고 이슈(할 일·버그 신고 카드)를 정리(triage — 우선순위 매기고 나누기)할 수 있게 합니다.

PR 하나의 일생

① 초안 (Draft) 아직 작업 중 병합·자동 병합 불가 ② 검토 요청 Mark ready for review 동료가 보고 코멘트 ③ 체크 (Checks) 자동 채점기(CI)가 검사 실패하면 빨간 칩 ④ 병합 (Merge) 본 원고(main)에 합침 자동 병합도 가능 Orca 사이드바에 상태가 표시됩니다: 열림 · 병합됨 · 닫힘 체크가 실패하면 Fix broken checks로 에이전트에게 고치게 할 수 있습니다(GitHub)
PR 하나가 지나가는 길. 분홍 점이 PR 하나입니다.
  1. 만들기워크트리를 푸시한 뒤 Source Control에서 PR을 만듭니다(처음엔 초안으로 둘 수 있음).
  2. 검토·체크동료의 코멘트와 자동 검사 결과가 Orca의 PR 화면·Checks 패널에 모입니다. 거기서 바로 답글을 달 수 있습니다.
  3. 병합조건이 맞으면 병합합니다. GitHub에서는 “조건이 충족되면 알아서 합치기(자동 병합)”도 켤 수 있습니다.

제공자(provider) 연결하기

제공자(코드를 맡아 두고 PR·이슈를 주고받는 서비스 — GitHub·GitLab 같은 곳)는 저장소마다 다릅니다. 저장소가 쓰는 서비스를 Settings → Integrations(설정 → 연동)에서 연결합니다.

GitHub는 Orca가 가장 많은 기능을 지원하는 서비스입니다(특히 Actions와 이슈). 자동 병합, 스택 PR, 반응(이모지), Fix broken checks, Projects 보기 등은 GitHub 전용입니다.

GitLab의 MR과 이슈도 같은 워크트리 리뷰 흐름을 씁니다.

SSH 워크트리에서 GitLab 쓰기 (GITLAB_HOST)

Workspace(워크스페이스 — 워크트리와 같은 것)가 SSH(원격 서버에 접속하는 방법)로 원격 서버에 있으면, GitLab MR·이슈 동작이 그 서버에 설정된 환경 변수(프로그램이 읽어 가는 컴퓨터 쪽 설정값) GITLAB_HOST를 거치므로, 쓰기 요청이 올바른 GitLab 서버로 갑니다.

같은 설정 화면에서 앱 안에서 연결합니다. Connect with Email & API token(이메일과 API 토큰(비밀번호 대신 쓰는 출입증 문자열)) 또는 Access token(액세스 토큰) 중 하나로 연결하며, Orca가 저장 전에 자격 증명을 확인합니다. Source Control에서 PR을 만들 수 있고, 초안 PR이 없어서 작성 화면에 Draft 토글이 없습니다.

관리자용: 환경 변수가 우선

환경 변수(프로그램이 읽어 가는 컴퓨터 쪽 설정값) ORCA_BITBUCKET_*가 있으면 화면에서 저장한 자격 증명보다 그것이 우선합니다.

Azure DevOps와 Gitea(GitHub와 같은 종류의 코드 저장·검토 서비스)의 PR도 GitHub·GitLab·Bitbucket과 나란히 워크트리 사이드바와 Checks 패널에 나타납니다. 워크트리 생성 흐름은 푸시 전에 이들에서도 원격 충돌을 확인합니다.

리뷰(PR/MR) 다루기

PR을 만들고, 상태를 보고, 코멘트에 답하고, 브라우저로 열고, 초안을 “검토 준비 완료”로 바꾸는 일을 모두 Orca 사이드바·PR 화면에서 합니다.

리뷰 다루기 세부 기능 13가지
  • 워크트리가 푸시되면 Source Control 패널에서 호스팅 리뷰를 엽니다. 만들기 전에 base 브랜치·제목·설명·초안 여부를 확인하세요.
  • 리뷰를 만들거나 여는 동안에도 Source Control의 브랜치 정보 줄에 현재 브랜치가 계속 보입니다. Create PR 동작이 브랜치 라벨을 대신 차지하지 않습니다.
  • 연결된 리뷰는 사이드바에 상태(열림 · 병합됨 · 닫힘)와 함께 표시됩니다.
  • 연결된 PR/MR의 URL을 알면 브랜치 정보 줄에 작은 Open review page in browser(브라우저에서 리뷰 페이지 열기) 링크가 생깁니다. 내부 PR 화면을 거치지 않고 GitHub·GitLab·Bitbucket·Azure DevOps·Gitea의 리뷰 페이지로 바로 갑니다.
  • 연결된 리뷰나 이슈의 더보기(overflow) 메뉴에서 Open in Orca browser를 고르면, 터미널이나 작업 화면을 떠나지 않고 현재 워크트리의 브라우저 탭에서 엽니다.
  • GitHub PR은 사이드바의 PR 동작 메뉴에서 리뷰 링크 복사, 닫기, (상태 변경을 확인한 뒤) 다시 열기를 할 수 있습니다.
  • 초안 상태의 GitHub PR과 GitLab MR은 사이드바 동작에서 Mark ready for review(검토 준비 완료로 표시) 또는 Close를 할 수 있습니다. GitLab에서는 이 동작이 Draft/WIP 상태를 없앱니다. 초안인 동안에는 병합과 자동 병합을 쓸 수 없습니다.
  • 연결된 GitLab MR은 Checks 사이드바의 리뷰 링크 메뉴에서 Unlink MR(연결 해제) 또는 Link another MR(다른 MR 연결)을 할 수 있습니다.
  • GitHub의 체크·리뷰·코멘트는 PR 탭 안에서 열립니다. GitLab MR과 이슈도 같은 리뷰 화면에서 열립니다.
  • GitLab 파이프라인의 경우 Checks 패널에 최상위 작업뿐 아니라 bridge·child 파이프라인 작업도 나옵니다. 작업을 펼치면 가능할 때 그 작업의 trace(로그)를 불러옵니다(GitHub 체크 상세가 열리는 곳과 같은 자리). 실패한 작업이 “상세 없음”으로 막히지 않습니다.
  • Checks 패널에서는 리뷰 스레드의 첫 코멘트뿐 아니라 아무 코멘트에나 답할 수 있습니다.
  • GitHub PR 대화 코멘트와 줄 단위 리뷰 스레드 코멘트에는 GitHub의 반응 8가지(👍 👎 😄 😕 ❤️ 🎉 🚀 👀)를 고르는 선택기가 있습니다. 이미 있는 반응 칩은 눌러서 켜고 끕니다. GitLab 코멘트는 바뀌지 않았습니다.
  • 묶어 보여 주는 PR 코멘트 구역은 최신순이라 새 답글이 달린 스레드가 위로 올라옵니다. Timeline 탭은 그대로 오래된 순입니다.
  • GitHub PR에 실패한 체크가 있으면 PR 화면의 Fix broken checks(깨진 체크 고치기)로 실패한 체크 이름과 링크를 에이전트에게 넘깁니다.

자동 병합 (Auto-merge)

열려 있는 GitHub PR에서 PR 화면의 병합 버튼은 Enable auto-merge(자동 병합 켜기)를 제공합니다. 요구 조건(체크 통과, 필수 리뷰 승인)이 충족되면 GitHub가 알아서 브랜치를 병합합니다. 같은 버튼으로 끌 수도 있습니다.

자동 병합 방식 · merge queue · 버튼이 숨는 경우
  • 병합 방식은 저장소 기본값을 따르며 Squash and merge(커밋을 하나로 합쳐 병합), Create merge commit(병합 커밋 만들기), Rebase and merge(커밋들을 base 위로 옮겨 병합) 중 하나입니다. 저장소가 막아 둔 방식은 보이지 않습니다.
  • 같은 버튼의 Disable auto-merge로 대기 중인 자동 병합을 취소합니다.
  • base 브랜치가 GitHub의 merge queue(병합 대기열)를 쓰면 같은 버튼이 Merge when ready로 바뀌고, PR을 대기열에 넣습니다.
  • GitHub가 초안·닫힘·충돌·불안정(unstable)으로 보고한 PR, 그리고 자동 병합을 허용하지 않는 저장소에서는 자동 병합 버튼이 숨겨지고 수동 병합만 보입니다.

스택 PR (Stacked pull requests)

스택 PR은 PR 위에 PR을 쌓는 방식입니다. 큰 작업을 작은 PR 여러 개로 나누고, 각 PR이 바로 아래 PR을 base로 삼습니다.

main (스택 base 브랜치) #101 데이터 모델open · checks passed #102 APIreview needed #103 화면 (지금 보는 PR)draft · 새 브랜치 Stack this PR above #102 → Create PR in stack Merge through #103 · 3 PRs 현재 PR과 그 아래 모든 PR을 한꺼번에 병합 (merge queue를 쓰면 Queue through #N · M PRs) 확인 창에 포함 번호 목록 표시 전부 아니면 전무 하나라도 막히면 아무것도 합치지 않음
스택 PR: 아래에서 위로 쌓이고, 스택 병합은 현재 PR부터 맨 아래까지 한 번에(전부 아니면 전무) 병합합니다.

GitHub 전용 기능입니다. PR을 만들 때 “#N 위에 쌓기”를 고르면 스택이 되고, 병합 버튼은 지금 PR과 그 아래 PR들을 한꺼번에 합칩니다. 하나라도 합칠 수 없으면 아무것도 합치지 않습니다.

스택 PR 세부 동작 (작성 화면 라벨 · Stack 지도 · 병합 라벨)
  • GitHub PR을 만들 때 고른 base에 이미 열린 PR이 있으면 작성 화면이 Stack this PR above #N을 제안합니다. 체크하면 GitHub Stack을 새로 만들거나(또는 부모의 기존 스택을 늘리고), 제출 버튼 라벨이 Create PR in stack(또는 Create draft PR in stack / Push & Create PR in stack)으로 바뀝니다. 작은 미리보기가 부모 PR과 새 브랜치를 보여 줍니다.
  • 이 옵션은 GitHub 전용이고, 실행 중인 호스트가 스택 생성을 지원할 때만 나타납니다. GitLab MR과 Bitbucket PR은 하나씩만 만듭니다.
  • GitHub가 PR을 스택의 일부로 등록하면, PR 사이드바에 접을 수 있는 Stack #N 지도가 나옵니다: 스택 안 내 위치, 스택 크기, 스택 base 브랜치. 펼치면 순서대로 늘어선 층과 상태(open, draft, checks pending/failed, review needed, conflicts, merged, closed)가 보입니다. 층을 클릭하면 그 PR을 Orca에서 엽니다.
  • 스택을 아는 병합은 단일 PR 병합 라벨 대신 Merge through #N · M PRs(merge queue를 쓰면 Queue through #N · M PRs)를 보여 줍니다. 현재 PR과 그 아래 모든 PR을 다룹니다. 스택 정보가 완전하면 확인 창에 포함된 번호들이 나열됩니다.
  • GitHub에 스택으로 등록되지 않은 평범한 의존 PR 사슬은 일반 단일 PR 병합을 그대로 씁니다. GitLab MR은 바뀐 것이 없습니다.

이슈 (Issues)

이슈 패널(화면 옆에서 밀려 나오는 패널. 원문 이름 issue drawer)에서 GitHub와 GitLab 이슈를 둘러보고, 거르고, 편집합니다. 이슈에서 바로 워크트리를 만들면 이슈와 작업이 서로 연결됩니다.

이슈에서 워크트리 만들기 · Activity · GitLab 이슈 목록
  • GitHub 이슈나 PR에서 워크트리를 만들면 조용히 백그라운드에서 만드는 대신 대화형 워크트리 작성 화면(composer)이 열립니다. 그래서 issue-command 자동화, SSH 대상, 폴더 워크트리가 다른 생성 경로와 똑같이 동작합니다. 작성 화면은 작업 이름을 미리 채우고 이슈를 연결해, 리뷰가 그 작업에 계속 붙어 있게 합니다.
  • GitHub 이슈의 상세 창에는 Activity 구역이 있어 코멘트와 타임라인 이벤트(담당자 지정, 멘션, 교차 참조, 상태 변경, 프로젝트 칼럼 이동)를 섞어 시간순으로 보여 줍니다.
  • 워크트리 사이드바의 연결된 이슈 메뉴에서 이슈 패널을 열지 않고 이슈 링크를 복사할 수 있습니다.
  • GitLab 저장소에서는 이슈 패널이 선택한 프로젝트의 열린 이슈를 보여 주고, 나에게 배정된 이슈만 남길 수 있습니다.

Actions (CI)

실패한 GitHub Actions 체크는 워크트리에 빨간 칩으로 표시됩니다. 클릭하면 실패한 작업의 로그를 화면 안에서 바로 봅니다.

Tasks — GitHub Projects 보기

사이드바의 Tasks(작업) 항목에서 GitHub Projects(GitHub의 작업 보드) 전체 보기를 씁니다. 여러 저장소에 걸친 프로젝트 카드를 보고, 출처 저장소로 거르고, 초안 PR 상태를 보고, 아무 카드에서나 워크트리를 만들 수 있습니다. Board(보드) 보기는 칸반(포스트잇을 칸별로 옮기는 보드)으로 그려져 카드를 끌어 옮길 수 있고, 놓으면 카드의 상태(status) 필드가 프로젝트에 다시 기록됩니다. 표(table)와 그 밖의 보기는 목록 형태를 유지합니다.

문제 해결먼저 할 일: 문서의 “Troubleshooting GitHub errors” 항목을 열어 아래 원인 중 어느 것인지 확인하세요. PR 상태, 체크, Tasks가 새로 고쳐지지 않으면 — 사용량 제한(rate limit), gh auth(GitHub CLI 로그인), 권한, 네트워크 문제일 수 있습니다 — 문서의 “Troubleshooting GitHub errors” 항목을 참고하세요.

Jira 연동 — Jira 이슈 패널

무엇인가. Jira(이슈 = 할 일·버그 카드를 관리하는 서비스) Cloud 또는 자체 설치(Server/Data Center — 회사 서버에 직접 설치한 Jira) Jira의 이슈를 Orca 안에서 둘러보고, 고치고, 워크트리와 연결합니다. Linear나 GitHub 항목을 연결하는 방식과 똑같습니다. Jira는 작업 패널(화면 옆에서 밀려 나오는 패널. 원문 이름 task drawer)에서 GitHub·Linear 옆에 자리합니다.

Jira 사이트 연결하기

  1. Tasks에서 Jira 고르기사이드바 Tasks를 열고 출처 선택기에서 Jira를 고릅니다. 자격 증명을 저장하기 전에도 Jira는 기본으로 GitHub·Linear 옆에 있습니다.
  2. Connect Jira누르면 Connect Jira site 대화상자가 뜹니다.
  3. Cloud 또는 Self-hosted 선택아래 탭에서 각각 넣을 값을 확인하세요. 대부분은 주소 + 이메일 + 토큰(비밀번호 대신 쓰는 출입증 문자열)입니다.
  4. ConnectOrca가 자격 증명을 확인하고 사이트를 불러옵니다.
Jira Cloud site URL예: https://example.atlassian.net
Atlassian emailAtlassian 계정의 이메일 주소
Atlassian API token비밀번호 대신 쓰는 출입증 문자열. id.atlassian.com → Security → API tokens에서 만듭니다.
Jira base URLServer/DC의 기본 주소. Jira가 /가 아닌 하위 경로에 있다면 그 경로까지 넣습니다.
Auth method
(로그인 방식)
Personal access token — Bearer PAT(개인 액세스 토큰(나 한 사람용 출입증 문자열)). 최신 Server/DC에서 권장.
Username and password — PAT가 없는 오래된 버전용 Basic 인증(아이디·비밀번호를 그대로 보내는 가장 기본적인 로그인 방식).
  • Atlassian 사이트를 여러 개 연결할 수 있습니다. 사이트가 연결되면 Tasks 머리글에 사이트 선택기가 생기고, All sites를 고르면 여러 사이트 이슈를 합쳐 봅니다.
  • Jira를 전혀 안 쓴다면 Settings → Tasks에서 출처 선택기에서 숨길 수 있습니다.
① 토큰 만들기 Atlassian 계정 설정 (출입증 발급) ② Orca에 붙여 넣기 Connect Jira site 저장 전에 확인 ③ OS 키체인 보관 암호화 · 내 컴퓨터에만 (운영체제 비밀번호 보관함) ④ Jira 사이트 설정한 사이트를 부를 때만 사용 그만 쓸 때: Atlassian 계정 설정에서 토큰 폐기(revoke)
토큰은 출입증입니다. 발급 → Orca에 맡김 → 내 컴퓨터 금고에 보관 → Jira 갈 때만 사용 → 필요 없으면 폐기.

Jira 쓰기

GitHub·Linear·Jira 이슈가 한 목록에 모이고, 이슈를 열어 상태·담당자를 고치거나 코멘트를 달고, 이슈에서 바로 워크트리를 만들 수 있습니다. 검색창에는 평범한 단어를 넣어도 됩니다.

Jira 쓰기 세부 기능 (JQL 검색 · 새 이슈 대화상자 · URL 붙여 넣기 · 출처 기억)
  • 각 출처를 켜면 작업 패널이 GitHub·Linear·Jira 이슈를 하나의 목록으로 보여 줍니다.
  • 검색창은 JQL(Jira 전용 검색 문법. 예: project = ABC AND status = Done)만이 아니라 평범한 단어도 받습니다. JQL 연산자가 없으면 이슈 본문을 검색하고(단어 일부도 일치), ABC-1처럼 이슈 키 모양이면 그 이슈를 먼저 찾은 뒤 없으면 본문 검색으로 넘어갑니다. JQL처럼 보이는 검색을 Jira가 400 오류로 거부하면 Orca는 본문 검색 결과를 대신 보여 주고, Jira가 밝힌 이유는 Details 안에 둡니다.
  • 이슈를 열면 옆 패널에서 전체 설명·코멘트·메타데이터를 봅니다. 상태(가능한 전환(transition)으로), 우선순위, 담당자, 사용자 정의 필드를 그 자리에서 고칩니다.
  • 패널의 코멘트 작성란에서 코멘트를 추가합니다.
  • New Jira issue 대화상자는 실수로 닫아도(Esc, Cancel, 바깥 클릭, 닫기) 제목과 설명을 기억합니다. 같은 앱 세션에서 다시 열면 글이 돌아오고, 생성에 성공하면 지워지며, 앱을 다시 시작하면 남지 않습니다. 이슈 유형 등 다른 선택기는 평소처럼 열 때의 기본값을 씁니다.
  • 같은 대화상자에서 담당자를 미리 정할 수 있습니다: Automatic(프로젝트 기본값), me(나), 또는 배정 가능한 사용자 검색. 이 선택기는 Jira 생성 화면이 담당자를 받을 때만 나타나며, 고른 프로젝트와 사이트 범위로 제한됩니다.
  • Jira 이슈에서 워크트리를 만들면 작업 이름이 미리 채워지고 워크트리가 이슈와 연결되어, 리뷰와 이슈가 함께 묶입니다.
  • Create workspace(워크트리 만들기) 대화상자의 이름 칸에 Jira 이슈 URL(https://…/browse/ABC-123)을 붙여 넣거나, 칸을 Jira search로 바꿔 글자로 이슈를 고를 수도 있습니다. Orca가 워크트리 이름을 채우고 이슈를 연결하며, 워크트리 카드에 키와 요약, View on Jira를 보여 줍니다. 붙여 넣기는 여러 사이트를 고려합니다. URL 주소와 맞는 연결 사이트가 둘 이상이면 어느 사이트인지 묻고, 하나도 없으면 연결되지 않은 사이트라고 알려 줍니다.
  • Orca는 저장소마다 마지막으로 쓴 작업 출처를 기억해서, Jira 중심 저장소는 다음에 열 때 Jira가 기본입니다.
자격 증명은 어디에 저장되나요?Atlassian API 토큰이나 자체 설치용 자격 증명은 OS 키체인(운영체제의 비밀번호 보관함)으로 암호화되어 내 컴퓨터에만 저장되며, 설정한 Jira 사이트를 호출할 때만 쓰입니다. Orca를 더 이상 쓰지 않으면 Atlassian 계정 설정에서 토큰을 폐기(revoke)하세요.

Linear 연동 — Linear 이슈 패널

Linear(이슈·프로젝트 관리 서비스)는 작업 패널(화면 옆에서 밀려 나오는 패널)에서 GitHub 같은 호스팅 리뷰 서비스 옆에 있습니다. GitHub 이슈처럼 Linear 이슈를 둘러보고, 만들고, 고치고, 워크트리와 연결합니다.

설정

  1. Settings → Integrations → Linear설정의 연동 화면에서 Linear를 엽니다.
  2. API 토큰 붙여 넣기Linear의 Settings → API에서 만든 개인 API 토큰(비밀번호 대신 쓰는 출입증 문자열)을 붙여 넣습니다.
  3. 팀 고르기보고 싶은 팀(들)을 고릅니다.

Linear 쓰기

한 목록

작업 패널이 GitHub와 Linear 이슈를 하나로 합쳐 보여 줍니다.

이슈 → 워크트리

이슈에서 워크트리를 만들면 이름과 브랜치 이름이 미리 채워지고 이슈가 연결됩니다.

그 자리에서 고치기

상태·담당자·우선순위·라벨·추정치를 Orca 안에서 바꿉니다.

그림도 에이전트에게

이슈 속 이미지가 에이전트 프롬프트에 함께 들어갑니다.

Linear 쓰기 세부 기능 (Has Workspace · 이슈 다시 연결 · 대화상자 기억 · 화면 배치 저장)
  • 작업 패널이 GitHub와 Linear 이슈를 하나로 합쳐 보여 줍니다.
  • Linear 작업 보기의 Has Workspace 모드는 이미 로컬 워크트리나 폴더 워크트리에 연결된 이슈만 보여 줍니다. 워크트리가 붙은 줄을 누르면 그 워크트리가 열리고, 두 번째 작업본이 필요하면 같은 이슈에서 새로 시작할 수도 있습니다.
  • Linear 이슈에서 워크트리를 만들면(GitHub 항목과 같은 경로로) 대화형 워크트리 작성 화면이 열려 issue-command 자동화·SSH·폴더 워크트리가 적용됩니다. Orca가 이름을 미리 채우고 이슈 ID를 붙입니다. Linear가 이슈의 브랜치 이름을 제공하면 제목을 줄인 이름 대신 그것을 워크트리 브랜치로 씁니다(Linear가 제안하는 것과 같은 이름). 이슈 상세 메뉴에서 Copy suggested branch name(제안 브랜치 이름 복사)도 할 수 있습니다.
  • 만든 뒤에는 워크트리 카드의 Edit Worktree Details를 열고 Issue 칸에서 Linear 칩을 쓰거나 Linear URL을 붙여 넣어, 워크트리를 다시 만들지 않고 이슈를 연결·변경합니다. GitHub와 Linear는 이 한 칸을 함께 쓰므로, 새 링크를 저장하면 이전 제공자의 링크가 대체됩니다.
  • 이슈 상세 보기에서 상태, 담당자, 우선순위, 라벨, 추정치(estimate)를 고칩니다. 우선순위는 Linear 고유 아이콘으로 표시되어 Linear 화면과 똑같아 보입니다.
  • Linear 이슈에서 에이전트를 실행하면, 이슈 설명·코멘트·하위 이슈에 들어 있는 이미지와 미디어가 프롬프트 맥락에 함께 들어갑니다. 시안이나 버그 재현 화면을 직접 캡처해 붙일 필요가 없습니다. 이슈 설명 속 비공개 Linear 이미지도 깨진 그림 대신 패널에 제대로 뜹니다.
  • New Linear issue와 New Linear project는 실수로 닫아도(Esc, Cancel, 바깥 클릭, 닫기) 제목·설명(프로젝트는 이름·요약·brief까지)을 기억합니다. 같은 앱 세션에서 다시 열면 돌아오고, 생성에 성공하면 지워지며, 앱 재시작 후에는 남지 않습니다. 팀/프로젝트 선택기는 열 때의 기본값을 씁니다.
  • 긴 목록은 Load more(더 불러오기)로 나눠 불러옵니다.
  • 화면 배치 선택은 재시작 후에도 유지됩니다: 목록/보드, 묶기(group-by), 정렬(order-by), 보이는 칼럼, 속성 필터. 속성 필터는 Linear 워크스페이스(Linear 쪽 팀 공간)별로 저장되어, Linear 워크스페이스를 바꿔도 다른 곳의 필터가 섞이지 않습니다.
  • Orca는 저장소마다 마지막으로 쓴 작업 출처(GitHub, Linear, Jira)를 기억합니다.
상태 자동 동기화는 선택워크트리를 만들 때 이슈를 “In Progress”로 옮기는 Linear 상태 동기화는 팀별로 직접 켜야 합니다.

에이전트와 CLI

에이전트도 명령으로 Linear 이슈를 읽고 쓸 수 있습니다.

orca linear 명령 · 스킬 · 플래그

에이전트는 orca linear 명령(과 orca-linear 스킬)으로 Linear를 읽고 쓸 수 있습니다. 여기에는 MCP 호환 생성/수정과 목록 필터(save-issue, list-issues, relation add/remove)와 이슈 맥락 플래그(--activity, --full)가 포함됩니다. 자세한 것은 CLI 레퍼런스의 Linear 항목을 보세요.

GitHub 이슈 · Projects Linear 이슈 Jira 이슈 워크트리 작성 화면 이름 미리 채움 · 이슈 연결 워크트리 → PR/MR 이슈와 리뷰가 함께 묶임
어느 이슈 트래커에서 시작하든 같은 작성 화면을 거쳐 워크트리가 만들어지고, 이슈·작업·리뷰가 한 줄로 이어집니다.

레시피: AI diff를 줄 단위로 리뷰하기

AI diff를 잘 리뷰하느냐가 “빠르게 배포”와 “버그를 배포”를 가릅니다. 아래 순환을 그대로 따라 해 보세요. 이전/다음 버튼으로 한 단계씩 넘길 수 있습니다.

1. diff 열기

워크트리의 diff 보기를 엽니다.

2. 파일별로 훑기

j / k로 파일을 하나씩 넘깁니다. hunk마다 세 가지를 물어보세요.

  • 이 변경이 꼭 필요한가?
  • 최소한으로 바꿨나?
  • 파일의 나머지 부분과 어울리나(스타일·구조)?

3. 코멘트 남기기

바꾸고 싶은 곳에 c로 코멘트를 답니다. 완전한 문장으로 쓰는 것이 가장 효과적입니다.

4. Send to agent

diff 전체를 다 봤으면 Send to agent를 누릅니다. Orca가 모든 코멘트를 프롬프트 하나로 묶습니다.

5. 에이전트가 고치는 모습 지켜보기

노랑 = 입력 기다림 초록 = 작업 중
상태 점이 노랑(더 많은 입력을 기다림) 또는 초록(작업 중)으로 바뀝니다.

6. 쉬는 상태가 되면 다시 diff 열기

에이전트가 idle(쉬는 상태)이 되면 diff를 다시 엽니다. 코멘트는 그대로 고정되어 있습니다. 고쳐진 것은 Resolve하고, 나머지에는 후속 코멘트를 남깁니다.

7. 깨끗해질 때까지 반복, 그다음 커밋

더 고칠 것이 없을 때까지 3~6단계를 반복한 뒤 커밋합니다. 이후는 커밋 · 푸시 · PR 만들기를 따르세요.

코드를 모른다면

2단계의 세 질문은 코드를 읽을 줄 알아야 답할 수 있습니다. 코드를 모르면 대신 이렇게 확인하세요.

  • 바뀐 파일 수·범위가 요청과 맞는지 보기 — “메모 화면 글자색만 바꿔 줘”라고 했는데 파일이 열 개 넘게 바뀌었다면 이상한 신호입니다. 파일 트리와 늘어난/줄어든 줄 수 칩만 봐도 알 수 있습니다.
  • 모르는 줄에는 질문 코멘트 달기 — 그 줄에서 c를 누르고 “이 줄이 하는 일을 쉬운 말로 설명해 줘”라고 적어 보내면, 에이전트가 설명해 줍니다. 설명이 요청과 어긋나면 그때 고쳐 달라고 하면 됩니다.
  • 결과 화면을 직접 보기 — 화면(HTML)을 바꾼 작업이면 Diff viewer의 눈 모양 아이콘이나 내장 브라우저로 결과 화면을 열어, 원하던 모습인지 눈으로 확인합니다.
Diff — 바뀐 파일 1개
M memo/static/index.html+2 −1
+ 40 color: #2b6cb0;L40
💬 나: 이 줄이 하는 일을 쉬운 말로 설명해 줘.Resolve
요청: “글자색만 파랗게” → 파일 1개, 줄 몇 개 = 범위가 맞음Send to agent ▾
한눈에 정리
  • 변경은 작업 폴더 → 스테이징 → 커밋 → 원격 → PR/MR 순서로 이동하고, Orca는 이 전 과정을 Diff viewer·커밋 패널·Source Control 패널에서 처리합니다.
  • Diff viewer: 합친 diff, 이미지·HTML 미리보기, 3방향 충돌 해결, hunk/줄 스테이징, 공백 표시, 구간 접기·줄바꿈(둘 다 기본 꺼짐), 비교 대상 변경, 파일 트리. 단축키 j/k, n/p, F7, s, c.
  • Annotate AI Diff: 줄에 코멘트를 고정하고 Send to agent로 한 번에 보냅니다. 보내기 단축키는 기본으로 비어 있으니 Settings → Shortcuts에서 지정합니다.
  • Attribution: AI가 쓴 줄을 거터에 표시하며 Orca 로컬 전용입니다(커밋되지 않음, 필요하면 내보내기).
  • Push는 몰래 강제 푸시하지 않고, 기록을 다시 쓴 경우에만 별도의 Force push with lease가 나타납니다. Amend는 명시적이고, 푸시된 커밋은 확인을 받습니다.
  • Generate/Fix/Resolve with AI와 PR 내용 생성은 Action recipes(AI 버튼이 어떤 지시문으로 움직이는지 정하는 설정)로 에이전트·인자·템플릿을 저장소별로 바꿀 수 있습니다.
  • GitHub는 Orca가 가장 많은 기능을 지원하는 서비스로, 자동 병합·스택 PR·반응·Fix broken checks·Actions 빨간 칩·Projects 칸반까지 지원하고, GitLab·Bitbucket·Azure DevOps·Gitea도 같은 리뷰 흐름에 들어옵니다.
  • Jira(Cloud/Self-hosted, 여러 사이트)와 Linear(API 토큰, 팀 선택, 이미지 맥락 포함)는 작업 패널(옆에서 밀려 나오는 패널)에서 이슈를 다루고 워크트리와 연결합니다.
  • 리뷰 레시피: 열기 → j/k로 훑기 → c로 코멘트 → Send to agent → 지켜보기 → Resolve·후속 코멘트 → 깨끗해지면 커밋. 코드를 모르면 바뀐 범위 확인 · “쉬운 말로 설명해 줘” 코멘트 · 결과 화면 확인으로 대신합니다.

출처: onorca.dev/docs/review/diff-viewer · onorca.dev/docs/review/annotate-ai-diff · onorca.dev/docs/review/attribution · onorca.dev/docs/review/commit-push · onorca.dev/docs/review/github · onorca.dev/docs/review/jira · onorca.dev/docs/review/linear · onorca.dev/docs/recipes/review-ai-diff

CHAPTER 07

Orca CLI와 자동화 — 명령, 예약 작업, 오케스트레이션, Computer Use, 스킬

마우스로 하던 Orca 조작을 글자 명령으로 할 수 있게 해 주는 orca 명령줄 도구를 배웁니다. 사람이 스크립트로 쓸 수도 있고, AI 에이전트가 직접 Orca를 움직이는 데도 씁니다.

이 장에서 배우는 것
  • CLI(명령줄)가 무엇이고, “에이전트가 Orca를 조작한다”는 말이 무슨 뜻인지
  • orca 명령 설치·확인 방법과 선택자(selector)·호스트 지정법
  • 분야별 명령 레퍼런스 — 런타임, 저장소, 워크트리, 터미널, 파일, 브라우저, 에뮬레이터, Linear, 아티팩트 등
  • 예약 자동화(orca automations)로 정해진 시간에 프롬프트 실행하기
  • 오케스트레이션 — Run·Task·Dispatch·Message·Decision gate로 여러 에이전트를 감독하며 일 나누기
  • Computer Use — 에이전트가 데스크톱 앱을 접근성 트리로 조작하기
  • 스킬 레지스트리와 MCP, 그리고 진행 상황을 남기는 워크트리 체크포인트
처음이라면 이것만

건너뛰어도 되는 곳: 명령 레퍼런스는 에이전트·스크립트가 찾아보는 사전입니다. 🔧 표시가 붙은 접힌 상자도 처음엔 열지 않아도 됩니다.

CLI란 무엇이고, 왜 에이전트가 Orca를 조작하나

쉽게 말하면

Orca 앱은 보통 버튼과 메뉴로 씁니다. 그런데 같은 일을 글자로 된 명령으로 시킬 수도 있습니다. 예를 들어 “새 작업 공간 만들어 줘”를 버튼 대신 orca worktree create --name my-task라고 타이핑하는 식입니다. 이렇게 글자 명령을 입력하는 창을 터미널(글자로 명령을 입력하고 결과를 글자로 돌려받는 창. 맥의 ‘터미널’ 앱, 윈도우의 PowerShell 등)이라 하고, 그 안에서 쓰는 조작 방식을 CLI(Command-Line Interface, 명령줄 인터페이스 — 버튼 대신 명령어로 프로그램을 조작하는 방식)라고 부릅니다.

글자 명령의 큰 장점은 사람이 아니어도 칠 수 있다는 것입니다. Claude·Codex 같은 AI 에이전트는 화면의 버튼을 누르기는 어렵지만 터미널에 명령을 치는 건 아주 잘합니다. 그래서 에이전트가 orca 명령을 치면, 에이전트가 직접 Orca를 움직여 새 워크트리를 만들고, 다른 에이전트에게 일을 시키고, 브라우저를 클릭하고, 진행 상황을 남길 수 있습니다. 이것이 “에이전트가 Orca를 조작한다”는 뜻입니다.

이 장에 자주 나오는 낱말 세 개
  • 런타임(지금 켜져서 일하고 있는 Orca 프로그램 본체) — orca 명령은 혼자 일하지 않고, 이 런타임에게 “이것 좀 해 줘” 하고 말을 전합니다. 그래서 Orca가 켜져 있어야 대부분의 명령이 동작합니다.
  • 셸(shell — 터미널 창 속에서 명령을 받아 실행하는 프로그램. zsh, bash, PowerShell 등) — “셸에서 실행한다” = “터미널에 쳐서 실행한다”로 읽으면 됩니다.
  • 스크립트(명령 여러 개를 적어 둔 작업 순서표. 엑셀 매크로와 비슷합니다) — 사람이 한 줄씩 치지 않아도 순서대로 자동 실행됩니다.

명령 한 줄 읽는 법 — 해부도

orca worktree create --name my-task --json ① 프로그램“Orca야” ② 대상무엇을 — 워크트리를 ③ 동작어떻게 — 만들어라 ④ 옵션과 값-- 로 시작하면 옵션 이름,바로 뒤 my-task 가 그 값 ⑤ 결과 형식기계가 읽기 좋은JSON 으로 돌려 달라 소리 내어 읽기: “Orca야, 워크트리를 만들어라. 이름은 my-task, 결과는 JSON으로.”
거의 모든 orca 명령이 이 순서입니다. 옵션(--로 시작하는 부분)은 여러 개 붙을 수 있고, 값이 필요 없는 옵션(--json처럼)은 이름만 씁니다. JSON(프로그램끼리 주고받기 좋게 정해진 틀로 적은 글자 데이터)은 사람보다 스크립트·에이전트가 읽기 편한 형식입니다.
사람 (터미널)직접 명령 입력 셸 스크립트반복 작업 자동화 AI 에이전트Claude · Codex … orca 명령 (CLI)--json 으로 결과 반환 실행 중인 Orca 런타임 • 워크트리 · 저장소 • 에이전트 터미널 • 파일 · diff 열기 • 내장 브라우저 • 예약 자동화 • 오케스트레이션 • 데스크톱 앱(Computer use) • iOS 시뮬레이터 · 아티팩트
누가 명령을 치든 orca CLI는 이미 실행 중인 Orca에게 말을 걸어 일을 시킵니다. 에이전트도 사람과 똑같은 명령을 씁니다.

정리하면 Orca CLI는 “아무 셸에서나, 실행 중인 Orca를 스크립트로 조작하는 orca 명령”입니다. 할 수 있는 일은 다음과 같습니다.

워크트리

워크트리(작업마다 따로 꺼내 놓은 프로젝트 폴더)를 만들고, 목록을 보고, 상태를 기록합니다.

에이전트 터미널

에이전트가 돌고 있는 터미널을 읽고, 글자를 보내고, 끝날 때까지 기다립니다.

파일·diff

파일과 diff(무엇이 바뀌었는지 이전과 비교해 보여 주는 화면)를 Orca 탭으로 엽니다.

내장 브라우저

Orca 안 브라우저 탭을 이동·클릭·입력·스크린샷합니다.

예약 자동화

정해진 시간에 프롬프트를 실행합니다.

아티팩트 공유

HTML·Markdown을 공개 링크로 공유합니다.

Orca 고유 도구

오케스트레이션, Computer use, 에뮬레이터, Linear 등을 스크립트나 AI 에이전트가 제어합니다.

설치·등록과 동작 확인

CLI는 데스크톱 앱에 함께 들어 있습니다. 따로 내려받는 게 아니라, 앱 설정에서 “터미널에서 orca를 쓸 수 있게 등록”만 하면 됩니다.

① 설정에서 등록Settings → General또는 → Experimental ② 명령이 보이나?command -v orca ③ Orca와 연결되나?orca status --json 준비 완료명령을 쓸 수 있음 Orca가 꺼져 있으면orca open --json 다시 ③으로
등록은 한 번만 합니다. 그다음부터는 orca status --json으로 연결만 확인하면 됩니다.
  1. CLI 등록앱 설정에서 Orca CLI를 등록합니다. 버전에 따라 Settings → General → Orca CLI(설정 → 일반) 또는 Settings → Experimental → CLI(설정 → 실험 기능)에 있습니다.
  2. 명령이 보이는지 확인command -v orca — orca 명령의 위치가 출력되면 등록된 것입니다. 성공: 경로가 한 줄 나옵니다. 실패: 아무것도 나오지 않으면 ①(설정에서 등록)로 돌아갑니다.
  3. Orca와 연결되는지 확인orca status --json — CLI가 실행 중인 Orca 런타임에 닿는지 확인합니다.
  4. Orca가 꺼져 있다면orca open --json으로 연 뒤 다시 orca status --json을 실행합니다.
command -v orca
orca status --json
# Orca가 실행 중이 아니라면
orca open --json
orca status --json

코드 속 #로 시작하는 줄은 설명 메모입니다. 실행되지 않습니다.

--json을 붙이는 이유

다른 도구(스크립트·에이전트)가 결과를 읽어야 할 때는 --json을 붙이세요. 사람이 읽기 좋은 출력은 터미널에서 빠르게 확인할 때만 씁니다.

에이전트에게 CLI 사용법 가르치기 — 에이전트가 이 명령들을 정확히 쓰도록, 앱 버전과 맞는 orca-cli 스킬(에이전트용 사용 설명서)을 설치할 수 있습니다. 스킬은 뒤의 스킬 레지스트리에서 다룹니다.

PATH 우선순위와 스킬 설치 명령

PATH(터미널이 명령어 프로그램을 찾는 폴더 목록. 앞에 있는 폴더가 먼저 쓰입니다) — 셸 시작 파일(.zshrc 등)이 예전에 따로 설치한 전역 orca를 PATH에 넣더라도, Orca는 자기 터미널 안에서는 자신의 orca를 항상 맨 앞에 둡니다. 그래서 스크립트와 에이전트는 지금 실행 중인 앱과 버전이 맞는 CLI를 부르게 됩니다.

npx skills add https://github.com/stablyai/orca --skill orca-cli
# 설정 화면이 없는 헤드리스 환경:
orca skills install --skill orca-cli

선택자(selector)와 호스트 고르기

명령 예시 읽는 약속 (이 장 전체에 적용)
  • < > — 바꿔 넣는 칸입니다. <repoId>는 글자 그대로 치는 게 아니라, 그 자리에 실제 저장소 ID를 넣으라는 뜻입니다(꺾쇠는 지웁니다).
  • # — 그 뒤는 설명 메모입니다. 실행되지 않습니다.
  • \ — 줄 끝의 역슬래시는 “다음 줄로 이어짐”입니다. 긴 명령을 보기 좋게 여러 줄로 나눈 것일 뿐, 한 줄짜리 명령입니다.
  • a|b — 옵션 설명 속 세로 막대는 “a 또는 b 중 하나”입니다.

대부분의 명령은 긴 ID 대신 선택자(selector — “어떤 워크트리·저장소를 말하는지”를 짧게 가리키는 표현)를 받습니다. 사람에게 “그 파일” 대신 “3층 회의실 왼쪽 책상의 파란 파일”이라고 정확히 짚어 주는 것과 같습니다.

선택자뜻예
id:<repoId>ID로 지정orca repo show --repo id:<repoId> --json
active / current지금 셸의 현재 폴더나 터미널이 속한, Orca가 관리하는 워크트리orca worktree show --worktree active --json
path:/abs/path절대 경로로 지정orca worktree show --worktree path:/abs/path/to/worktree --json
branch:이름브랜치 이름으로 지정orca worktree show --worktree branch:feature-name --json
issue:번호연결된 이슈 번호로 지정orca worktree show --worktree issue:123 --json
name:이름Workspace(워크스페이스 — 워크트리와 같은 것) 이름으로 지정(References 예시에 등장)--worktree name:api
스크립트에서는 명시적으로

active·current는 “지금 내가 서 있는 곳”을 기준으로 합니다. 대상 워크트리 밖에서 실행될 수도 있는 스크립트라면 id:·path: 같은 명시적 선택자를 쓰세요.

원격 런타임에서의 선택자

원격 런타임(다른 컴퓨터에서 켜져 있는 Orca)이라면 내 컴퓨터의 현재 폴더가 원격 호스트에 없을 수 있으므로 id:<repoId>::<absolute-worktree-path>나 path:<absolute-server-path>처럼 서버 쪽 전체 선택자를 쓰는 게 좋습니다.

어느 컴퓨터에서 실행할지(호스트) 고르기

호스트(명령이 실제로 실행되는 컴퓨터)는 내 컴퓨터일 수도, 다른 컴퓨터일 수도 있습니다. orca host list --json은 지금 Orca가 대상으로 삼을 수 있는 모든 컴퓨터와 각각의 선택자를 보여 줍니다. 결과에는 이 컴퓨터, 등록된 SSH(다른 컴퓨터에 안전하게 원격 접속하는 방법) 대상, 짝지어진(paired) Remote Orca Server가 포함됩니다.

orca host list고를 수 있는 컴퓨터 목록 이 컴퓨터--host local지금 앉아 있는 컴퓨터 SSH 대상--host ssh:<target-id>원격 접속으로 연결한 컴퓨터 짝지은 Remote Orca Server--environment <server-name>짝지어 둔 다른 Orca 서버
호스트 종류마다 고르는 옵션이 다릅니다. SSH와 Remote Orca Server는 8장에서 자세히 다룹니다.
호스트 지정 표와 이름 찾기 규칙
지정 방법대상
--host local이 컴퓨터
--host ssh:<target-id>SSH 대상
--environment <server-name>짝지어진 Remote Orca Server

SSH 라벨과 서버 이름이 하나뿐이면 이름으로도 찾아집니다. 이름이 겹치면 host list의 ID를 쓰세요. 컴퓨터 이름을 엉뚱한 옵션에 넣으면 Orca가 빈 결과 대신 “이 컴퓨터는 이 옵션으로 지정하세요”라고 알려 줍니다.

명령 레퍼런스 — 분야별

이 절은 사전입니다 — 건너뛰어도 됩니다

여기는 에이전트·스크립트가 정확한 명령을 찾아보는 사전입니다. 처음 읽는다면 아래 지도와 탭마다 맨 위 한 문장(“이걸로 할 수 있는 일”)만 훑고 다음 절로 넘어가세요. 명령 목록은 탭 안의 🔧 접힌 상자에 있습니다. 모든 명령 끝의 --json은 “기계가 읽을 결과로 달라”는 뜻입니다.

Orca 자체켜기·서버·예약 작업 공간프로젝트·에이전트·파일 화면 조작대신 눌러 주기 바깥 서비스·공유티켓·계정·링크 런타임·serve 자동화·환경·훅 저장소·검색 워크트리 에이전트·참조 터미널 파일 브라우저 컴퓨터·에뮬레이터 Linear 스킬·계정·아티팩트
아래 탭 11개를 성격별로 묶은 지도입니다. 찾는 일이 어느 묶음인지 먼저 고르고, 해당 탭을 여세요.

이걸로 할 수 있는 일 — Orca를 켜고(open), 연결을 확인하고(status), 화면 없는 컴퓨터에서 Orca를 서버로 계속 돌려 둘(serve) 수 있습니다.

런타임·serve 명령 목록
orca open --json
orca status --json
orca serve --port 6768 --pairing-address 100.64.1.20 --json
orca serve --supervise --json
orca serve service install --port 6768 --dry-run
orca serve service status --json
orca serve service uninstall --json
orca serve restore resume --json
명령하는 일
orca openOrca를 엽니다.
orca statusCLI가 런타임에 닿는지 확인합니다.
orca serve데스크톱 창을 열지 않고 런타임 서버를 앞단(foreground)에서 띄웁니다. Remote Orca Server나 화면 없는(headless) 환경용이며 Ctrl-C로 멈춥니다. --port로 포트, --pairing-address로 짝짓기 주소를 정합니다.
orca serve --supervise서비스 관리자용. 서버가 멈춰도 종료하지 않고 점점 늘어나는 간격으로 스스로 재시작하고, 앱 업데이트가 교체되는 동안 기다리며, 반복 실패하면 포기합니다.
orca serve service install이 프로필용으로 orca serve --supervise --no-pairing을 실행하는 사용자 단위 서비스(macOS LaunchAgent, Linux systemd user unit)를 씁니다. --dry-run은 실제로 쓰지 않고 보여만 줍니다.
orca serve service status서비스가 실행 중인지 알려 줍니다.
orca serve service uninstall서비스를 멈추고 제거합니다.
orca serve restore resume터미널 자동 복원에 걸린 일시정지를 풀고, 옛 클라이언트가 요청한 복원 목록을 보여 줍니다.
제약

이 serve·service·supervisor 명령들은 아직 Windows에서는 쓸 수 없고, service와 supervisor 명령은 그 컴퓨터에 Orca 앱이 설치돼 있어야 합니다. 자세한 건 Remote Orca Servers → orca serve as a service 문서를 보세요.

이걸로 할 수 있는 일 — Orca에 저장소(프로젝트 폴더)를 추가·확인하고, 지난 에이전트 대화 기록에서 “rate limit” 같은 낱말을 검색할 수 있습니다.

저장소·세션 검색 명령 목록

저장소(Repos)

orca repo list --json
orca repo add --path /abs/path/to/repo --json
orca repo show --repo id:<repoId> --json
orca repo set-base-ref --repo id:<repoId> --ref origin/main --json
orca repo search-refs --repo id:<repoId> --query main --limit 10 --json

list 목록, add 추가, show 상세, set-base-ref 기준 ref 지정, search-refs 브랜치·ref 검색입니다.

기준 ref 먼저

워크트리를 많이 만들기 전에 set-base-ref로 저장소의 기준 ref(브랜치나 커밋을 가리키는 이름. 예: origin/main)를 정해 두세요. 그래야 새 작업이 기본적으로 올바른 지점에서 갈라져 나옵니다.

세션 검색(Session search)

색인된 에이전트 대화 기록을 셸에서 검색합니다.

orca search --query "rate limit" --scope conversation --limit 20 --json
orca search --query "migration" --agent codex --since 30d --sort recent --json
orca search --index-status --json
옵션뜻
--scope conversation|all대화 일치만, 또는 색인된 모든 텍스트
--fresh검색 전에 색인을 새로 고침
--limit, --cursor개수 제한, 다음 페이지
--agent, --path, --since, --sort에이전트·경로·기간·정렬로 좁히기
--index-status검색 없이 색인 상태만 보고

연결된 컴퓨터와 짝지어진 서버가 접근을 허락했다면, 그 호스트의 세션도 결과에 포함될 수 있습니다.

이걸로 할 수 있는 일 — 예: “fix-login이라는 워크트리를 만들고 Codex에게 ‘로그인 테스트를 조사해 줘’라고 바로 시켜라” — 이런 일을 한 줄로 시킬 수 있습니다.

워크트리 명령과 옵션 목록
orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree active --json
orca worktree create --repo id:<repoId> --name fix-login --json
orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
orca worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
orca worktree set --worktree active --workspace-status in-review --unread --json
orca worktree rm --worktree id:<worktreeId> --force --json
명령·옵션뜻
list / ps / current / show저장소의 워크트리 목록 / 실행 현황 / 지금 워크트리 / 상세
create --name새 워크트리. --name은 워크트리 이름
--branch <branch>설정된 브랜치 접두어 없이 Git 브랜치 이름을 직접 지정. 이름이 겹치면 Orca가 숫자 꼬리를 붙일 수 있음
--parent-worktree active / --no-parentOrca 관리 워크트리 안에서 create하면 관계를 추론할 수 있을 때 새 워크트리를 자식으로 기록합니다. 명시하려면 --parent-worktree active, 독립 작업이면 --no-parent
--agent첫 터미널에서 선택한 에이전트를 실행
--prompt그 에이전트에게 첫 작업을 바로 보냄(터미널에서 도는 에이전트 포함)
--setup run|skip|inherit저장소 setup 훅을 실행 / 건너뜀 / 저장소 정책을 따름
set --comment워크트리 메모(체크포인트) 기록 — 체크포인트 참고
set --workspace-status카드 상태 변경
set --unread / --read사이드바 워크트리에 “안 읽음” 점을 켬(에이전트가 끝났을 때 보이는 그 점) / 끔
rm --force워크트리 삭제

에이전트 시작 옵션 예

orca worktree create --name review-api --agent claude --setup run --json
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
orca worktree create --name hidden-setup --setup inherit --json

이슈·리뷰 연결

orca worktree create --repo id:<repoId> --name my-task --issue 123 --json
orca worktree create --repo id:<repoId> --name review-task --pr 123 --json
orca worktree create --repo id:<repoId> --name gitlab-task --gitlab-issue 42 --gitlab-mr 77 --json
orca worktree set --worktree active --gitlab-issue '#42' --gitlab-mr '!77' --json
orca worktree set --worktree active --pr null --gitlab-mr null --json
  • --pr: GitHub PR(Pull Request. 내 변경을 합쳐 달라고 요청하는 것) 번호. --issue: 이슈 번호.
  • --gitlab-issue: 번호 또는 #42. --gitlab-mr: 번호 또는 !77(MR = GitLab의 Merge Request). HTTP(S) URL도 받으며 자체 호스팅·중첩 그룹도 됩니다. 단 URL의 호스트·프로젝트가 워크트리에 저장된 GitLab 출처나 저장소 원격과 일치해야 합니다.
  • 옵션을 빼면 그 링크는 그대로 둡니다. set에서 글자 그대로 null을 주면 그 링크만 지웁니다(create는 null을 거부).
  • 제공자마다 필드가 따로라서 GitLab 링크를 바꿔도 GitHub·Linear 링크는 보존됩니다.

이걸로 할 수 있는 일 — 이미 있는 워크트리에서 에이전트를 하나 더 띄우거나, 워크트리에 PR·Linear 이슈 링크를 여러 개 붙여 두고 나중에 이슈 번호로 그 작업과 담당 에이전트를 찾을 수 있습니다.

에이전트 실행·References 명령 목록

기존 워크트리에서 에이전트 실행

orca agent launch --agent codex --json
orca agent launch --agent codex --model gpt-6-astra --effort high --prompt "Write the design doc" --json
orca agent launch --agent claude --worktree path:/projects/myapp --focus --json
  • 새 에이전트 탭을 여는 것과 같은 방식으로 시작합니다. Chat UI 설정이 켜져 있고 에이전트·호스트가 지원하면 구조화된 채팅으로, 아니면 터미널로 열립니다. 결과의 outcome.kind가 어느 쪽이 열렸는지와 이유를 알려 줍니다.
  • --worktree 기본값은 현재 폴더를 포함한 워크트리/폴더 워크스페이스입니다. 완전히 새 체크아웃이 필요하면 orca worktree create --agent를 쓰세요.
  • --model과 --effort(--model 필요)는 두 화면 모두에 적용됩니다.
  • 탭은 포커스를 빼앗지 않고 열립니다. 보이게 하려면 --focus.
  • 응답을 못 받았다면 에이전트를 하나 더 띄우지 말고, 같은 호스트·같은 폴더에서 같은 명령에 --retry-launch <operationId>를 붙여 다시 실행하세요.

References — 워크트리에 리뷰·이슈 여러 개 연결

orca reference list --worktree name:api --json
orca reference add https://github.com/acme/api/pull/5123 https://linear.app/acme/issue/STA-1234 --worktree name:api --json
orca reference remove https://github.com/acme/api/pull/5123 --worktree name:api --json
orca reference remove --key '<key-from-list>' --worktree name:api --json
orca worktree create --name fix --reference https://github.com/acme/api/pull/5123 --reference https://linear.app/acme/issue/STA-1234 --json
orca reference find STA-1234 --json
  • 저장소 밖의 출처도 연결할 수 있습니다. 쓰기는 전체 URL을 받고, remove --key는 URL이 없는 옛 링크도 처리합니다.
  • 중복 추가·없는 것 삭제는 아무 일도 안 하며(no-op), 관련 없는 링크는 보존됩니다.
  • --pr·--gitlab-issue·--linear-issue 같은 이슈 연결 옵션과 --reference는 한 명령에 같이 쓸 수 없습니다.
  • find는 전체 URL이나 STA-1234 같은 고유 키를 받습니다(숫자만은 거부). 저장된 메타데이터만 읽고(외부 요청·대화 검색 없음) 일치하는 워크트리와 연관 에이전트(연결 상태, 터미널·메일함 주소 포함)를 돌려줍니다. 대화 내용 검색은 orca search.

찾은 에이전트에게는 명시적 주소로 메시지를 보냅니다.

orca terminal send --terminal '<terminal-from-find>' --text 'Status?' --enter
orca orchestration send --to '<mailbox-from-find>' --subject 'Status?' --type question

이걸로 할 수 있는 일 — 에이전트가 돌고 있는 터미널 화면을 읽고, “continue”를 입력해 주고, 일이 끝날 때까지 기다릴 수 있습니다.

터미널 명령 목록
orca terminal list --worktree active --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal read --terminal <handle> --screen --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal create --worktree active --title "tests" --command "npm test" --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "runner" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json
명령하는 일
list / show터미널 목록 / 상세
read출력 읽기. 기본은 이스케이프 문자를 뺀 누적 출력 스트림이라, 줄을 다시 그리는 프로그램은 조각이 겹쳐 보일 수 있습니다. 지금 그려진 화면이 필요하면 --screen(응답의 source가 stream / screen / screen-unavailable 중 무엇인지 알려 줌). 화면 읽기는 넘길 기록이 없으므로 --screen과 --cursor는 함께 못 씁니다.
read --cursor긴 출력은 한 번 읽을 때 받은 nextCursor를 저장했다가 다음에 넘겨 새 출력만 받습니다.
send --text … --enter글자 입력 후 Enter
wait --for tui-idle --timeout-ms에이전트 화면이 조용해질(일을 멈출) 때까지 대기
create / split새 터미널 / 화면 나누기(--direction horizontal|vertical), --command로 실행할 명령
rename / switch / close이름 바꾸기 / 전환 / 닫기
  • --terminal을 빼면 현재 워크트리의 활성 터미널이 대상입니다.
  • 터미널이 무엇을 기다리는지 모를 때는 보내기 전에 먼저 읽으세요.
터미널 핸들은 런타임 한정

핸들(터미널을 가리키는 짧은 이름)은 그 런타임에서만 유효합니다. Orca가 재시작됐거나 “오래된 핸들”이라는 오류가 나면 orca terminal list --json으로 다시 받으세요.

terminal list는 확인 가능할 때 각 터미널의 executionHostId와, 결과 수준의 hostScope(포함·제외된 호스트 ID)를 줍니다. 호스트 정보나 범위가 없으면 “로컬”이 아니라 “확인 불가”로 취급하세요. 터미널이 목록에 없다는 것은 그 실행 호스트가 hostScope.hostIds에 있을 때만 “종료됐다”는 증거가 됩니다.

추적이 필요한 다중 에이전트 작업은

그냥 터미널에 프롬프트를 보내지 말고 오케스트레이션을 쓰세요.

이걸로 할 수 있는 일 — 바뀐 파일이나 그 변경 내용(diff)을 Orca 화면의 탭으로 열어 줍니다.

파일 명령 목록
orca file open src/App.tsx --worktree active --json
orca file diff src/App.tsx --staged --worktree active --json
orca file open-changed --mode both --worktree active --json
  • 경로는 선택한 워크트리 기준 상대 경로입니다. 셸의 현재 폴더가 대상 워크트리 안이 아니면 --worktree <selector>를 쓰세요.
  • diff --staged: staged(git add로 커밋 대기열에 올린 상태)된 변경의 diff를 엽니다.
  • open-changed: git status를 읽어 바뀐 파일을 edit, diff, both 모드로 엽니다.
  • 이 명령들은 화면을 바꾸지 않고 탭으로만 엽니다(지금 보고 있는 워크트리여도). 탭을 보이게 하려면 --focus — 에이전트는 사용자가 그 파일을 보고 싶다고 했을 때만 붙이세요.

이걸로 할 수 있는 일 — 사람이 웹 화면을 확인하듯, Orca 안의 내장 브라우저에서 주소로 이동하고, 입력칸을 채우고, 버튼을 누르고, 스크린샷을 찍을 수 있습니다.

브라우저 명령 목록

Orca 안에 있는 내장 브라우저 탭(선택한 워크트리의 것)을 조작합니다. Chrome·Safari나 Orca 데스크톱 UI 자체는 조작하지 않습니다.

orca goto --url http://localhost:3000 --worktree active --json
orca snapshot --worktree active --json      # @e1, @e3 같은 ref를 돌려줌
orca click --element @e3 --worktree active --json
orca fill --element @e1 --value "user@example.com" --worktree active --json
orca wait --text "Welcome" --worktree active --json
orca screenshot --worktree active --json

snapshot → 행동 → 다시 snapshot 순환으로 씁니다. @e3 같은 ref는 snapshot에서 나옵니다. 페이지 이동, 탭 전환, 페이지를 바꾸는 클릭 뒤, 그리고 “오래된 ref” 오류가 나면 다시 snapshot하세요.

탭·기록(capture) 명령

orca tab list --worktree active --json
orca tab create --url http://localhost:3000 --worktree active --json
orca tab switch --index 1 --worktree active --json
orca capture start --worktree active --json
orca console --limit 50 --worktree active --json
orca network --limit 50 --worktree active --json
orca full-screenshot --worktree active --json
orca pdf --worktree active --json

console은 콘솔 로그, network는 네트워크 요청, full-screenshot은 페이지 전체 캡처, pdf는 PDF 저장입니다. 아직 전용 Orca 명령이 없는 브라우저 동작만 orca exec --command "<agent-browser command>" --json으로 실행하세요.

기기 흉내(반응형 확인)

orca set device --name "iPhone 12" --worktree active --json
orca screenshot --worktree active --json

브라우저 프로필

프로필은 탭의 세션 상태(쿠키, 로컬 저장소, 로그인한 신원)를 서로 분리해, 스크립트나 에이전트가 다른 계정으로 테스트할 수 있게 합니다. orca tab profile list --json으로 시작해 필요에 따라 create, set, clone, use-default를 씁니다.

이걸로 할 수 있는 일 — Orca 밖의 데스크톱 앱을 누르거나, iOS 시뮬레이터(컴퓨터 속 가상 아이폰)를 탭·회전할 수 있습니다.

Computer use·에뮬레이터 명령 목록

데스크톱 Computer use (요약)

orca computer permissions --json
orca computer list-apps --json
orca computer get-app-state --app com.apple.Safari --json
orca computer click --app com.apple.Safari --element-index 12 --json
orca computer paste-text --app com.apple.Safari --text "hello" --json

내장 브라우저 밖의 네이티브 데스크톱 앱용입니다. 전체 흐름과 권한 설정은 Computer Use 절에서 다룹니다.

모바일 에뮬레이터(iOS Simulator)

orca emulator list --worktree active --json
orca emulator attach "<device-name-or-udid>" --worktree active --json
orca emulator tap 0.5 0.7 --worktree active --json
orca emulator type "hello" --worktree active --json
orca emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
orca emulator button home --worktree active --json
orca emulator rotate landscape_left --worktree active --json
orca emulator exec --command "tap 0.5 0.7" --worktree active --json
orca emulator kill --worktree active --json
orca emulator shutdown --worktree active --json
  • Orca의 워크트리 단위 브리지로 iOS Simulator를 조작합니다. Orca 안에서 일하는 에이전트는 날것의 serve-sim·simctl 대신 이 명령을 써야 수명주기와 활성 기기 상태가 현재 워크트리에 붙어 있습니다.
  • 할 수 있는 일: 목록에서 시뮬레이터 연결(attach), 탭, 글자 입력, 제스처, 하드웨어 버튼(button home), 회전, 종료(kill/shutdown).
  • 좌표는 화면 크기와 무관하게 0~1로 정규화됩니다(0.5 = 가운데). 한 번 누르기는 tap, 끌기나 여러 단계 터치는 gesture.
  • 특정 시뮬레이터를 겨냥하려면 --device <udid-or-name> 또는 --emulator <id>, 워크트리를 지정하려면 --worktree <selector>.

이걸로 할 수 있는 일 — 에이전트가 Linear(팀 업무 티켓 관리 서비스)의 티켓을 읽고, 상태를 “진행 중”으로 바꾸고, 댓글을 다는 등 티켓을 관리합니다.

Linear 명령 목록

Linear 명령은 에이전트가 orca-linear 스킬을 통해 쓰는 영역입니다(옛 설치 이름 linear-tickets도 동작). --json을 권장하고, 연결된 워크트리에서는 --current로 그 이슈를 가리킵니다. Orca에 연결되지 않은 워크트리 밖에서 돌 수 있는 스크립트는 ENG-123처럼 이슈 ID를 명시하세요.

읽기(Read) 명령
orca linear issue --current --full --json
orca linear issue ENG-123 --comments --children --relations --activity --json
orca linear search "auth bug" --workspace all --json
orca linear list --filter assigned --limit 10 --json
orca linear list-issues --team ENG --state started --assignee me --json
orca linear list-issues --query auth --updated-at -P7D --cursor <cursor> --workspace <id> --json
orca linear team list --json
orca linear team states --team ENG --json
orca linear team labels --team ENG --json
orca linear project list --query launch --json

--full은 댓글·하위 이슈·첨부·관계·활동을 모두 펼칩니다. 각각(--comments, --children, --attachments, --relations, --activity)만 따로 써도 됩니다.

MCP 방식 쓰기(save-issue, relation)
# id/--current를 빼면 새로 만들기(이때 --team, --title 필수)
orca linear save-issue --team ENG --title "Fix auth" --priority high --json
orca linear save-issue ENG-123 --state "In Progress" --assignee me --json
orca linear save-issue --current --project null --due-date null --json
orca linear relation add ENG-1 --related ENG-2 --type blocks --json
orca linear relation remove ENG-1 --related ENG-2 --type related --json

save-issue의 라벨은 전체 라벨 집합을 통째로 교체합니다(Linear MCP save_issue와 같은 의미). 글자 그대로 null은 담당자·추정치·마감일·프로젝트·상위 이슈를 지웁니다.

필드 도우미(여전히 유효)
orca linear status set --current --to "In Progress" --json
orca linear assignee set --current --me --json
orca linear priority set ENG-123 --to high --json
orca linear estimate set --current --to 3 --json
orca linear due-date set --current --to 2026-08-01 --json
orca linear label add --current --label backend --json
orca linear comment add --current --body "Investigating regression" --json
orca linear comment edit <commentId> --body "Investigating the regression" --json
orca linear comment delete <commentId> --json
orca linear attach --current --url https://example.com/repro --title "Repro" --json
orca linear create --title "Flaky login test" --team ENG --priority high --json

comment edit·comment delete는 정확한 Linear 댓글 ID를 대상으로 하며, comment rm은 delete의 별칭입니다. 바꿀 글을 파일이나 표준 입력에서 가져오려면 edit에 --body-file <path|->를 쓰세요.

버전에 맞는 전체 목록은 orca linear --help 또는 orca skills get orca-linear로 확인합니다.

이걸로 할 수 있는 일 — 에이전트용 설명서(스킬)를 설치하고, 원격 컴퓨터에 Claude/Codex 계정을 추가하고, 보고서 HTML·Markdown 파일을 공개 링크로 공유할 수 있습니다.

스킬·계정·아티팩트 명령 목록

Skills (로컬, 런타임 불필요)

orca skills list
orca skills get orca-cli
orca skills get orchestration --full
orca skills install --skill orca-cli --skill orchestration
orca skills install --all --dry-run
orca skills update --all

번들된 가이드 목록, 버전에 맞는 가이드 출력, 스킬 설치·업데이트를 설정 화면 없이 합니다. install/update는 설정 화면이 쓰는 것과 같은 npx skills 명령을 실행하며 Orca 런타임에 연락하지 않습니다. 자세히는 스킬 레지스트리.

Account (호스트 로컬 런타임)

orca account list
orca account add                 # 기본은 Claude
orca account add --agent codex

Orca가 도는 헤드리스 호스트(orca serve 또는 데스크톱 앱)에서, 원격 클라이언트가 Add account 버튼을 쓸 수 없을 때(원격 런타임 범위에서는 그 버튼이 꺼짐) 관리형 Claude/Codex 계정을 추가합니다. account add는 그 호스트 터미널에서 claude login/codex login을 실행한 뒤 받은 자격 증명을 로컬 런타임에 등록합니다. Codex는 장치 인증 방식이라 브라우저 쪽 로그인은 다른 컴퓨터에서 마쳐도 됩니다. 계정을 소유한 그 컴퓨터에서 실행하세요 — 클라이언트 전용 원격 세션을 통해서가 아니라.

Artifacts — HTML·Markdown 공개 링크

orca artifacts share ./report.html --json
orca artifacts share ./notes.md --json
orca artifacts update ./notes.md --json
orca artifacts unshare ./notes.md --json
orca artifacts list --json
orca artifacts list --cursor <cursor> --json
orca artifacts delete <id> --json
공개는 기본으로 꺼져 있음

로그인한 Orca 계정으로 게시합니다. 공개 링크 보기는 로그인이 필요 없지만 만들기·목록·수정·삭제는 필요합니다. 사람이 그 기기에서 Settings → Artifacts → Allow publishing public artifact links(공개 아티팩트 링크 게시 허용)를 직접 켜야 하며, 이 관문을 여는 CLI 옵션은 없습니다. 게시를 끈 뒤에도 list·unshare·delete는 쓸 수 있어 링크를 점검·회수할 수 있습니다.

  • 받는 파일: .html, .htm, .md, .markdown. 파일당 최대 10 MiB.
  • share는 편집 토큰을 현재 Orca 프로필에 저장하고 출력하지 않습니다. update/unshare는 처음 공유한 것과 같은 로컬 경로·프로필로 찾습니다.
  • list는 페이지로 나뉩니다(nextCursor → --cursor). delete는 list의 ID를 받으며 원본 파일이 없어도 됩니다.
  • HTML의 상대 경로 자원(이미지 등)은 올라가지 않습니다 — 모든 것이 한 파일에 든 HTML이나 절대 URL 자원을 쓰세요.
  • 거부되면 artifact_sharing_disabled로 실패합니다. 재시도하지 말고 설정을 고치세요.
  • 데스크톱에서는 로컬 HTML/Markdown을 열고 Share as artifact를 누르거나, 사이드바 Artifacts 페이지에서 링크를 관리합니다.

이걸로 할 수 있는 일 — 예약 프롬프트를 만들고, 관리하는 원격 Orca 서버를 업데이트·복구하고, 에이전트 상태 훅을 켜고 끌 수 있습니다.

자동화·환경·훅 명령 목록

예약 프롬프트

orca automations list --json
orca automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider claude --repo id:<repoId> --extra-agent-args="--model opus" --disabled --json
orca automations run <automationId> --json

자세히는 예약 자동화 절.

관리형 SSH 서버(Managed servers)

orca environment list --json
orca environment status --environment <selector> --json
orca environment update --environment <selector> --json
orca environment rollback --environment <selector> --json
orca environment recover --environment <selector> --json
orca environment stop --environment <selector> --yes --json
orca environment forget --environment <selector> --yes --json

--environment는 이 컴퓨터가 SSH로 배포한 관리형 Orca 서버를 가리킵니다(Settings → Managed servers와 같은 동작). 상태 확인·업데이트·되돌리기(rollback)·복구가 있고, stop은 서버를 폐기하며, forget은 호스트가 사라진 서버의 연결을 끊습니다. 자세히는 SSH worktrees → Managed Orca server 문서.

원격 런타임 환경

orca environment add --name work-laptop --pairing-code "orca://pair?code=..." --json
orca environment list --json
orca environment rm --environment <selector> --json

에이전트 상태 훅

orca agent hooks status --json
orca agent hooks on --json
orca agent hooks off --json

에이전트 상태 훅의 현재 상태 확인·켜기·끄기입니다.

에이전트 습관(Agent habits) — 권장 사항
  • 결과를 프로그램이 읽어야 하면 --json을 붙인다(기계가 읽기 쉬운 형식).
  • 화면에 보이는 글자로 대상을 짐작하지 말고, id: 같은 정확한 선택자(대상을 가리키는 이름표)로 고른다.
  • 다음에 무엇을 입력할지 분명하지 않으면, 보내기 전에 터미널 화면을 먼저 읽어 본다.
  • 진행 상황은 워크트리 카드의 코멘트로 남긴다(체크포인트).
  • 누가 무엇을 맡았고 끝났는지 따라가야 하는 여러 에이전트 작업은, 터미널에 그때그때 지시를 넣는 대신 오케스트레이션을 쓴다.

예약 자동화 — 정해진 시간에 프롬프트 실행

무엇인가 — Orca 자동화(automation)는 정해진 일정에 프롬프트를 실행합니다. 왜 필요한가 — 매일 아침 이슈 정리, 매시간 PR 리뷰 같은 반복 일을 사람이 워크트리를 직접 열지 않아도 시작할 수 있습니다. 아래에서 “꺼진 자동화를 만들고 → 살펴보고 → 준비되면 실행”하는 흐름을 따라갑니다.

하루 타임라인 (0시 → 24시) 0시12시24시 hourly daily 09:00 매일 한 번 한 주 (월 → 일) 월화수목금토일 weekdays weekly 한 주에 한 번 · 그 밖에 cron 식 · RRULE(반복 규칙 표기)도 가능
--trigger 프리셋의 감을 잡기 위한 그림입니다. 정확한 시각은 --time, 시간대는 --timezone으로 정합니다.

1단계 — 꺼진 상태로 안전하게 만들기

프롬프트와 대상을 다듬는 동안 실수로 돌지 않도록 --disabled로 시작합니다.

orca automations create \
  --name "Weekday triage" \
  --trigger weekdays \
  --time 09:00 \
  --prompt "Triage new issues and summarize blockers" \
  --provider codex \
  --repo my-repo \
  --disabled \
  --json

2단계 — 목록과 상세 확인

orca automations list --json
orca automations show <automationId> --json

켜기 전에 이름·프롬프트·대상·일정이 맞는지 살핍니다.

3단계 — 지금 한 번 직접 실행해 보기

orca automations run <automationId> --json
orca automations runs --id <automationId> --json

다음 예약 시간을 기다리지 않고 수동 실행해 프롬프트와 대상이 맞는지 확인하고, runs로 실행 기록을 봅니다. 실행이 워크트리를 열거나 대상에 다시 연결하기 전에 실패했다면 Orca에서 그 실행을 열고 Rerun을 눌러 같은 자동화의 새 수동 실행을 대기열에 넣습니다.

4단계 — 켜기

orca automations edit <automationId> --enabled --json

edit로 이름·프롬프트·provider·대상·일정·켜짐 상태를 바꿀 수 있고, remove는 자동화와 실행 기록까지 지웁니다.

처음에는 위 네 단계(꺼진 채 만들기 → 확인 → 한 번 실행 → 켜기)만 기억하면 됩니다. 옵션마다의 뜻은 아래 접힌 표에 있습니다.

create 옵션 전체 표
옵션뜻
--name자동화 이름
--trigger일정. 프리셋 hourly·daily·weekdays·weekly, 또는 cron 식(‘분 시 일 월 요일’ 다섯 칸으로 반복 일정을 적는 표기법. 예: 0 18 * * 1-5 = 평일 18시), 또는 RRULE(달력 표준(iCalendar)의 반복 규칙 문자열) 문자열
--time실행 시각(예: 09:00)
--timezone <tz>런타임 기본값 대신 특정 IANA 시간대(예: Asia/Seoul)를 따름
--prompt에이전트에게 줄 프롬프트
--provider실행할 에이전트(예: codex, claude)
--repo <selector>실행마다 저장소에서 작업을 만들거나 고름
--workspace <selector>이미 있는 워크트리나 폴더 워크스페이스 안에서 실행
--project / --host특정 프로젝트 호스트 setup에서 실행
--project-host-setup <id>setup ID를 이미 알 때
--source-context '<json>'작업/provider 데이터를 특정 호스트·계정에 고정(편집 시 null로 지움)
--precheck실행 전 가벼운 셸 검사
--reuse-session / --fresh-session이전 터미널 이어 쓰기 / 매번 새 터미널
--extra-agent-args=실행마다 덧붙일 모델·effort 인자
--missed-run-grace-minutes놓친 실행의 유예 시간(분)
--disabled / --enabled꺼짐 / 켜짐

화·목·토처럼 프리셋 이름이 없는 여러 요일 규칙은 “Invalid schedule” 대신 저장된 일정 그대로 표시됩니다.

어디서 실행할지 고르기

실행할 때마다 저장소에서 작업을 만들거나 고릅니다. 위 1단계 예가 이 방식입니다.

orca automations create \
  --name "Nightly status" \
  --trigger "0 18 * * 1-5" \
  --prompt "Summarize today's changes" \
  --provider claude \
  --workspace active \
  --disabled

0 18 * * 1-5 읽는 법: 0분 · 18시 · 매일(*) · 매월(*) · 월~금(1-5) = 평일 오후 6시.

이미 있는 Orca 워크트리 안에서 돌립니다.

대상 생략 시 동작과 에이전트별 프롬프트 입력

이미 있는 Orca 워크트리나 폴더 워크스페이스 안에서 돌립니다. 두 대상 옵션을 모두 빼면 Orca가 가능할 때 현재 셸 폴더가 속한 워크트리를 씁니다.

Orca 서버의 기존 워크트리에서 예약 실행될 때, 시작 후에 프롬프트를 읽는 에이전트(Aider, Goose, Amp 등)에게는 준비되는 대로 Orca가 프롬프트를 입력해 줍니다(놀고 있게 두지 않음). Claude·Codex처럼 명령줄로 프롬프트를 받는 에이전트는 원래 영향이 없었습니다.

특정 프로젝트·호스트(작업이 돌아가는 컴퓨터)를 정해 돌릴 때 씁니다.

--project / --host 예시와 세부 옵션
orca automations create \
  --name "Remote triage" \
  --trigger daily \
  --time 09:00 \
  --prompt "Triage open issues" \
  --provider claude \
  --project <projectId> \
  --host <hostId> \
  --disabled \
  --json

--repo/--workspace만이 아니라 특정 프로젝트 호스트 setup에서 돌려야 할 때 씁니다. setup ID를 알면 --project-host-setup <id>. --source-context '<json>'은 작업·provider 데이터를 호스트/계정에 고정합니다(편집 때 null을 주면 지워짐).

실행 전 검사(precheck)

precheck는 예약 시각에 에이전트를 깨우기 전에 “오늘 할 일이 있나?”를 먼저 확인하는 짧은 셸 명령입니다.

예약 시각 도착 --precheck 셸 명령“할 일 있나?” 미리 확인 성적표 0(성공) → 실행에이전트에게 프롬프트 0이 아님(실패) → skipped건너뜀으로 기록
종료 코드(명령이 끝나면서 남기는 성적표 숫자. 0이면 성공, 그 밖의 숫자는 실패)로 갈림길이 정해집니다. 가벼운 검사 명령이 실패하면 그 회차는 “건너뜀(skipped)”으로 기록됩니다. 할 일이 없을 때 에이전트를 깨우지 않는 방법입니다.
orca automations create \
  --name "PR review" \
  --trigger hourly \
  --precheck "gh pr list --json number -q .[0].number" \
  --prompt "Review requested PRs" \
  --provider codex \
  --repo my-repo \
  --disabled \
  --json

gh pr list …는 검토 요청된 PR이 있는지 확인하는 명령입니다. 이런 검사 명령은 에이전트에게 만들어 달라고 해도 됩니다.

그 밖의 세부 조정

놓친 실행을 얼마나 늦게까지 따라잡을지(--missed-run-grace-minutes), 지난번 터미널에서 이어서 할지(--reuse-session), 이 자동화만 다른 모델을 쓸지(--extra-agent-args)도 정할 수 있습니다.

놓친 실행 유예·세션 이어 쓰기·실행별 모델과 effort

놓친 실행 유예, 세션 이어 쓰기

orca automations edit <automationId> --missed-run-grace-minutes 30 --json

놓친 실행(missed run)의 유예 시간을 분 단위로 정합니다.

orca automations create \
  --name "Inbox digest" \
  --trigger hourly \
  --prompt "Summarize unread mail" \
  --provider codex \
  --workspace active \
  --reuse-session \
  --disabled

기존 워크트리를 대상으로 하는 자동화에 --reuse-session을 붙이면, 다음 실행이 빈 터미널이 아니라 이전의 살아 있는 자동화 터미널에서 이어서 진행됩니다. 다시 매번 새 터미널로 돌리려면 orca automations edit <automationId> --fresh-session --json.

실행별 모델·effort(--extra-agent-args)

orca automations create \
  --name "Docs tidy" \
  --trigger daily \
  --prompt "Tidy the docs" \
  --provider claude \
  --extra-agent-args="--model opus --add-dir docs" \
  --disabled
  • 자동화마다 실행 때 추가 에이전트 인자를 줄 수 있어, 호스트 기본값을 바꾸지 않고 이 자동화만 다른 모델·effort를 씁니다. 데스크톱 편집기에서는 Advanced → Extra agent arguments(고급 → 추가 에이전트 인자).
  • 새 실행마다 호스트의 그 에이전트 기본 Arguments에서 시작해 추가 인자를 덧붙이며, 추가 인자에 모델·effort가 있으면 기본값의 것을 대체합니다.
  • 값이 --로 시작하므로 반드시 =로 붙여 씁니다.
  • 허용되는 것은 모델·effort 옵션과 Claude의 --add-dir뿐이며, 대상 에이전트는 Claude, Codex, CodeBuddy, Cursor, Grok, OMP입니다. 권한·설정·프롬프트·세션 옵션은 거부됩니다.
  • 매번 새 세션이 필요하므로 --reuse-session과 함께 못 씁니다. 지우려면 orca automations edit <automationId> --extra-agent-args=.

데스크톱 Automations 페이지와 여러 호스트

Automations

검색: 이름·프로젝트·프롬프트 Filters: Host · Enabled/Paused · Failed/Succeeded/Never ran · Agents

Name ↕HostLast run ↕
Weekday triagethis computerSucceeded · 2h ago
Remote triagessh: build-boxFailed · 1d ago
Docs tidypaired serverNever ran

위는 화면 구성을 설명하기 위한 흉내입니다(값은 예시).

앱의 Automations 페이지에서는 이 컴퓨터와 연결된 다른 컴퓨터의 예약 작업을 한 표로 보고, 검색·필터·정렬할 수 있습니다.

Automations 페이지 세부 동작과 단축키
  • 이 컴퓨터와 지원되는 연결된 Orca 호스트의 일정을 한 표로 불러옵니다. Host 열은 자동화가 저장·예약된 곳이며, Filters → Host로 특정 호스트만 보거나 All hosts로 돌아갑니다.
  • UI에서 만들 때는 Create on으로 먼저 호스트를 고르고, 그다음 프로젝트를 고릅니다(프로젝트 목록은 그 호스트 것). 더 새 Orca 서버가 필요한 호스트는 사라지지 않고 비활성 상태로 Update server 안내와 함께 보입니다.
  • 검색창은 이름·프로젝트·프롬프트 글자로 거릅니다. SSH 호스트에 있는 외부 자동화는 그 호스트가 끊겨 있어도 관리(삭제 포함)할 수 있어, 일정 하나 지우려고 SSH 연결을 할 필요가 없습니다.
  • Filters: Host, Enabled/Paused 상태, 마지막 실행 결과(Failed, Succeeded, Never ran), Agents(여러 개 가능, 목록이 길면 하위 메뉴 안에서 검색). 걸린 필터는 표 위에 지울 수 있는 알약으로 보입니다.
  • 표에는 호스트, 마지막 실행 결과, 상대 시간이 보입니다. Name(가나다/알파벳순)이나 Last run(기본 최신순) 열을 눌러 정렬합니다.
키동작
검색창에서 ↑/↓보이는 일치 행 사이로 선택 이동(선택 행이 화면에 유지됨). 수정키를 누르거나 글자 조합 중이면 원래 커서 동작
Enter선택한 자동화나 실행 열기
상세에서 ↑/↓실행 기록 이동
←/→Overview ↔ Runs 전환
Esc상세에서 목록으로

오케스트레이션 — 여러 에이전트를 감독하며 일 나누기 Experimental

쉽게 말하면

팀장(코디네이터 에이전트)이 할 일 목록(Task)을 만들고, 팀원(워커 에이전트)에게 하나씩 맡긴 뒤(Dispatch), 우편함(Inbox)으로 “다 했어요”(worker_done)나 “질문 있어요”(question) 편지를 받는 구조입니다. 중요한 결정은 팀장이 “결정 관문”(Decision gate)을 세워, 답이 나올 때까지 그 일을 멈춰 둡니다.

언제 쓰나 — 누가 맡았는지(소유), 끝났는지(완료 추적), 작업 간 순서(DAG(“A가 끝나야 B 시작” 같은 순서 관계를 화살표로 이은 그림))가 필요할 때 씁니다. 한 번 던지는 프롬프트라면 orca terminal send, 감독 없이 일을 통째로 넘기려면 orca-cli 스킬의 worktree/terminal 명령을 쓰세요.

먼저 확인할 것
  • 이 명령을 쓰기 전에 Settings → Experimental(설정 → 실험 기능)에서 orchestration을 켜야 합니다.
  • 실험적 Orchestration 패널은 성능 문제로 v1.4.247에서 꺼져 있지만, 명령은 여전히 동작합니다.
  • CLI는 실행 중인 Orca 런타임과 대화하므로 orca status --json이 먼저 성공해야 합니다.
은퇴한 옛 명령

orca orchestration run, run-stop, coordinator-start, coordinator-stop은 아무 효과가 없고, orca skills get orchestration --full을 가리키는 복구 안내만 돌려줍니다. 아래 Run + worker-start 흐름을 쓰세요.

핵심 낱말 다섯 가지 — 비유로

Run = 프로젝트 폴더

이번 일 전체를 담는 폴더이자 팀장의 우편함입니다. 폴더가 일을 직접 나눠 주지는 않습니다 — 나눠 주는 건 팀장입니다.

Task = 할 일 카드

카드 한 장에 무엇을 할지, 먼저 끝나야 할 카드, 지금 상태(대기·준비·배정됨·완료·실패·막힘)가 적혀 있습니다.

Dispatch = 1회 배정

카드 한 장을 팀원 한 명(터미널 하나)에게 한 번 맡기는 것. 다시 맡기면 새 Dispatch(시도 2)가 됩니다. “다 했어요” 보고는 지금 맡은 배정으로만 받아 줍니다.

Message = 우편함 편지

“다 했어요”(worker_done), “질문 있어요”(question), “아직 일하는 중이에요”(heartbeat) 같은 편지입니다.

Decision gate = 자물쇠

팀장이 답해야 풀리는 자물쇠. 답이 정해질 때까지 그 카드를 잠가 둡니다.

Run = 프로젝트 폴더목표(objective) 하나 + 팀장 우편함 우편함(Inbox) Task 카드 A할 일 카드 Task 카드 B할 일 카드 Task 카드 C막힘(blocked) Dispatch 시도 1실패 → 다시 맡김 재시도 Dispatch 시도 2새 배정 · 작업 중 Dispatch 시도 1“다 했어요” → 완료 Decision gate = 자물쇠팀장이 답하면 풀림 Dispatch = 카드를 터미널 한 곳에 1회 배정 · 다시 맡기면 새 Dispatch
포함 관계: Run(프로젝트 폴더) 안에 Task(할 일 카드)가 있고, 카드마다 아래로 Dispatch(배정 시도)가 쌓입니다. 시도 1이 실패하면 시도 2로 다시 맡기고, 자물쇠(Decision gate)가 걸린 카드는 답이 나올 때까지 기다립니다.

그래서 워커가 “다 했어요”나 “아직 일하는 중이에요”를 보낼 때는 카드 번호(taskId)와 배정 번호(dispatchId)를 둘 다 적습니다. 예전 시도가 엉뚱하게 지금 카드를 완료 처리하지 못하게 하려는 것입니다.

다섯 낱말의 원래 정의와 Task ID 링크
  • Run — 오래 유지되는 이름 공간이자 코디네이터의 집 우편함. 워커를 스케줄하거나 배치하지는 않습니다.
  • Task — 사양(spec), 의존 관계, 상태를 가진 작업 항목. 상태: pending, ready, dispatched, completed, failed, blocked.
  • Dispatch — 한 터미널에서 Task를 한 번 시도하는 것. worker_done·heartbeat를 받아들일 권한(수명주기 권한)을 가집니다.
  • Message — 우편함 편지: status, dispatch, worker_done, escalation, question, heartbeat 등.
  • Decision gate — 코디네이터가 소유하는 질문. 해결될 때까지 Task를 막아 둡니다.

완료 권한은 활성 Dispatch 맥락에서 나옵니다. 그래서 워커의 완료·heartbeat 메시지에는 taskId와 dispatchId를 둘 다 넣어야 합니다. 터미널에 찍힌 task_... 같은 Task ID는 클릭할 수 있는 링크로, 누르면 Orca 런타임에 그 Task의 현재 Dispatch를 물어 배정된 터미널로 포커스를 옮깁니다(원격·SSH 런타임에 있는 Task도 됨).

pending대기 ready준비 dispatched배정됨 completed완료 failed실패 blocked막힘 먼저 할 카드 끝남 worker-start(배정) worker_done succeeded (성공 보고) worker_done failed (실패 보고) 자물쇠(gate) 또는task-update --status blocked
할 일 카드(Task)의 상태 그림. 화면·명령에 나오는 영어 이름 아래에 뜻을 달았고, 화살표는 이해를 돕기 위한 대표적 흐름입니다(blocked는 결정 관문이나 task-update --status blocked로 막힌 상태).

권장 감독 루프 — 단계별

이 명령은 누가 치나요?

아래 ①~⑥ 명령은 보통 코디네이터(팀장 역할 에이전트)와 워커 에이전트가 스스로 칩니다. 사람이 할 일은 코디네이터에게 목표를 말해 주고, 질문·결정이 올라오면 답하고, 결과를 확인하는 것입니다.

① Run 만들기

orca orchestration run-create --objective "Split checkout QA and summarize blockers" --json

목표(objective)를 가진 이름 공간과 코디네이터 우편함이 생깁니다.

② Task 만들기

orca orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json

③ 워커 시작(= Dispatch 생성)

할 일 카드를 팀원(에이전트)에게 맡깁니다. 이 순간 Dispatch(1회 배정)가 하나 생깁니다.

orca orchestration worker-start --task <taskId> --worktree current --agent codex --json
새 자식 워크트리·워커별 모델 예시
# 새 자식 워크트리에서:
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# 워커별 모델/effort (Claude, Codex, Muse, Cursor, Antigravity, OpenCode; --terminal과 같이 못 씀):
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json
# Antigravity를 로컬 자식 워크트리의 감독 워커로:
orca orchestration worker-start --task <taskId> --worktree new-child --name research --agent antigravity --setup run --json

새 워크트리에서 --name을 빼면 Orca가 이름을 지어 줍니다.

④ 우편함 확인하며 기다리기(다 읽으면 ack = 받았음 도장)

orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
orca orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

--timeout-ms 900000 = 900,000밀리초 = 15분까지 기다린다는 뜻입니다.

팀장은 편지가 올 때까지 기다렸다가, 한 번에 배달된 편지 묶음을 모두 처리한 뒤 --ack로 “받았음” 도장을 찍습니다. 기다리는 동안에도 CLI는 주기적으로 “살아 있어요” 신호(heartbeat)를 냅니다.

Delivery와 출력 채널

한 번의 Delivery(배달 묶음)에 든 메시지를 모두 처리한 뒤 --ack로 표시합니다. 기다리는 동안 CLI는 15초마다 작은 JSON heartbeat 줄을 stderr로 내보내고, 최종 결과는 stdout에 나옵니다.

⑤ 워커가 완료 보고(워커 창에서)

orca orchestration send \
  --type worker_done \
  --subject "Completed mobile audit" \
  --body "Fixed footer overlap; no follow-ups." \
  --task-id <taskId> \
  --dispatch-id <dispatchId> \
  --outcome succeeded \
  --files-modified "src/app/settings/Billing.tsx" \
  --json

worker_done은 --outcome succeeded|failed가 필수입니다. ID는 워커에게 주입된 값을 씁니다.

⑥ 정리 — release 또는 retain

orca orchestration worker-release --dispatch <dispatchId> --json
orca orchestration worker-retain --dispatch <dispatchId> --json

받아들여진 worker_done 뒤에는 같은 터미널을 다음 Dispatch에 재사용하거나, release로 내보냅니다(살펴볼 출력은 보관하고 코디네이터 소유 에이전트 터미널만 닫음). 사용자가 남겨 달라고 했다면 디버깅용으로 retain.

코디네이터 ↔ 워커 메시지 흐름

코디네이터 Run 우편함(Inbox) check --wait --ack <deliveryId> gate-create / resolve 워커 에이전트 Dispatch 하나 = 시도 한 번 작업 중… dispatch = 일 배정 (안내문 + 카드·배정 번호) heartbeat = 살아 있다는 신호 (기본 5분마다) ask = 질문 → ← 답이 워커에게 돌아감 worker_done = “다 했어요” (정확히 1번)
한 Dispatch 동안 오가는 편지들. 코디네이터가 일을 보내면, 워커는 오래 걸릴 때 heartbeat, 막히면 ask(question), 끝나면 worker_done을 정확히 한 번 보냅니다.

더 깊은 운영 — 접어 둔 부분

워커마다 다른 모델 고르기, 멈춘 워커 살펴보기·복구, 다른 컴퓨터에서 워커 띄우기(연합), 직접 조립하는 저수준 배정, 여러 에이전트에게 한꺼번에 보내는 그룹 주소는 아래 접힌 상자에 있습니다.

워커 설정·복구·연합 워커·저수준 dispatch·우편함 주소 규칙

워커별 모델·effort와 시작 관련 설정

  • --model은 Claude, Codex, Muse, Cursor, Antigravity, OpenCode의 제공자 모델 ID를 그대로(opaque) 받습니다. Muse는 설치된 Muse가 받는 ID(예: muse-spark-1.3), Antigravity는 agy models가 알려 주는 모델 슬러그를 씁니다.
  • OpenCode 워커가 요청한 모델은 실행 호스트에서 검증되고 그 워커에만 적용되어, 다른 실행의 기본 모델을 바꾸지 않습니다.
  • --effort는 --model이 있어야 하고, 그 에이전트·모델이 그 수준을 지원할 때만 적용됩니다. 두 옵션 모두 --terminal(기존 창 재사용)과 같이 못 씁니다.
  • Orca 내장 목록보다 새 Codex 모델(예: gpt-6.x)에는 설치된 Codex가 지원하면 max, ultra를 포함한 알려진 전체 effort 어휘를 받습니다. 모르는 effort 이름은 여전히 거부됩니다.
  • 재정의는 그 실행에만 적용되고, 시작 영수증(receipt)의 launch.requested / launch.effective에 표시됩니다. 연합(federated) 시작은 실행 선호 지원을 알리는 워커 호스트가 필요합니다.
  • Settings → Agent Orchestration에서 워커 heartbeat를 끄거나 1~60분 간격을 고릅니다(기본 5분). 새로 Dispatch되는 워커에만 적용되고, 기존 워커는 원래 브리프를 유지하며, 옛 호스트는 5분 기본값을 유지합니다.
  • Chat UI가 켜져 있으면 worker-start도 새 에이전트 탭처럼, 지원되면 구조화된 채팅으로, 아니면 터미널로 엽니다. --terminal은 여전히 기존 창을 재사용합니다.
  • Orca는 로컬 Antigravity 자식 워크트리의 신뢰(trust)를 워커 시작 전에 준비합니다. SSH 너머의 Antigravity 감독은 이 신뢰 설정으로 지원되지 않습니다.

살펴보기·복구

orca orchestration worker-show --dispatch <dispatchId> --json
orca orchestration worker-read --dispatch <dispatchId> --limit 50 --json
orca orchestration worker-stop --dispatch <dispatchId> --json
orca orchestration worker-release --dispatch <dispatchId> --json
orca orchestration worker-retain --dispatch <dispatchId> --json
# 재시도 배치는 명시적 — --retry-of는 --on/worktree를 물려받지 않음
orca orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json
하지 말 것
  • 출력을 다시 읽으려고 끝난 워커 터미널을 열어 두지 마세요 — worker-release 뒤 worker-read를 씁니다.
  • release가 release_pending이나 release_unknown을 돌려줄 때 터미널을 마구 닫지 마세요. 영수증에 적힌 복구 동작을 따르세요.

연합 워커(Federated, 선택)

orca orchestration worker-start \
  --task <taskId> \
  --on windows \
  --worktree new-top-level \
  --repo <exact_remote_repo_selector> \
  --name remote-worker \
  --agent codex \
  --setup run \
  --json
orca orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --json

--on으로 다른 호스트에서 워커를 띄웁니다. 이후 명령은 Dispatch ID로 길을 찾으므로 --on을 반복하지 마세요.

저수준 dispatch(직접 구성)

orca worktree create --name billing-audit --agent codex --json
orca terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <taskId> --to <workerHandle> --inject --json

워크트리와 에이전트를 직접 띄우고, 화면이 조용해지길 기다린 뒤, Task를 그 터미널에 주입(--inject)합니다.

메시지 주소와 우편함 규칙

  • 기본 check는 연결된 Run의 가장 오래된 미확인(unacked) Delivery를 줍니다(먼저 온 것 먼저, FIFO). --ack할 때까지 같은 것을 다시 줍니다.
  • --peek / --all은 편지를 소비하지 않고 보기만 합니다.

그룹 주소: @all@idle@claude@codex@opencode@gemini@droid@grok@cursor@worktree:<id> — 그 밖에 dispatch:<dispatchId>, 코디네이터 핸들, reference find로 찾은 메일함 주소처럼 개별 주소도 씁니다.

그룹 주소 주의

그룹 주소는 worker_done·heartbeat에는 절대 쓰지 않습니다. PowerShell에서는 따옴표로 감싸세요: --to "@all".

orca orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
orca orchestration send --to @idle --subject "Anyone free?" --json
orca orchestration send --to @codex --subject "Codex agents only" --json

워커 계약(Worker contract)

일을 배정받은 워커는 팀장과 연락하는 법이 적힌 안내문(preamble)을 함께 받습니다. 약속은 다섯 가지입니다.

  1. worker_done은 정확히 한 번실패해도 보내고, --outcome을 붙입니다.
  2. 짧은 --body 요약한 일, 찾은 것, 남은 것.
  3. task ID와 dispatch ID 둘 다오래된 재시도가 엉뚱한 Dispatch를 완료 처리하지 못하게 합니다.
  4. heartbeat배정 안내문이 요구하면, 오래 걸리는 작업 중에 “살아 있어요” 신호를 보냅니다.
  5. 막히는 질문은 ask로자기 터미널 화면에서 사용자에게 묻지 말고 orca orchestration ask로 팀장에게 묻습니다.
ask 명령 예시
orca orchestration ask \
  --to <coordinatorHandle> \
  --question "Should I update the shared component or only this page?" \
  --options "shared,page-only" \
  --timeout-ms 600000 \
  --json

--json이면 ask는 JSON 객체 하나만 출력하므로, 워커는 jq -r .answer로 답만 꺼낼 수 있습니다.

결정 관문(Decision gates)

ask — 워커 → 코디네이터 질문.

gate — 코디네이터가 Task DAG를 만들어 두고, 결정이 기록될 때까지 특정 Task를 막고 싶을 때.

gate 명령 예시
orca orchestration gate-create \
  --task <taskId> \
  --question "Merge the shared button change into the task branch?" \
  --options '["yes","no"]' \
  --json
orca orchestration gate-resolve --id <gateId> --resolution "yes" --json
상태 복구와 초기화(reset)

상태 복구와 초기화

orca orchestration dispatch-show --task <taskId> --json
orca orchestration dispatch-show --task <taskId> --preamble --json
orca orchestration task-list --json
orca orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --json

dispatch-show --preamble은 워커가 받은 머리말까지 보여 줍니다. 초기화는 오케스트레이션 상태를 의도적으로 버릴 때만:

orca orchestration reset --tasks --json
orca orchestration reset --messages --json
orca orchestration reset --all --json
reset은 런타임 전체에 영향

다른 코디네이터가 활동 중일 때는, 그 정리가 의도한 게 아니라면 실행하지 마세요.

어떤 명령을 고를까

상황명령
지켜보고 있는 에이전트에게 가벼운 프롬프트orca terminal send
워커가 worker_done을 보고하고, 코디네이터를 통해 질문하고, Task ID로 추적돼야 함orca orchestration worker-start (또는 dispatch --inject)
Run(프로젝트 폴더)으로 오래 묶어 두고 감독하는 다중 에이전트 작업run-create + Task + 워커 (은퇴한 orchestration run 아님)
전체 가이드는 앱에서

명령 옵션은 앱과 함께 바뀝니다. 설치 후 에이전트는 orca skills get orchestration --full을 실행해 버전에 맞는 전체 가이드를 읽어야 합니다.

Computer Use — 데스크톱 앱 조작 Beta

무엇인가 — orca computer는 에이전트가 네이티브 데스크톱 앱(브라우저 안이 아니라 컴퓨터에 직접 설치된 앱)을 살피고 조작하게 합니다: 실행 중 앱 목록, 접근성 트리(화면의 버튼·입력칸 등을 운영체제가 나무 구조로 정리한 목록. 시각장애인용 화면 낭독기도 이걸 씁니다) 읽기, 컨트롤(버튼·체크박스 같은 화면 부품) 클릭, 값 설정, 글자 입력, 스크롤, 스크린샷. 언제 — 터미널이나 내장 브라우저가 아니라 운영체제나 다른 회사 앱을 다뤄야 할 때.

Beta

플랫폼별 네이티브 도우미가 함께 들어 있으며, 손쉬운 사용(Accessibility) 권한과 macOS에서는 화면 기록(Screen Recording) 권한이 필요합니다. 명령은 대체로 안정적이지만 옵션 이름은 바뀔 수 있습니다.

처음 설정

orca status --json
orca computer permissions --json
orca computer capabilities --json

permissions가 빠진 권한을 알려 주면 시스템 설정에서 Orca Computer Use에 Accessibility(macOS는 Screen Recording도)를 허용하고, permissions --json을 다시 실행해 확인합니다.

macOS에서는 기본적으로 에이전트가 뒤에서 앱을 다루므로, 그동안 여러분은 마우스·키보드를 계속 쓸 수 있습니다.

macOS 백그라운드 동작과 앞쪽 모드

macOS에서는 기본적으로 백그라운드에서 동작해, 에이전트가 다른 앱을 만지는 동안 여러분은 마우스·키보드를 계속 쓸 수 있습니다. 일부 동작은 그래도 앱이 앞으로 나와야 합니다. 앞쪽(foreground) 모드는 --restore-window이며, Chromium·Electron 앱에서 끌기(drag)는 이 모드가 필요합니다.

snapshot → act → snapshot

① 상태 읽기get-app-state ② 요소 하나 조작click --element-index 42 ③ 다시 읽어 확인get-app-state 화면이 바뀌면 인덱스는 무효 → 다시 읽기부터
모든 상호작용은 같은 순환입니다: 앱의 현재 상태를 읽고 → 특정 요소에 동작 → 다시 읽어 결과 확인.
orca computer list-apps --json
orca computer get-app-state --app com.spotify.client --json
orca computer click --app com.spotify.client --element-index 42 --json

com.spotify.client는 앱 식별자(bundle ID)입니다. 첫 줄 list-apps 결과에서 찾아 씁니다.

번호는 “방금 읽은 화면”에서만 유효

요소 번호(인덱스)는 가장 최근에 읽은 화면 기준입니다. 화면이 바뀌면 다시 읽고 나서 번호를 쓰세요.

요소 인덱스 규칙 전체
  • 인덱스는 가장 최근 get-app-state 결과에만 유효하고 번호가 띄엄띄엄일 수 있습니다.
  • --json 출력에서는 result.snapshot.treeText에서 트리를 읽습니다.
  • elementCount를 보고 인덱스를 지어내지 마세요.
  • 화면 이동, 포커스 변경, 스크롤, 앱이 다시 그려진 뒤에는 상태를 새로 읽은 다음 인덱스를 쓰세요.
여러 창, 앱 고르기
orca computer list-windows --app com.microsoft.edgemac --json
orca computer get-app-state --app com.microsoft.edgemac --window-id <id> --json
orca computer click --app com.microsoft.edgemac --window-id <id> --element-index 12 --json
  • 목록의 창 id가 none이 아니면 안정적인 --window-id를, 아니면 --window-index를 씁니다.
  • 앱은 list-apps가 주는 번들 ID(예: com.microsoft.edgemac)가 가장 좋습니다. 겹치지 않으면 앱 이름(--app Spotify)도 됩니다. 번들 ID와 이름이 모두 겹칠 때만 --app pid:<number>.

쓸 수 있는 동작

명령하는 일
click --element-index <i>요소 클릭 의미 기반
set-value --element-index <i> --value "text"입력칸 값 직접 설정 의미 기반
perform-secondary-action --element-index <i> --action <name>요소의 보조 동작 실행 의미 기반
type-text --text "text"키보드로 글자 타이핑
press-key --key Return키 하나 누르기
hotkey --key CmdOrCtrl+A단축키 조합(CmdOrCtrl = macOS는 Cmd, Windows·Linux는 Ctrl)
paste-text --text "text"붙여넣기로 입력
scroll --element-index <i> --direction down스크롤
drag --from-x 100 --from-y 100 --to-x 300 --to-y 300좌표로 끌기

“의미 기반” 동작은 “7번째 줄 120픽셀 지점”이 아니라 “저장 버튼”처럼 요소 자체를 겨냥하므로 더 안정적입니다. 이쪽을 먼저 쓰세요.

동작 선택 규칙·좌표 대체·민감한 입력과 스크린샷

모든 명령은 --app <app>과 --json을 함께 씁니다. 의미 기반 동작(click, set-value, perform-secondary-action)을 날것의 type-text·press-key보다 우선하세요 — 접근성 요소를 직접 겨냥하므로 키보드 입력이 깨지는 포커스 변화에도 견딥니다.

접근성 겨냥이 실패하면 조심스럽게 좌표로 물러섭니다.

orca computer click --app com.apple.Safari --x 120 --y 340 --json
orca computer drag --app <app> --from-element-index 3 --to-element-index 9 --json

민감한 입력과 스크린샷

printf '%s' "$TEXT" | orca computer set-value \
  --app com.apple.Safari --element-index 7 --value-stdin --json
  • 비밀번호 같은 비밀값은 표준 입력(stdin)으로 넘겨 셸 기록에 남지 않게 합니다. type-text·paste-text에는 --text-stdin이 같은 역할을 합니다.
  • get-app-state는 접근성 트리와 기본으로 스크린샷도 돌려줍니다. --json이면 이미지는 디스크에 쓰이고 응답에는 경로(screenshot.path)만 들어갑니다.
  • 픽셀이 필요 없으면 --no-screenshot(더 빠르고 작음). 숨겨지거나 최소화된 창을 찍기 전에 보이게 하려면 --restore-window.

에이전트에서 쓰기 — 같은 명령에 안전 지침을 묶은 computer-use 스킬을 에이전트 스킬 폴더에 설치합니다.

npx skills add https://github.com/stablyai/orca --skill computer-use

스킬 레지스트리와 MCP

스킬이란

스킬(에이전트가 특정 일을 할 때 읽는 사용 설명서 묶음, SKILL.md 파일)은 에이전트용 사용 설명서입니다. 에이전트의 스킬 폴더에 넣어 두면, 에이전트가 “아, Orca 일을 할 때는 이렇게 하면 되는구나” 하고 꺼내 읽습니다.

설명서 표지만 설치하고, 본문은 앱에서 꺼내 읽기

핵심은 하나입니다. 에이전트 폴더에는 설명서 표지(짧은 안내문)만 설치되고, 본문은 그때그때 앱에서 최신으로 꺼내 읽습니다. 그래서 앱이 업데이트돼도 설명서와 실제 명령이 어긋나지 않습니다.

npx skills add표지 설치 설명서 표지 (SKILL.md)언제 Orca를 쓸지+ 본문 꺼내 읽는 법 orca skills get <topic>본문은 앱(CLI) 안에= 앱 버전과 항상 일치 본문이 앱 안에 들어 있으므로 앱 버전과 어긋나지 않습니다
표지는 짧게, 실제 명령 옵션은 실행 중인 CLI에서 받아 옵니다.
표지(stub)에 적힌 내용과 skills get 명령

공개 설치 패키지는 “하이브리드 발견 stub”입니다(바이너리 = 설치된 CLI 실행 파일). npx skills add 뒤에 에이전트가 보는 stub은 다음을 말합니다.

  • 이 세션의 CLI 실행 파일을 정한다: ORCA_CLI_COMMAND → orca-dev → (Linux) orca-ide → 그 외 orca.
  • 전체 가이드를 불러온다: orca skills get <topic>(긴 가이드는 --full).
  • --json을 선호하고, 기억에 의존해 옵션을 지어내지 않는다.
orca skills list
orca skills get orca-cli
orca skills get orchestration --full
orca skills get orca-linear --json

자동화에서 결정적인 출력이 필요하면 --json. skills show는 skills get의 별칭입니다.

설치할 수 있는 Orca 스킬

보통은 앱의 Update skills 창으로 충분합니다(아래 「스킬 최신 상태 유지」). 명령으로 직접 설치할 때는 npx(인터넷에서 도구를 받아 바로 실행하는 명령)를 씁니다.

기본 에이전트 설정은 보통 orca-cli, computer-use, orchestration을 설치합니다. 설치 명령 형식은 모두 npx skills add https://github.com/stablyai/orca --skill <이름> --global입니다.

스킬용도
orca-cli워크트리, 터미널, 파일, 자동화, 내장 브라우저
orchestration다중 에이전트 Run, Task, 감독 워커, 메시지, 관문
computer-use접근성 트리와 안전한 UI 동작으로 데스크톱 앱 조작
orca-linearorca linear로 Linear 티켓 읽기/쓰기
orca-emulatoriOS Simulator 제어
orca-emulator-androidadb로 연결된 Android 에뮬레이터/기기
orca-per-workspace-env워크트리별 환경 레시피(orca.yaml)
스킬별 추가 안내
스킬추가 안내
orca-cli설치 후 orca skills get orca-cli
orchestration오케스트레이션 상태를 바꾸기 전 항상 orca skills get orchestration --full(옛 run 명령은 은퇴)
computer-use로컬 데스크톱 앱 창을 살피고 다룰 때
orca-linear티켓 변경 전 orca skills get orca-linear. issue --full, save-issue, list-issues, 관계, 완료 시 attach+comment 흐름, 신뢰할 수 없는 티켓 규칙 포함. 기존 linear-tickets 설치도 동작
orca-emulatorOrca 안에서 orca emulator 명령으로
orca-emulator-android목록/부팅, 탭/스와이프/입력, 하드웨어 버튼, 설치/실행, 권한, 접근성 트리, logcat. 자세히 orca skills get orca-emulator-android
orca-per-workspace-env설정·디버깅할 때. Ways to run Orca 문서 참고

스킬 최신 상태 유지

새 버전이 나오면 앱이 update available(업데이트 있음)을 알려 주고, Update skills 창에서 한 번에 업데이트합니다. 가능하면 이 방법을 쓰세요.

앱 업데이터 세부 동작

Orca가 전역 설치본보다 새 스킬 패키지를 내놓으면 앱은:

  • update available(업데이트 있음) 알림을 띄우고, 업데이트 도구가 안전하게 다시 쓸 수 없는 곳에 오래된 사본이 있으면 Needs attention을 표시합니다.
  • Update skills 창을 엽니다 — 배치 위치와 건너뛴 이유 목록을 보여 주고, npx --yes skills update <names> --global -y를 화면 없이(내장 터미널 없이) 실행합니다.
  • 실행은 백그라운드로 이어지며 창을 닫아도 취소되지 않습니다. 상태 표시줄 조각이 진행을 보여 줍니다(실행 중 회전, 성공 시 잠깐 체크, 실패는 조치할 때까지 유지). 클릭하면 창이 다시 열립니다.
  • Settings → Agents에서 설치된 스킬의 최신 여부(전역 설치 레일)를 보여 주고, 검토가 필요한 행은 Details를 제공합니다.

가능하면 앱 업데이터를 쓰세요 — 앱이 스캔한 같은 전역 위치를 다시 씁니다. Skipped 행은 자동 업데이트가 안 되는 이유(예: 출처 등록 없음)를 설명하니, 위치를 고친 뒤 다시 확인하세요.

npx skills update orca-cli orchestration computer-use --global

데스크톱 설정 화면도 같은 npx 형식을 보여 줍니다.

설정 화면이 없는 컴퓨터(원격 서버 등)에서는 orca skills install / orca skills update 명령으로 설치·업데이트합니다.

헤드리스 CLI 명령과 옵션

SSH, 컨테이너, CI, orca serve처럼 설정 화면이 없는 호스트에서는 로컬 CLI 래퍼를 씁니다. 같은 npx 명령을 만들어 비대화형 옵션을 붙이며, 실행 중인 Orca 런타임이 필요 없습니다.

orca skills install                                      # 설치 가능한 이름 목록
orca skills install --skill orca-cli --skill orchestration
orca skills install --skill orca-cli --agent claude-code,codex
orca skills install --all --dry-run
orca skills update --all
orca skills update --skill orca-cli --dry-run
  • 기본 범위는 전역(--global), 현재 프로젝트만이면 --local.
  • install은 호스트에서 Orca가 감지한 에이전트(그리고 공용 .agents/skills 폴더)를 대상으로 합니다. --agent <name>[,<name>…]나 --agent universal로 바꿀 수 있고, 감지된 에이전트가 없으면 --agent가 필수입니다.
  • update는 이미 설치된 스킬만 새로 고칩니다.
  • --dry-run은 만들어진 명령만 출력합니다. --json은 목록 출력이나 --dry-run에서만 유효합니다.

스킬 화면에서 관리·공유하기

앱의 Skills 화면에서 스킬을 설치·삭제하고, 내 스킬을 링크 하나로 다른 컴퓨터나 동료에게 비공개로 나눠 줄 수 있습니다. 링크가 있으면 누구나 설치할 수 있으니 비밀번호처럼 다루세요.

Skills 페이지 설치·삭제, 호스트 간 비공개 공유, 발견 위치

Skills 페이지에서 설치·삭제

  • 앱 안 설치가 설치할 워크트리를 물으면, 선택기에서 워크트리 이름이나 종류(worktree / folder)로 검색합니다.
  • 에이전트 선택기는 Orca가 항상 포함하는 폴더와 추가로 고를 수 있는 에이전트 폴더를 나눠 보여 주므로, 정확한 설치 대상을 확인하고 진행할 수 있습니다.
  • 스캔된 스킬 하나를 지우려면 그 동작 메뉴에서 Delete…, 여러 개는 페이지의 More actions → Delete skills…에서 고릅니다. 지울 수 없는 사본은 이유(번들됨, 플러그인 관리, 읽기 전용, 지울 수 있는 스킬 폴더 밖)를 확인 전에 알려 줍니다.
  • 이는 공유 링크로 설치한 사본을 관리하는 Manage installs와는 별개입니다.

호스트 간 비공개 스킬 공유

  1. 게시Skills → Share skills에서 스킬 하나나 묶음(bundle)을 목록에 안 뜨고 회수 가능한 링크 하나로 게시합니다. Orca 계정이 필요합니다. 게시 전 포함 파일·스크립트·실행 파일·다이제스트·선택적 릴리스 노트를 검토하세요. 게시된 버전은 바뀌지 않으므로(immutable) 나중에 로컬을 고쳐도 받는 사람이 설치하는 내용이 몰래 바뀌지 않습니다.
  2. 받기활성 링크가 있으면 누구나 로그인 없이 살펴보고 설치할 수 있으니 링크를 비밀번호처럼 다루세요. 받는 사람은 정확한 버전을 검토하고, 전부 또는 일부 스킬을 고르고, 이 컴퓨터·짝지어진 Orca 런타임·WSL·SSH 호스트 중 전역 또는 워크트리 범위를 고릅니다. 이미 고친 기존 스킬은 기본값이 Keep local(로컬 유지)입니다.
  3. 관리Skills → Manage installs에서 Orca가 설치한 사본을 업데이트·되돌리기·제거하고, Settings → Share Skills에서 활성 링크를 복사하거나 회수합니다. 회수하면 앞으로의 접근은 막히지만 이미 설치된 사본은 지워지지 않습니다.

에이전트가 CLI로 게시하려면, 별도로 있고 기본으로 꺼진 Settings → Share Skills → Allow agents and the Orca CLI to publish skill links 권한을 사람이 켜야 합니다.

orca skills installed --json
orca skills share --skill frontend --skill testing --bundle-name "Team Toolkit" --json

skills installed는 로컬 경로를 노출하지 않는 안전한 선택자를 돌려줍니다. skills share는 정확한 발견 ID나 모호하지 않은 이름만 받고, 임의 경로나 --all은 받지 않습니다.

발견 위치와 나만의 스킬

  • Orca 스킬 화면은 Claude, Codex, Agent Skills, OMP(~/.omp/agent/skills)의 설치된 스킬 폴더를 스캔하므로, 거기 둔 스킬은 수동 심볼릭 링크 없이 보입니다.
  • skills/<name>/SKILL.md 파일이 있는 저장소는 무엇이든 npx skills add로 설치할 수 있습니다. 사내 저장소를 가리키면 에이전트에게 회사 고유의 능력을 줄 수 있습니다.

MCP 서버

MCP(Model Context Protocol — AI 에이전트에게 외부 도구를 연결해 주는 표준 규약) 서버는 호환 에이전트에게 외부 도구를 제공합니다. Settings → Integrations → MCP(설정 → 연동 → MCP)에 서버 주소(엔드포인트)를 등록하면, MCP를 지원하는 에이전트 CLI 안에 그 도구들이 나타납니다.

워크트리 체크포인트 — 진행 상황 남기기

무엇인가 — 모든 Orca 워크트리에는 UI에 보이는 가벼운 자유 글 코멘트 칸이 있습니다. “이 워크트리가 지금 무엇을 하는 중인지” 보여 주는 상태 스냅샷입니다. 왜 — 에이전트가 CLI로 갱신할 수 있어서, 채팅을 강요하지 않고도 사람 동료에게 진행을 알리는 권장 방법입니다. 일하는 사람이 책상 위에 붙여 두는 “지금 하는 일” 메모지와 같습니다.

사이드바 — 워크트리 카드

fix-search-debounce in-review

added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review
goal: reduce redundant API calls per #298

위 카드는 코멘트와 상태가 함께 보이는 모습을 설명하는 흉내입니다.

기본 패턴과 카드 상태

orca worktree set --worktree active --comment "reproduced auth failure; testing credential-chain fix" --json

# 단계가 바뀌면 카드 상태도 함께(선택)
orca worktree set --worktree active \
  --comment "fix implemented; running integration tests" \
  --workspace-status in-progress \
  --json

상태 값: todo in-progress in-review completed 또는 워크트리가 쓰는 사용자 정의 id.

todo in-progress in-review completed 코멘트 갱신 코멘트 갱신 단계가 바뀌는 순간마다 --comment 와 --workspace-status 를 함께
코멘트는 수시로, 카드 상태는 단계가 바뀔 때. 순서 화살표는 일반적인 흐름의 예입니다.

체크포인트를 남기기 좋은 순간

한 조각 완성

구현의 의미 있는 한 조각을 끝냈을 때

추측 확인

가설을 확인하거나 반박했을 때

리뷰 끝

코드 리뷰를 마쳤을 때

막힘

외부 입력 대기, 상위 버그, 접근 권한 없음

단계 전환

조사 → 수정, 수정 → 검증으로 넘어갈 때

쓰는 형식

첫 줄은 행동입니다: 방금 무엇을, 어디서 했고, 상태나 다음 단계는 무엇인지. 그 아래 줄에 목표 같은 맥락을 둡니다.

줄무엇을 쓰나예
첫 줄행동 — 방금 무엇을, 어디서, 상태·다음 단계added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review
다음 줄맥락 — 목표 등goal: reduce redundant API calls per #298
orca worktree set --worktree active --comment "added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review
goal: reduce redundant API calls per #298" --json
쓰기 전에 먼저 읽기

코멘트에 사용자가 직접 쓴 맥락(목표·제약)이 있을 수 있으니, 덮어쓰기 전에 읽으세요.

orca worktree current --json

여전히 유효한 것은 남기고, 낡은 것은 버리고, 내 갱신을 그 사이에 엮어 넣습니다.

한눈에 정리
  • orca 명령은 앱에 들어 있습니다. 설정에서 등록하고 orca status --json으로 켜져 있는 Orca(런타임)와 연결되는지 확인합니다.
  • 명령은 “프로그램 → 대상 → 동작 → 옵션 → 결과 형식” 순서로 읽고, 스크립트·에이전트는 --json과 id:·path: 같은 정확한 선택자를 씁니다.
  • 명령 레퍼런스는 에이전트용 사전입니다. 워크트리·터미널·파일·브라우저·에뮬레이터·Linear·아티팩트까지 명령으로 다룹니다.
  • 예약 자동화는 꺼진 채 만들고 → 확인하고 → 한 번 돌려 보고 → 켭니다.
  • 오케스트레이션(실험 기능): Run(프로젝트 폴더) 안의 Task(할 일 카드)를 Dispatch(1회 배정)로 맡기고, 워커는 “다 했어요”를 정확히 한 번 보냅니다. 질문은 ask, 결정은 자물쇠(gate).
  • Computer Use(Beta)는 접근성 권한이 필요하고, 화면을 읽고 → 하나 조작하고 → 다시 읽습니다.
  • 스킬은 표지만 설치하고 본문은 앱에서 최신으로 꺼내 읽습니다. 진행 상황은 orca worktree set --comment로, 쓰기 전에 먼저 읽습니다.

출처: onorca.dev/docs/cli/overview · onorca.dev/docs/cli/reference · onorca.dev/docs/cli/automations · onorca.dev/docs/cli/orchestration · onorca.dev/docs/cli/computer-use · onorca.dev/docs/cli/skills · onorca.dev/docs/cli/worktree-checkpoints

CHAPTER 08

원격과 모바일 — SSH, 원격 Orca 서버, 폰 앱

노트북이 아닌 다른 컴퓨터(성능 좋은 개발 서버, GPU 장비, 집에 둔 Mac mini)에서 에이전트를 돌리고, 그 모습을 노트북이나 휴대폰으로 지켜보고 조종하는 방법을 다룹니다.

이 장에서 배우는 것
  • SSH·원격 서버·페어링·Tailscale이 무엇인지, 둘 중 어떤 방식을 골라야 하는지
  • SSH 대상(target)을 추가하고, 호스트 키·암호·다단계 인증·Kerberos·보안키를 다루는 법
  • 연결이 끊겨도 에이전트가 살아남는 구조, 재연결·재시작 동작, 포트 포워딩, 원격 파일 내려받기
  • Orca가 원격 호스트에 스스로 설치하는 관리형 서버(managed server)
  • 원격 Orca 서버: 데스크톱 앱 + Tailscale 설정, orca serve로 헤드리스 서버 운영, 서비스 등록, 보안
  • iOS·Android 모바일 앱의 모든 기능과 페어링, Android APK 설치
처음이라면 이것만

다른 컴퓨터(서버)가 없다면 SSH·원격 서버 부분은 건너뛰어도 됩니다. 폰 앱만 보세요.

건너뛰어도 되는 곳: 「호스트 키 확인」, 「고급 연결 옵션과 인증」, orca serve·서비스 등록. 「🔧 개발자용 참고」로 접힌 상자는 모두 접어 둔 채 읽어도 됩니다.

먼저 알아 둘 말: SSH · 원격 서버 · 페어링

쉽게 비유하면 노트북은 리모컨, 원격 컴퓨터는 TV라고 생각해 보세요. 리모컨(노트북)으로 버튼을 누르면 실제 화면과 소리(빌드·에이전트 실행)는 TV(원격 컴퓨터)에서 나옵니다. 리모컨 전원이 꺼져도 TV는 계속 켜져 있지요. 휴대폰 앱은 두 번째 리모컨입니다. "페어링"은 리모컨과 TV를 처음 한 번 짝지어 주는 일입니다.

SSH

SSH(Secure Shell — 다른 컴퓨터에 암호화된 통로로 접속해 명령을 실행하게 해 주는 표준 방법)는 인터넷이나 사내망 너머의 다른 컴퓨터에 안전하게 접속하는 통로입니다. 접속할 컴퓨터를 호스트(host — 접속해 들어갈 그 컴퓨터), Orca에 저장한 접속 정보를 SSH 대상(target — 주소·사용자 이름을 적어 둔 즐겨찾기)이라고 부릅니다. 로그인은 보통 비밀번호 대신 키 파일(identity file — 내 컴퓨터에 보관하는 비밀 파일. 이 파일을 가진 사람만 로그인할 수 있음)로 합니다.

원격 Orca 서버

다른 컴퓨터에서 Orca 전체를 계속 실행해 두고, 노트북·휴대폰·브라우저는 화면만 보여 주는 방식입니다. 프로젝트·워크트리(작업마다 따로 쓰는 작업 폴더)·터미널·탭·계정·에이전트 세션이 모두 서버 쪽에 있습니다.

페어링(pairing)

클라이언트(화면을 보여 주는 쪽 — 노트북·폰)와 서버를 한 번 짝지어 서로 믿게 만드는 절차입니다. 서버가 만든 접속 링크나 코드·QR을 클라이언트에 넣으면, 그 기기 전용 토큰(출입증 같은 비밀 문자열. 서버가 이 출입증만 취소하면 그 기기만 내보낼 수 있음)이 생깁니다.

LAN

LAN(Local Area Network — 근거리 네트워크)은 같은 사무실이나 집의 공유기 안에 묶인 네트워크입니다. 같은 Wi‑Fi·공유기에 붙은 기기끼리 바로 통하는 길이라고 보면 됩니다. 이 장에서 "믿을 수 있는 LAN", "집 LAN"이라고 할 때 이 뜻입니다.

Orca Relay

Relay(중계)는 이름 그대로 Orca가 중간에서 폰과 데스크톱 사이를 전달해 주는 중계소입니다. 모바일 페어링에서 쓸 수 있으면 권장되는 길이며, 이 길을 쓸 때만 데스크톱과 폰 두 기기 모두 같은 Orca 계정 로그인이 필요합니다. Relay로 짝지은 폰은 데스크톱의 Relay 연결을 따라갑니다.

Tailscale·tailnet

Tailscale(여러 기기를 하나의 사설 네트워크로 묶어 주는 VPN 서비스)은 내 기기들끼리만 쓰는 비공개 네트워크를 만들어 주는 도구입니다. 그 네트워크를 tailnet이라 하고, 각 기기는 보통 100.으로 시작하는 사설 주소를 받습니다.

헤드리스(headless)

모니터·창 없이 돌아가는 컴퓨터나 프로그램. 클라우드 리눅스 서버, VM(가상 머신 — 한 컴퓨터 안에 소프트웨어로 만든 또 하나의 컴퓨터)이 대표적입니다. orca serve가 Orca를 창 없이 실행합니다.

포트 포워딩

포트(한 컴퓨터 안의 프로그램마다 붙은 문 번호) 포워딩은 원격에서 띄운 개발 서버(예: 3000번 포트)를 내 노트북 브라우저에서 localhost(내 컴퓨터 자신을 가리키는 주소)처럼 열게 해 주는 연결입니다.

💻 노트북 (Orca) 편집기 · diff · 브라우저 화면 입력을 보냄 🖥 원격 호스트 git 저장소 · 워크트리 터미널 · 에이전트 실행 실제 일은 여기서 (무엇을 더 맡는지는 아래 비교) 📱 휴대폰 앱 상태 보기 · 짧은 답장 알림 받기 사설 네트워크 SSH · Tailscale · LAN · Relay 녹색 점 = 원격에서 돌아오는 출력·상태·알림 일은 원격에서, 화면은 노트북·폰에서
노트북과 휴대폰은 "보는 창"이고, 실제 작업(터미널·에이전트·파일)은 원격 호스트에서 일어납니다. 입력은 원격으로, 출력·상태는 다시 화면으로 흐릅니다.

어떤 방식을 고를까: SSH 워크트리 vs 원격 Orca 서버

Orca를 실행하는 방법은 네 가지(로컬, SSH, 자체 호스팅 서버, 일회용 VM)이며, 이 장은 그중 SSH와 원격 Orca 서버를 다룹니다. 둘 다 "다른 컴퓨터에서 일을 시킨다"는 점은 같지만, 누가 Orca의 두뇌(런타임 — 실제로 판단하고 기억하는 Orca 본체)를 가지느냐가 다릅니다. 아래 그림에서 초록 상자(두뇌)가 어디 있는지만 보세요.

① SSH 워크트리 두뇌는 내 노트북, 원격은 손발 💻 내 노트북 (Orca) 🧠 두뇌: 편집기 · diff · 설정 무엇을 할지 정하고 결과를 검토 🖥 원격 호스트 🦾 손발: 터미널 · 에이전트 시킨 일을 실제로 실행 일 시키기 결과 돌려받기 ② 원격 Orca 서버 두뇌와 손발이 모두 서버에 🖥 서버 컴퓨터 (Orca 전체) 🧠 두뇌 프로젝트·설정·계정 🦾 손발 터미널·에이전트 💻 노트북화면 📱 폰화면 🌐 브라우저화면 어느 기기로 봐도 같은 세션
왼쪽: 노트북이 지휘하고 원격 컴퓨터는 일만 합니다. 오른쪽: 서버가 지휘도 일도 다 하고, 노트북·폰·브라우저는 그 화면을 보여 주는 창일 뿐입니다.

노트북의 Orca가 주인입니다. 다른 컴퓨터는 고른 워크트리와 터미널만 실행하는 "작업장"으로 씁니다. 편집기와 diff는 노트북에 있고, 에이전트는 원격 호스트에서 돕니다.

  • 좋은 경우: 오래 걸리는 빌드, GPU 장비, 노트북이 적합하지 않은 환경
  • 설정: Settings → SSH에 호스트 추가

다른 컴퓨터의 Orca가 주인입니다. 그 컴퓨터가 Orca 런타임 전체를 갖고, 데스크톱·브라우저·모바일·자동화 클라이언트가 같은 세션을 공유합니다.

  • 좋은 경우: 늘 켜 둘 Mac mini·데스크톱·헤드리스 리눅스 서버, 여러 기기에서 같은 세션 보기
  • 설정: Settings → Remote Orca Servers 또는 orca serve
  • Beta 베타 기능입니다.

SSH 대상 추가하기

SSH 원격 Workspace(워크스페이스 — 워크트리와 같은 것)에서는 에이전트는 원격 호스트에서 돌고, 편집기와 diff(무엇이 바뀌었는지 전·후를 나란히 보여 주는 화면)는 내 노트북에 그대로 있습니다. 먼저 접속할 호스트를 등록합니다.

1단계 · 설정 열기

Settings → SSH(설정 → SSH)를 열고 Add Target(대상 추가)을 누릅니다. 호스트 입력 양식은 목록 아래가 아니라 모달 창으로 뜹니다. 그래서 등록된 호스트가 아무리 많아도 Host·Advanced·Save 버튼이 항상 손 닿는 곳에 있습니다.

2단계 · 접속 정보 입력

host(주소), user(사용자 이름), port(포트), 그리고 선택 사항인 identity file(키 파일)을 넣습니다. 이 값들은 그 서버를 관리하는 사람(IT 담당자)이 알려 줍니다(일반적인 안내). 모르는 값을 짐작해 넣지 마세요.

Add Target
Host: gpu-box.example
User: dev · Port: 22
Identity file: ~/.ssh/id_ed25519 (선택)

Advanced Test Save
3단계 · 또는 SSH 설정 파일에서 가져오기

같은 창에서 OpenSSH config 선택기(내 컴퓨터에 적어 둔 SSH 접속 목록 파일에서 고르는 창)를 열면 ~/.ssh/config(그 파일이 다른 설정 파일을 불러와 쓰고 있으면 그 파일까지)를 검색해 호스트 하나를 골라 양식을 자동으로 채울 수 있습니다. 이미 Orca에 저장된 호스트에는 In Orca 배지가 붙습니다. 일괄 가져오기(bulk import) 흐름이 제공될 때는 config에서 여러 호스트를 한꺼번에 가져올 수도 있습니다.

4단계 · 암호(passphrase)

키 파일(passphrase는 키 파일을 여는 비밀번호)이 암호로 잠겨 있으면 처음 접속할 때 Orca가 암호를 묻습니다.

5단계 · Test 후 Save

Test로 접속이 되는지 확인한 뒤 Save로 저장합니다. 나중에 Edit(편집)도 같은 창을 쓰며, 대상 이름과 user@host:port를 함께 보여 줍니다.

실수로 입력을 날리지 않게입력 중인(내용이 바뀐) 추가·편집 양식은 창 바깥을 클릭해도 닫히지 않습니다. 정말 버리려면 Esc, Cancel, 또는 ×를 누르세요.

호스트 키 확인 — "이 서버가 진짜 그 서버인가?"

호스트 키란?서버마다 가진 고유한 "지문"입니다. 한 번 접속한 서버의 지문을 기억해 두었다가, 다음에 지문이 달라지면 "누군가 서버인 척하는 것 아닐까?" 하고 접속을 막습니다. 이 기억 목록이 known_hosts 파일입니다.

Orca의 내장 SSH 연결은 내 컴퓨터에서 실제로 적용되는 OpenSSH(컴퓨터에 깔린 표준 SSH 프로그램) known_hosts 파일들과, Orca가 예전에 저장해 둔 키를 기준으로 확인합니다.

상황 (관련 설정)Orca의 동작
전에 접속한 서버이고 지문이 같을 때아무것도 묻지 않고 조용히 접속
처음 접속하는 서버일 때 (기본 설정)받아들이고 기억하며, 지문(fingerprint)을 보여 줌
엄격 모드를 켠 경우 (StrictHostKeyChecking yes)처음 보는 호스트는 거부
확인을 끈 경우 (StrictHostKeyChecking no / off)받아들이지만 신뢰 기록은 저장하지 않음
지문이 바뀌었거나, 폐기된(revoked) 키이거나, 키 종류가 예상과 다를 때비밀번호나 키 암호를 묻기 전에 거부
"지문이 바뀌었다"는 경고가 뜨면직접 처리하지 말고 서버 관리자(IT 담당자)에게 문의하세요(일반적인 안내). 서버를 일부러 새로 설치한 경우라도, 새 지문이 맞는지 관리자가 확인한 뒤에 복구하는 것이 안전합니다.
관리자용: 지문 불일치 복구 방법

호스트를 의도적으로 재구축·재설치했다면 먼저 새 지문이 맞는지 확인한 뒤, 오류 메시지에 나온 복구 방법을 따르세요. known_hosts 불일치일 때는 Orca가 알맞은 ssh-keygen -R 명령을 알려 줍니다(필요하면 [host]:port처럼 대괄호로 감싼 호스트와 포트까지 포함).

SSH 대상 사용하기 — 원격 워크트리 레시피

워크트리를 만들 때 위치로 Local 대신 SSH 대상을 고르면 Orca가 다음을 해 줍니다.

  • 원격 호스트에 git 워크트리(같은 저장소를 여러 폴더에 펼쳐 각각 다른 작업을 하게 하는 git 기능)를 만듭니다.
  • SSH 연결을 통해 에이전트를 원격에서 실행합니다.
  • 파일 이벤트를 동기화해, 편집기·diff·브라우저가 여전히 로컬처럼 느껴지게 합니다.

성능 좋은 개발 서버, GPU 호스트, 클라우드 샌드박스 — 어떤 SSH 대상이든 같은 편집기, 같은 diff 화면, 같은 에이전트에 컴퓨팅만 다른 로컬 워크트리처럼 쓸 수 있습니다. 원격 저장소뿐 아니라 그냥 아무 폴더도 열 수 있습니다.

준비 1 · 호스트 추가

Settings → SSH에 호스트를 추가합니다.

준비 2 · 연결 시험

Test로 연결을 확인합니다. 저장소로 작업한다면 호스트에 git이 설치되어 있어야 합니다.

준비 3 · 저장소 등록

저장소를 Orca에 추가하면서 위치로 SSH 대상을 고릅니다. 또는 파일 선택기에서 원격 폴더를 바로 엽니다.

실행 1 · 워크트리 만들기

워크트리를 만들면 Orca가 원격에서 git worktree add를 실행합니다.

실행 2 · 에이전트 실행

에이전트를 띄우면 노트북이 아닌 원격 호스트에서 돕니다.

실행 3 · 파일 편집

파일을 그 자리에서 고치면 Orca가 저장 내용을 원격 파일 시스템으로 흘려보냅니다.

실행 4 · 검토와 커밋

diff를 검토하고, 커밋하고, 푸시하는 일은 평소처럼 노트북에서 합니다.

끊겨도 괜찮음

노트북이 잠들거나 Wi‑Fi가 끊겨도 에이전트는 원격에서 계속 돕니다. Orca가 다시 연결해 터미널을 붙여 주므로 잃는 것이 없습니다.

고급 연결 옵션과 인증(암호 · MFA · Kerberos · 보안키)

회사 IT가 이 방식을 요구할 때만보통은 앞의 "SSH 대상 추가하기"만으로 충분합니다. 회사 IT 담당자가 프록시·점프 호스트·Kerberos·USB 보안키 같은 방식을 쓰라고 안내했을 때만 아래 상자를 펼치세요.

한 줄 요약: 키 암호는 Orca가 켜져 있는 동안만 기억하고, 인증 코드(OTP·MFA)를 묻는 서버는 Orca가 질문을 화면에 띄워 줍니다. 회사 로그인(Kerberos)이나 USB 보안키처럼 특별한 방식은 Orca가 알아서 컴퓨터에 깔린 표준 SSH 프로그램으로 넘겨 처리합니다.

고급 연결 옵션 · 암호 · 다단계 인증 · Kerberos · FIDO2 보안키

Settings → SSH에서 대상을 편집하고 Advanced Connection(고급 연결)을 펼치면 프록시, 점프 호스트(최종 서버로 가기 전에 거쳐 가는 중간 서버, bastion), SSH 멀티플렉싱 설정을 바꿀 수 있습니다.

  • Reuse SSH connection(SSH 연결 재사용) — 기본으로 켜져 있습니다. macOS·Linux에서 OpenSSH 연결 재사용(멀티플렉싱)을 써서, 설정 명령마다 새로 SSH 악수(handshake)를 하지 않아 빨라집니다. 호스트 정책이 멀티플렉스 세션을 거부할 때만 끄세요.
  • Reconnect on launch(시작 시 재연결) — 기본은 켜짐. 필요할 때만 쓰는 호스트라면 꺼 두세요. 꺼져 있으면 Orca는 그 세션 동안 사용자가 Connect를 누를 때까지 그 호스트와 관리형 서버에 다시 연결하지 않습니다.
  • Allow this host's orca CLI to control Orca — 아래 "SSH 호스트의 orca CLI" 절 참고.

키 암호(passphrase)는 Orca가 켜져 있는 동안만 메모리에 보관됩니다. Orca를 닫으면 지워집니다. SSH 설정에서 더 긴 보관 시간(TTL)을 직접 선택할 수 있습니다.

인증 코드나 일회용 비밀번호(OTP), MFA 확인처럼 "키보드로 답하는(keyboard-interactive)" 질문을 하는 호스트도 내장 연결로 동작합니다. Orca가 질문을 사용자에게 전달하고 답을 다시 보냅니다. 질문이 자동 설정 단계 도중에 나오면, 연결을 실패시키지 않고 사용자가 답할 수 있는 단계로 미뤄 둡니다.

내장 클라이언트와 호스트가 공통으로 쓸 수 있는 SSH 알고리즘이 없으면, Orca는 시스템 ssh로 다시 시도합니다. 시스템 ssh는 그 설치본에 설정된 알고리즘을 쓸 수 있습니다.

회사 SSO 등에서 쓰는 Kerberos/GSSAPI 인증입니다. OpenSSH config에서 호스트에 GSSAPIAuthentication yes가 설정되어 있으면, Orca는 그 대상에 시스템 OpenSSH 연결을 우선 사용합니다(내장 ssh2 클라이언트는 GSSAPI를 지원하지 않음).

  • 접속 전에 유효한 Kerberos 티켓을 갖고 있어야 합니다(kinit 또는 회사 SSO).
  • 수동으로 만든 대상도 시스템 SSH로 설정하면 GSSAPI를 켤 수 있습니다.
  • config에서 가져온 호스트는 별도의 "Kerberos 모드" 스위치가 필요 없습니다 — 가져오기/ssh -G가 그 설정을 그대로 넘겨 줍니다.

USB 보안키처럼 하드웨어에 저장된 OpenSSH 키(ed25519-sk, ecdsa-sk, 에이전트에 올린 보안키 포함)도 내장 ssh2 대신 시스템 OpenSSH를 씁니다. Orca가 키 파일에서 종류를 알아내 OS의 OpenSSH 프로그램에 연결을 넘기므로, 터치·PIN 요청이 평소처럼 뜹니다.

  • 일반 Ed25519·ECDSA·RSA 키는 내장 연결을 그대로 씁니다.
  • 컴퓨터에 OpenSSH가 없으면 FIDO2 대상은 인증할 수 없습니다. OpenSSH를 설치해 PATH(또는 Windows·macOS·Linux의 일반적인 위치)에 두세요.
SSH 대상키 종류·설정 확인 내장 ssh2 클라이언트Ed25519 · ECDSA · RSA 시스템 OpenSSHGSSAPI · *-sk 보안키 · 알고리즘 불일치 원격 호스트관리형 서버
Orca는 보통 내장 클라이언트로 접속하고, Kerberos·하드웨어 보안키·알고리즘 불일치일 때만 컴퓨터의 OpenSSH로 넘깁니다.

연결 상태, 끊김, 재연결

원격 워크트리에는 실시간 SSH 상태를 보여 주는 칩이 붙습니다: ● 연결됨● 재연결 중● 끊김

연결됨에이전트 상태 실시간 끊김원격 에이전트는 계속 실행 재연결 중다시 붙여 이어 보기 Wi‑Fi 끊김 자동 복구 다시 연결되면 원래 화면으로
끊김은 에이전트를 멈추지 않습니다. Orca가 다시 연결해 원래 화면을 이어서 보여 줍니다.

꼭 알아 둘 것은 두 가지뿐입니다.

  • 끊겨도 에이전트는 계속 돕니다 — 노트북이 잠들거나 Wi‑Fi가 끊겨도 에이전트는 원격 컴퓨터에서 하던 일을 이어 갑니다. 연결이 돌아오면 Orca가 자동으로 다시 붙여, 그동안의 화면을 그대로 보여 줍니다. 그러니 "끊김"을 보고 같은 워크트리에 에이전트를 하나 더 띄우지 말고, 먼저 다시 연결해 상태를 확인하세요.
  • 카드에서 바로 재연결 — 호스트가 끊기면 해당 워크트리 카드에 Connect/재연결 버튼이 나타나, 터미널 창을 열거나 상태 표시줄을 찾지 않아도 복구할 수 있습니다.
끊김·재연결 세부 (출력 재생 · 앱을 닫았을 때 · 복원되는 것)
  • 재연결 때 화면 복원 — Orca가 재연결해 다시 붙이며, 스크롤 출력을 재생하고 전체 화면 앱 창은 렌더링된 화면 그대로 복원합니다(빈 화면이나 깨진 화면이 아님).
  • 연결 중에도 사이드바가 비지 않음 — 호스트가 아직 연결 중일 때는 로컬에 저장된 정보로 워크트리 목록을 먼저 보여 주고, 연결이 자리 잡으면 원격의 실제 상태로 갱신합니다.
  • 재연결 중 친 키도 보존 — 복원 중인 SSH 터미널에 입력한 키는 버려지지 않습니다.
  • "Multiplexer disposed" 같은 오류 — 창이 멈춘 채 재시작을 기다리지 않고 자동으로 복구합니다.
  • 에이전트 상태 전달 — working(작업 중)·idle(대기)·blocked(막힘) 상태가 로컬과 똑같이 SSH로 전달되어, 사이드바와 Agents 피드에 원격 에이전트가 실시간으로 보입니다.

앱을 닫아도 원격 세션은 유지

데스크톱 앱을 닫아도 원격 PTY(가상 터미널 — 원격에서 돌아가는 명령 창 하나) 세션은 죽지 않습니다. 세션이 호스트의 관리형 Orca 서버에 있기 때문입니다. 앱을 다시 열고 대상에 연결하면 세션이 원래 탭에 붙은 상태로, 스크롤 기록과 함께 돌아옵니다. 관리형 서버의 구조화된 채팅(Chat UI)은 답변이 진행 중이거나 질문이 기다리는 동안 제공자를 계속 띄워 두므로, 데스크톱 연결이 끊겨도 승인 요청이 그대로 남아 있습니다.

재연결과 재시작 후 복원되는 것

  • 열린 파일, 살아 있는 에이전트 탭, 일시정지된 Claude·Codex의 이어하기(resume) 제안이 SSH 재연결과 앱 재시작 후에도 남아, 떠날 때 모습 그대로 돌아옵니다.
  • 연결이 끊긴 동안 친 키는 연결이 돌아오면 정확히 한 번, 순서대로 전달됩니다. 창의 스크롤 기록과 크기도 유지됩니다.
  • 관리형 서버가 업데이트된 뒤에도 열린 탭이 다시 붙습니다.
  • 오래전에 닫은 탭이 빈 껍데기로 되살아나지 않습니다. 마지막 탭까지 닫은 SSH 워크트리를 클릭하면 새 터미널이 열립니다.
  • 무언가를 출력하는 셸 시작 파일, 수만 개 항목이 든 폴더, 64비트 ARM 리눅스 서버 때문에 연결이 깨지거나 끊기지 않습니다.
  • 두 컴퓨터가 같은 경로를 가지고 있어도 파일·브라우저 탭·링크·드래그 앤 드롭은 원래 속한 컴퓨터에 머뭅니다.
끊겼다고 멈춘 게 아닙니다호스트와 연락이 끊겼다는 것이 그쪽 작업이 멈췄다는 증거는 아닙니다. 같은 워크트리에 두 번째 에이전트를 띄우기 전에 호스트 상태를 먼저 확인하세요.

SSH 호스트에서 쓰는 orca CLI

CLI(마우스 대신 터미널에 명령어를 입력해 프로그램을 조종하는 방식)인 orca 명령을 SSH 호스트에서 실행하면, 기본적으로는 그 호스트 자신의 터미널과 오케스트레이션 메시지(에이전트끼리 일을 나누고 보고하는 메시지)에만 닿습니다. 그 호스트의 에이전트는 자기를 보낸 조정자(coordinator)에게 결과를 보고할 수는 있지만, 다른 호스트·데스크톱 제어·계정·설정에는 닿지 못합니다.

🖥 SSH 호스트 에이전트가 orca 명령 실행 $ orca … 자기 터미널 · 보고기본으로 허용 내 Orca 조종워크트리 만들기 · 터미널 열기 · 일 나누기 🔒 스위치를 켜면 열림 Settings → SSH → 호스트 편집 → Advanced Connection
기본은 "자기 일만". 그 호스트의 에이전트가 내 Orca를 조종하게 하려면 스위치를 직접 켜야 합니다.
  • 그 호스트의 에이전트가 orca로 워크트리를 만들고, 터미널을 열고, 작업을 배분하게 하려면 Settings → SSH → 호스트 편집 → Advanced Connection에서 Allow this host's orca CLI to control Orca를 켭니다.
  • Orca가 호스트에서 지우지 못하는 SSH 워크트리를 삭제할 때는 Remove from Orca를 쓰면 앱에서만 지우고 호스트의 파일은 남겨 둡니다.
권한은 꼭 필요할 때만이 스위치를 켜면 그 호스트의 에이전트가 내 Orca를 조종할 수 있게 됩니다. 믿을 수 있는 호스트에만 켜세요.
예전 버전(v1.4.224)에서 올라온 경우

v1.4.224에서 넘어온 터미널에는 orca가 없습니다. 같은 호스트에서 새 터미널을 열어 실행하세요.

원격 파일 내려받기와 VS Code로 열기

원격 컴퓨터에 있는 파일을 내 노트북으로 가져오거나, 익숙한 편집기 VS Code(마이크로소프트의 무료 코드 편집기)로 원격 폴더를 바로 열 수 있습니다. 둘 다 오른쪽 클릭 메뉴에서 시작합니다.

파일 탐색기 · 오른쪽 클릭
📄 report.csv → Download 파일 하나 받기
📁 results/ → Download Folder 폴더째 받기

→ 운영체제 저장 창이 뜨고 노트북으로 복사됨
워크트리 · 오른쪽 클릭
Open in ▸
  VS Code Remote SSH
  Finder / Explorer (로컬 전용)

→ VS Code가 원격 폴더를 열어 줌

파일·폴더 내려받기

SSH 워크트리의 파일 탐색기에서 오른쪽 클릭합니다.

  • 파일 → Download — 운영체제 저장 창이 뜨고 파일이 노트북으로 복사됩니다.
  • 폴더 → Download Folder — 고른 폴더로 하위 폴더까지 통째로 내려받습니다(데스크톱 전용).

VS Code Remote-SSH로 열기

  1. 메뉴에 VS Code 넣기Settings → General → Open in menu에서 VS Code를 목록에 추가합니다(프리셋 또는 사용자 명령).
  2. 열기SSH 워크트리를 오른쪽 클릭(또는 워크트리 더보기 메뉴) → Open in → VS Code.
Download Folder가 안 보일 때 · VS Code 연결 세부 · 지원되지 않는 편집기

전송은 연결과 같은 SSH 경로로 합니다. Download Folder는 연결이 폴더 재귀 전송을 지원한다고 알릴 때(보통 완전한 SFTP(SSH 위에서 파일을 주고받는 표준 방법))만 보입니다. 시스템 OpenSSH 전송만 쓰는 연결은 파일은 받을 수 있어도 폴더 받기 메뉴는 없을 수 있습니다.

웹 클라이언트에는 Download가 없습니다 — Electron의 저장 창에 의존하기 때문입니다.

설정한 앱이 VS Code 또는 VS Code Insiders(code/code-insiders, 또는 그 실행 파일의 직접 경로)라면, 워크트리 메뉴의 Open in 목록이 원격 경로를 VS Code Remote-SSH에 넘깁니다. Orca가 --remote ssh-remote+<host> <path>로 VS Code를 실행합니다. 메뉴 항목에 Remote SSH 배지가 보일 수 있습니다.

이 원격 경로에는 Cursor, Zed, 복합 셸 명령, 원격 Orca 서버를 활성 런타임으로 쓰는 경우가 지원되지 않습니다(그것들은 Local 전용). Finder/Explorer 항목은 로컬 경로에만 쓰세요.

관리형 Orca 서버(Managed Orca server)

평소엔 신경 쓰지 않아도 됩니다아래 내용은 자동으로 동작하니 평소엔 신경 쓸 필요 없습니다. SSH 연결 중에 오류가 날 때만 보세요.

처음 연결할 때 Orca는 호스트에 자기 전용 작은 서버 프로그램을 설치합니다. Orca가 함께 배포하고 최신으로 유지하는, 버전이 고정된(pinned) 런타임입니다. 그래서 호스트에 깔린 Node(Node.js — Orca 서버가 돌아가는 데 필요한 부품) 버전이 틀리거나 빌드 도구가 없어도 연결이 실패하지 않습니다. 켜는 설정은 따로 없습니다 — 항상 이렇게 동작합니다.

빈 호스트

서버를 설치하고 그 관리형 서버에 연결합니다.

Orca 프로젝트는 있지만 열린 터미널이 없는 호스트

다음 연결 때 프로젝트·폴더·프로젝트 그룹·열린 편집기 탭을 관리형 서버로 옮깁니다.

관리형 서버를 돌릴 수 없는 호스트

예전 SSH 런타임으로 몰래 되돌아가지 않습니다. 연결이 이유와 함께 실패하고 Settings → SSH Hosts에 그 이유가 표시됩니다. 그 호스트에 계속 연결하려면 더 오래된 Orca 버전을 쓰세요.

Node.js를 내려받을 수 없을 때내 컴퓨터도 호스트도 Node.js를 받지 못하면 연결 오류에 Use a Node.js mirror…가 나타납니다. 미러(같은 파일을 받을 수 있는 다른 다운로드 창구) 주소가 미리 채워져 있으니 확인하거나 바꾼 뒤 Save and retry를 누르세요. Orca는 받은 파일마다 고정된 체크섬(파일이 중간에 바뀌거나 깨지지 않았는지 확인하는 지문 같은 숫자)으로 검증합니다. 설정한 미러도 실패하면 Settings → Advanced → Network에서 미러를 고친 뒤 다시 연결하세요.

서버 관리 화면

Settings → Managed servers에서 서버마다 버전과 실행 중인 터미널을 보고 다음을 할 수 있습니다.

버튼뜻
Update새 버전으로 업데이트. 터미널이 실행 중이면 Update anyway가 터미널을 닫지 않고 업데이트
Roll back이전 버전으로 되돌리기
Recover중간에 끊긴 업데이트 복구
Stop…서버 중지
Forget…서버를 목록에서 잊기
(상태 보기)버전·터미널 확인
같은 일을 명령(CLI)으로 하기
버튼CLI
Updateorca environment update
Roll backorca environment rollback
Recoverorca environment recover
Stop…orca environment stop
Forget…orca environment forget
(상태 보기)orca environment status
예전 버전에서 올라온 경우 (v1.4.224 터미널 · 사라진 Runtime 선택)

v1.4.224가 띄운 터미널이 남아 있는 호스트 — 기존 탭의 터미널은 업그레이드와 재연결 동안에도 계속 동작합니다. 그 호스트의 새 터미널은 관리형 서버에서 열립니다.

런타임 선택지는 사라졌습니다 — 예전의 호스트별 Runtime 선택(Auto / Orca-managed Node / Host Node)과 relay 전용 수명 주기 설정은 없어졌습니다. 이제 모든 SSH 연결은 관리형 Orca 서버에서 돕니다. 지원하지 않는 OS·CPU, 실행이 금지된(noexec) 홈 디렉터리, 포트 포워딩을 거부하는 SSH 서버처럼 관리형 서버를 돌릴 수 없으면, 조용히 다른 방식으로 넘어가지 않고 Settings → SSH Hosts에서 이유를 설명합니다.

포트 포워딩 — 원격 웹서버를 내 브라우저로

원격 워크트리에서는 오른쪽 사이드바에 Ports 탭이 있습니다(Cmd+Shift+I로 켜고 끄기 — macOS). Orca는 노트북이 아니라 워크트리가 실제로 도는 호스트(관리형 SSH 서버나 페어링된 서버)를 살펴, 접속을 기다리고 있는(listening) 포트를 Detected(감지됨) 아래에 보여 줍니다.

노트북 브라우저 localhost:3000 localhost:10080 원격 호스트 개발 서버 :3000 웹서버 :80 (특권 포트) 3000 → 3000 80 → 10080 (자동 재매핑)
감지된 포트를 한 번 클릭하면 내 쪽으로 연결됩니다. 권한이 필요한 특권 포트는 로컬에서 자동으로 다른 번호로 바뀝니다.
  • 감지된 포트는 한 번 클릭으로 포워딩하고, 같은 패널에서 그 포트를 멈출 수도 있습니다.
  • 포워딩을 수동으로 추가·편집·삭제할 수 있습니다.
  • 저장한 포워딩은 관리형 호스트에 재연결하면 돌아오고, 앱을 재시작해도 남습니다.
  • 권한이 필요한 원격 포트(특권 포트 — 80번처럼 관리자 권한이 있어야 여는 문)는 로컬에서 자동으로 다른 번호로 바뀝니다(예: 원격 80 → 로컬 10080).
  • 저장한 포워딩을 시작할 수 없으면 그 줄에 이유가 표시되고 바로 지울 수 있습니다.

원격 Orca 서버 Beta

한 컴퓨터가 일을 하고, 다른 컴퓨터는 화면만 제공합니다. 서버가 프로젝트·워크트리·터미널·탭·제공자 계정·에이전트 세션을 가지고, 노트북은 실행 중인 그 Orca에 접속합니다. 가장 쉬운 방법은 양쪽 모두 Orca 데스크톱 앱 + Tailscale이며, 이 경우 orca serve는 필요 없습니다.

베타 · 사설 경로에서만원격 Orca 서버는 베타입니다. 서버와 클라이언트는 같은 Tailscale tailnet이나 LAN(같은 사무실·집 공유기 안의 네트워크)처럼 내가 통제하는 사설 네트워크 경로에 두세요.
클라이언트 컴퓨터 Orca 클라이언트 화면을 보여 주고 입력을 보냄 서버 컴퓨터 저장소·워크트리 보관 터미널·에이전트 실행 입력 화면·상태 사설 네트워크 경로 (Tailscale · LAN)
무엇이 어디서 도는가: 클라이언트는 화면, 서버는 모든 작업.
에이전트 도구는 서버에 설치Codex, Claude Code, OpenCode, git, 그 밖의 제공자 CLI는 서버 컴퓨터에 설치하고 로그인해야 합니다. 노트북에서 로그인한 상태가 서버로 자동으로 넘어가지 않습니다.
창 없는 서버(orca serve)에서 계정 등록 · 스킬 설치

헤드리스 orca serve 호스트에서는 원격 클라이언트의 Add account가 꺼져 있으므로, 관리형 Claude/Codex 계정을 서버 셸에서 등록합니다. 설정 화면 없이 에이전트 스킬도 설치·갱신할 수 있습니다.

orca account add --agent claude
orca account add --agent codex
orca account list

orca skills install --skill orca-cli --skill orchestration
orca skills update --all

권장: 데스크톱 앱 + Tailscale

준비 0단계 — 먼저 두 컴퓨터를 같은 Tailscale에 묶어 둡니다.

  1. 두 컴퓨터 모두에 Tailscale 설치 — 설치 방법은 Tailscale 공식 안내를 따릅니다. 두 컴퓨터 모두 최신 Orca도 설치해 둡니다.
  2. 두 컴퓨터 모두 같은 Tailscale 계정으로 로그인 — 그래야 같은 tailnet(내 기기끼리만 쓰는 비공개 네트워크)에 들어갑니다.
  3. 서버 컴퓨터는 켜 두기 — 깨어 있고, 인터넷에 연결돼 있고, Orca가 실행 중이어야 합니다.
  4. 준비 완료 확인 — 서버 컴퓨터의 Orca 연결 주소 목록(아래 서버 ③단계)에 100.으로 시작하는 주소가 보이면 준비 완료입니다. Orca는 이 주소를 목록 맨 위에 둡니다.
🖥 서버일을 할 컴퓨터 💻 클라이언트화면을 볼 노트북 ① New Link새 접속 링크 시작 ② 주소 선택100.x.y.z 고르기 ③ Generate Access Link링크 만들고 복사 ④ 링크 전달비밀번호처럼 조심 ⑤ Add Server이름 + 링크 붙여넣기 ⑥ ConnectConnected 되면 끝 위 줄: 서버 컴퓨터에서 · Settings → Remote Orca Servers 아래 줄: 노트북에서 · Settings → Remote Orca Servers
서버에서 링크를 만들어(①~③) 건네주면(④), 노트북은 그 링크로 서버를 추가하고 연결합니다(⑤~⑥). 아래 단계 버튼으로 한 장씩 볼 수 있습니다.
서버 ① · 설정 열기

세션을 계속 돌릴 컴퓨터에서 Orca 데스크톱 앱을 열고 Settings → Remote Orca Servers로 갑니다.

서버 ② · 새 링크

Advertise this app as a server(이 앱을 서버로 알리기) 아래의 New Link를 누릅니다.

서버 ③ · 주소 고르기

Connection address에서 Tailscale 주소(보통 100.x.y.z)를 고릅니다. 목록에 없으면 Tailscale이 연결됐는지 확인하고 Connection address 옆 새로고침 버튼을 누르세요.

Remote Orca Servers
Advertise this app as a server
Connection address: 100.64.1.20 ⟳
Generate Access Link
서버 ④ · 링크 생성·복사

Generate Access Link를 누르고 Pair another Orca client 아래의 링크를 복사합니다. 이 접근 권한은 나중에 취소할 수 있습니다.

링크는 비밀번호처럼페어링 URL은 이 Orca 런타임에 들어갈 권한 그 자체입니다. 짝지을 클라이언트에게만 보내세요.
클라이언트 ① · 서버 추가

노트북에서 Settings → Remote Orca Servers → Add Server를 누르고, 알아보기 쉬운 이름(예: Remote Server)을 넣고, 서버에서 받은 링크를 붙여 넣은 뒤 Add Server를 누릅니다.

클라이언트 ② · 연결

저장된 서버가 Disconnected로 보이면 Connect를 누릅니다. 서버를 추가해도 새 프로젝트가 모두 그 서버로 가지는 않습니다. 새로 여는 프로젝트(와 그 터미널·브라우저·모바일 연결)를 기본으로 이 서버에서 열고 싶으면 Advanced → Active Server를 켜세요.

서버 사용하기

서버가 Connected가 되면 서버나 그 프로젝트를 골라 평소처럼 Orca를 씁니다. 터미널·에이전트 프로세스·파일·워크트리·세션 상태는 모두 서버 컴퓨터에 있습니다. 그래서:

  • 클라이언트 노트북이 잠들거나 끊겨도 에이전트는 계속 돕니다.
  • 서버에는 에이전트가 쓰는 저장소·도구·자격 증명(로그인 정보)이 있어야 합니다.
  • 서버는 깨어 있고 tailnet에 연결된 상태여야 합니다.
재연결·재시작 때 무엇이 남는지, 여러 클라이언트가 함께 쓸 때
  • 클라이언트가 재연결하거나 Orca를 다시 열면, 페어링된 탭을 중복하지 않고 서버가 가진 워크트리·탭·보이는 창 상태로 돌아옵니다. 페어링 서버 탭은 데스크톱 재시작 후에도 남고, 닫은 탭은 닫힌 채로 있습니다.
  • 호스트 앱이 다시 실행된 뒤 페어링된 터미널이 다시 입력을 받고, 네트워크가 끊겼다 돌아오면 원격 브라우저 탭이 돌아오며, orca serve가 재시작해도 폰의 터미널이 유지됩니다.
  • 원격 호스트에 워크트리를 만들어도 다른 연결된 데스크톱이 그쪽으로 끌려가지 않습니다.
  • 서버에서 삭제한 프로젝트는 모든 페어링 클라이언트의 사이드바에서 사라집니다(유령 줄이 남지 않음).
  • 여러 클라이언트가 한 서버를 공유하면 사이드바 필터의 Hide other-client workspaces로 이 기기가 만든 워크트리만 볼 수 있습니다(워크트리 장의 사이드바 레이아웃 참고).

접근 권한과 보안

Orca는 페어링한 클라이언트마다 따로따로, 취소 가능한 토큰을 만들고, 서버의 Shared Server Access에 목록으로 보여 줍니다. 지킬 일은 세 가지입니다.

🗑 필요 없어진 기기는 바로 내보내기

Shared Server Access에서 그 기기 옆 휴지통 버튼을 누르면 취소되고, 그 권한을 쓰던 클라이언트는 즉시 끊깁니다.

🎯 닿을 수 있는 기기를 최소로

Tailscale 관리 화면에서 이 서버에 닿을 수 있는 기기를 꼭 필요한 것만 남기세요.

🚫 인터넷에 직접 열지 않기

Orca 서버는 Tailscale이나 믿을 수 있는 LAN 같은 사설 경로로만 쓰세요.

링크 교체 규칙 · ACL/grant · 공개 포트 · 127.0.0.1
  • 링크를 새로 만들면 아직 안 쓴 이전 링크는 대체됩니다. 이미 페어링한 클라이언트는 취소하기 전까지 자기 권한을 유지합니다.
  • Tailscale ACL이나 grant(누가 어느 기기에 닿을 수 있는지 정하는 규칙)는 가능한 한 좁게 설정하세요.
  • Orca 포트를 공개 인터넷에 직접 열지 마세요. Tailscale, WireGuard, 믿을 수 있는 LAN, SSH 포워딩, 인증된 터널을 쓰세요.
  • 다른 컴퓨터용으로 127.0.0.1(localhost — 내 컴퓨터 자신을 가리키는 주소)을 고르지 마세요. 그 주소는 서버 자신에게서만 통합니다.

대안: orca serve (헤드리스 서버)

데스크톱 창 없이 돌려야 할 때 — 예를 들어 헤드리스 리눅스 서버나 서비스로 관리되는 VM — orca serve를 씁니다. 로그인한 채 둘 수 있는 MacBook·데스크톱이라면 위의 앱 안 설정이 더 간단합니다. 서버에 Orca와 함께 들어 있는 CLI를 설치하고 실행합니다.

orca serve --pairing-address <server-tailscale-ip-or-hostname>
# 예
orca serve --pairing-address 100.64.1.20
# 방화벽·터널·서비스 정의가 고정 포트를 요구할 때
orca serve --port 6768 --pairing-address 100.64.1.20

실행하면 터미널에 페어링 URL이 찍힙니다. 이 URL을 클라이언트의 Settings → Remote Orca Servers → Add Server에 붙여 넣으면 됩니다.

orca serve 동작 세부 (앞 실행 · --pairing-address · orcad)
  • 데스크톱 창을 열지 않고 Orca 런타임을 시작합니다.
  • Ctrl-C를 누를 때까지 앞(foreground)에서 실행됩니다.
  • 바인딩된 엔드포인트와 런타임 페어링 URL을 출력합니다.
  • --pairing-address는 클라이언트가 찾아올 주소를 알리는 데만 쓰입니다.
  • 기본으로 Orca 자체 Node 서버(orcad)에서 돕니다. orcad가 그 컴퓨터에서 돌 수 없으면 데스크톱 앱의 서버로 넘어가며, 이유를 한 줄 출력합니다. 패키지된 macOS 앱은 페어링된 클라이언트가 업데이트할 수 있도록 현재 항상 데스크톱 앱 서버를 쓰며, ORCA_SERVE_RUNTIME=electron으로 그 경로를 강제할 수 있습니다.
한 번에 한 가지 호스트 모드만그 컴퓨터를 이미 Orca 데스크톱 앱이 공유하고 있다면, 같은 설정에 두 번째 orca serve 프로세스를 띄우지 마세요.

헤드리스 서버에 폰 연결하기

모바일 앱용으로는 모바일 범위의 QR 코드와 링크를 요청합니다.

orca serve --pairing-address 100.64.1.20 --mobile-pairing

폰을 같은 tailnet에 두고, Orca Mobile에서 Pair를 고른 뒤 터미널에 뜬 QR 코드를 찍거나 출력된 링크를 붙여 넣습니다.

서비스로 계속 돌리기

한 줄 요약: 컴퓨터가 켜지면 자동으로 Orca 서버를 띄워 두는 등록입니다. 등록·상태 확인·해제 명령 세 개만 기억하면 됩니다(아직 Windows에서는 쓸 수 없음).

orca serve service install --port 6768
orca serve service status
orca serve service uninstall
LaunchAgent · systemd · lingering · 감독자 재시작 규칙
  • install은 macOS에서는 LaunchAgent, Linux에서는 systemd 사용자 유닛을 만들어 이 프로필용으로 orca serve --supervise --no-pairing을 실행합니다.
  • 감독자(supervisor)는 실패가 반복돼도 무한히 재시작하지 않고 점점 긴 간격을 두고 재시작하며, 업데이트가 앱을 바꾸는 동안은 기다립니다.
  • 서비스 로그에는 페어링 링크를 절대 출력하지 않습니다. 클라이언트 페어링은 데스크톱 앱에서 하거나, 서비스를 멈춘 상태에서 터미널로 orca serve를 실행해 하세요.
  • Linux에서는 lingering이 켜져 있지 않으면(loginctl enable-linger) 로그아웃 시 서비스가 멈춥니다. install이 이를 알려 줍니다.
  • status는 실행 여부를, uninstall은 서비스를 멈추고 유닛을 지우되 터미널 데몬과 그 세션은 계속 돌게 둡니다.
  • 이 서비스 명령은 아직 Windows에서 쓸 수 없습니다.
  • 다른 서비스 관리자나 컨테이너가 이미 프로세스를 재시작해 준다면 orca serve --supervise를 직접 쓰세요.

데스크톱 앱인가, orca serve인가?

서버에서 데스크톱 앱orca serve
잘 맞는 곳오래된 노트북, Mac mini, 데스크톱헤드리스 리눅스, VM, 관리형 서비스
설정설정 화면과 버튼터미널 명령과 서비스 설정
서버 창열려 있음없음
접근 링크New Link → Generate Access Link터미널에 출력
살아 있는 기간데스크톱 앱이 실행 중인 동안앞 프로세스나 서비스가 실행 중인 동안

원격 서버 문제 해결

Tailscale 주소가 목록에 없음

서버에서 Tailscale이 연결됐는지 확인하고 Connection address 옆 새로고침을 누르세요. 두 컴퓨터가 같은 tailnet에 로그인해야 합니다. Tailscale IPv4 주소는 보통 100.으로 시작합니다.

서버가 Disconnected

서버 컴퓨터가 깨어 있는지, Orca가 실행 중인지, Tailscale에서 두 기기가 온라인인지 확인하세요. 한쪽이 닿지 않으면 Tailscale 관리 화면에서 두 기기가 서로 닿도록 허용돼 있는지(ACL·grant — 어느 기기가 어느 기기에 닿을 수 있는지 정하는 규칙) 확인하세요. 서버 줄에 호환되지 않는 프로토콜 버전이 보이면 두 컴퓨터 모두 Orca를 업데이트하세요.

접근 링크를 엉뚱한 사람에게 보냈음

서버에서 Settings → Remote Orca Servers → Shared Server Access를 열고 그 권한을 취소한 뒤, 원래 클라이언트용 새 링크를 만드세요.

서버가 에이전트 CLI를 찾지 못함

그 CLI를 서버 컴퓨터에 설치하고 로그인하세요. 원격 세션은 클라이언트가 아니라 서버의 PATH·홈 디렉터리·자격 증명을 씁니다.

orca serve가 잘못된 주소를 알림

명령을 멈추고 클라이언트가 닿을 수 있는 주소로 다시 시작하세요: orca serve --pairing-address <reachable-tailscale-ip-or-hostname>. 원격 클라이언트용으로 와일드카드 주소(특정 주소 대신 "아무 주소나"를 뜻하는 값)나 127.0.0.1을 쓰지 마세요.

모바일 앱(Orca Mobile) Beta

Orca 모바일 컴패니언은 iOS·Android 앱으로, 데스크톱 Orca와 짝을 지어 주로 보기 위한(read-mostly) 화면을 제공합니다. 에이전트 상태, 최근 터미널 출력, 그리고 폰에서 정말 필요한 조작(질문에 답하기, 워크트리 재우기, 소스 컨트롤 검토, 에이전트 계정 바꾸기)이 들어 있습니다. 페어링은 한 번이면 되고, 진짜 데이터와 작업은 언제나 데스크톱에 있고 폰은 그걸 보여 줄 뿐입니다. iOS는 App Store에서, Android는 최신 APK로 설치합니다(아래 절 참고).

편집기가 아니라 리모컨모바일 앱은 일부러 완전한 편집기로 만들지 않았습니다. 이미 돌아가고 있는 데스크톱을 조종하는 리모컨입니다.
Orca Mobile
🖥 Studio Mac · macOS연결됨
fix-login · Claudeworking
gpu-train · Codex (SSH)waiting
docs-update · OpenCodedone

모바일에서 할 수 있는 일

👀 보기

연결된 모든 컴퓨터의 워크트리·에이전트 상태(작업 중 / 완료 / 입력 대기), 파일, 최근 터미널 출력을 한 화면에서.

💬 답하기

에이전트가 기다리면 짧은 답장, 사진·파일 첨부, 받아쓰기로 답하기. 저장해 둔 명령(Quick Commands) 실행.

🌳 워크트리·호스트

폰에서 워크트리를 만들고 에이전트 시작. 저장된 컴퓨터의 이름·주소 고치기.

🔔 기타

에이전트가 끝나면 푸시 알림. 브라우저 탭을 폰 크기로 확인. 바뀐 파일 검토·커밋, 에이전트 계정 바꾸기.

모바일 기능 전체 목록 (보기 · 조작 · 워크트리·호스트 · 기타)
  • 모든 워크트리·에이전트·상태(working 작업 중 / done 완료 / waiting 입력 대기)를 봅니다. 연결된 모든 호스트(로컬 데스크톱과 원격 Orca 서버)의 워크트리를 한 화면에 모아 보여 주므로 기기를 바꿀 필요가 없습니다. SSH 호스트의 워크트리는 줄 배지에 그 호스트의 상태를 데스크톱과 같은 말로 보여 줘, 끊긴 기계를 한눈에 알 수 있습니다.
  • 파일 트리 전체를 깊은 경로까지 탐색해 아무 파일로나 바로 갈 수 있습니다. 동영상·음악 파일은 폰에서 미리보기로 재생됩니다.
  • 지원되는 에이전트 세션을 Chat UI(채팅 형식 대화 기록)나 원래 터미널로 엽니다. 기기 기본값은 Settings → Chat UI, 탭 하나만 바꾸려면 세션 탭을 길게 누릅니다.
  • 최근 터미널 스크롤 기록을 불러와 에이전트가 무엇을 했고 무엇을 물었는지 읽습니다. 터미널 스트림이 끝난 뒤에도 새 스냅숏을 받아 화면이 멈춰 있지 않습니다. 채팅 형식 화면의 마크다운은 메시지에 Mermaid 다이어그램이 있으면 그려 주고, 네이티브 채팅은 데스크톱과 같은 인라인 시각 자료와 하위 에이전트(subagent) 줄을 보여 줍니다.
  • 모바일 터미널에서 텍스트를 선택·복사·붙여넣기 — 길게 눌러 선택하고, 공유 시트로 답장에 붙여 넣습니다.
  • 터미널 보조 키 줄에서 폰 키보드로 치기 힘든 Tab, Shift+Tab 같은 키를 씁니다. 글자 하나하나를 바로 터미널로 보내려면 Live로 바꿉니다.
  • 에이전트가 입력을 기다리면 짧은 답장(continue, yes, 자유 문장)을 보내거나, 사진·파일을 첨부하거나, 마이크를 눌러 받아쓰기로 답합니다. Live 모드에서는 받아쓴 글이 Return 없이 활성 터미널에 들어갑니다. Chat UI에서는 첨부 이미지가 메시지에 썸네일로 보이고, 글과 함께 또는 이미지만 보낼 수 있습니다.
  • 세션 탭 줄에서 Quick Commands(저장된 터미널 명령·에이전트 프롬프트, 데스크톱 목록과 동기화)를 실행합니다.
  • 세션 탭을 길게 눌러 여러 탭 한꺼번에 닫기(Close Other Tabs, Close Tabs to the Left, Close Tabs to the Right). 저장 안 된 마크다운 탭과 고정 탭은 건너뜁니다.
  • 워크트리의 Source Control을 열어 바뀐 파일을 보고, stage/unstage하고, 커밋합니다.
  • 에이전트 계정 바꾸기와 사용량·한도(rate-limit) 확인. Codex에 리셋 크레딧이 쌓였으면 계정 화면에서 하나를 씁니다.
  • 데스크톱과 같은 Smart 소스 모드(Smart, GitHub, Linear, GitLab, Branch, Name)로 워크트리 만들기. 데스크톱이 여러 대 연결돼 있으면 New Workspace가 먼저 어느 호스트에 만들지 묻습니다(호스트가 하나면 묻지 않음).
  • 폰에서 워크트리에 에이전트 시작 — 그 탭이 데스크톱에 바로 나타나지만, 데스크톱 창이 그 워크트리로 이동하지는 않습니다.
  • 호스트 카드의 ⋯ 메뉴로 Edit, Connect, Remove 등(길게 누르기도 단축키로 동작).
  • 다시 페어링하지 않고 저장된 호스트의 표시 이름이나 접속 주소 수정(예: 데스크톱이 집 LAN과 Tailscale 사이를 오갈 때).
  • 호스트 목록과 열린 세션 사이를 슬라이드 전환으로 이동. Back은 그 페이지의 호스트 스택을 원래 자리로 되돌립니다.
  • iPad에서는 호스트가 하나의 사이드바에 늘 보이고, 호스트 목록과 세션을 오가도 채팅 초안이 보존됩니다.
  • 폰에서 브라우저 세션을 Web 또는 Mobile 보기로 열어 반응형 페이지를 확인합니다. 폰에서 연 브라우저 탭은 데스크톱이 최소화되거나 화면 보호기 상태여도 계속 로드됩니다.
  • 에이전트가 끝나면 데스크톱 알림을 그대로 따라 하는 푸시 알림을 받습니다.
  • 더 새로운 모바일 버전이 있으면 앱이 알려 주고 해당 릴리스로 연결해 줍니다.

페어링하기

데스크톱일회용 페어링 코드또는 딥 링크 · QR 경로 선택Orca Relay 중계소 (권장)또는 LAN(같은 공유기) · Tailscale 휴대폰Pair → 코드 붙여넣기기기 토큰 저장 한 번 짝지으면 이후로는 토큰으로 자동 재연결
데스크톱이 코드를 만들고, 폰이 그 코드를 받아 자기 전용 토큰을 얻습니다.
1 · 데스크톱에서 코드 만들기

데스크톱 Orca의 계정 / 상태 메뉴(account / status menu)에서 페어링 흐름을 엽니다. Orca가 일회용 페어링 코드를 보여 줍니다.

2 · 폰에서 Pair

Orca 모바일 앱에서 Pair를 고르고 코드를 붙여 넣습니다. 데스크톱의 딥 링크를 눌러 모바일 페어링 화면으로 바로 갈 수도 있습니다.

3 · 경로 고르기

가능하면 Orca Relay(Orca가 중간에서 전달해 주는 중계소)로 페어링하세요. Relay를 쓸 때만 데스크톱과 폰 두 기기 모두 같은 Orca 계정으로 로그인해야 합니다(LAN·Tailscale로 짝지을 때는 로그인이 필요 없습니다). Relay에서는 로컬 네트워크 주소 선택이 선택 사항이며(같은 공유기 안의 LAN으로 빠르게 가고 싶을 때 펼침), LAN 페어링에는 주소가 꼭 필요합니다.

4 · 토큰 발급

페어링 교환으로 그 폰 전용 기기 토큰이 생깁니다. 고른 경로로 데스크톱에 계속 닿을 수 있게 두세요.

5 · 호스트 이름 표시

페어링 후 폰은 데스크톱의 기기 이름으로 호스트를 부르고 운영체제를 보여 줍니다. 기기 이름은 데스크톱 Settings → Remote Orca Servers에서 바꿀 수 있으며, 폰은 다시 연결될 때 바뀐 이름을 가져옵니다.

데스크톱을 닫으면직접/LAN 세션은 데스크톱 앱을 닫는 순간 끊기고, 다시 열어야 이어집니다. Relay 기반 페어링은 데스크톱의 Relay 연결을 따르므로, 호스트가 오프라인이 되면 데스크톱을 다시 여세요. 창 없는 서버라면 앞의 orca serve --mobile-pairing을 쓰세요.

Chat UI · Quick Commands · 세션 탭

한 줄 요약: 지원되는 에이전트(Claude, Codex 등)는 폰에서 메신저 같은 대화 화면(Chat UI)으로 열 수 있고, 데스크톱에 저장해 둔 명령 목록(Quick Commands)을 폰에서 그대로 실행할 수 있습니다. 세션 탭을 길게 누르면 닫기·화면 바꾸기 메뉴가 나옵니다.

Chat UI 세부 (기기 기본값 · 입력창 · 모델 옵션)

데스크톱과 같은 채팅 지원 에이전트 — Claude, Codex, Grok, OpenCode, OMP, Pi — 는 모바일에서도 원래 터미널 대신 Chat UI로 열 수 있습니다. 읽기 쉬운 대화 기록, 입력창(composer), 권한 요청·질문, 이미지 첨부가 있습니다.

  • 기기 기본값 — 처음 실행할 때 이 폰에서 세션을 어떻게 열지 묻습니다. 나중에 Settings → Chat UI → Open sessions in Chat UI에서 바꿉니다. 고르기 전까지 기본은 터미널입니다.
  • 세션별 — 세션 탭을 길게 눌러 Switch to chat view 또는 Switch to terminal view. 그 탭에만 적용되고 기기 기본값은 바뀌지 않습니다.
  • 입력창 — 답장 입력, @로 워크트리 파일 언급, 공유 카탈로그의 에이전트별·슬래시 명령(Claude용과 Codex용이 따로, 설명 포함), 사진 첨부, 받아쓰기. 첨부 이미지는 지울 수 있는 썸네일로 보이며 함께 전송됩니다(이미지만 보내기, 여러 장 첨부 포함).
  • 모델·세션 옵션 — 입력창에 현재 모델과 세션 옵션을 보여 주는 알약 줄이 있습니다. 눌러서 모델이나 옵션을 고르면 터미널로 내려가지 않아도 됩니다(Codex 모델 직접 선택, 활성 모델이 지원할 때 제공자별 Fast 모드 포함).
  • 에이전트 주인은 여전히 데스크톱 — Chat UI는 페어링된 데스크톱 세션을 보여 주는 화면일 뿐, 별도의 클라우드 에이전트가 아닙니다.
Quick Commands 세부

워크트리 세션에서 세션 탭 줄(새 터미널 버튼 옆)의 Quick Commands를 엽니다. 데스크톱과 같은 저장 목록이며 양쪽으로 동기화됩니다.

  • Terminal Command — 셸 명령을 새 탭에 붙여 넣거나 실행합니다(먼저 고칠 수 있게 Enter를 누르지 않는 선택도 가능).
  • Agent Prompt — 고른 에이전트를 저장된 프롬프트와 함께 엽니다.
  • 줄의 복사 버튼으로 명령 내용을 클립보드에 복사합니다(내용이 비면 비활성).
  • 명령의 범위를 전체(global) 또는 현재 프로젝트로 정합니다. 시트에서 추가·편집·삭제하며, 공유 목록 최대 개수는 데스크톱 호스트가 정합니다.
  • 페어링된 데스크톱이 너무 오래된 버전이면 데스크톱을 업데이트할 때까지 실행기가 꺼져 있습니다.
세션 탭 길게 누르기 메뉴

세션 줄의 탭을 길게 누르면 Close, Close Other Tabs, Close Tabs to the Left, Close Tabs to the Right 같은 동작이 나옵니다. 여러 탭 닫기는 저장 안 된 마크다운 탭(모바일은 닫을 때 저장할지 묻지 않음)과 고정 탭을 건너뜁니다. 채팅 지원 에이전트 탭이면 같은 시트에서 Chat UI ↔ 터미널을 바꿀 수 있습니다.

계정 전환기 · 워크트리 만들기

폰에서 계정을 바꾸면 페어링된 데스크톱의 계정이 바뀝니다. 폰 홈 화면의 Create Workspace / New Workspace로 데스크톱에 새 워크트리를 만들 수도 있습니다.

계정 전환기 · Codex 리셋 크레딧 세부

데스크톱 상태 표시줄과 같은 계정 전환기가 있으며, 비활성 계정의 사용량도 함께 보입니다. 제공자가 세션·주간 한도의 리셋 시각을 알려 주면 계정 화면에 남은 시간이 표시됩니다. 여기서 바꾸면 페어링된 데스크톱에서 계정이 바뀝니다.

활성 Codex 계정에 한도 리셋 크레딧이 쌓였으면, 사용 가능한 개수(다음 크레딧 만료 시각 포함)와 Use reset 동작이 보입니다. 확인하면 현재 Codex 대상(호스트 또는 WSL 배포판)에 크레딧 하나를 쓰고 해당 한도 창을 새로 고칩니다. 폰이 시도를 기록해 두므로 연결이 불안정해 다시 시도해도 두 번 쓰이지 않습니다. 결과는 성공, 리셋할 것 없음, 남은 크레딧 없음, 이미 리셋됨 중 하나입니다(사용량·한도 추적 장 참고).

워크트리 만들기 세부 (소스 모드 · 호스트 고르기)

모바일 홈 화면에서 Create Workspace / New Workspace를 열고 소스 모드를 고릅니다. Smart는 지원되는 작업 제공자와 브랜치를 모두 검색하고, 나머지 모드는 GitHub, Linear, GitLab, 브랜치, 또는 그냥 워크트리 이름으로 범위를 좁힙니다. 소스를 고른 뒤 Advanced에서 이름과 브랜치를 정하고 페어링된 데스크톱에 만듭니다. 데스크톱이 여러 대 연결돼 있으면 먼저 호스트를 고르며(비슷한 이름도 구분되도록 엔드포인트를 함께 표시), 연결된 데스크톱이 없으면 이 동작은 꺼져 있습니다.

페어링된 호스트 편집

호스트 목록에서 카드의 ⋯(또는 카드 길게 누르기) → Edit host.

항목설명
Name이 폰에서만 쓰는 표시 이름. 데스크톱 기기 이름보다 우선하며, 비우면 데스크톱 이름으로 돌아감
AddressIP, host:port, 또는 ws:///wss://. 포트를 빼면 현재 포트를 유지(없으면 기본 6768). 이 폰이 접속하는 곳만 바뀌고 다시 페어링하지 않음. 같은 데스크톱에 다른 경로(집 LAN ↔ Tailscale)로 닿을 때 사용

주소를 바꿔 저장하면 새 엔드포인트로 다시 연결하며, 페어링 토큰은 그대로입니다.

소스 컨트롤 · 브라우저 · 화면 설정

한 줄 요약: 브랜치 아이콘으로 바뀐 파일을 보고 커밋하고, 브라우저 창의 Web / Mobile 스위치로 폰 크기 화면을 확인하며, Settings에서 화면 테마(밝게·어둡게)와 언어를 고릅니다.

소스 컨트롤 · 브라우저 보기 · Appearance·Language 세부
Source Control

워크트리 세션에서 브랜치 아이콘을 누릅니다. 작은 후속 작업용입니다: 브랜치 상태 확인, 바뀐 경로 살펴보기, 파일 stage/unstage, stage가 준비되면 커밋. 브랜치 커밋을 둘러보고 바뀐 파일을 diff 화면에서 엽니다. diff에서는 파일 사이를 이동하고, 문맥을 접고, PR(Pull Request — 내 변경을 합쳐 달라고 요청하고 검토받는 GitHub 기능) 리뷰 댓글을 코드 옆에서 읽거나 답니다. 충돌을 해결하고 병합을 마칠 수도 있습니다. 브랜치에 이미 GitHub PR이 있으면 빈 PR 화면의 Link an existing PR로 새로 만들지 않고 연결합니다.

브라우저 보기

모바일 브라우저 창에 Web / Mobile 스위치가 있습니다. Web은 일반 페이지를, Mobile은 페어링된 데스크톱 브라우저에 폰 크기의 반응형 화면을 요청합니다.

Appearance · Language

모바일 Settings의 Appearance에서 Light·Dark·System(밝게·어둡게·기기 설정 따름)을, Language에서 표시 언어를 고릅니다. 최신 모바일 설정을 쓰려면 Orca Mobile과 데스크톱(또는 서버)을 모두 업데이트하세요.

터미널 설정 (Settings → Terminal)

글자 크기(50%–200%)와 자동 고침 켜기/끄기를 폰마다 따로 정할 수 있습니다.

Text size · Autocomplete & autocorrect · 키보드 세부
  • Text size — 화면 폭 맞춤 위에 적용되는 50%–200% 기본 확대 비율. 터미널에서 두 손가락으로 확대/축소하면 같은 단계에 맞춰지고 저장됩니다. 기기별 설정이라 데스크톱 터미널은 바뀌지 않습니다.
  • Autocomplete & autocorrect — 기본은 꺼짐. 그래서 OS가 명령·옵션·경로를 멋대로 고치지 않습니다. 폰식 입력을 원하면 켜세요. 어느 쪽이든 실시간 키보드 입력은 원래 키 그대로 전달됩니다.
  • 키보드는 일반 앱 화면처럼 페이지를 덮고, 페이지가 높이를 알려 주므로 입력창과 현재 입력란이 타이핑 중에도 보입니다.

모바일 문제 해결

워크트리에서 스피너가 계속 돎

폰은 데스크톱 에이전트 프로세스의 하트비트(살아 있다는 신호)를 따라갑니다. 데스크톱은 idle인데 폰은 working이면 그 워크트리 줄을 강제로 새로 고쳐 상태를 맞추세요.

페어링 실패

Relay로 페어링한다면 데스크톱과 폰 두 기기 모두 같은 Orca 계정에 로그인했는지 확인하세요. 페어링 코드는 몇 분 뒤 만료되므로, 화면에 오래 떠 있었다면 새로 만드세요.

Authentication failed / pairing invalid

데스크톱이 이 기기 토큰을 더 이상 받지 않는 상태입니다(예: 데스크톱이 페어링된 기기를 지웠을 때). 먼저 배너의 Retry를 눌러 보세요(일시적 거부는 다시 페어링하지 않아도 회복될 수 있음). 계속 실패하면 Re-pair from desktop을 쓰거나, 호스트를 Remove하고 다시 페어링하세요.

Update Orca Mobile / Update Orca on your computer

폰과 데스크톱은 버전이 있는 모바일 프로토콜로 대화합니다. 어느 한쪽이 너무 오래되면 모바일이 그 호스트를 막고 App Store(iOS)나 GitHub Releases(Android APK 또는 데스크톱)로 안내한 뒤 호스트 목록으로 돌아갑니다. 업데이트 후 연결을 새로 고치고, 메시지가 남아 있으면 호스트를 지우고 다시 페어링하세요.

Quick Commands를 쓸 수 없음

페어링된 데스크톱을 업데이트해 quick-commands 기능을 알리게 하세요.

데스크톱에 닿지 않음

폰과 데스크톱이 같은 네트워크 경로(LAN, Tailscale, 또는 페어링에 쓴 경로)를 공유해야 합니다. 데스크톱 앱을 닫으면 연결이 끊기며, 다시 열면 폰이 자동으로 재연결합니다.

함께 보면 좋은 것: 에이전트 완료 알림이 알맞은 기기로 가도록 모바일 알림과 데스크톱 알림을 짝지으세요. 창 없는 기계는 원격 Orca 서버의 모바일 페어링을, 제공자 사용량은 사용량·한도 추적 장을 참고하세요.

Android에 Orca Mobile 설치하기 (APK)

APK란?Android 앱 설치 파일입니다. Play 스토어를 거치지 않고 웹에서 직접 받아 설치할 때 쓰며, 이때 Android가 "출처를 알 수 없는 앱" 설치를 허락할지 묻습니다.
  1. 내려받기Chrome 같은 완전한 브라우저에서 Orca 다운로드 페이지를 열고 Android를 고릅니다.
  2. 파일 열기다운로드가 끝나면 브라우저의 다운로드 목록이나 기기의 Files → Downloads에서 app-release.apk를 누릅니다.
  3. 설치Android 설치 안내를 따릅니다. 물으면 브라우저나 Files 앱에만 "출처를 알 수 없는 앱 설치"를 허용하고, Orca 설치가 끝나면 그 권한을 다시 끄세요.
① 내려받기Chrome → Orca 다운로드→ Android ② 파일 열기Files → Downloadsapp-release.apk ③ 잠깐 허용출처를 알 수 없는 앱브라우저·Files에만 ④ 설치 후 다시 끄기허용했던 권한 OFFPlay Protect는 그대로 ③에서 연 문은 ④에서 꼭 다시 닫습니다
APK 설치는 "받고 → 열고 → 잠깐 허용하고 → 다시 끄기" 네 걸음입니다.

설치 문제 해결

다운로드가 시작되지 않거나 끝나지 않음

Discord, GitHub 같은 다른 앱 안에서 링크가 열렸다면 Open in browser / Open in Chrome을 고르거나 링크를 복사해 완전한 브라우저에 붙여 넣으세요. 그런 다음 Android 다운로드를 다시 시작하고 끝날 때까지 기다리세요.

Samsung Galaxy: Auto Blocker가 설치를 막음

Settings → Security and privacy → Auto Blocker(설정 → 보안 및 개인정보 보호 → 자동 차단)를 열어 잠시 끄고, Orca를 설치한 뒤 다시 켜세요. Play Protect는 끄지 마세요.

한눈에 정리
  • 다른 컴퓨터(서버)가 없다면 SSH·원격 서버는 건너뛰고 모바일 앱만 보면 됩니다.
  • SSH 워크트리: 노트북 Orca가 주인, 원격 호스트는 작업장. Settings → SSH에서 대상 추가(host·user·port는 IT 담당자에게) → Test → Save, 워크트리 위치로 SSH 대상 선택.
  • 호스트 키(서버 지문)가 바뀌었다는 경고가 뜨면 직접 처리하지 말고 서버 관리자에게 문의합니다.
  • 끊겨도 원격 에이전트는 계속 돌고, 끊기면 워크트리 카드의 재연결 버튼으로 다시 붙습니다.
  • 관리형 Orca 서버는 자동으로 설치·업데이트되므로 오류가 날 때만 Settings → Managed servers를 봅니다.
  • Ports 탭(Cmd+Shift+I — macOS)으로 원격 포트를 감지해 한 번 클릭으로 내 브라우저에 연결합니다.
  • 원격 Orca 서버(베타): 서버가 Orca 전체를 가짐. 두 컴퓨터를 같은 Tailscale에 묶고(100. 주소 확인) → 서버에서 New Link → Generate Access Link → 노트북에서 Add Server → Connect. 접근 링크는 비밀번호처럼, 필요 없어진 기기는 바로 취소.
  • 모바일 앱(베타): 상태 보기·짧은 답장·푸시 알림·워크트리 만들기. 데스크톱 계정/상태 메뉴에서 코드를 만들어 폰에서 Pair. Relay를 쓸 때만 두 기기 모두 같은 Orca 계정 로그인.
  • Android: app-release.apk 설치, 알 수 없는 앱 권한은 설치 후 끄기, Samsung Auto Blocker는 잠시만 끄고 Play Protect는 그대로.

출처: onorca.dev/docs/ssh · onorca.dev/docs/remote-servers · onorca.dev/docs/recipes/remote-worktrees · onorca.dev/docs/mobile · onorca.dev/docs/android-apk

CHAPTER 10

봇(Bots) — 일을 받아 오고, 일정대로 돌고, 사람 대신 보고하는 에이전트

봇은 이름·목적·기억을 가진 에이전트입니다. Slack·GitHub·Linear·자기 채팅·정해 둔 일정에서 일을 받아, 내 컴퓨터의 Claude Code나 Codex로 처리하고, 부탁받은 곳에 결과를 보고합니다. 결정이 필요하면 Orca에서 나를 기다립니다.

이 장에서 배우는 것
  • 봇이 무엇이고, 그냥 에이전트 채팅과 무엇이 다른지
  • 봇 만들기, 첫 일 맡기기, 대화하기, 일정·이벤트로 돌리기, 중간에 끼어들기
  • Slack·GitHub·Linear·Google·웹훅(webhook) 연결과, 봇이 누구의 이름으로 일하는지
  • 누가 봇에게 일을 시킬 수 있는지(Who can ask)와 권한·보안 — Orca가 강제하는 것과 봇이 지시만 받는 것
  • 봇이 시키지 않아도 하는 일(둘러보기·기억 정리), 다른 앱의 봇 가져오기, 쓰임새 8가지와 템플릿 24종
처음이라면 이것만

건너뛰어도 되는 곳: 「연결(Connectors)」의 서비스별 설정, 「다른 앱의 봇 가져오기」. 「🔧」로 접힌 상자는 접어 둔 채 읽어도 됩니다.

봇이란 무엇인가

쉽게 비유하면 봇은 내 컴퓨터에 사는 비서입니다. 비서에게는 이름표(이름·사진), 업무 설명서(목적), 수첩(기억), 일정표(자동화)가 있습니다. 동료가 Slack에서 "@scout 이것 좀 봐 줘" 하고 부르거나, 정해 둔 시간이 되면 비서가 일을 시작합니다. 손이 많이 가는 코드 작업은 조수(작업자)에게 따로 책상(워크트리)을 내줘서 맡깁니다. 중요한 결정은 혼자 하지 않고 "이렇게 할까요?" 하고 나에게 물어봅니다.

봇은 자기 채팅, Slack, Linear, GitHub, 정해 둔 일정에서 일을 받습니다. 일은 내 컴퓨터에서, 내가 이미 쓰는 Claude Code나 Codex(또는 다른 지원 에이전트)로 합니다. 그래서 봇이 한 일은 그 에이전트 요금제 사용량으로 잡힙니다. 끝나면 부탁받은 곳에 보고하고, 결정이 필요하면 Orca 안에서 나를 기다립니다.

이름과 사진

Slack에서는 @scout처럼 자기 이름으로 보입니다.

목적(soul)

"무엇을 하는 봇인지" 적은 설명. 첫 대화 뒤 봇이 스스로 적어 두어, 이후 모든 대화가 같은 곳에서 시작합니다.

기억(memory)

일하며 배운 것을 적어 두는 곳. 새 일마다 새 채팅을 열어도 같은 설명을 반복할 필요가 없습니다.

자동화

"평일 9시마다", "PR이 열리면"처럼 정해 둔 때에 스스로 시작하는 일.

봇은 한 컴퓨터의 폴더 하나에 삽니다. 목적·기억·능력은 그 폴더 안의 평범한 Markdown 파일이라 직접 읽고 고칠 수 있습니다.

💬 봇 채팅Orca 안에서 직접 # Slack@봇이름 · DM GitHub · Linear이슈·PR에서 부름 ⏰ 일정 · 이벤트평일 9시, CI 실패 등 일을 받는 곳 🤖 봇 (예: Scout) 내 컴퓨터의 폴더 하나 목적 · 기억 · 자동화 내 Claude Code / Codex로 일함 🛠 작업자 (worker) 자기 워크트리에서 코드 수정 📣 보고부탁받은 스레드·이슈·채팅 ? Needs you결정·승인은 나를 기다림 🔀 PR검토하고 합칠지 결정
일은 여러 곳에서 오지만, 처리는 언제나 내 컴퓨터의 봇이 합니다. 코드 수정은 작업자가 자기 워크트리에서 하고, 결과는 PR로 돌아옵니다.
언제 나왔나 Bots는 1.4.265(2026-11-19)에 나왔습니다("Work with Orca Bots"). 1.4.268(11-21)부터 봇의 에이전트로 Cursor · GitHub Copilot · Hermes도 고를 수 있고, 봇 그룹 채팅에 이미지를 넣을 수 있습니다.

시작 전 준비

  1. 최신 Orca봇을 둘 컴퓨터에 최신 버전 Orca를 설치합니다.
  2. 에이전트 설치·로그인그 컴퓨터에 Claude Code·Codex 등 지원 에이전트를 설치하고 로그인해 둡니다. 봇은 그 에이전트로 일하므로 사용량도 그 요금제에서 나갑니다.
  3. (선택) Orca 로그인Slack·GitHub·Linear에서 봇을 부르려면 Orca에 로그인(Sign in to Orca)해야 합니다. 봇 채팅·일정·Google은 로그인 없이도 됩니다.

봇 만들기

1. 새 봇 시작 — 사이드바의 Bots 칸에서 +(New bot or group) → New bot → Start from scratch(처음부터). 템플릿 24종 중에서 고르려면 Browse templates를 누릅니다.

2. 이름과 사진 — 봇의 이름과 사진을 정합니다. Slack 등에서 이 이름으로 불립니다.

3. 하는 일 적기(선택) — Who it is and what it does(누구이고 무엇을 하나) 칸에 할 일을 한 문장으로 적습니다. 비워 두고 첫 채팅에서 말해도 됩니다.

4. 어디서 돌지 확인 — 어느 컴퓨터에서, 어느 에이전트로 돌지 적힌 줄을 확인합니다. 바꾸려면 Change. 봇은 고른 컴퓨터에 계속 머뭅니다.

5. 만들기 — Create를 누릅니다. 누르기 전까지는 아무것도 만들어지지 않습니다.

Bots 칸이 안 보이면 Bots는 기본으로 켜져 있습니다. 사이드바에 Bots 칸이 없으면 Settings → Bots → Enable bots(설정 → 봇 → 봇 켜기)를 켭니다. 봇을 끄면 봇이 숨겨지고 새 메시지와 자동화 실행이 멈춥니다. 봇 폴더·기억·채팅은 그대로 남습니다.

첫 일 맡기기

처음부터 만든 봇은 인사를 하고 "무엇부터 할까요?" 하고 묻습니다. 진짜 할 일 하나로 답합니다.

봇 채팅 — 첫 일 예시

🤖 봇: 안녕하세요! 무엇부터 할까요?

🙂 나: "매일 아침 acme/web에서 무엇이 바뀌었고 내가 검토할 것이 무엇인지 요약해 줘."

🙂 또는: "PR에서 CI(코드를 올릴 때마다 자동으로 돌아가는 검사)가 실패하면, 우연히 한 번 실패한 것(flaky)인지 진짜 문제인지 알려 줘."

봇은 그 일에 무엇이 필요한지 살펴보고, 작은 조각 하나를 바로 해서 결과를 보여 줍니다. 그다음 자기 목적을 적어 두고, 배운 것은 기억에 남깁니다.

코드 수정은 작업자가 코드를 바꿔야 하면 봇은 일을 작업자(worker)에게 넘깁니다. 작업자는 새 워크트리(작업마다 따로 쓰는 작업 폴더)에서 도는 Claude Code나 Codex 세션이라, 그 변경이 내 작업 폴더에 섞이지 않습니다. 작업자는 사이드바에서 봇 아래에 보이고, 작업자가 연 PR(Pull Request — "이 변경을 합쳐 주세요" 요청)은 봇에게 돌아옵니다.

템플릿으로 만든 봇은 목적이 이미 있고, 일부는 능력과 일정도 갖고 있습니다. 템플릿의 일정은 꺼진 채로 시작합니다. 어느 저장소·채널을 쓸지 첫 채팅에서 정하면, 그때 자동화와 연결이 설정됩니다.

대화하기와 「Needs you」

사이드바에서 봇을 누르면 봇 채팅이 열립니다. 무엇이든 물어보면 됩니다. 다른 Orca 채팅에서도 @를 입력해 봇을 부르면 그 대화에 봇을 데려올 수 있습니다.

봇이 나를 필요로 할 때(결정·로그인·승인)는 그렇게 말하고, 그 요청은 봇 Home의 Needs you(내 차례) 아래에서 내가 답할 때까지 기다립니다. 봇이 제안한 답 중 하나를 누르거나 내 말로 답합니다.

Scout — Home (예시 화면)

Needs you 1 — Pay button ignores first tap on Safari

In progress 작업 중 — Search shows stale results… · Coupon field accepts expired codes…

Automations — Triage new bugs (New Linear bug) · Morning bug digest (Weekdays 9:00 AM)

봇 Home은 위에서부터 "나를 기다리는 것 → 봇이 하는 일 → 자동화" 순서로 보여 줍니다. 위 화면은 공식 문서의 예시 데이터를 옮긴 것입니다.

폰에서도: iOS·Android Orca 앱이 Needs you를 한 목록으로 보여 줍니다. 한 번 눌러 답하거나 승인하고, 밖에서도 새 일을 맡길 수 있습니다. 모바일 앱 자체는 8장 모바일 앱을 보세요.

일정·이벤트로 돌리기

봇 채팅에서 일정("평일 9시마다")이나 이벤트("acme/web에 PR이 열리면")를 말하면, 봇이 자동화를 만들고 어디서 돌며 결과가 어디로 가는지 알려 줍니다. 자동화는 봇 패널에 보이고 거기서 멈추거나 다시 켤 수 있습니다.

  • 일정 종류: 매시간 · 매일 · 평일 · 매주 · cron · RRULE(둘 다 "매달 첫째 월요일"처럼 복잡한 반복을 글자로 적는 방식).
  • 시작할 수 있는 이벤트는 붙인 연결에 따라 다릅니다(→ 연결). 예약 자동화 자체는 7장 예약 자동화에 있습니다.
Slack · GitHub · Linear 요청 컴퓨터가 잠들면 최대 하루 기다림 💻 봇의 컴퓨터 깨어 있고 온라인일 때만 일함 Mac은 덮개를 닫으면 잠듦 늘 닿게 하려면 Orca와 페어링한 서버에 봇을 두고 깨워 둠
봇은 사는 컴퓨터가 깨어 있어야 일합니다. Orca의 Keep computer awake 설정은 에이전트가 일하는 동안 저절로 잠드는 것을 막지만, Mac 덮개를 닫으면 그래도 잠듭니다.

중간에 끼어들기

봇의 일은 모두 Orca 안에 남으므로 언제든 이어받을 수 있습니다.

보고 싶은 것여는 법
작업자의 작업 공간사이드바에서 봇 아래의 작업자를 누릅니다. 작업자가 멈춘 곳 그대로 그 워크트리의 에디터·터미널·브라우저가 열립니다.
Slack·GitHub·Linear에서 온 대화봇 아래에 대화마다 채팅이 따로 있습니다. Slack 스레드의 Open this thread in Orca 링크, Linear 이슈의 봇 세션에서 Open in Orca로도 엽니다.
봇의 PR다른 PR처럼 검토합니다. 내 작업 폴더가 아니라 작업자의 브랜치에서 옵니다.

연결(Connectors) — Slack · GitHub · Linear · Google · 웹훅

연결은 세 가지 일을 합니다. ① 사람들이 Slack·GitHub·Linear에서 봇을 부르게 하고, ② 그곳에서 무슨 일이 생기거나 웹훅이 호출되면 자동화를 시작하고, ③ Google 같은 다른 앱에서 봇이 일하게 합니다.

봇의 Connectors 탭에서 Add a connector(이미 하나 있으면 Add)를 누르고 서비스를 고릅니다. Slack·GitHub·Linear 카드에는 그 봇을 정확히 어떻게 부르는지 적힌 How to ask 줄이 있습니다. 봇에게 "연결해 줘"라고 해도 되는데, 그러면 채팅에 Connect 카드가 뜨고 내가 끝까지 진행하기 전에는 아무것도 연결되지 않습니다.

연결부르는 법봇이 누구로 일하나거치는 길
Slack채널에서 @봇이름, 또는 DM봇 자신(봇마다 따로 만든 Slack 앱)Orca Cloud
GitHub이슈·PR에서 How to ask 줄대로 언급부른 곳의 답은 Orca 앱, 그 밖의 GitHub 일은 나(push도 내 git 로그인)Orca Cloud
Linear이슈에 @Orca <handle>, 또는 라벨 bot:<handle>부른 곳의 답은 Orca 앱, 그 밖의 Linear 일은 나Orca Cloud
Google부르는 곳은 아님. 새 메일·다가오는 일정으로 자동화 시작나(Gmail·Calendar·Drive·Docs·Sheets)내 컴퓨터 → Google 직접
웹훅어떤 도구·스크립트든 봇의 주소(URL)를 호출자동화만 시작, 자기 신분 없음Orca Cloud

<handle>은 봇의 짧은 이름으로, How to ask 줄에 나옵니다.

Slack · GitHub Linear · 웹훅 사람이 부름 ☁ Orca Cloud 누가 부를 수 있는지 검사 컴퓨터가 가져갈 때까지 보관 💻 봇의 컴퓨터 스스로 밖으로 접속해 새 요청을 가져감 (열어 둘 포트 없음) Google Orca Cloud를 거치지 않음 화살표: 컴퓨터 쪽이 먼저 연결
바깥에서 내 컴퓨터로 들어오는 길은 없습니다. 내 컴퓨터가 Orca Cloud에 먼저 접속해 요청을 가져가고, 부탁받은 스레드·PR·이슈에 답합니다. Google만은 내 컴퓨터가 Google에 직접 접속합니다.
Slack·GitHub·Linear·웹훅은 Orca 로그인이 먼저 이 넷은 Orca Cloud를 거치므로 연결하기 전에 Sign in to Orca가 필요합니다. 로그아웃하면 봇 채팅과 일정은 그대로 두고, 바깥 이벤트만 다시 로그인할 때까지 멈춥니다.

봇마다 자기 Slack 앱이 생겨서, 사람들은 @봇이름으로 채널에서 부르거나 DM을 보냅니다. 부르면 봇이 자기 컴퓨터에서 일을 시작합니다.

한 Slack 워크스페이스에 봇을 처음 넣을 때 App Configuration Token(Slack이 "이 도구가 나 대신 앱을 만들어도 된다"고 내주는 비밀 문자열)을 한 번 넣습니다. Orca는 이걸로 봇마다 이름·사진이 다른 Slack 앱을 만듭니다. 워크스페이스에 따라 관리자가 봇 앱을 승인해야 들어옵니다.

🔧 토큰 넣는 순서와 지우기
  1. Orca에서 Get your configuration token을 누릅니다. Slack 앱 설정에서 Your App Configuration Tokens를 찾아 Generate Token.
  2. 봇을 둘 워크스페이스를 고릅니다.
  3. Refresh Token(xoxe-로 시작)을 복사해 Orca에 붙여 넣습니다.

Orca Cloud는 이 토큰을 내 Orca 계정·그 워크스페이스용으로 암호화해 보관하므로, 같은 워크스페이스의 다음 봇부터는 다시 넣지 않습니다. 그다음 Slack에서 나로서 봇 앱을 승인합니다. 관리자 승인이 필요한 워크스페이스면 승인 뒤에 봇이 들어옵니다.

워크스페이스 토큰은 언제든 지울(forget) 수 있습니다. 이미 Slack에 있는 봇은 남고, 새 봇은 새 토큰이 필요합니다. Slack 연결을 지우면 Slack에서 오는 새 일만 멈추고, Slack의 앱 자체는 지워지지 않습니다.

  1. 연결Orca에 로그인한 뒤 봇의 Connectors에서 GitHub → Connect GitHub. 브라우저에서 GitHub로 로그인합니다.
  2. 앱 설치Install the Orca app으로 봇이 일할 저장소에 Orca 앱을 설치합니다. 조직(organization)에서는 소유자 승인이 필요할 수 있습니다.
  3. 켜기Turn on으로 봇에 켭니다. 나중에 Add repositories or organizations로 일할 곳을 늘립니다.

부른 곳에는 Orca 앱으로 답하고, 그 밖의 GitHub 일은 그 컴퓨터의 내 gh 로그인으로 합니다. 봇은 "내가 시킬 때만 승인·변경 요청·병합(merge)하라"는 지시를 받지만, Orca가 강제하지는 않습니다(→ 권한과 보안).

🔧 자동화를 시작할 수 있는 GitHub 이벤트
  • 새 이슈·PR, push, 댓글·리뷰, 리뷰 요청, 라벨.
  • CI 실패·통과, 병합 충돌(merge conflict), 병합, 배포, 보안 경고, 끝난 워크플로 실행.

내가 GitHub에서 직접 한 일(댓글·리뷰·push)은 봇을 깨우지 않습니다. 봇이 거기서 나로 일하기 때문입니다. 예외는 "내 새 PR을 리뷰해 줘"처럼 내가 연 PR을 대상으로 한 규칙입니다. GitHub가 알려 주는 변화(CI 결과·병합 충돌·병합·닫힌 PR·배포·보안 경고·끝난 워크플로)는 내가 일으켰어도 켜 둔 규칙을 시작합니다.

  1. 연결Orca에 로그인한 뒤 봇의 Connectors에서 Linear → Connect Linear. 브라우저에서 Linear로 로그인하고 워크스페이스를 고릅니다.
  2. 앱 설치(한 번)그 워크스페이스에 Orca가 아직 없으면 Linear 관리자가 모두를 위해 한 번 설치합니다.
  3. 켜기Turn on으로 봇에 켭니다.

사람들은 이슈에 @Orca <handle>(예: @Orca scout — @scout가 아님)을 쓰거나 라벨 bot:<handle>을 붙입니다. Linear 언급은 Orca 앱을 거치기 때문입니다. 자동화 이벤트: 이슈 배정, 언급, 새 이슈, 이슈 이동.

봇이 내 Gmail·Calendar·Drive·Docs·Sheets에서 일하고, 새 메일이나 곧 시작할 일정으로 자동화를 시작하게 합니다. 봇마다 꺼진 채로 시작하며, 그 봇의 Connectors에서 켭니다.

설정할 때는 나만의 Google Cloud 앱을 만들고, 봇이 채팅에서 안내합니다. Orca 브라우저에서 클릭을 대신 해 주거나, 그곳에서 안내하거나, 내 브라우저에서 안내할 수 있습니다. Google 약관 동의 칸은 내가 직접 체크합니다.

앱이 내 것이라 Google 로그인은 내 컴퓨터에 머물고, 봇은 거기서 Google로 바로 호출합니다. 그래도 봇이 읽은 내용은 에이전트의 모델 회사로 갈 수 있고, 봇이 Slack·GitHub·Linear에 올리는 답에 들어갈 수 있습니다. 새 메일·일정 규칙은 내 컴퓨터에서 약 1분마다 확인합니다.

봇은 "시키지 않았으면 메일은 보내지 말고 초안만 쓰라"는 지시를 받지만, Orca가 강제하지는 않습니다. 봇의 Google은 언제든 끌 수 있고, 그 컴퓨터의 다른 봇에는 Google 연결이 그대로 남습니다.

웹훅(webhook)(다른 프로그램이 "일 생겼어" 하고 주소 하나를 호출해 알려 주는 방식)은 어떤 도구·스크립트든 웹 요청 하나로 봇을 시작하게 합니다. 봇 채팅에서 만들어 달라고 하고, 자동화 카드의 Copy URL로 주소를 복사합니다. 호출은 Orca Cloud를 거쳐 내 컴퓨터로 오고, Orca는 호출 내용을 지시가 아니라 정보로 봇에게 넘깁니다.

웹훅 주소는 비밀번호처럼 주소를 가진 사람은 누구나 그 자동화를 시작할 수 있습니다. 주소만으로 부족하면 signing secret(서명용 비밀값)을 더합니다. 주소가 새면 웹훅의 Rotate key…(키 바꾸기)나 Delete hook…(지우기)을 씁니다.
  • Composio: Orca가 직접 연결하지 않는 앱(예: Outlook·Notion·HubSpot)은 내 Composio 키를 넣어 씁니다. 앱 로그인은 Composio가, 키는 Orca가 갖고 있어 봇은 키를 보지 못합니다.
  • MCP 서버(에이전트에게 새 도구를 붙여 주는 표준 플러그인): 봇에게 "그 봇만 쓰는 MCP 서버"를 붙여 달라고 합니다. 웹으로 닿는 서버는 Orca가 키·로그인을 암호화해 보관하고 호출할 때마다 직접 붙이므로 봇이 키를 갖지 않습니다. 명령으로 실행하는 서버는 저장된 설정에서 키를 받는데, 그 설정은 암호화되지 않습니다.

Bots 소개 쪽에는 이 밖에 Sentry·Vercel·Notion·Datadog·PostHog·Supabase·Stripe·Atlassian·HubSpot 등이 "봇이 일할 수 있는 곳"으로 나옵니다. MCP 서버나 Composio로 연결하는 곳들입니다.

🔧 「누가 시켰는지」 기록 줄

Orca가 나 아닌 사람이 시킨 일임을 알 수 있으면, 봇이 Orca를 통해 쓰는 새 Linear 댓글, Gmail 초안, 설명이 있는 새 캘린더 일정, Docs 댓글 글에 "asked by Maya via Scout" 같은 줄을 넣습니다. 초안은 누가 먼저 고치지 않는 한 보낼 때도 그 줄이 남습니다. 봇이 만든 Drive 파일·폴더·Docs의 설명과 Drive 공유 메일에도 누가 시켰는지 적습니다. 누가 시켰는지 모르면 아무것도 넣지 않고, 이슈 수정 같은 편집에는 넣지 않습니다.

누가 시킬 수 있나 (Who can ask)

기본으로는 나만 내 봇에게 일을 시킬 수 있습니다. 동료가 Slack·Linear·GitHub에서 시키게 하려면 봇 설정의 Who can ask에 그 사람을 넣습니다. 넣기 전에 알아 둘 것:

🙂 나기본으로 나만 👥 Who can ask에 넣은 사람내가 넣은 동료 🚫 목록에 없는 사람"주인에게 물어보세요" ☁ Orca Cloud요청마다 목록 검사 🤖 봇누가 시켜도내 권한 · 내 컴퓨터로 일함
목록에 넣은 사람의 요청도 내 권한으로 돕니다. 목록에 없는 사람의 요청은 Orca Cloud에서 걸러집니다.
그 사람의 요청은 「내 권한」으로 돕니다
  • 그 사람 자기 권한이 아니라 내 권한, 내 컴퓨터로 일합니다. 봇이 할 수 있는 일이면 그 사람도 시킬 수 있습니다.
  • 봇을 원격으로 조종할 수 있습니다: 시작·방향 바꾸기·승인·멈추기.
  • 그래서 내 키보드 앞에 앉혀도 믿을 사람만 넣습니다.
목록에 없는 사람이 부르면
  • Orca가 보통 "주인에게 물어보세요"라는 메모로 답하고, 결정은 내가 Orca에서 합니다. Slack에서는 그 사람에게만 보이고, GitHub·Linear에서는 공개 답글입니다.
  • 봇이 이미 있는 스레드에서 그 사람들의 메시지는 봇이 맥락으로 읽습니다. 다만 일을 시작하거나 방향을 바꾸지는 못합니다.

이벤트 자동화와 웹훅은 Who can ask와 따로입니다. "#eng에 누가 글을 올리면" 같은 규칙을 켜면, 나만 봇을 부를 수 있어도 나와 봇이 함께 있는 곳의 누구든 그 규칙을 시작시킵니다. 봇에게 듣는 곳을 좁혀 달라고 하거나, 일부 이벤트는 "Maya나 Sam이 올릴 때만"처럼 사람을 정할 수 있습니다. 쓰지 않는 규칙은 멈춰 둡니다. 웹훅은 signing secret이 없으면 주소를 가진 누구나 시작시킵니다.

팀이 쓸 봇이면 따로 하나 팀용으로는 별도의 봇을 만드는 것을 고려하세요. 그 봇은 자기 권한·Google 스위치·도구를 따로 갖습니다. 다만 여전히 그 컴퓨터에서 나로 돕니다.

시키지 않아도 하는 일 — 둘러보기와 기억 정리

내가 시킨 일과 자동화 말고도, 봇은 작은 일 두 가지를 스스로 합니다. 둘 다 에이전트 요금제를 씁니다.

👀 Look around (둘러보기)

Claude Code나 Codex로 도는 봇이 하루 몇 번 Slack·Linear·GitHub와 내 프로젝트에서 나를 기다리는 것을 읽고, Suggestions(제안)에 다음 할 일을 적습니다. 읽기만 하며 글을 올리거나 파일을 바꾸지 못합니다. 기본은 평일 오전 8시~오후 8시, 4시간마다이고, 봇 컴퓨터에서 Orca가 켜져 있을 때 돕니다. 봇 설정의 Look around에서 횟수를 바꾸거나 끕니다.

🧹 Memory upkeep (기억 정리)

기본으로, 새 채팅이 있었던 날이면 Claude Code나 Codex 봇이 그날 밤 3시 이후(멈춰 있거나 바쁘지 않을 때) 기억을 정리합니다. 컴퓨터가 자느라 놓친 정리는 깨어난 뒤 따라잡을 수 있습니다. 바뀐 내용을 검토할 수 있고, 가능할 때는 Undo로 MEMORY.md를 되돌립니다. 봇 설정의 Memory upkeep에서 주 1회로 바꾸거나 끕니다.

권한과 보안 — Orca가 막는 것과 봇이 지시만 받는 것

봇은 내 권한으로, 나를 대신해 일합니다. 다른 사람이 봇을 부르게 하거나, 바깥에서 오는 메일·이슈·메시지를 봇에 연결하기 전에 이 소절을 읽으세요.

봇이 닿을 수 있는 곳

어디무엇을 할 수 있나
자기 컴퓨터그곳의 내 파일·명령·계정을, 나로서, 권한이 허락하는 만큼
Slack자기 앱(@봇이름)으로 글 올리기
GitHub부른 곳에는 Orca 앱으로 답, 그 밖의 댓글·리뷰·push는 나로
Linear부른 곳에는 Orca 앱으로 답, 이슈 댓글·수정·생성은 나로
Google켜 준 서비스만 — 메일 읽기·보내기, 캘린더, Drive 파일·Docs·Sheets 읽기·고치기 등

연결은 붙인 뒤에만 닿는 곳을 늘립니다.

권한 모드

봇 대화도 다른 Orca 채팅과 같은 권한 모드로 돕니다: Ask for approval(매번 승인 받기) · Accept edits(편집은 허용) · Approve for me(나 대신 승인) · Full access(전부 허용). 쓸 수 있는 모드는 에이전트마다 다릅니다(→ 3장 권한 기본값).

  • 봇의 새 대화는 따로 정하지 않으면 내 채팅 권한 설정으로 시작합니다. Orca 채팅 기본값이 Full access라서, 바꾸지 않으면 새 봇도 Full access — 명령 실행·파일 수정 전에 묻지 않습니다.
  • 다른 사람이 부르는 봇, 바깥 메일·이슈·메시지를 읽는 봇은 봇 설정에서 Ask for approval로 바꿉니다. Codex라면 요청이 승인될 때까지 읽기 전용으로 일합니다. 이미 열린 대화는 원래 권한을 유지합니다.
  • 승인 모드가 없는 에이전트로 도는 봇은 늘 Full access입니다. 승인이 필요하면 Claude Code나 Codex처럼 승인 모드가 있는 에이전트를 고릅니다.
  • 봇이 승인을 구하면 그 일을 시킨 사람이 승인할 수 있습니다.
🔒 Orca가 막는 것 (강제) · Who can ask — Orca Cloud가 요청마다 검사 · 둘러보기는 읽기만 (쓰기·실행·전송 거부) · 기억 정리는 도구 없음 (명령 실행 불가) · 가져오기는 키·로그인 파일을 건너뜀 · 새 봇은 내가 Create bot을 눌러야 생김 · 누가 시켰는지 기록 📝 봇이 지시만 받는 것 · PR 승인·변경 요청·병합은 시킬 때만 · 시키지 않았으면 메일은 초안만 · 메일·메시지·이슈·파일·웹훅은 정보일 뿐 지시로 따르거나 기억에 넣지 않기 · 토큰을 묻거나 로그인을 우회하지 않기 · 가져온 자동화는 멈춘 채로 모델이 따르지만, 반드시 지킨다는 보장은 없음
왼쪽은 Orca가 구조적으로 막는 것, 오른쪽은 봇이 받은 규칙입니다. 오른쪽은 모델이 속을 수도 있으므로, 위험을 줄이려면 Ask for approval · Google 끄기 · 필요한 연결만을 함께 씁니다.
다른 사람의 글은 봇을 조종하려 할 수 있습니다 봇이 읽는 메일·이슈·메시지·파일·웹훅 호출은 다른 사람이 쓴 글이라, 봇의 방향을 바꾸려 할 수 있습니다. Orca는 Google 메일·파일과 웹훅 호출처럼 일부를 "정보"로 표시해 넘기고, 나머지(봇이 직접 연 파일 포함)도 같은 식으로 다루라고 봇에게 지시합니다. 그래도 모델은 속을 수 있습니다. 믿을 수 없는 글을 읽거나 다른 사람이 부르는 봇은, 에이전트가 지원하면 새 대화를 Ask for approval로 시작하고 필요 없는 것은 끕니다.

작업자는 자기 워크트리 안에서만: 봇이 코드 일을 넘기면 작업자는 내 작업 폴더가 아니라 봇 아래의 새 워크트리에서 돌고, 변경은 내가 검토할 브랜치와 PR로 들어옵니다.

🔧 데이터가 머무는 곳과 비밀값 보관
  • 봇은 한 컴퓨터(이 컴퓨터 또는 Orca와 페어링한 서버)의 폴더에 삽니다. 목적·기억·능력은 그 폴더의 평범한 파일이고, 채팅 기록은 그 컴퓨터의 Orca 저장소에 있습니다.
  • 봇은 내가 고른 에이전트의 내 로그인으로 돕니다. 다른 에이전트 세션처럼, 봇이 읽은 것은 그 에이전트의 모델 회사로 갑니다.
  • Slack·GitHub·Linear·웹훅은 Orca Cloud를 거칩니다. Orca Cloud는 컴퓨터가 가져갈 때까지(잠들어 있으면 최대 하루) 요청을 보관합니다. 전달 뒤에도 일부 글이 한동안 남습니다 — 봇이 맥락으로 쓰는 최근 스레드 메시지, 전달되지 않은 요청(다시 보낼 수 있게), 웹훅 호출 본문(살펴볼 수 있게 최대 7일).
  • Slack용으로 Orca Cloud는 내 Orca 계정·워크스페이스마다 암호화한 configuration token 하나를 보관합니다.
  • Google은 내가 만든 Google Cloud 앱을 쓰고, 로그인은 내 컴퓨터에 머뭅니다. 새 메일·일정 규칙도 내 컴퓨터에서 확인합니다.
  • Google·Composio 로그인은 봇 컴퓨터에 OS 키체인(keychain — 운영체제의 비밀번호 금고)으로 암호화해 저장합니다. 키체인이 없으면 내 사용자만 읽을 수 있는 파일(0600)에 암호화 없이 둡니다.
  • 웹으로 닿는 MCP 서버의 헤더·로그인은 Orca가 암호화해 보관하고 호출마다 붙입니다. 키체인이 없으면 저장하지 않습니다.
  • 명령으로 실행하는 MCP 서버의 설정(환경 변수에 넣은 키 포함)은 봇의 도구 설정에 암호화 없이, 내 사용자만 읽을 수 있게 저장됩니다.
  • 봇은 비밀값을 기억에 저장하지 말라는 지시를 받습니다. 가져오기는 키·로그인 파일을 건너뛰고 서비스마다 다시 연결하게 합니다.

검토할 수 있는 것

  • 봇의 모든 채팅(자동화·이벤트로 시작한 실행 포함)이 기록에 남습니다.
  • 자동화마다 실행 기록, 웹훅마다 받은 호출 목록이 있습니다.
  • 목적·기억은 봇 폴더의 Markdown 파일 — 읽고 고치고, 밤 정리가 바꾼 것을 검토합니다.
  • 코드 일은 브랜치와 PR로 옵니다.

권한 되돌리기 (봇 설정에서 언제든)

  • Keep only me: Who can ask에 넣은 사람을 뺍니다. 이벤트 자동화·웹훅은 멈추지 않으니 따로 멈춥니다.
  • 봇의 Google 끄기(다음 Google 요청부터 모두에게).
  • 새 대화를 Ask for approval로 시작.
  • Connectors 탭에서 연결 지우기, Slack 워크스페이스 토큰 지우기.
  • 자동화 멈추기, 또는 Settings → Bots에서 봇 끄기.
  • 웹훅 주소가 샜으면 키 바꾸기·웹훅 지우기.

다른 앱의 봇 가져오기

다른 봇 앱에서 쓰던 봇이 있으면 그 봇의 성격(persona)·기억·능력·일정을 가져올 수 있습니다. 새 Orca 봇이 옛 봇을 읽고, 계획을 보여 주고, 내가 승인하면 스스로 설정합니다. 옛 봇은 읽기만 하고 바꾸지 않습니다. Bots 소개 쪽은 OpenClaw·Hermes에서 가져오는 경우를 예로 듭니다.

  1. 시작사이드바 Bots 칸에서 + → New bot → Import from another app…. Orca가 이 컴퓨터에서 지원하는 봇 앱의 봇을 찾아 목록으로 보여 줍니다(찾으면 먼저 가져오기를 권할 수도 있습니다).
  2. 고르기찾은 봇이면 골라서 새 이름을 주고 만듭니다. 못 찾은 봇은 Another app…: Orca가 주는 메시지를 옛 봇에게 보내면 옛 봇이 자기 파일을 한 폴더에 복사합니다. 그 폴더를 넣고, 옛 봇이 답을 썼으면 붙여 넣고, 이름을 주고 만듭니다.
  3. 계획 검토새 봇이 찾은 것을 묶어서 보여 줍니다. 채팅에서 "전부 가져와" 또는 "이건 빼"라고 답할 때까지 아무것도 설정하지 않습니다.
✅ 가져옴 (Comes over) · 성격 → 봇의 목적(soul) · 나에 대한 사실 → 기억 · 능력(skills) → 같은 형식 · 일정 → 자동화 🔄 바뀜 (Changes) · Orca에 없는 채팅 앱으로 가던 결과 → Orca 봇 채팅으로 · 작은 메모 여럿 → 기억 주제 몇 개 · Slack 연결 → 봇 자기 Slack 앱 ⛔ 남겨 둠 (Stays behind) · Telegram·WhatsApp 같은 채팅 앱 · 채팅 기록 · 모델 설정 · 옛 앱에 딸려 온 능력 · 스크립트만 돌리는 루틴 · 키와 로그인
가져오기 계획은 세 묶음으로 나옵니다. 옛 앱이 기본으로 주던 능력은 넘어오지 않고, 내가 추가한 능력만 넘어옵니다.
키와 로그인은 넘어오지 않습니다 — 붙여 넣는 글은 직접 확인 가져오기 판독기는 키·로그인·세션 파일을 건너뛰고 비밀값처럼 보이는 줄을 뺍니다. 다만 최선을 다할 뿐이라 비밀값처럼 안 보이는 비밀은 놓칠 수 있습니다. 옛 봇에게서 붙여 넣은 답은 붙여 넣은 그대로 저장됩니다. 가져오기 전에 그 답과 내보낸 폴더에서 키·토큰을 지우세요. 각 서비스는 Orca에서 다시 연결합니다.

가져온 뒤

  • 자동화는 멈춘 채로 옵니다. 옛 봇과 새 봇이 같은 일을 두 번 하지 않게, 옛 앱에서 옛 봇을 끈 뒤 새 봇에게 자동화를 켜 달라고 합니다. 옛 앱이 아직 돌고 있으면 봇이 어떤 일이 두 번 돌지 알려 줍니다.
  • 옛 봇이 쓴 말은 참고용으로 새 봇의 기억에 남되, 지시가 아닌 메모로 표시됩니다.
  • 옛 봇이 쓰던 도구는 키 없이 옵니다. 봇이 물어보면 다시 로그인합니다.
  • Slack·GitHub·Linear가 필요한 것이 있으면 봇이 연결을 권합니다. 이벤트로 시작하는 자동화는 그 연결이 붙을 때까지 기다립니다.
  • 새 봇은 옛 앱의 모델 설정이 아니라 내 Claude Code·Codex(또는 다른 지원 에이전트) 로그인으로 돕니다.
  • 이 컴퓨터에서 찾은 봇이면, 나중에 같은 옛 봇으로 가져오기를 다시 시작해 Update할 수 있습니다. 새로 생기거나 바뀐 것만 더하고, Orca에서 내가 고친 것은 지킵니다.

쓰임새 8가지와 템플릿 24종

모든 쓰임새는 같은 모양입니다: 내가 부탁(Slack·Linear·GitHub·봇 채팅·일정) → 봇이 내 컴퓨터에서 일함 → 부탁받은 곳에 보고 → 사람이 정할 곳에서 기다림. 대부분의 템플릿은 먼저 보고하고, 바꾸기 전에 묻습니다. 봇이 스스로 하는 범위는 채팅에서 넓힐 수 있습니다.

아래 예는 공식 문서의 예시 봇 Scout, 예시 저장소 acme/web, Slack 채널 #eng를 씁니다.

시작: Bug investigation 템플릿 + GitHub, 사람들이 부를 Slack.

  1. 부탁#eng에서 Maya: "@scout checkout breaks on Safari, can you look?"
  2. 봇이 하는 일새 워크트리에서 작업자가 버그를 재현하고 단계를 적은 뒤 시작점을 찾습니다. 수정 전에 묻고, 동의하면 작업자가 고치고 테스트를 돌려 내 git 로그인으로 PR을 엽니다.
  3. 돌아오는 것Slack 스레드에 원인·테스트 결과·PR.
  4. 내가 끼는 곳"Start a fix?" 질문이 Needs you에서 기다립니다. PR은 다른 PR처럼 검토합니다.

시작: Linear를 연결한 봇(템플릿 없음 — 채팅에서 설명).

  1. 부탁"ENG 팀에 새 이슈가 오면 재현 단계가 있는지 보고, 중복을 찾고, 라벨과 담당자를 제안해. 닫기 전엔 물어봐."
  2. 봇이 하는 일Linear 새 이슈 이벤트로 시작하는 자동화를 만들고, 이슈마다 설명을 읽고 중복을 찾고, 허락한 변경을 나로서 합니다.
  3. 돌아오는 것봇 채팅에 이슈마다 짧은 한 줄.
  4. 내가 끼는 곳중복 닫기처럼 묻기로 한 일은 Needs you에서 기다립니다.

시작: CI failures 템플릿 + GitHub.

  1. 부탁템플릿에 이미 "검사가 실패하면 flaky인지 진짜인지 말해 줘"가 있습니다. 채팅에서 "진짜면 고치기 전에 물어봐"를 더합니다.
  2. 봇이 하는 일실패를 읽고 설명하며 flaky인지 진짜인지 말합니다. flaky 검사 목록을 모아 매주 월요일 오전 9시에 올립니다.
  3. 돌아오는 것봇 채팅에 설명.
  4. 내가 끼는 곳진짜 실패면 Needs you에서 수정 작업자를 시작할지 묻고, 수정은 PR로 옵니다.

시작: Daily standup notes 템플릿 + GitHub·Linear(올리려면 Slack).

  1. 부탁템플릿 일정은 평일 오전 9시. 봇 패널에서 켭니다. 공유하려면 "#standup에도 올려 줘".
  2. 봇이 하는 일워크트리·PR·이슈를 보고, 어제 나와 에이전트들이 한 일과 다음 할 일을 씁니다.
  3. 돌아오는 것봇 채팅에, 부탁했으면 #standup에도 봇의 Slack 앱으로.
  4. 내가 끼는 곳틀린 것은 채팅에서 고칩니다. 배운 것은 기억에 남아 다음 날부터 반영됩니다. 일정은 봇 컴퓨터가 깨어 있을 때만 돕니다.

시작: Pull request review 템플릿 + GitHub.

  1. 부탁고른 저장소에서 누군가 내 리뷰를 요청하면 시작(템플릿 설정).
  2. 봇이 하는 일PR을 검토해 위험한 변경과 빠진 테스트를 파일·줄과 함께 적습니다.
  3. 돌아오는 것봇 채팅에 결과. 예: "#4121: 재시도 횟수가 초기화되지 않아 두 번째 장애 때 재시도가 멈춥니다."
  4. 내가 끼는 곳내가 허락할 때까지 GitHub에 댓글을 달지 않습니다. 올릴 항목을 말하면 나로서 올립니다.

시작: Release notes 템플릿 + GitHub.

  1. 부탁봇 채팅에서 "4.12 노트 초안 써 줘" (Slack이 있으면 채널에서 "@scout draft the notes for 4.12").
  2. 봇이 하는 일지난 릴리스 뒤 병합된 PR을 읽고 사용자용 노트를 새 기능·고친 것·바뀐 것 세 묶음으로 씁니다.
  3. 돌아오는 것부탁한 스레드나 채팅에 초안.
  4. 내가 끼는 곳채팅에서 문구를 고치고, 마음에 들면 changelog에 넣는 PR을 열어 달라고 하거나 직접 복사합니다.

시작: Docs upkeep 템플릿 + GitHub.

  1. 부탁템플릿 일정은 매주 수요일 오전 10시, 고른 저장소 대상.
  2. 봇이 하는 일최근 병합된 PR과 문서를 비교해, 더는 맞지 않는 쪽과 틀린 줄을 적습니다.
  3. 돌아오는 것봇 채팅에 목록.
  4. 내가 끼는 곳고칠 쪽을 고르면 작업자가 자기 워크트리에서 고쳐 PR을 엽니다.

시작: Deploy watch 템플릿 + GitHub(배포마다 실린 PR을 읽으려고).

  1. 부탁"배포용 웹훅 만들어 줘." 자동화 카드의 Copy URL로 주소를 복사해 배포 도구에 넣고, 지원하면 signing secret도 넣습니다.
  2. 봇이 하는 일도구가 호출할 때마다 실린 PR로 배포를 요약하고 실패한 배포를 표시합니다. 호출 내용은 지시가 아니라 정보로 받습니다.
  3. 돌아오는 것배포마다 봇 채팅에 요약.
  4. 내가 끼는 곳이상해 보이면 물어봅니다. 주소가 새면 Rotate key….
나머지 템플릿 16종 (위 8가지에 쓰인 것 말고)
템플릿하는 일보고 시점
Bug report intakeSlack 채널에 올라온 버그마다 재현 단계가 있는 Linear 이슈 초안을 쓰고, 승인하면 등록버그가 올라올 때
GitHub issue triage새 이슈마다 라벨·중복을 제안하고 빠진 정보를 적음이슈가 열릴 때
Support triage고른 Slack 채널의 답 없는 질문과, 이미 Linear 이슈가 있는지 적음평일 오전 9시~오후 5시, 2시간마다
Feedback digestSlack 피드백을 주제별로 묶고 인용·개수를 붙임월요일 오전 9시
Backlog cleanup오래된 이슈, 중복 의심, 담당자 없는 이슈매달 1일
Dependency updates오래되거나 취약한 패키지를 급한 순으로. 동의하면 묶음마다 PR 하나월요일 오전 9시
Security check병합된 변경에서 새어 나간 비밀값·주입(injection)·빠진 인증·위험한 기본값 확인월요일 오전 9시, PR 병합 때
Release readiness실패한 검사, 리뷰 기다리는 PR, 열린 걸림돌 짧은 목록평일 아침
Incident notes장애 채널에서 타임라인을 쓰고, 탓하지 않는 회고 초안장애 중과 뒤
On-call handoff한 주의 경보·장애 요약과 남은 후속 일금요일 오후 4시
Replies you oweSlack·Linear에서 내가 답하지 않은 질문과 하겠다고 한 일매일 오후 4시
Email digest내가 답해야 할 메일 목록. 메일은 절대 보내지 않음평일 오전 9시·오후 2시
Meeting prep회의 주제인 이슈·PR·문서를 한 메모로각 회의 15분 전
Project briefing바뀐 것, 막힌 것, 결정이 필요한 것금요일 오후 3시
Spec draftingSlack 스레드나 문서를 한 쪽짜리 명세로부탁할 때
Unreviewed agent work리뷰나 PR이 아직 없는 끝난 에이전트 작업평일 오전 9시
Workspace cleanup끝났거나 버려진 워크트리 목록. 고른 것만 지움금요일 오후 4시
내 봇에게 첫 부탁 쓰는 법 — 네 가지를 넣기
  • 언제: 일정("평일 9시마다"), 이벤트("acme/web에서 검사가 실패하면"), 또는 "지금".
  • 무엇을: 한 문장으로 일 하나.
  • 어디에 보고: 봇 채팅, Slack 채널, 또는 부탁받은 이슈·PR.
  • 무엇을 물어볼지: 행동하기 전에 나에게 물어야 할 것.
예: "acme/web에 PR이 열리면 고친 것마다 테스트가 있는지 확인해. 없는 것은 #eng에 알려 줘. GitHub에는 댓글 달지 마."
한눈에 정리
  • 봇 = 이름·목적·기억·자동화를 가진 에이전트. 한 컴퓨터의 폴더에 살고, 내 Claude Code·Codex 등으로 일합니다(1.4.265부터).
  • 사이드바 Bots 칸 + → New bot으로 처음부터 또는 템플릿 24종에서 만들고, 첫 채팅에 진짜 할 일 하나를 줍니다.
  • 결정·승인은 봇 Home의 Needs you에서 기다립니다. 코드 수정은 작업자가 자기 워크트리에서 하고 PR로 돌아옵니다.
  • 봇의 컴퓨터가 깨어 있어야 일합니다. Slack·GitHub·Linear 요청은 최대 하루 기다립니다.
  • Slack·GitHub·Linear·웹훅은 Orca 로그인과 Orca Cloud가 필요하고, Google은 내 컴퓨터에서 직접 연결합니다.
  • Who can ask에 넣은 사람은 내 권한으로 봇을 씁니다. 이벤트 자동화·웹훅은 Who can ask와 따로입니다.
  • 새 봇은 기본 Full access로 시작합니다. 다른 사람이 부르거나 바깥 글을 읽는 봇은 Ask for approval로 바꿉니다.

출처: orca.dev/docs/bots · /docs/bots/connectors · /docs/bots/import · /docs/bots/security · /docs/bots/use-cases · orca.dev/bots · orca.dev/changelog (1.4.265 · 1.4.268) — 2026-11-22 수집

APPENDIX

부록 — 사이트맵 · 플러그인 · 최근 변경 · 출처

onorca.dev 사이트가 어떻게 짜여 있는지, 어떤 플러그인이 있는지, 최근에 무엇이 바뀌었는지 정리합니다.

이 장에서 배우는 것
  • 사이트의 페이지 120개가 어떤 구역으로 나뉘는지
  • 공식·커뮤니티 플러그인 전체 목록
  • 최근 다섯 버전의 주요 변경(봇이 나온 1.4.265 포함)

사이트맵 — www.onorca.dev

사이트가 공개한 sitemap.xml(검색엔진에게 알려 주는 페이지 목록)에 등재된 URL 120개를 구역별로 묶었습니다.

구역별 페이지 수 Plugins59 Docs57 Changelog1 Enterprise1 Download · 홈2
Docs와 Plugins가 거의 전부입니다. Changelog의 버전별 상세(“Read more”) 페이지는 sitemap에 없어 세지 않았습니다.
2026-11-22에 다시 받은 사이트맵
  • 사이트 주소가 www.onorca.dev에서 orca.dev로 바뀌었습니다(옛 주소는 새 주소로 넘어갑니다). URL은 493개로 늘었습니다.
  • Docs 63쪽: 위 57쪽에 bots/ 5쪽(→ 10장)과 migrate-from-conductor 1쪽이 더해졌습니다. migrate-from-conductor는 아직 받지 않아 이 가이드에 없습니다.
  • 새 구역 /bots: 봇 소개 쪽 1개(→ 10장).
  • Plugins 425개(공식 stablyai 43개 포함): 아래 「플러그인 전체 목록」은 11-04 기준 59개 그대로이며 새로 늘어난 플러그인은 반영하지 않았습니다.
www.onorca.dev /  홈 (소개 · 기능 탭 · 사용자 후기 · FAQ)

Changelog 1

/changelog
버전별 릴리스 노트

Enterprise 1

/enterprise

Download 1

/download
Mac · Intel · Windows · Linux · iOS · Android APK

Plugins 59

/plugins
플러그인 등록/plugins/add공식 (43)/plugins/stablyai/orca-plugins/…커뮤니티 (14)/plugins/<작성자>/<저장소>

Docs 57

/docs
시작 · 일반 (15) → 1장, 3장, 8장(index), install, first-session, ways-to-run, settings, notifications, terminal, ssh, remote-servers, mobile, android-apk, activity, telemetry, troubleshooting, github-errors
model/ (5) → 2장worktrees, agents-sessions, tabs-panes-splits, quick-open, session-restore
agents/ (11) → 3장supported, claude-code, codex, codex-hot-swap, cursor-cli, glm-agent, native-chat, session-history, hibernation, hooks-memory, usage-tracking
browser/ (3) → 4장overview, profiles, design-mode
editing/ (4) → 5장file-explorer, markdown, monaco, viewers
review/ (7) → 6장diff-viewer, annotate-ai-diff, attribution, commit-push, github, jira, linear
cli/ (7) → 7장overview, reference, automations, orchestration, computer-use, skills, worktree-checkpoints
bots/ (5) → 10장 · 2026-11-22 추가(index), use-cases, connectors, import, security
recipes/ (5) → 각 장parallel-agents(1장), jump-worktrees(2장), design-mode-fix(4장), review-ai-diff(6장), remote-worktrees(8장)

헤더의 외부 링크: Discord · X · GitHub

플러그인 전체 목록

플러그인은 Orca에 테마·아이콘·언어 지원·뷰어 등을 더하는 확장입니다. Settings → Plugins에서 설치하며, 코드를 실행하는 플러그인은 설치 전에 동의를 구하고, 동의하면 컴퓨터에 대한 전체 접근 권한을 갖습니다(1.4.245 변경 내용). 이름만으로 분류했으며 각 플러그인의 상세 설명은 읽지 않았습니다.

테마 · 아이콘

midnight-themenord-themeoled-themedusk-embergithub-light-themesolarized-light-themedracula-themegruvbox-themecatppuccin-themetokyo-night-themeone-dark-pro-themerose-pine-themegithub-vscode-themeayu-themenight-owl-themevscode-default-themessolarized-terminalminimal-iconsmaterial-icons

언어 · 구문 강조

gleamprismamatlabocamljuliahaskellerlangjspnixgodotlatexvhdlvclqmltaxihttpsystemd

에디터 · 뷰어 · 도구

excalidrawspreadsheetdocximage-markupsqlite-browserrunnermultipass-recipes
vale-c/orca-tokyonightvale-c/orca-catppuccinthailoc-dev/orca-rose-pinepiter75/orca-gruvbox-material-themelkgilgamesh/orca-ayudawidwetzler/orca-cobalt2-themethailoc-dev/orca-pptx-viewermbirepinte/orca-asciidoc-viewerthailoc-dev/orca-dev-toolboxkolebayev/orca-md-layoutsenadaruc/orca-grazrupstash/box-orca-plugininsforge/orca-instabox-plugincemalkilic/lima-orca-vm-recipes

최근 변경 (Changelog — 봇 관련 두 항목은 2026-11-22에, 나머지 셋은 11-04에 읽음)

1.4.268 · 2026-11-21
봇 선택지 확대, 원격 페이지 피드백
  • Orca 봇의 에이전트로 Cursor · GitHub Copilot · Hermes 선택, 봇 그룹 채팅에 이미지 추가
  • 원격 브라우저 페이지에서도 요소를 골라 메모를 달고 복사하거나 에이전트에게 보내기(원격 호스트가 새 메모 도구를 지원해야 함)
  • Activity 카드에서 에이전트 질문에 답하기, 조정자 채팅에서 작업자 권한 요청에 답하기(페어링 서버 포함)
1.4.265 · 2026-11-19
Orca Bots, Chat의 Hermes, 브라우저 확장 패널
  • Orca Bots 출시 — 관리되는 에이전트 세션이 도구와 신분을 갖고, 봇이 나 대신 공유하며, Slack 스레드에서 봇이 무엇을 하는지 보임. 봇 연결 시 접근 경고가 더 분명해짐(→ 10장)
  • Hermes와 채팅: 새 채팅 시작, Session History에서 터미널 대화 이어 가기. Hermes 0.23.0 이상 필요, 페어링 서버는 되고 SSH 워크스페이스는 안 됨
  • 지원하는 Chrome 확장의 사이드 패널을 Orca 브라우저 옆 크기 조절 패널로 열기
1.4.246 · 2026-11-02
Automations in Chat, 폰에서 병합 충돌 해결, 개인 설정 확대
  • 자동화를 Chat 또는 Terminal로 실행하도록 고르고, 실행 기록에서 녹화된 대화를 열어 결과 검토
  • 폰에서 충돌 파일 해결 방식을 고르고 Source Control에서 병합 완료 — 데스크톱과 같은 조작
  • 데스크톱에서 “응답 필요”와 “완료” 알림을 따로 제어, 폰은 “응답 필요” 알림만 받도록 설정 가능
1.4.245 · 2026-10-30
플러그인, 백그라운드 Computer Use, 더 강해진 폰 앱
  • Settings → Plugins에서 아이콘 테마·구문 강조·커스텀 에디터 설치. 코드를 실행하는 플러그인은 동의 후 컴퓨터 전체 접근
  • 사용자가 마우스·키보드를 쓰는 동안 에이전트가 Chrome·Blender 같은 앱을 뒤에서 조작(일부 동작은 앱을 앞으로 가져와야 함)
  • 폰 앱: 11개 언어, 말하는 동안 받아쓰기 표시, 코드·표·다이어그램 가독성 개선
1.4.244 · 2026-10-29
브라우저 확장, 유연한 채팅, 더 강해진 원격 작업
  • 실험 설정을 켜면 Orca 브라우저의 로컬 프로필에 Chrome 웹 스토어 확장 설치(1Password·Bitwarden 등). 일부 확장과 광고 차단은 아직 미지원
  • 에이전트가 끝난 뒤 Claude·Codex 터미널 대화를 Chat에서 이어 가기, 채팅에서 다른 에이전트에게 인계, 대기 메시지 순서 바꾸기, Claude를 첫 메시지 이전으로 되감기
  • 원격 파일: SSH 호스트·페어링 서버의 오디오·비디오 재생, 50MB까지 텍스트 저장, 큰 폴더 스크롤 탐색, 페어링된 데스크톱에서 워크스페이스 밖 파일 편집

출처와 기준

  • 2026-11-04에 Orca 내장 브라우저로 읽은 onorca.dev 홈, Changelog, Docs 57쪽 전체, sitemap.xml
  • 2026-11-22에 Orca 내장 브라우저로 읽은 orca.dev Bots 문서 5쪽, Bots 소개 쪽, Changelog(맨 위 1.4.268), sitemap.xml — 10장과 이 부록의 봇 관련 내용의 근거. 나머지 장은 11-04 수집본 기준입니다.
  • 로컬 Orca CLI 안내서 orca skills get orca-cli (브라우저 조작 참고)
  • 설명은 위 자료를 쉬운 말로 풀어 쓴 것이며, 원문에 없는 내용은 추가하지 않았습니다. 화면 이름·단축키·옵션은 읽은 시점(약 1.4.246~1.4.247) 기준이고 이후 버전에서 바뀔 수 있습니다.
한눈에 정리
  • 사이트는 Docs(57)·Plugins(59)가 대부분이고, Docs의 각 구역이 이 가이드의 1~8장에 대응합니다. 11-22 기준으로는 주소가 orca.dev로 바뀌고 Docs 63쪽(봇 5쪽 → 10장)·Plugins 425개입니다.
  • 플러그인은 공식 43개(테마·언어·도구)와 커뮤니티 14개가 있습니다.
  • 최근에는 플러그인, 백그라운드 Computer Use, 폰 앱, 브라우저 확장, 채팅 기능이 크게 늘었고, 1.4.265(11-19)에 Orca Bots가 나왔습니다.

출처: onorca.dev/sitemap.xml, onorca.dev/changelog (2026-11-04) · orca.dev/sitemap.xml, orca.dev/changelog (2026-11-22)