CLI는 설치됐는데 에이전트가 프로젝트를 못 찾는다면 무엇을 다시 설치해야 할까요. 바로 재설치하기 전에 어느 단계까지 되는지 나눠 보는 편이 빠릅니다. 터미널에서 명령을 찾는 문제와 에디터 연결 문제는 해결할 곳이 다릅니다.
아래 명령은 2026년 9월 22일 공식 CLI 레퍼런스에서 확인한 구문입니다. 실험 단계 도구이므로 설치된 버전의 help와 차이가 있으면 그 차이부터 기록합니다. 이 글에는 특정 환경에서 실행했다고 주장하는 출력 로그를 싣지 않았습니다.
터미널이 어느 실행 파일을 찾는지 본다
unity --version
unity --help
첫 명령부터 찾지 못한다면 에디터 패키지를 고칠 단계가 아닙니다. 설치 경로와 PATH, 새 터미널에서 인식되는지를 확인합니다. macOS·Linux에서는 command -v unity, PowerShell에서는 Get-Command unity로 실제 선택된 실행 파일을 확인할 수 있습니다.
수동 설치와 패키지 관리자 설치가 함께 있으면 생각한 버전과 실행되는 버전이 다를 수 있습니다. 한쪽을 업데이트했는데 출력 버전이 그대로라면 경로부터 봅니다. 에이전트가 실행되는 프로세스는 터미널과 다른 환경 변수를 가질 수도 있습니다.
설치된 에디터와 연결된 에디터는 다르다
unity editors -i
unity status
unity doctor
editors는 설치된 에디터를 확인하는 데, status는 연결된 에디터 상태를 보는 데 사용합니다. 에디터가 설치되어 있다는 사실만으로 특정 프로젝트와 연결되었다고 판단하지 않습니다. status 결과의 프로젝트 경로와 Editor 버전이 의도한 대상인지 봅니다.
프로젝트를 여러 개 열어 두었다면 특히 중요합니다. “Player를 수정해줘”라는 요청 전에 어떤 프로젝트의 Player인지 확정해야 합니다. 첫 연결 시험에서는 테스트 프로젝트 하나만 열어 두면 대상을 헷갈릴 여지가 줄어듭니다.
doctor 결과는 진단 자료로 남길 수 있지만 공유하기 전에 사용자 경로, 계정·조직 정보 등 공개할 필요 없는 내용을 확인합니다. 명령 성공 여부뿐 아니라 실행 시각과 오류 메시지도 같이 남기세요.
Pipeline 쪽 컴파일이 끝났는지 확인한다
Pipeline 패키지 문서의 설치·호환성 조건과 프로젝트 상태를 비교합니다. 설치 직후의 패키지 해결과 컴파일이 끝났는지, Console에 오류가 있는지 봅니다.
패키지 이름이 manifest에 있다는 것과 정상 로드되었다는 것은 다릅니다. 프로젝트에 기존 컴파일 오류가 있으면 연결 기능도 예상대로 준비되지 않을 수 있습니다. 같은 요청을 반복하기보다 먼저 Editor 안의 오류를 좁힙니다.
터미널에서 되면 에이전트 연결을 따로 본다
CLI를 직접 호출할 수 있는 구성인지, MCP 서버를 사용하는 구성인지 확인합니다. 플러그인이 설치되었다는 표시만으로 실행 파일 경로나 서버 연결까지 정상이라고 볼 수는 없습니다.
처음에는 수정 없이 프로젝트 이름이나 씬 목록처럼 읽기 작업을 요청합니다. 에이전트가 설명만 생성한 것인지 실제 도구 응답을 받았는지 구분하세요. 직접 명령은 성공하는데 에이전트에서 실패한다면 플러그인 활성 상태, 프로세스 재시작 필요 여부, 도구 권한과 환경 차이를 확인합니다.
오류를 보고할 때는 아래 다섯 가지가 있으면 재현에 도움이 됩니다.
- OS와 CLI 버전, 실행 파일 경로
- Editor와 Pipeline 패키지 버전
- 같은 명령의 터미널 성공·실패 여부
- 연결된 프로젝트 경로와 실제 의도한 프로젝트
- 최초 오류 메시지와 그 직전에 한 작업
연결이 확인된 다음에는 값을 하나 바꾸고 저장 후 다시 읽는 작은 작업을 해보세요. 코드 수정과 빌드까지 한 번에 요청하면 어디서 문제가 시작됐는지 알기 어렵습니다.