저는 터미널에서 바로 쓸 수 있는 완전한 AI 에이전트를 기대하며 Claude Code를 설치했습니다. 설치 자체는 쉬웠습니다. 놀라운 건 그다음이었습니다. Claude Code는 파일을 읽고, 코드를 수정하고, 명령을 실행할 수 있었지만 웹 검색, 에셋 생성, 결과 저장, 게시까지는 여전히 할 수 없었습니다.
대부분의 Claude Code 설정 가이드가 놓치는 지점이 바로 이 부분입니다. Claude Code는 에이전트 셸을 제공합니다. 하지만 실제 업무에 필요한 전체 capability layer는 제공하지 않습니다. 여기서 AnyCap이 등장합니다. AnyCap은 MCP 서버가 아니라, Claude Code에 검색, 미디어 생성, 저장, 퍼블리싱 기능을 제공하는 더 강력한 agent CLI이자 capability runtime입니다.
이 가이드에서는 제가 Mac, Linux, WSL에서 Claude Code를 설치하고, 설정을 확인한 다음, AnyCap으로 실제 현업에 쓸 수 있는 에이전트로 바꾼 과정을 보여드립니다.
사전 준비
설치 전에 다음을 확인하세요.
- 운영체제: macOS 13+ (Ventura), Ubuntu 20.04+ / Debian 10+, 또는 WSL이 있는 Windows 10 (1809+)
- RAM: 최소 4GB, 더 큰 코드베이스라면 8GB 권장
- 인터넷 연결: 모든 AI 처리는 Anthropic의 클라우드 인프라에서 실행됩니다. 연결이 없으면 Claude Code도 사용할 수 없습니다
- Anthropic 계정: Claude Pro(월 20달러), Max(월 100~200달러), Teams, Enterprise 또는 Console(API) 계정. 무료 Claude.ai 플랜에는 Claude Code가 포함되지 않습니다. 어떤 플랜을 고를지 모르겠다면 Claude Code 요금 비교를 참고하세요.
- 터미널: Bash, Zsh 또는 PowerShell
- Node.js 18+: npm 설치 방법을 사용할 때만 필요
GPU는 필요 없습니다. 로컬 머신에서는 가벼운 CLI 클라이언트만 실행되고, 모든 AI 계산은 서버 측에서 처리됩니다.
1단계: Node.js 설치하기 (npm 방식만 해당)
네이티브 설치 프로그램을 사용할 계획이라면 이 단계는 완전히 건너뛰어도 됩니다. 지금은 Anthropic이 이 경로를 권장하며, 의존성도 없습니다.
npm 사용자라면 먼저 Node 버전을 확인하세요.
node --version
출력이 v18.0.0 이상이면 2단계로 넘어가면 됩니다. 아니라면 권한 문제를 피하기 위해 nvm(Node Version Manager)으로 설치하세요.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
터미널을 닫았다가 다시 연 뒤 다음을 실행합니다.
nvm install 22
nvm use 22
node --version # v22.x.x가 표시되어야 함
Node.js 22는 현재 LTS 릴리스이며 Claude Code와 안정적으로 동작합니다.
2단계: Claude Code 설치하기
설치 방법은 세 가지입니다. 하나를 선택하세요.
옵션 A: 네이티브 설치 프로그램 (권장)
의존성이 전혀 없습니다. 백그라운드에서 자동 업데이트됩니다. Anthropic이 주로 테스트하고 지원하는 방식입니다.
macOS 및 Linux:
curl -fsSL https://claude.ai/install.sh | bash
Windows (PowerShell, 관리자 권한으로 실행):
irm https://claude.ai/install.ps1 | iex
설치 프로그램은 claude 바이너리를 PATH에 추가하고 자동 업데이트도 설정합니다. 시작부터 끝까지 1분도 걸리지 않습니다.
옵션 B: Homebrew (macOS / Linux)
brew install --cask claude-code
한 가지 주의할 점이 있습니다. Homebrew 설치는 자동 업데이트되지 않습니다. 정기적으로 brew upgrade claude-code를 실행하세요.
옵션 C: npm
npm install -g @anthropic-ai/claude-code
sudo를 사용하지 마세요. EACCES 권한 오류가 난다면 해결책은 nvm이지, npm을 root로 실행하는 것이 아닙니다. root 소유의 npm 디렉터리는 연쇄적인 권한 문제를 만듭니다.
확인
설치가 제대로 되었는지 확인하세요.
claude --version
전체 환경 진단을 하려면 다음을 실행하세요.
claude doctor
3단계: 인증하기
claude
처음 실행하면 Claude Code가 OAuth 인증을 위해 브라우저를 엽니다. Anthropic 계정으로 로그인하고 CLI를 승인하면 연결됩니다.
인증 옵션
브라우저 OAuth (기본값): 개인용 머신에 가장 적합합니다. Pro, Max, Teams, Enterprise 계정에서 동작합니다. 승인 후 세션 토큰이 로컬에 저장됩니다.
API 키 (CI/CD 및 헤드리스 환경): 브라우저를 사용할 수 없는 서버, 컨테이너, 파이프라인용입니다.
export ANTHROPIC_API_KEY=sk-ant-your-key-here
claude
키는 console.anthropic.com에서 생성할 수 있습니다. API 사용량은 Anthropic의 표준 요금에 따라 토큰 기준으로 청구됩니다. 구독과 API 과금의 차이를 자세히 보려면 Claude Code 요금 가이드를 참고하세요.
어떤 과금 모델을 써야 할까? 구독(Pro/Max)은 일상적인 사용에 더 단순하고 월간 플랜 안에 Claude Code가 포함됩니다. API 과금은 변동적이거나 자동화된 워크로드를 더 세밀하게 제어할 수 있습니다.
4단계: 첫 번째 Claude Code 세션
아무 프로젝트 디렉터리로 이동하세요.
cd ~/my-project
claude
Claude Code는 프로젝트 구조를 읽고 대화형 REPL로 들어갑니다. 먼저 위험이 낮은 작업부터 시작해 보세요.
> Explain the architecture of this project
파일을 스캔해 스택을 파악하고 구조 요약을 제공합니다. 그다음에는 실제 영향이 있는 작업을 시도해 보세요.
> Add input validation to the user registration form
Claude Code는 관련 파일을 찾고 변경안을 제안한 뒤 확인을 기다립니다. 수락하기 전에 diff 보기에서 각 변경 사항을 검토할 수 있으므로 파일을 무작정 덮어쓰지 않습니다.
대화형 모드에 들어가지 않고 일회성 작업만 하려면 -p 플래그를 사용하세요.
claude -p "Write unit tests for the auth module"
작업을 실행하고 결과를 출력한 뒤 종료합니다. 스크립팅과 CI/CD 파이프라인에 적합합니다.
5단계: Claude Code 설정하기
모델 선택
Claude Code는 기본적으로 최신 사용 가능 모델을 사용합니다. 필요하면 다음처럼 바꿀 수 있습니다.
claude config set model claude-opus-4-7
또는 단일 세션에만 적용하려면:
claude --model claude-sonnet-4-6
권한
Claude Code는 파일 쓰기나 명령 실행 전에 확인을 요청합니다. 특정 프로젝트에서 신뢰할 수 있다면 다음처럼 설정할 수 있습니다.
claude config set permissions.auto-accept-edits true
속도 면에서는 유용합니다. 프로덕션 코드에는 덜 유용합니다.
프로젝트 수준 설정
프로젝트 루트에 .claude/settings.json을 만드세요.
{
"permissions": {
"allow": ["read", "write", "shell"],
"deny": ["shell:rm -rf *"]
},
"model": "claude-sonnet-4-6",
"environment": {
"NODE_ENV": "development"
}
}
CLAUDE.md
가장 영향력이 큰 설정은 여전히 CLAUDE.md입니다. 이 파일은 빌드 명령, 프로젝트 규칙, 아키텍처 결정에 대한 지속적인 컨텍스트를 Claude에 제공합니다. Claude Code 안에서 /init을 실행해 초안을 만든 뒤 다듬으세요.
플랫폼별 안내
macOS
curl -fsSL https://claude.ai/install.sh | bash
Linux
같은 네이티브 설치 프로그램을 사용하면 됩니다. 오래된 배포판이라면 nvm과 함께 npm을 쓰세요.
Windows
PowerShell:
irm https://claude.ai/install.ps1 | iex
WSL:
wsl --install
그다음 WSL에서:
curl -fsSL https://claude.ai/install.sh | bash
Docker
FROM node:22-alpine
RUN npm install -g @anthropic-ai/claude-code
CI/CD
- name: AI Code Review
run: |
npx @anthropic-ai/claude-code -p "Review this PR for bugs" --output-format json
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
설치를 넘어서: 빠진 capability layer 추가하기
여기서부터 설치 이야기가 진짜 이야기가 됩니다.
Claude Code는 이제 설치되었고, 인증되었고, 실행 중입니다. 하지만 여전히 셸 계층일 뿐입니다.
기본 상태에서는 다음 기능을 제공하지 않습니다.
- 실시간 웹 검색
- 이미지 생성
- 비디오 생성
- 클라우드 저장소와 파일 공유
- 웹 퍼블리싱
그래서 많은 “Claude Code 설정” 가이드는 사용자를 여전히 반쯤 완성된 에이전트 상태로 남겨 둡니다. 코딩 셸은 작동합니다. 하지만 더 넓은 capability layer는 여전히 비어 있습니다.
더 깔끔한 사고 모델
- Claude 모델 = 추론
- Claude Code = 셸과 워크플로 루프
- AnyCap CLI = capability runtime과 실행 표면
- AnyCap skill = Claude Code가 runtime을 잘 활용하도록 가르치는 지시 계층
이 차이가 중요합니다. 제품의 가치는 “도구가 하나 더 생겼다”는 데 있지 않습니다. AnyCap이 Claude Code에 기본으로 없는 capability layer를 채워 준다는 데 있습니다.
AnyCap CLI 설치하기
curl -fsSL https://anycap.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
한 번만 인증하기
anycap login
Claude Code용 skill 추가하기
npx -y skills add anycap-ai/anycap -a claude-code
이제 Claude Code는 더 강력한 agent CLI를 통해 다음 작업을 수행할 수 있습니다.
| Capability | 예시 |
|---|---|
| 웹 검색 | 실시간 API, 경쟁사 페이지, 가격 조사 |
| 이미지 생성 | 히어로 비주얼, 다이어그램, 목업 생성 |
| 비디오 생성 | 데모와 모션 에셋 제작 |
| 클라우드 저장소 | 파일 업로드와 링크 공유 |
| 퍼블리싱 | 결과물을 웹에 게시 |
바로 그 지점에서 Claude Code는 단순한 터미널 기반 코딩 셸이 아니라 실제 업무형 에이전트처럼 느껴지기 시작합니다.
MCP는 어떤가요?
MCP 역시 여전히 중요합니다. 특히 내부 시스템, 독점 API, 데이터베이스, 좁고 특화된 맞춤 통합에서는 더욱 그렇습니다.
하지만 MCP는 프로토콜 계층입니다.
더 넓은 capability layer는 별개의 문제입니다. 그래서 AnyCap을 “그냥 MCP 서버”로만 보는 것은 더 유용한 아키텍처 관점을 놓치게 됩니다.
문제 해결
| 문제 | 해결 방법 |
|---|---|
command not found: claude |
새 터미널을 열거나 설치 프로그램을 다시 실행 |
| Node.js 버전이 너무 낮음 | nvm install 22 && nvm use 22 |
| npm EACCES 오류 | sudo 대신 nvm 사용 |
| 브라우저 인증 창이 열리지 않음 | ANTHROPIC_API_KEY 사용 |
| 설치 중 네트워크 문제 | 프록시와 npm 레지스트리 설정 확인 |
| Claude Code가 느리게 느껴짐 | Anthropic 상태와 네트워크 지연 확인 |
수동 디버깅 전에 claude doctor를 실행하세요. 대부분의 환경 문제를 빠르게 잡아냅니다.
다음 단계
Claude Code를 설치했다면 다음 세 가지를 하세요.
CLAUDE.md를 생성해 프로젝트 메모리를 제공하기- capability runtime 추가로 코드 전용 작업 이상을 할 수 있게 만들기
- 실제 워크플로 하나 실행해 조사, 미디어, 저장, 퍼블리싱이 필요한 작업을 해보기
차이는 바로 그 지점에서 드러납니다.
Claude Code는 셸입니다.
AnyCap은 그 셸에 빠져 있던 실행 레이어를 제공합니다.