AI 코딩 어시스턴트 시장에서 Claude Code가 빠르게 주목을 받고 있어요. Anthropic이 만든 터미널 기반 AI 에이전트로, 코드 작성부터 파일 편집, 리서치까지 다양한 개발 작업을 도와줘요. Ubuntu 환경에서 Claude Code를 설치하는 방법이 궁금하셨다면 이 가이드가 딱 맞을 거예요.
이 글에서는 Ubuntu 20.04 / 22.04 / 24.04 환경을 기준으로 Claude Code를 처음부터 끝까지 설치하는 방법을 안내할게요. 명령어 한 줄씩 따라 하시면 누구든 쉽게 설치할 수 있어요.
Claude Code란 무엇인가요?
Anthropic이 만든 터미널 AI 에이전트
Claude Code는 Anthropic에서 개발한 CLI(Command Line Interface) 기반 AI 에이전트예요. VS Code나 JetBrains 같은 GUI 편집기 플러그인과는 달리, 순수하게 터미널에서 동작하는 도구예요. 프로젝트 디렉터리 안에서 파일을 읽고, 코드를 수정하고, 명령을 실행하는 모든 작업을 자연어로 지시할 수 있어요.
왜 Ubuntu 개발자에게 유용한가요?
Ubuntu는 서버 개발, DevOps, 오픈소스 프로젝트에서 가장 많이 쓰이는 Linux 배포판이에요. 터미널 중심의 작업 흐름이 이미 잡혀 있는 Ubuntu 사용자에게 Claude Code는 자연스럽게 녹아드는 도구예요. 특히 다음과 같은 작업에서 빛을 발해요.
- 대형 코드베이스 리팩터링 — 여러 파일을 한 번에 수정하고 일관성을 유지해요
- 자동화 스크립트 작성 — bash, python 스크립트를 자연어 설명으로 빠르게 생성해요
- 에러 디버깅 — 터미널 오류 메시지를 붙여넣으면 원인과 해결책을 바로 알려줘요
- 문서 자동화 — README, API 문서를 코드 분석 후 자동 생성해요
요금 구조 이해하기
Claude Code는 Anthropic API를 사용하므로 API 사용량에 따라 요금이 발생해요. Claude Pro 구독자라면 Pro 플랜 내에서 일정량의 Claude Code 사용이 포함돼요. API 키를 직접 사용하는 경우 토큰 사용량에 따라 과금되니 미리 확인해 두세요.
사전 준비 사항
Node.js 설치 확인
Claude Code는 npm 패키지로 배포되기 때문에 Node.js가 필요해요. Ubuntu에 Node.js가 없다면 아래 절차로 설치해요. NVM(Node Version Manager)을 사용하는 방법이 버전 관리에 가장 편리해요.
- NVM 설치:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash - 터미널 재시작 또는 소스 적용:
source ~/.bashrc - Node.js LTS 설치:
nvm install --lts - 버전 확인:
node --version(v18 이상 권장)
apt를 통한 직접 설치도 가능해요. sudo apt update && sudo apt install -y nodejs npm 명령으로 설치하면 되는데, Ubuntu 기본 저장소의 Node.js 버전이 오래된 경우 NodeSource 저장소를 추가해서 최신 버전을 설치하는 것을 추천해요.
Anthropic API 키 준비
Claude Code를 사용하려면 Anthropic API 키가 필요해요. console.anthropic.com에 로그인한 후 API Keys 섹션에서 새 키를 생성하세요. 키는 sk-ant-로 시작하는 문자열이에요. 한 번만 표시되므로 생성 직후 안전한 곳에 저장해 두세요.
시스템 요구사항 확인
공식적으로 지원되는 Ubuntu 버전과 최소 사양은 다음과 같아요.
- Ubuntu 20.04 LTS (Focal), 22.04 LTS (Jammy), 24.04 LTS (Noble) 지원
- RAM 4GB 이상 (복잡한 프로젝트에는 8GB 권장)
- 인터넷 연결 필수 (API 호출)
- Node.js 18.x 이상, npm 8.x 이상
Claude Code 설치 단계별 안내
npm으로 전역 설치하기
Claude Code는 npm 패키지 @anthropic-ai/claude-code로 제공돼요. 전역 설치를 권장하는데, 어느 디렉터리에서든 claude 명령어를 사용할 수 있게 되기 때문이에요. 아래 명령어 한 줄로 설치가 완료돼요.
- 전역 설치:
npm install -g @anthropic-ai/claude-code - 권한 오류 발생 시:
sudo npm install -g @anthropic-ai/claude-code - 설치 확인:
claude --version
NVM으로 Node.js를 설치한 경우 sudo 없이도 전역 설치가 가능해요. 반면 시스템 Node.js(apt로 설치)를 사용하는 경우 /usr/local/lib에 쓰기 권한이 필요해 sudo가 필요할 수 있어요.
API 키 환경 변수 설정
설치 후 API 키를 환경 변수로 설정해야 해요. 세션마다 키를 입력하지 않으려면 shell 설정 파일에 영구적으로 저장하는 것이 편리해요.
- bash 사용자:
echo 'export ANTHROPIC_API_KEY="sk-ant-여기에키입력"' >> ~/.bashrc && source ~/.bashrc - zsh 사용자:
echo 'export ANTHROPIC_API_KEY="sk-ant-여기에키입력"' >> ~/.zshrc && source ~/.zshrc - 확인:
echo $ANTHROPIC_API_KEY
보안 측면에서 API 키를 shell 설정 파일에 평문으로 저장하는 것이 약간 걱정될 수 있어요. 더 안전한 방법으로는 pass나 secret-tool 같은 패스워드 매니저를 활용하거나, AWS Secrets Manager, HashiCorp Vault 같은 시크릿 관리 서비스와 연동하는 방법도 있어요.
첫 실행 및 초기 설정
API 키 설정 후 claude 명령어를 실행하면 초기 설정 화면이 나타나요. 처음 실행 시 이용약관 동의를 요청하고, 기본 설정 몇 가지를 물어봐요. 화살표 키와 Enter로 선택하면 돼요. 설정이 완료되면 대화형 프롬프트가 시작되고, 이제 자연어로 Claude에게 작업을 지시할 수 있어요.
자주 발생하는 설치 오류와 해결 방법
EACCES 권한 오류
npm 전역 설치 시 가장 흔한 오류가 권한 문제예요. EACCES: permission denied 메시지가 보이면 다음 방법으로 해결할 수 있어요.
- 방법 1 — NVM 사용: NVM으로 설치한 Node.js는 사용자 홈 디렉터리에 설치되므로 sudo가 필요 없어요
- 방법 2 — npm 전역 경로 변경:
mkdir ~/.npm-global && npm config set prefix '~/.npm-global'후 PATH에~/.npm-global/bin추가 - 방법 3 — sudo 사용: 가장 빠른 해결책이지만 보안 관점에서 방법 1, 2를 먼저 시도해요
Node.js 버전 호환성 문제
Ubuntu 20.04의 기본 apt 저장소에는 Node.js 10.x 또는 12.x가 포함되어 있을 수 있어요. Claude Code는 Node.js 18 이상을 요구하므로 구버전이면 설치 자체는 되어도 실행 시 오류가 발생해요. NodeSource 저장소를 추가하거나 NVM을 활용해 최신 LTS 버전으로 업그레이드하세요.
네트워크 및 프록시 오류
회사 내부망이나 VPN 환경에서 npm install이 실패하는 경우, npm 프록시 설정이 필요할 수 있어요. npm config set proxy http://proxy.example.com:8080와 npm config set https-proxy http://proxy.example.com:8080 명령으로 프록시를 설정할 수 있어요.
Claude Code 기본 사용법
프로젝트 폴더에서 시작하기
Claude Code는 현재 디렉터리를 작업 공간으로 사용해요. 작업할 프로젝트 폴더로 이동한 후 claude를 실행하면 해당 프로젝트의 파일들을 이해하고 도움을 줄 수 있어요. cd ~/myproject && claude처럼 사용하면 돼요.
주요 명령어와 단축키
Claude Code 대화형 세션에서 자주 사용하는 기능들이 있어요.
- /help — 사용 가능한 명령어 목록 확인
- /clear — 현재 대화 맥락 초기화
- /compact — 긴 대화 내용을 요약해서 컨텍스트 절약
- Ctrl+C — 현재 작업 중단
- Ctrl+D 또는 /exit — Claude Code 종료
비대화형 모드도 지원돼요. claude -p "main.py를 분석해서 버그를 찾아줘"처럼 -p 옵션으로 단일 명령을 실행할 수 있어요. 스크립트나 자동화에 유용한 기능이에요.
CLAUDE.md 프로젝트 설정 파일
프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude Code가 해당 프로젝트에 진입할 때 자동으로 읽어요. 여기에 코딩 컨벤션, 자주 쓰는 명령, 주의사항 등을 적어두면 매번 설명하지 않아도 돼요. 팀 프로젝트에서는 이 파일을 git에 커밋해서 팀원들과 공유할 수 있어요.
보안 및 권한 관리
Claude Code의 권한 모델
Claude Code는 터미널에서 직접 파일을 읽고, 쓰고, 명령을 실행할 수 있어요. 기본적으로 민감한 작업(파일 삭제, git push, 패키지 설치 등)을 수행하기 전에 사용자 승인을 요청해요. 승인 요청 없이 자동으로 진행하게 하려면 --dangerously-skip-permissions 플래그를 사용할 수 있지만, 이름처럼 위험할 수 있으니 신중하게 사용해야 해요.
API 키 보안 관리
API 키는 사용량에 따라 비용이 발생하므로 유출되지 않도록 주의해야 해요. 특히 다음 사항을 꼭 지켜주세요.
- API 키를 코드에 하드코딩하지 말고 항상 환경 변수로 관리해요
- .gitignore에 .env 파일을 추가해서 실수로 커밋되지 않도록 해요
- Anthropic Console에서 API 키 사용량을 정기적으로 모니터링해요
- 필요한 경우 IP 허용 목록을 설정해서 접근을 제한해요
Ubuntu 방화벽과 SELinux 고려
UFW(Uncomplicated Firewall)가 활성화된 Ubuntu 환경에서는 Claude Code의 API 호출(HTTPS, 포트 443)이 기본적으로 허용되므로 별도 설정이 필요하지 않아요. 단, 매우 제한적인 보안 정책이 적용된 서버 환경에서는 outbound HTTPS 트래픽이 막혀 있을 수 있으니 확인해보세요.
업그레이드 및 유지 관리
Claude Code 버전 업데이트
Anthropic은 Claude Code를 자주 업데이트해요. 최신 버전을 유지하면 새 기능과 버그 수정을 받을 수 있어요. 업데이트는 설치와 동일한 명령어로 할 수 있어요.
- 버전 확인:
claude --version - 최신 버전으로 업데이트:
npm update -g @anthropic-ai/claude-code - 특정 버전 설치:
npm install -g @anthropic-ai/claude-code@1.2.3
설정 파일 위치
Claude Code의 전역 설정은 ~/.claude/ 디렉터리에 저장돼요. 이 폴더에는 사용자 설정, 인증 정보, 허용 권한 목록 등이 담겨 있어요. 설정을 초기화하고 싶다면 이 폴더를 삭제하거나 이름을 바꾸면 돼요. 단, 커스텀 설정이 모두 사라지니 백업을 먼저 해두세요.
마무리
Ubuntu에서 Claude Code를 설치하는 것은 생각보다 훨씬 간단해요. Node.js 설치, npm으로 패키지 설치, API 키 설정의 세 단계만 거치면 강력한 AI 코딩 에이전트를 터미널에서 바로 사용할 수 있어요.
처음에는 낯설 수 있지만, 몇 번 사용하다 보면 코드 작성, 디버깅, 리팩터링, 문서화 등 다양한 개발 작업에서 생산성이 크게 향상되는 것을 경험하실 거예요. 궁금한 점이 생기면 claude 프롬프트에서 직접 Claude에게 물어보세요!