Orca 설치 방법과 기본 설정

Orca는 Codex, Claude Code, Cursor CLI 같은 여러 AI 코딩 에이전트를 한곳에서 관리하는 개발 도구입니다.

Orca의 개념과 주요 특징을 살펴봤다면 이제 직접 설치해볼 차례입니다. 이번 글에서는 macOS, Windows와 Linux에서 Orca를 설치하고 Codex·Claude Code를 연결하는 방법, 설치 후 처음 확인할 기본 기능을 간단히 정리합니다.

설치를 마친 뒤에는 Orca 사용법: Codex·Claude Code 병렬 실행하기에서 worktree를 만들고 여러 에이전트의 결과를 비교하는 과정을 따라 할 수 있습니다.

설치 전에 준비할 것

Orca를 사용하려면 다음 항목이 필요합니다.

Git이 설치된 macOS, Windows 또는 Linux
작업할 로컬 Git 저장소
Codex나 Claude Code 같은 CLI 코딩 에이전트
각 에이전트의 로그인 또는 구독

Orca 자체가 AI 모델이나 사용권을 제공하지는 않습니다. 실제 코드 분석과 수정은 설치된 CLI가 담당하고, Orca는 작업 공간과 터미널, 브라우저, 변경 사항을 관리합니다.

처음에는 중요한 프로젝트보다 변경 사항을 되돌리기 쉬운 테스트 저장소에서 시작하는 편이 좋습니다.

macOS에 Orca 설치하기

macOS에서는 Homebrew로 설치할 수 있습니다.

brew install --cask stablyai/orca/orca

새로운 안정 버전으로 업데이트할 때는 다음 명령을 사용합니다.

brew upgrade --cask orca

Homebrew를 사용하지 않는다면 Apple Silicon 또는 Intel Mac에 맞는 DMG 파일을 내려받아 설치할 수 있습니다.

Orca는 서명되고 공증된 앱이지만 첫 실행 시 macOS가 실행 여부를 다시 확인할 수 있습니다. 다운로드한 앱이 맞는지 확인한 뒤 실행하면 됩니다.

Windows와 Linux에 설치하기

Windows에서는 Windows 10/11용 x64 설치 파일을 제공합니다. 설치 후 기본 터미널은 Settings → Terminal에서 PowerShell 또는 CMD로 설정할 수 있습니다.

Linux에서는 AppImage와 .deb 패키지를 제공합니다. 사용하는 배포판에 맞는 파일을 선택하면 됩니다.

운영체제별 최신 설치 파일은 Orca 공식 다운로드에서 받을 수 있습니다. 이전 버전이나 개별 설치 파일이 필요하다면 GitHub Releases를 확인하세요.

설치 방식과 지원 환경은 빠르게 바뀔 수 있으므로 실제 설치 전에는 Orca 공식 설치 문서를 함께 확인하는 것이 좋습니다.

첫 실행에서 설정 가져오기

Orca를 처음 열면 로컬 저장소를 추가하기 위해 홈 디렉터리 접근 권한을 요청합니다.

기존 설정이 있다면 다음 항목을 가져올 수 있습니다.

~/.codex의 Codex 계정과 설정
~/.claude의 Claude Code 계정과 설정
Ghostty 터미널 설정

가져오기를 마치면 비어 있는 시작 화면이 나타납니다. 여기에서 첫 저장소를 추가할 수 있습니다.

Orca가 한국어로 표시되지 않는다면 Settings → Appearance → Language에서 한국어를 선택할 수 있습니다.

Codex와 Claude Code 연결 확인하기

Orca를 설치하기 전에 사용할 CLI를 각각 한 번 실행하고 로그인해두는 것이 좋습니다.

codex

claude

Codex는 기존 ~/.codex의 계정과 인증 정보를 사용합니다. Claude Code는 ~/.claude 설정을 자동으로 인식합니다.

Orca에서 에이전트를 확인하려면 Settings → Agents를 엽니다. 설치된 CLI가 정상적으로 감지됐다면 새 터미널의 에이전트 선택 목록에 표시됩니다.

목록에 나타나지 않는다면 Orca 터미널에서 해당 명령을 직접 실행해보세요. 여기에서도 실행되지 않으면 Orca 설정보다 CLI 설치나 로그인, PATH 문제일 가능성이 큽니다.

각 에이전트의 계정과 사용량 연동은 Codex in Orca와 Claude Code in Orca에서 확인할 수 있습니다.

저장소와 worktree

사이드바의 Add Repo를 선택하면 로컬 Git 저장소를 Orca에 추가할 수 있습니다. Orca는 저장소의 Git 상태를 읽고 기본 브랜치를 기준으로 사용합니다.

저장소 이름 옆의 + 버튼을 누르면 새로운 worktree를 만들 수 있습니다. Git 워크트리(Work Tree)는 같은 저장소의 여러 브랜치를 서로 다른 디렉터리에서 동시에 작업하게 해주는 Git 기능입니다.

Orca에서는 기능이나 버그마다 worktree를 만들고 그 안에서 에이전트와 터미널, 브라우저를 실행합니다. 이번 글에서는 설치 후 확인할 화면 구성까지만 간단히 살펴봅니다.

설치 후 확인할 기본 기능

Orca를 실행했다면 다음 영역을 먼저 확인해보세요.

에이전트 터미널

Worktree 안에서 Codex, Claude Code, Cursor CLI 등 설치된 에이전트를 선택해 실행하는 영역입니다. 일반 셸 터미널도 열 수 있고 화면을 좌우나 상하로 나눌 수 있습니다.

에이전트가 지원하는 상태 신호에 따라 작업 중, 입력 대기와 유휴 상태가 사이드바에 표시됩니다. 에이전트가 종료되면 Restart 버튼으로 같은 작업 디렉터리에서 다시 실행할 수 있습니다.

코드와 diff

파일 탐색기와 편집기에서 worktree의 코드를 확인할 수 있습니다. Diff 화면에서는 기준 브랜치와 비교해 어떤 파일과 코드가 변경됐는지 살펴볼 수 있습니다.

AI가 작업을 완료했다고 표시해도 diff는 직접 검토해야 합니다. Orca는 결과를 정리해 보여주지만 코드가 올바른지 대신 판단해주는 도구는 아닙니다.

내장 브라우저

Worktree마다 Chromium 기반 브라우저를 열 수 있습니다. 개발 서버의 화면을 확인하고 콘솔과 네트워크 상태를 살펴보거나, Design Mode로 UI 요소를 에이전트에게 전달할 수 있습니다.

브라우저 탭도 worktree에 연결되므로 다른 작업으로 이동했다가 돌아왔을 때 이전 화면을 이어서 확인할 수 있습니다.

GitHub와 작업 상태

GitHub를 연결하면 이슈와 PR, Actions 검사 상태를 Orca 안에서 확인할 수 있습니다. Worktree에서 변경 사항을 commit하고 push하는 작업도 이어갈 수 있습니다.

처음 설치한 직후에는 GitHub 연결까지 모두 설정할 필요는 없습니다. 로컬 저장소와 에이전트가 정상적으로 열리는지 먼저 확인한 뒤 필요한 통합을 추가하는 편이 간단합니다.

에이전트 권한 설정 확인하기

설치 후 가장 먼저 확인할 설정은 Settings → Agents → Agent Permissions입니다.

Orca는 일부 에이전트가 매번 승인을 기다리지 않고 작업하도록 자동 실행 옵션을 설정할 수 있습니다. Worktree에서 자유롭게 수정한 뒤 diff를 선택하거나 버린다는 사용 방식을 고려한 설정입니다.

하지만 Git worktree는 코드 변경을 분리할 뿐 운영체제 전체를 격리하는 보안 샌드박스는 아닙니다. 에이전트는 설정에 따라 파일을 읽거나 셸 명령과 네트워크 요청을 실행할 수 있습니다.

처음에는 Manual 권한으로 시작하고, 테스트 저장소에서 어떤 명령을 실행하는지 확인한 뒤 자동 승인 범위를 조정하는 편이 안전합니다.

업데이트 채널 선택하기

Orca는 기본적으로 안정 버전을 자동으로 업데이트합니다. 새로운 기능을 먼저 사용하고 싶다면 RC 버전을 설치할 수도 있지만 업데이트가 잦고 예상하지 못한 문제가 생길 수 있습니다.

처음 사용하는 경우에는 안정 채널을 유지하는 편이 좋습니다. 이전 버전이 필요할 때는 GitHub Releases에서 내려받을 수 있습니다.

에이전트가 보이지 않을 때

Codex나 Claude Code가 목록에 나타나지 않는다면 다음 순서로 확인합니다.

Orca 터미널에서 CLI 명령을 직접 실행합니다.
로그인 또는 인증 오류가 없는지 확인합니다.
Settings → Agents에서 실행 경로를 확인합니다.
Orca가 사용하는 PATH에 CLI 위치가 포함됐는지 확인합니다.
에이전트 터미널의 Restart 버튼으로 다시 실행합니다.

Worktree 생성이 실패한다면 기준 브랜치를 가져오지 못했을 수 있습니다.

git fetch origin

같은 브랜치를 사용하는 worktree가 이미 존재하는지도 확인해야 합니다. 더 자세한 해결 방법은 Orca Troubleshooting에 정리되어 있습니다.

마무리

Orca 설치는 일반적인 데스크톱 앱과 크게 다르지 않습니다. 운영체제에 맞는 앱을 설치하고 기존 Codex와 Claude Code 설정을 가져온 뒤 로컬 저장소를 추가하면 기본 준비가 끝납니다.

설치 후에는 에이전트가 정상적으로 감지되는지와 권한 설정을 먼저 확인하세요. 그다음 저장소, worktree, 터미널, diff와 브라우저의 위치를 살펴보면 됩니다.

이제 Orca 사용법 글로 이어서 실제 worktree 두 개를 만들고, Codex와 Claude Code에 같은 작업을 맡긴 뒤 브라우저 검증과 diff 비교, commit까지 진행해보세요.

자주 묻는 질문

Orca는 무료인가요?

Orca는 오픈소스로 공개되어 있지만 Codex와 Claude Code 등의 구독이나 API 비용은 별도입니다. 원격 서버나 클라우드 환경을 사용한다면 해당 비용도 사용자가 부담합니다.

Codex와 Claude Code를 미리 설치해야 하나요?

네. 사용할 CLI를 별도로 설치하고 한 번 로그인해야 합니다. Orca는 로컬에 저장된 인증 정보와 실행 파일을 감지해 에이전트를 시작합니다.

GitHub 저장소가 꼭 필요한가요?

로컬 Git 저장소만으로도 Orca를 사용할 수 있습니다. 원격으로 push하거나 PR과 Actions를 확인하려면 GitHub 등의 원격 저장소가 필요합니다.

Windows에서도 사용할 수 있나요?

Windows 10/11용 설치 파일을 제공하며 PowerShell이나 CMD를 기본 셸로 선택할 수 있습니다. Codex는 Windows 호스트 또는 WSL 환경에서 실행할 수 있습니다.

Worktree는 보안 샌드박스인가요?

아닙니다. Worktree는 코드 변경을 다른 디렉터리와 브랜치로 분리하지만 에이전트의 시스템 권한까지 완전히 격리하지는 않습니다.

목차