Linux + Claude Code 설정 가이드

Linux 서버 환경에서 Claude Code를 설치하고, AI 기반의 자율 최적화 및 로컬 코드 편집 기능을 GIIP 플랫폼과 연동하는 방법을 안내합니다.

📋 개요

Claude Code는 Anthropic의 Claude 모델을 터미널에서 직접 실행할 수 있게 해주는 도구입니다. Linux 서버에서 복잡한 설정 파일(Config)을 교정하거나, 시스템 성능을 분석하고 코드를 최적화하는 데 매우 강력한 성능을 발휘합니다.

🛠️ 설치 및 설정 단계

1. 사전 요구 사항

• Node.js 및 npm: Node.js 18 이상 버전이 필요합니다.
• Anthropic API Key: Claude 모델 사용을 위한 API 키가 필요합니다.

2. Claude Code 설치

터미널에서 다음 명령을 사용하여 전역으로 설치합니다.

npm install -g @anthropic-ai/claude-code

3. 인증 및 API 설정

1. Anthropic Console에서 API 키를 생성합니다.
2. 쉘 프로필(.bashrc 또는 .zshrc)에 API 키를 등록합니다.

   export ANTHROPIC_API_KEY="your-api-key"
   source ~/.bashrc

4. GIIP 연동

GIIP Agent Linux(giipAgentLinux)가 설치된 환경에서 Claude Code를 실행하면, 에이전트가 수집한 시스템 메트릭과 로그를 Claude가 직접 읽어 분석 보고서를 작성할 수 있습니다.

🚀 주요 활용 사례

• 설정 파일 최적화: claude "nginx.conf 파일의 성능 최적화 포인트 찾아줘"
• 시스템 보안 점검: claude "/etc/ssh/sshd_config 파일의 보안 취약점 점검해줘"
• 자동화 스크립트 작성: claude "서버 백업을 자동화하는 bash 스크립트 작성해줘"

💡 팁

• claude --help 명령어로 다양한 CLI 옵션을 확인할 수 있습니다.
• GIIP 플랫폼의 이슈 관리 페이지에서 Linux + Claude 조합으로 등록된 테스크를 선택하면 원격으로 분석 결과가 동기화됩니다.

🔧 문제 해결

증상	원인	해결
설치 후 claude: command not found 발생	Node.js 버전이 18 미만이거나 npm 전역 경로가 잡히지 않음	Node.js 18 이상을 설치하고 npm install -g @anthropic-ai/claude-code를 다시 실행
실행 시 인증 오류(API 키 무효) 발생	ANTHROPIC_API_KEY가 설정되지 않았거나 셸에 반영되지 않음	.bashrc(또는 .zshrc)에 키를 등록하고 source ~/.bashrc 실행
npm install -g 도중 권한(EACCES) 오류	전역 설치 경로에 쓰기 권한이 없음	sudo로 실행하거나 npm 전역 prefix를 사용자 경로로 변경
GIIP 시스템 메트릭·로그를 Claude가 읽지 못함	giipAgentLinux가 설치·실행되지 않음	Linux 에이전트가 정상 구동 중인지 먼저 확인

---

버전: 1.0 최종 업데이트: 2026-03-19 소스 파일: giipv3/public/help/agent-setup-linux-claude.ko.md