공식 시작 안내에서 설치 확인에 사용하는 명령은 claude --version입니다. Claude Code 공식 시작 안내를 기준으로 보면, 이 도구는 프로젝트를 저장하고 명령을 실행할 원격 맥에 직접 설치해야 합니다. 이번 주에는 원시 설치를 먼저 진행하고, 버전 확인과 환경 진단을 마친 뒤 작은 프로젝트 하나로 권한을 시험하는 것이 안전합니다.
이 글이 필요한 학습자
윈도우 컴퓨터만 있지만 macOS 환경에서 프로그래밍을 배우려는 학생에게 맞습니다.
이미 원격 맥을 받았지만 터미널과 AI 코딩 도구가 낯선 초보자도 따라 할 수 있습니다.
짧게 Claude Code를 사용해 본 뒤 장기적으로 맥 환경이 필요한지 판단하려는 학습자에게도 유용합니다.
마지막 업데이트: 2026년 9월 1일. 설치 경로, 인증, 진단 명령은 게시 시점의 Claude Code 공식 문서와 권한 안내를 기준으로 확인했습니다.
설치 위치와 세 가지 역할
Claude Code 원격 맥 설치에서 가장 먼저 정할 것은 명령을 입력하는 컴퓨터가 아니라 프로젝트가 실제로 있는 컴퓨터입니다. 원격 데스크톱 화면을 보여 주는 윈도우는 교실의 화면이고, SSH는 교실로 들어가는 입구입니다. Claude Code는 옆에서 파일을 읽고 작업을 돕는 조교에 해당합니다.
따라서 윈도우에 도구를 설치하면 원격 맥의 프로젝트를 자동으로 볼 수 없습니다. 프로젝트가 원격 맥에 있다면 Claude Code도 같은 원격 맥, 가능하면 같은 사용자 계정에 설치해야 합니다.
| 접속 방식 | 하는 일 | 설치 위치 |
|---|---|---|
| 원격 데스크톱 | 맥 화면과 터미널을 그래픽으로 조작합니다 | 도구는 원격 맥에 설치합니다 |
| SSH | 화면 없이 원격 맥의 명령줄에 들어갑니다 | 도구는 접속된 원격 맥에 설치합니다 |
| Claude Code | 프로젝트 파일을 읽고 수정 계획과 명령 실행을 돕습니다 | 프로젝트가 있는 원격 맥에 설치합니다 |
원격 맥에서 Claude Code를 쓰려면 Node.js를 먼저 설치해야 하나요?
공식 원시 설치 경로를 선택한다면 Node.js를 먼저 준비할 필요가 없습니다. 다만 다른 설치 경로를 선택하면 Node.js가 필요한 경우가 있으므로, 예전 블로그의 명령을 기본값으로 사용하지 말고 공식 설치 문서의 현재 경로를 확인해야 합니다.
첫 접속과 학습 공간
먼저 원격 데스크톱의 터미널을 열거나, Apple 공식 SSH 원격 로그인 안내에 따라 SSH로 접속합니다. 두 방식 모두 같은 원격 계정으로 들어갔는지 확인해야 합니다.
whoami
pwd
mkdir -p ~/study/claude-first-project
cd ~/study/claude-first-project
touch permission-check.txt
ls -la
whoami는 현재 학생의 계정을 보여 줍니다. pwd는 지금 서 있는 책상, 즉 작업 디렉터리의 위치를 알려 줍니다. 마지막 목록에 permission-check.txt가 보이면 해당 폴더에 쓸 수 있다는 뜻입니다.
다음 조건이면 설치를 멈추고 관리자에게 문의해야 합니다.
whoami가 본인이 예상한 계정과 다릅니다.- 프로젝트가 다른 사람의 공유 폴더나 시스템 폴더에 있습니다.
- 파일을 만들 때 권한 거부가 표시됩니다.
- 그래픽 화면과 SSH 터미널에서 서로 다른 홈 폴더가 나타납니다.
학습용 파일은 개인 홈 폴더 아래에 두는 편이 좋습니다. 학교 장비의 관리 제한을 끄거나, 다른 사람의 계정을 사용하거나, 공유 폴더에 비밀 정보를 저장해서는 안 됩니다.
주의: 원격 맥의 프로젝트와 윈도우의 다운로드 폴더는 기본적으로 같은 공간이 아닙니다. 파일이 어디에 있는지 먼저 pwd와 ls로 확인한 뒤 Claude Code를 실행해야 합니다.
공식 원시 설치와 오류 확인
현재 공식 문서가 안내하는 원시 설치를 우선 사용합니다. 설치 명령을 복사하기 전 주소가 공식 문서의 주소와 일치하는지 확인합니다. 포럼, 영상 설명란, 파일 공유 서비스에서 받은 정체불명의 스크립트는 실행하지 않습니다.
curl -fsSL https://claude.ai/install.sh | bash
이 명령은 반드시 공식 시작 문서의 현재 내용과 대조한 뒤 실행해야 합니다. 설치가 끝났다는 문장만 보고 성공으로 판단하지 말고, 새 터미널을 열어 명령 경로를 다시 읽습니다.
claude --version
claude doctor
claude --version은 실행 파일이 발견되는지 확인합니다. claude doctor는 환경 문제를 진단하는 공식 명령입니다. 공식 명령줄 참고서에서 게시 시점의 명령과 출력 항목을 다시 확인할 수 있습니다.
| 증상 | 먼저 확인할 곳 | 다음 조치 |
|---|---|---|
| 명령을 찾을 수 없음 | 셸 환경과 새 터미널 | 터미널을 다시 열고 설치 경로를 확인합니다 |
| 내려받기 실패 | 네트워크와 프록시 | 공식 프록시 설정 안내를 확인합니다 |
| 권한 거부 | 현재 폴더와 사용자 | 개인 폴더로 이동하고 관리자 권한 명령은 임의로 사용하지 않습니다 |
| 진단 오류 | 환경 진단 결과 | 오류 문구를 기록한 뒤 공식 문서 기준으로 하나씩 수정합니다 |
Homebrew는 선택 사항입니다. 이미 익숙한 학습자에게는 편할 수 있지만, 초보자의 첫 설치에서는 여러 경로를 동시에 시도하지 않는 것이 낫습니다. 한 경로가 실패했다고 곧바로 다른 명령을 섞으면 어느 단계에서 문제가 생겼는지 알기 어려워집니다.
브라우저 인증과 계정 보호
설치가 확인되면 프로젝트 폴더에서 실행합니다.
cd ~/study/claude-first-project
claude
화면에 인증 안내가 나오면 공식 로그인 페이지를 사용합니다. 원격 맥에 브라우저가 자동으로 열리지 않아도 당황할 필요는 없습니다. 터미널에 표시된 공식 주소를 확인한 뒤, 본인이 제어하는 브라우저에서 주소를 열고 인증을 완료합니다. 주소가 예상과 다르거나 출처를 확인할 수 없으면 진행하지 않습니다.
계정 종류와 사용 자격은 게시 시점의 공식 안내를 따라야 합니다. 로그인 방식이 바뀌었을 가능성이 있으면 공식 인증 안내를 다시 엽니다. 원격 환경의 신원, 권한, 접근 통제는 공식 권한 문서를 기준으로 확인합니다.
브라우저 인증 화면이 자동으로 돌아오지 않으면 어떻게 하나요?
브라우저에서 인증을 끝낸 뒤 터미널으로 돌아가 대기 중인 안내를 확인합니다. 다시 로그인하라는 메시지가 나오면 새 주소가 공식 주소인지 먼저 검토합니다. API 키를 작업 파일, 채팅 기록, 공개 저장소에 붙여 넣거나 환경 파일을 공유해서는 안 됩니다.
버릴 수 있는 프로젝트에서 첫 작업
처음부터 실제 과제나 중요한 저장소를 열지 않습니다. 다음처럼 파일 세 개만 있는 연습 폴더를 만듭니다.
cd ~/study/claude-first-project
printf '# 첫 연습\n' > README.md
printf 'print("hello")\n' > hello.py
printf '이 파일은 설명용입니다.\n' > note.txt
claude
첫 요청은 파일을 바꾸라는 명령이 아니라 구조 설명으로 시작합니다. Claude Code가 README.md, hello.py, note.txt를 읽고 각각의 역할을 설명하게 합니다. 그다음 수정 계획을 먼저 제시하도록 요청하고, 계획이 맞을 때만 제한된 파일 편집을 승인합니다.
읽기, 파일 수정, 명령 실행은 서로 다른 권한입니다. 특히 셸 명령은 파일 삭제나 설정 변경으로 이어질 수 있으므로, 처음부터 제한 없는 자동 실행을 허용하지 않습니다. 학생은 명령의 목적과 영향을 이해하지 못한 상태에서 승인해서는 안 됩니다.
검증은 세 가지 중 하나로 합니다.
git diff로 실제 변경 내용을 확인합니다.python3 hello.py로 실행 결과를 확인합니다.- 수업에서 제공한 테스트를 실행해 예상 결과와 비교합니다.
AI가 “완료했습니다”라고 답한 것만으로 성공 처리하지 않습니다. 코드 차이, 실행 결과, 테스트 통과 여부 중 하나를 직접 확인해야 합니다.
Claude Code가 원격 맥의 프로젝트를 직접 수정할 수 있나요?
가능하지만 현재 작업 폴더와 승인된 권한에 한정됩니다. 프로젝트가 원격 맥에 있고 Claude Code를 그 폴더에서 실행하면 파일을 읽고 수정할 수 있습니다. 다만 수정 전 계획을 확인하고, 중요한 파일이 아닌 복사본에서 시험하는 것이 안전합니다.
종료 후 보관과 사용 기간 판단
첫 작업이 끝나면 터미널을 닫기 전에 파일이 남아 있는지 확인합니다.
pwd
ls -la
git status
프로젝트가 개인 폴더나 본인 저장소에 보이는지 확인합니다. 세션을 종료하는 것과 파일을 삭제하는 것은 다른 일입니다. 그래도 원격 환경의 초기화 정책에 따라 파일이 사라질 수 있으므로, 중요한 학습 결과는 개인 저장소나 별도 백업 위치에 보관합니다.
원시 설치와 다른 설치 경로는 업데이트 방식이 다를 수 있습니다. 업데이트 명령을 예전 글에서 가져오지 말고, 현재 공식 문서의 업데이트 항목을 다시 확인합니다.
현재 접속 환경을 계속 쓸지 결정할 때는 다음 표를 활용합니다.
| 상황 | 선택 | 판단 근거 |
|---|---|---|
| 특정 수업이나 짧은 실습만 필요합니다 | 단기 원격 맥 사용 | 구매 전에 실제 접속과 작업 흐름을 검증할 수 있습니다 |
| 여러 주 동안 같은 프로젝트를 계속 개발합니다 | 원격 환경 유지 검토 | 파일 보관, 접속 안정성, 비용을 학습 기간과 함께 비교합니다 |
| 터미널과 파이썬 기초도 아직 낯섭니다 | 유료 도구 사용을 잠시 보류 | 먼저 기본 명령과 코드 읽기를 익혀야 AI 승인 실수를 줄일 수 있습니다 |
| 물리 장치나 로컬 주변 기기가 필요합니다 | 본인 맥 또는 다른 환경 검토 | 원격 접속만으로 해결되지 않는 요구입니다 |
원격 맥을 처음 준비하는 과정에서 연결 방식이 막힌다면 윈도우에서 원격 맥에 접속하는 방법을 함께 확인할 수 있습니다. 학습 파일을 어디에 둘지 고민된다면 먼저 개인 폴더와 버전 관리 기준을 세우고, NodeMini의 원격 맥 학습 환경 선택 안내에서 필요한 사용 기간과 접속 방식을 비교하는 편이 좋습니다.
이미 연결할 맥이 없다면 NodeMini의 원격 맥 이용 방식을 살펴볼 수 있습니다. 반대로 매일 장시간 같은 프로젝트를 실행하거나 물리 아이폰 연결이 반드시 필요한 경우에는 단기 임대보다 직접 장비를 준비하는 편이 맞을 수 있습니다. 현재 학교 컴퓨터만 사용하는 방식은 설치 권한이 부족하고, 파일 위치가 분리되며, 접속이 끊길 때 작업 흐름이 멈추는 단점이 있습니다. 이런 조건에서 Claude Code를 잠시 시험하거나 수업 기간에만 macOS 개발 환경이 필요하다면, 원격 맥을 먼저 빌려 실제 프로젝트와 인증 과정을 확인한 뒤 장기 결정을 내리는 것이 낭비를 줄이는 방법입니다.