Desktop이 사용자의 Node 환경을 사용하는 방식

HagiCode Desktop은 **시스템에 직접 설치한 외부 node와 npm**을 사용합니다. Desktop을 처음 실행하기 전에 Node.js를 설치하고 두 명령을 모두 시스템 PATH에서 찾을 수 있는지 확인하세요.

이 FAQ는 Desktop이 외부 Node 환경을 찾는 방법, Agent CLI 설치 위치, Node 또는 npm을 찾을 수 없을 때의 해결 방법을 설명합니다.

버전 요구 사항

Node.js 24 이상이 필요합니다(최소 요구 사항도 24입니다). npm은 Node.js와 함께 설치됩니다. 설치 방법은 Node.js 설치를 참고하세요.

Git도 직접 설치해야 합니다. 설치 가이드를 참고하세요.

Desktop이 node와 npm을 찾는 방법

Desktop은 시작할 때 시스템 PATH를 읽고, 그 안에서 node, npm, git을 찾습니다. 이는 다음을 의미합니다.

터미널에서 node --version으로 보이는 버전이 보통 Desktop이 사용하는 버전입니다.
Desktop은 사용자의 Node 환경을 사용할 뿐, 교체하거나 수정하지 않습니다.
Desktop이 이미 열려 있는 상태에서 Node.js를 설치하거나 업그레이드했다면, Desktop을 완전히 종료한 뒤 다시 시작해 새로운 PATH를 읽게 하세요.

버전 관리 도구와 PATH

macOS와 Linux에서 nvm, fnm 같은 버전 관리 도구는 대개 셸 설정 파일에서만 PATH를 설정합니다. Dock, 앱 메뉴, 바탕화면 아이콘에서 실행한 Desktop은 이 설정을 읽지 않아 node를 찾지 못할 수 있습니다. 이미 node를 실행할 수 있는 터미널에서 Desktop을 시작하거나, 시스템 수준 설치를 사용하세요.

Agent CLI 같은 관리 대상 패키지는 어디에 설치되나요

Desktop의 종속성 관리 페이지는 PATH에 있는 node와 npm을 찾아내 확인된 npm 전역 접두사(prefix)를 표시하고, 카탈로그에 나열된 CLI 패키지를 이 외부 전역 디렉터리에 설치합니다.

관리 대상 CLI마다 Desktop은 다음 순서로 실행 파일을 찾습니다.

이미 존재하는 관리 경로
npm 전역 bin 디렉터리(Windows에서는 .cmd와 .ps1 실행 스크립트 포함)
PATH

npm 미러 설정은 설치와 동기화 작업에 적용됩니다. 제거도 외부 전역 디렉터리를 대상으로 하며, 화면에서 확인을 거쳐야 합니다. 다음 명령으로 현재 전역 디렉터리를 확인할 수 있습니다.

npm prefix -g

전역 디렉터리가 관리자 권한이 필요한 위치에 있으면 설치 중 권한 오류가 발생할 수 있습니다. 이때는 npm 전역 디렉터리 설정을 참고하세요.

Node 또는 npm을 찾을 수 없다고 안내할 때는

터미널에서 node --version을 실행해 Node.js 버전이 24 이상인지 확인합니다. 이어서 npm --version을 실행해 npm을 사용할 수 있는지 확인합니다.
설치되어 있지 않거나 버전이 너무 낮다면, 먼저 Desktop 밖에서 Node.js를 설치합니다.
Desktop을 완전히 종료한 뒤 다시 시작하고, 종속성 페이지로 돌아가 새로 고침을 클릭합니다.

Desktop이 특정 CLI 패키지를 수동으로 설치하라고 안내하면 Desktop 밖의 터미널에서 안내된 명령을 실행하고, 끝난 뒤 Desktop으로 돌아와 한 번 새로 고쳐 다시 감지하게 하세요.