클로드 코드 설치 방법: 윈도우·맥 설정부터 로그인과 오류 해결까지

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

클로드 코드(Claude Code)는 프로젝트의 파일을 읽고 코드를 설명하거나 수정하는 AI 개발 도구입니다. 터미널에서 자연어로 작업을 요청할 수 있으며, 설치 후 계정에 로그인하면 작업 폴더 안의 파일을 대상으로 대화를 시작할 수 있습니다.

처음 사용할 때는 프로그램 설치, 계정 로그인, 프로젝트 실행을 나누어 보면 이해하기 쉽습니다. 오늘은 윈도우와 맥의 클로드 코드 설치 방법부터 첫 실행, 자주 만나는 오류까지 살펴보겠습니다.

클로드 코드 설치 전에 필요한 환경

터미널용 Claude Code는 macOS 13 이상과 Windows 10 1809 이상을 지원하며 메모리는 4GB 이상이 필요합니다. 인터넷 연결도 필요합니다. 회사 컴퓨터에서는 조직에서 허용하는 설치 방식과 AI 서비스 이용 기준이 적용될 수 있습니다.

로그인에는 Pro·Max·Team·Enterprise 구독 또는 Console 계정 등을 사용합니다. 구독으로 이용하는 방식과 API 사용량에 따라 결제하는 방식은 다르므로, 이미 사용하는 팀 계정이 있다면 해당 계정의 이용 권한을 확인하면 됩니다.

터미널은 글자로 명령어를 입력하는 프로그램입니다. 맥에서는 터미널 앱을, 윈도우에서는 PowerShell을 열어 아래 설치 명령을 실행할 수 있습니다. 설치 명령은 운영체제와 터미널 종류에 따라 다릅니다.

맥과 윈도우의 설치 명령어

맥에서 설치하기

맥의 Spotlight에서 ‘터미널’을 검색해 실행한 뒤 다음 명령어를 입력합니다. 공식 배포 주소에서 설치 프로그램을 받아 실행하는 명령입니다.

curl -fsSL https://claude.ai/install.sh | bash

윈도우에서 설치하기

시작 메뉴에서 PowerShell을 열고 다음 명령어를 입력합니다. 입력 줄에 PS C:\가 보이면 PowerShell 창으로 구분할 수 있습니다.

irm https://claude.ai/install.ps1 | iex

이 명령은 PowerShell용이므로 CMD에서는 동작하지 않습니다. 윈도우 네이티브 환경에서 Git for Windows는 선택 사항이며, 설치하면 Bash 도구를 사용할 수 있습니다.

위 방식의 네이티브 설치는 자동 업데이트를 지원합니다. Homebrew나 WinGet으로 설치한 경우에는 해당 패키지 관리자로 업데이트합니다. 지원 환경과 다른 설치 방법은 Claude Code 설치 문서를 참고해 보세요.

설치 확인과 첫 로그인

설치가 끝나면 새 터미널을 열고 claude --version을 입력합니다. 버전 번호가 출력되면 터미널에서 Claude Code 실행 파일을 찾을 수 있는 상태입니다.

다음으로 작업할 프로젝트 폴더로 이동한 뒤 claude를 입력합니다. 처음 실행하면 계정 인증 안내가 나타나며, 브라우저에서 로그인을 마친 후 터미널로 돌아와 대화를 이어갈 수 있습니다. 설치와 로그인은 별도 과정이므로 버전이 표시되더라도 계정의 이용 권한에 따라 실행이 제한될 수 있습니다.

첫 요청으로는 “이 폴더의 파일 역할과 실행 방법을 설명해줘”처럼 프로젝트를 이해하는 질문을 사용할 수 있습니다. 파일 수정 없이 설명만 받고 싶다면 그 조건을 요청에 함께 적으면 됩니다.

예를 들어 테스트용 프로젝트에서 “실행 방법이 적힌 문서를 찾아줘. 파일은 수정하지 마”라고 요청할 수 있습니다. 답변에 나온 파일 경로와 실제 문서를 비교하면 어떤 자료를 바탕으로 설명했는지 살펴볼 수 있습니다. 첫 세션의 자세한 흐름은 공식 시작 안내에서 확인하실 수 있습니다.

자주 만나는 설치 오류와 원인

명령어를 찾을 수 없다는 메시지

command not found 또는 명령을 인식하지 못한다는 메시지는 실행 파일의 위치를 터미널이 찾지 못할 때 나타날 수 있습니다. 새 터미널에서도 같은 메시지가 나온다면 설치 완료 여부와 PATH 설정을 확인합니다. PATH는 명령어를 찾는 폴더 목록입니다.

irm을 인식하지 못하는 경우

'irm' is not recognized는 CMD에서 PowerShell용 명령을 실행했을 때 발생할 수 있습니다. 이 경우 PowerShell 창을 열어 위의 윈도우 설치 명령을 사용합니다. 같은 윈도우 환경이라도 어떤 터미널을 열었는지에 따라 사용할 수 있는 명령이 달라집니다.

권한 오류가 나타나는 경우

permission denied나 EACCES는 파일이나 폴더에 대한 접근이 거부됐다는 뜻입니다. 오류에 표시된 경로와 설치 방식을 보면 원인을 좁히는 데 도움이 됩니다. Claude Code를 실행할 수 있다면 claude doctor로 설치 상태를 확인할 수 있습니다.

운영체제, 터미널 종류, 실행한 명령과 오류 메시지를 함께 기록해 두면 문제를 재현하기 쉽습니다. 증상별 해결 방법은 공식 문제 해결 안내를 참고해 보세요.

설치가 끝난 뒤에는 무엇을 할 수 있나요?

프로젝트 구조를 설명받거나 코드의 동작을 묻고, 필요한 수정 사항을 요청할 수 있습니다. 문서 정리나 반복 작업을 위한 스크립트 작성에도 활용할 수 있습니다. 실제 수행 가능한 작업은 폴더의 내용과 도구에 허용한 권한에 따라 달라집니다.

처음에는 결과를 비교하기 쉬운 작은 작업으로 시작하면 사용 방식을 익히기 편합니다. 코드 수정 후에는 변경된 부분과 실행 결과를 확인하는 과정이 이어집니다. 설치가 도구를 준비하는 단계라면, 첫 작업은 우리 프로젝트에서 어떻게 활용할지 알아보는 단계라고 볼 수 있습니다.

우리 업무에 맞는 AI 활용을 함께 고민합니다

도구를 설치하고 나면 “우리 팀에서는 어떤 일부터 맡겨볼 수 있을까?”라는 궁금증이 생기기도 합니다. 반복하는 업무는 비슷해 보여도 사용하는 자료와 결과를 확인하는 방식은 팀마다 다르니까요.

똑똑한개발자는 기획·디자인·개발 과정에 AI를 활용하고, 사람이 결과를 검토하는 방식으로 내부 업무에도 자동화를 적용해 왔습니다. 이런 경험을 바탕으로 업무를 살펴보고 필요한 시스템을 만드는 과정을 함께합니다.

AI를 어디에 활용하면 좋을지 고민 중이라면 지금 반복하고 있는 일부터 편하게 들려주세요. 아래 똑똑한개발자 링크에서 함께 이야기 나눌 수 있습니다. 감사합니다. :)