[Orca] Orca IDE에서 WSL 프로젝트 연결하기

Windows에 설치한 Orca IDE에서 WSL의 Linux 파일 시스템에 있는 프로젝트를 여는 방법을 정리합니다.

이 글에서는 WSL 배포판이 Ubuntu-24.04이고, 프로젝트가 다음 위치에 있다고 가정합니다.

/home/user/projects/my-project

Windows에서는 같은 폴더에 다음 UNC 경로로 접근할 수 있습니다.

\\wsl.localhost\Ubuntu-24.04\home\user\projects\my-project

Orca의 호스트 선택 화면에서는 Local Windows를 유지한 상태로 WSL 경로를 선택하면 됩니다. Orca 공식 문서에 따르면 \\wsl.localhost\... 경로의 프로젝트는 WSL 파일 시스템에 있는 프로젝트로 인식되며, 터미널을 열 때 해당 WSL 배포판을 통해 실행됩니다.

WSL 프로젝트 경로 확인

WSL 터미널에서 프로젝트 폴더로 이동한 뒤 현재 경로를 확인합니다.

cd ~/projects/my-project
pwd

출력 예시는 다음과 같습니다.

/home/user/projects/my-project

WSL 배포판 이름은 Windows PowerShell에서 확인할 수 있습니다.

wsl -l -v

출력 예시:

  NAME            STATE           VERSION
* Ubuntu-24.04    Running         2

Linux 경로와 배포판 이름을 조합하면 Windows에서 사용할 경로는 다음과 같습니다.

\\wsl.localhost\Ubuntu-24.04\home\user\projects\my-project

Windows 탐색기 주소창에 이 경로를 입력했을 때 프로젝트 폴더가 보이면 Orca에서도 같은 경로를 선택할 수 있습니다.

WSL 터미널의 현재 폴더를 Windows 탐색기로 바로 열 수도 있습니다.

explorer.exe .

Orca에 프로젝트 추가

Orca에서 프로젝트 추가 버튼을 누르면 다음과 같은 화면이 나타납니다.

이 화면에서는 다음과 같이 진행합니다.

• 호스트는 Local Windows로 유지합니다.
• 폴더 찾아보기를 선택합니다.
• 폴더 선택 창의 주소창에 WSL UNC 경로를 입력합니다.
• 프로젝트로 사용할 폴더를 선택합니다.

입력할 경로 예시:

\\wsl.localhost\Ubuntu-24.04\home\user\projects\my-project

Local Windows를 유지하는 이유는 Orca 데스크톱 애플리케이션이 Windows에서 실행되고 있기 때문입니다. 선택한 폴더가 \\wsl.localhost\... 형식이면 Orca가 해당 경로를 WSL 파일 시스템으로 처리합니다.

Git 저장소가 없어도 사용할 수 있는가

Git 저장소가 없는 일반 폴더도 Orca 프로젝트로 추가할 수 있습니다.

프로젝트 추가 화면의 폴더 찾아보기는 다음과 같은 대상을 열 수 있습니다.

• 일반 로컬 프로젝트 폴더
• Git 저장소
• 여러 Git 저장소가 들어 있는 상위 폴더

따라서 선택한 폴더에 .git 디렉터리가 없어도 파일 편집, 터미널 실행, 에이전트 사용 같은 일반 작업은 가능합니다.

다만 Git 저장소가 아닐 때는 다음 기능을 사용할 수 없습니다.

• Git 브랜치 관리
• Git worktree 생성
• 변경 사항 diff 확인
• commit과 push
• Git 기반 리뷰 작업

Git 기능이 필요해진 경우에는 WSL 터미널에서 프로젝트를 Git 저장소로 초기화할 수 있습니다.

cd ~/projects/my-project
git init

Git을 사용하지 않을 프로젝트라면 git init을 실행할 필요가 없습니다.

Orca의 주요 병렬 작업 기능은 Git worktree를 기반으로 동작합니다. 일반 폴더도 열 수 있지만, 브랜치별 작업 공간 생성과 변경 사항 비교 같은 기능을 사용하려면 Git 저장소가 필요합니다.

Orca 터미널이 WSL에서 실행되는지 확인

프로젝트를 추가한 뒤 Orca 터미널을 열고 다음 명령을 실행합니다.

pwd
uname -a
cat /etc/os-release

정상적으로 WSL에서 실행된다면 pwd 결과가 Windows 경로가 아니라 Linux 경로로 표시됩니다.

/home/user/projects/my-project

운영체제 정보에도 Ubuntu가 표시되어야 합니다.

cat /etc/os-release

Orca 공식 문서에 따르면 Windows에서 \\wsl.localhost\... 경로의 프로젝트를 열면 Orca는 다음과 같은 방식으로 해당 배포판의 셸을 실행합니다.

wsl.exe -d <배포판 이름>

예를 들어 프로젝트가 Ubuntu-24.04에 있다면 해당 배포판을 통해 터미널이 실행됩니다.

기본 터미널을 WSL로 설정

Windows에서 Orca의 기본 셸은 PowerShell, 명령 프롬프트 또는 WSL 중에서 선택할 수 있습니다.

Orca 설정에서 다음 항목을 확인합니다.

Settings
→ Terminal
→ Default shell
→ WSL

Orca는 Windows에서 wsl.exe --status가 정상적으로 실행되면 WSL을 터미널 선택 항목으로 제공합니다.

기본 셸을 WSL로 지정하지 않아도 \\wsl.localhost\... 프로젝트에서는 해당 배포판을 통해 터미널이 실행될 수 있습니다. 다만 새 터미널의 기본 동작을 일관되게 유지하려면 WSL을 기본 셸로 설정하는 것이 편리합니다.

WSL 안에 개발 도구 설치

프로젝트 파일이 WSL에 있으면 프로젝트에서 사용하는 개발 도구도 WSL 안에 설치하는 것이 좋습니다.

Go 프로젝트라면 Orca 터미널에서 다음 명령을 확인합니다.

go version
which go
git --version
which git

정상 출력 예시:

go version go1.26.1 linux/amd64
/usr/local/go/bin/go
git version 2.x.x
/usr/bin/git

Windows에 Go나 Git이 설치되어 있어도 WSL 터미널에서는 별개의 프로그램으로 취급됩니다. Orca가 WSL 셸에서 명령을 실행한다면 WSL 배포판 내부에 설치된 Go와 Git을 사용합니다.

Codex 같은 CLI 에이전트를 WSL에서 실행하려는 경우에도 대상 WSL 배포판 안에 해당 CLI가 설치되어 있어야 합니다.

which codex
codex --version

권장 프로젝트 위치

WSL에서 빌드하고 실행할 프로젝트는 Linux 파일 시스템 아래에 두는 것이 좋습니다.

/home/user/projects/my-project

Windows 드라이브를 WSL에서 마운트한 다음 위치에도 프로젝트를 둘 수 있습니다.

/mnt/c/projects/my-project

하지만 Linux 도구를 중심으로 개발한다면 /home/... 아래에 두는 편이 파일 입출력, 파일 감시, 권한 처리와 Linux 도구 호환성 측면에서 더 적합합니다.

권장 구성은 다음과 같습니다.

Windows
└── Orca IDE

WSL Ubuntu-24.04
└── /home/user/projects/my-project
    ├── 소스 파일
    ├── 설정 파일
    └── .git                 # Git을 사용할 때만 존재

Orca에서 선택할 Windows 경로:

\\wsl.localhost\Ubuntu-24.04\home\user\projects\my-project

Orca 터미널에서 확인되는 Linux 경로:

/home/user/projects/my-project

연결되지 않을 때 확인할 사항

먼저 PowerShell에서 WSL 상태를 확인합니다.

wsl --status
wsl -l -v

배포판이 중지되어 있다면 실행합니다.

wsl -d Ubuntu-24.04

Windows 탐색기에서 다음 경로가 열리는지도 확인합니다.

\\wsl.localhost\Ubuntu-24.04

프로젝트 경로가 보이지 않는다면 다음 항목을 확인합니다.

• Ubuntu-24.04가 실제 배포판 이름과 같은지 확인합니다.
• /home/user의 user가 실제 WSL 사용자 이름인지 확인합니다.
• 프로젝트 폴더가 실제로 존재하는지 확인합니다.
• WSL 배포판이 정상 실행되는지 확인합니다.
• Orca를 다시 시작한 뒤 폴더를 다시 선택합니다.

WSL 사용자 이름은 WSL 터미널에서 확인할 수 있습니다.

whoami

프로젝트 폴더의 실제 위치는 다음 명령으로 확인합니다.

realpath ~/projects/my-project

정리

Windows용 Orca IDE에서 WSL 프로젝트를 열 때는 호스트를 Local Windows로 유지하고 폴더 찾아보기에서 \\wsl.localhost\... 경로를 선택하면 됩니다.

Git 저장소가 아니어도 일반 폴더 프로젝트로 추가할 수 있습니다. 다만 Orca의 Git worktree, 브랜치, diff, commit, push 기능을 사용하려면 해당 폴더가 Git 저장소여야 합니다.

연결 후 Orca 터미널에서 pwd, uname -a, cat /etc/os-release를 실행하면 WSL 배포판과 프로젝트 경로가 올바르게 연결되었는지 확인할 수 있습니다.

참고 자료

• Orca 공식 Terminal 문서: https://www.onorca.dev/docs/terminal
• Orca 공식 Worktrees 문서: https://www.onorca.dev/docs/model/worktrees
• Orca 공식 첫 세션 안내: https://www.onorca.dev/docs/first-session
• Orca 공식 Remote Worktrees 문서: https://www.onorca.dev/docs/recipes/remote-worktrees
• Orca 공식 Codex 연동 문서: https://www.onorca.dev/docs/agents/codex
• Microsoft WSL 파일 시스템 안내: https://learn.microsoft.com/windows/wsl/filesystems