Browse documentation
JetBrains IDE에서 Claude Code 사용하기
JetBrains IDE에서 Claude Code를 AI in IDE API 키 하나로 사용합니다. 대상은 IntelliJ IDEA, PyCharm, WebStorm, GoLand, PhpStorm, Android Studio입니다.
이 통합은 VS Code나 Cursor와 다릅니다. JetBrains에는 채팅을 내장한 확장이 없습니다. 플러그인이 IDE 통합 터미널에서 claude 명령을 실행하고 로컬 소켓으로 연결합니다. 그래서 CLI를 설치하고, 플러그인을 설치하고, CLI 환경을 설정하는 세 단계가 됩니다. 여기에 원클릭 설치는 없으며, 그렇게 안내하는 문서는 틀렸습니다.
JetBrains 통합이 다른 점
| VS Code / Cursor | JetBrains | |
|---|---|---|
| 설치 항목 | CLI를 내장한 확장 하나 | CLI 그리고 플러그인 |
| 채팅 위치 | 편집기 안의 네이티브 패널 | IDE 터미널, diff는 IDE에 표시 |
| Claude 탐색 | 내장 바이너리 | PATH의 claude, 또는 설정에서 지정한 경로 |
| 연결 방식 | 확장 프로세스 | 플러그인이 로컬 MCP 서버를 띄우고 CLI가 무작위 loopback 포트로 ws:// 접속 |
네트워크와 대화하는 주체가 CLI이므로 AI in IDE 설정은 CLI에 속하고 플러그인 GUI에는 없습니다. 오히려 이게 낫습니다. ~/.claude/settings.json 하나로 CLI, 플러그인, 터미널 세션이 모두 설정됩니다.
버전과 사전 준비
| 항목 | 요구 사항 |
|---|---|
| JetBrains IDE | IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, GoLand, Android Studio의 현재 빌드 |
| Node.js | npm으로 설치할 때는 22 이상이 필요합니다. 네이티브 CLI를 실행할 때는 Node.js가 필요하지 않습니다. |
| Claude Code CLI | 현재 버전, 전역 설치 |
| Claude Code 플러그인 | JetBrains Marketplace Beta 채널 |
| AI in IDE 키 | AWSQ 또는 CCMAX 채널, API Keys에서 발급 |
| Anthropic 계정 | API 키와 베이스 URL을 설정하면 불필요 |
플러그인은 **Claude Code [Beta]**로 배포됩니다. 기능과 설정 메뉴는 릴리스마다 바뀌므로, 설치한 빌드의 플러그인 페이지를 확인하고 옵션이 있다고 단정하지 마세요.
설치
1. CLI
1 npm install -g @anthropic-ai/claude-code2 claude --version
일반 터미널에서 claude가 해석되는지 확인합니다. 안 되면 플러그인이 실행하지 못하고 Cannot launch Claude Code를 표시합니다. 흔한 원인은 Node 버전 관리자(nvm, fnm, asdf)입니다. claude는 셸 초기화 스크립트를 거쳐 PATH에 들어가는데 IDE는 그 스크립트를 실행하지 않습니다. 시스템 Node로 설치하거나 다음 단계에서 절대 경로를 지정하세요.
2. 플러그인
Settings → Plugins → Marketplace를 열고 Claude Code를 검색해 설치한 뒤 IDE를 완전히 재시작합니다(프로젝트만 다시 여는 것으로는 부족). Remote Development에서는 **Settings → Plugin (Host)**를 통해 호스트에 설치하세요. 로컬 클라이언트에 설치하면 원격 프로젝트에 연결되지 않습니다.
3. 플러그인에 CLI 알려 주기
Settings → Tools → Claude Code [Beta] → Claude command는 경로만이 아니라 명령 문자열을 받습니다.
- PATH에 있을 때
claude /usr/local/bin/claude같은 절대 경로- 항상 최신 공개 CLI를 쓰려면
npx @anthropic-ai/claude-code - WSL을 쓰는 Windows에서는
wsl -d Ubuntu -- bash -lic "claude"(Ubuntu는 배포판 이름으로 교체)
command not found 알림이 뜰 때 확실한 해결책이 이 설정입니다.
API 키 만들고 복사하기
- 요금 페이지에서 플랜을 고릅니다. 하나의 계정에서 Claude, GPT, Gemini용 키를 각각 만들 수 있으며 각 키는 선택한 채널의 모델에 사용됩니다.
- API Keys를 열어 키를 만듭니다.
- AWSQ 또는 CCMAX를 고릅니다. Claude Code용 채널은 이 둘이고, Codex와 Gemini 키는 엔드포인트가 달라 여기서 실패합니다.
- 나중에도 API Keys 목록에서 전체 키를 확인하거나 복사할 수 있습니다.
설정
CLI는 ~/.claude/settings.json(macOS/Linux) 또는 C:/Users/<UserName>/.claude/settings.json(Windows)을 읽습니다. 다음 내용으로 만드세요.
1 {2 "$schema": "https://json.schemastore.org/claude-code-settings.json",3 "env": {4 "ANTHROPIC_BASE_URL": "https://api.aiinide.com",5 "ANTHROPIC_AUTH_TOKEN": "YOUR_DASHBOARD_API_KEY",6 "API_TIMEOUT_MS": "600000",7 "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"8 }9 }
ANTHROPIC_BASE_URL은 호스트 이름까지만 씁니다. CLI가 /v1/messages를 붙이므로 /v1을 넣으면 /v1/v1/messages가 되어 404이 납니다. 권한 규칙이나 훅이 들어 있는 settings.json이 이미 있다면 파일을 통째로 바꾸지 말고 env 객체를 추가하세요.
왜 셸 export가 아니라 파일일까요. Dock이나 시작 메뉴로 띄운 JetBrains IDE는 셸 프로필을 실행하지 않고, 플러그인은 IDE 환경을 물려받기 때문입니다. 파일은 CLI가 직접 읽으므로 터미널을 어떻게 띄웠든 동작합니다. 환경 변수를 고집한다면 셸 프로필에 넣고 IDE를 셸에서 실행하거나, 플러그인 명령줄에 포함하세요.
CLI의 첫 실행 로그인 화면도 필요 없습니다. ANTHROPIC_AUTH_TOKEN이 있고 claude.ai 세션이 없으면 Claude Code가 그 토큰을 사용합니다.
확인
먼저 모델 목록을 조회해 키와 Claude 채널을 확인하세요. 이 요청은 할당량을 사용하지 않습니다.
1 curl --globoff -i 'https://api.aiinide.com/v1/models' \2 -H "x-api-key: YOUR_DASHBOARD_API_KEY" \3 -H "anthropic-version: 2023-06-01"
HTTP 200이면 모델 목록이 반환됩니다. 401은 키 누락, 무효 또는 만료를, 400은 채널 불일치를 뜻합니다. 아래 Messages 예시에는 목록에 있는 모델 ID를 입력하세요.
- 터미널부터. 프로젝트 루트에서 IDE 통합 터미널을 열고
claude를 실행합니다. 로그인 화면 없이 프롬프트가 나와야 합니다. 여기서 실패하면 플러그인도 안 됩니다. 플러그인을 건드리기 전에 CLI와 환경을 고치세요. - IDE에서 연결. 프로젝트를 연 상태에서 IDE 터미널로
claude를 실행하거나Cmd+Esc/Ctrl+Esc를 누릅니다. 플러그인이 CLI를 띄우고 연결합니다. - 연결 확인.
/status를 실행하면 버전, 모델, 계정 상태가 나옵니다. 연결된 세션에서는 파일 편집이 터미널이 아니라 IDE diff 뷰어로 표시됩니다. - 외부 터미널에서 연결. IDE 밖에서
claude를 띄웠다면 Claude Code 안에서/ide를 입력합니다. 성공하면Connected to IntelliJ IDEA.(IDE 이름은 환경에 따라 다름)가 표시됩니다. CLI는 프로젝트 루트와 같은 디렉터리에서 시작하세요. 아니면 파일 집합이 어긋납니다. - 검증한 키로 모델을 직접 호출하세요.
1 curl --globoff 'https://api.aiinide.com/v1/messages' \2 -H "x-api-key: YOUR_DASHBOARD_API_KEY" \3 -H "anthropic-version: 2023-06-01" \4 -H "Content-Type: application/json" \5 -d '{"model":"MODEL_ID_FROM_LIST","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'
- 사용량. 첫 프롬프트가 성공하면 사용량 페이지에 그 키의 토큰 사용이 나타납니다.
문제 해결
GET /v1/models가 돌려준 정확한 ID를 사용하세요. claude-* 이름을 잘못 입력하면 설정된 기본 Claude 모델로 전달되어 해당 모델 요금이 부과될 수 있습니다.
API Error: 404
ANTHROPIC_BASE_URL을 https://api.aiinide.com으로 설정하세요. /v1을 덧붙이면 요청이 /v1/v1/messages로 전송되어 404가 반환됩니다.
API Error: 400
- 채널 오류. Codex나 Gemini 키는
/responses또는/v1beta/models/...로 인증하므로 이 엔드포인트에서는 400입니다. AWSQ나 CCMAX 키를 만드세요. - 깨진
settings.json. JSON이 해석되지 않으면 CLI는 조용히 기본값으로 돌아가고, 요청은 프록시 토큰을 단 채 실제 Anthropic 엔드포인트로 날아가 실패합니다. 파일을 검증하세요.$schema줄이 있으면 IDE가 바로 오류를 표시합니다.
API 키 인증 확인
키를 진단할 때는 GET /v1/models의 상태 코드를 확인하세요. 네이티브 POST /v1/messages는 키가 없거나 유효하지 않아도 HTTP 200을 반환하고 content에 인증 오류를 표시할 수 있습니다.
- 설정 위치가 틀림. Remote Development나 컨테이너에서는
~/.claude/settings.json이 CLI를 실행하는 호스트나 컨테이너에 있어야 합니다. 노트북이 아닙니다. - 남아 있는
ANTHROPIC_API_KEY. 환경에 Anthropic 키도 있으면ANTHROPIC_AUTH_TOKEN보다 우선할 수 있습니다. 해제하고 IDE를 재시작하세요. - 키 만료. 대시보드에서 만료일을 확인하고 연장이 아니라 교체하세요.
JetBrains 특유의 통합 실패
| 표시 | 원인 | 해결 |
|---|---|---|
Cannot launch Claude Code | claude가 IDE의 PATH에 없음 | Claude command를 절대 경로나 npx @anthropic-ai/claude-code로 |
/ide에서 No available IDEs detected | 플러그인 비활성, IDE 미재시작, CLI를 다른 사용자 세션에서 실행 | 플러그인 활성화, IDE 완전 재시작, IDE 터미널에서 claude 실행 |
WSL2에서 No available IDEs detected | NAT 네트워크나 Windows 방화벽이 WSL과 IDE 사이 loopback 차단 | 방화벽에서 WSL 서브넷 허용, 또는 .wslconfig를 networkingMode=mirrored로 |
| 플러그인은 설치됐는데 diff가 안 보임 | Diff tool이 terminal로 설정됨 | /config에서 Diff tool을 auto로. 이 항목은 IDE에 연결된 상태에서만 나타남 |
Esc가 Claude를 중단하지 못함 | IDE가 키를 가로챔 | Settings → Tools → Terminal에서 Move focus to the editor with Escape 해제 |
| Remote Development에서 기능 누락 | 플러그인이 클라이언트에 설치됨 | **Settings → Plugin (Host)**로 다시 설치 |
| diff가 프로젝트가 아닌 새 창에서 열림 | 프로젝트 루트 불일치 | 프로젝트 루트에서 claude 실행 |
타임아웃과 프록시
API_TIMEOUT_MS는 긴 에이전트 턴을 감당하기 위한 값이고, 사내 프록시는 요청마다 지연을 더합니다. 일정한 간격으로 실패한다면 타임아웃이 읽히지 않은 것입니다. settings.json의 env 안에 있는지 확인하고 IDE를 재시작하세요. TLS를 검사하는 프록시 뒤에서는 같은 env에 NODE_EXTRA_CA_CERTS를 넣어 프록시 루트 CA를 지정합니다.
권한 모드에 대한 주의
JetBrains에서는 플러그인이 IDE가 실행할 수 있는 설정 파일을 수정할 수 있습니다. 신뢰할 수 없는 저장소에서는 Manual 모드를 유지하고 acceptEdits를 끄며, 쓰기 가능한 세션에서 어떤 프로젝트 디렉터리를 여는지 의식적으로 고르세요.
모델과 가격
| 모델 | 채널 | 용도 |
|---|---|---|
claude-opus-5-5 / claude-opus-5.5 | AWSQ, CCMAX | 여러 파일 리팩터링, 긴 자율 작업 |
claude-sonnet-5-5 / claude-sonnet-5.5 | AWSQ, CCMAX | 일상 작업 기본값 |
claude-haiku-4-5-20251001 | AWSQ, CCMAX | 빠르고 저렴한 수정과 확인 |
Opus 5.5 기본 요율은 100만 토큰당 입력 $4, 캐시 읽기 $0.20, 출력 $20입니다. 쿼터 소모는 AWSQ가 0.8배, CCMAX가 2배입니다. 업스트림이 Fast 모드로 처리하면 기본·캐시 요율이 두 배가 됩니다.
- 플랜: 요금
- 키와 쿼터: API Keys
- 프로토콜 세부: 설정
- 공식 플러그인 페이지: JetBrains Marketplace
- 공식 통합 가이드: code.claude.com JetBrains
자주 묻는 질문
왜 원클릭 설치가 없나요? 플러그인이 의도적으로 CLI를 내장하지 않고, 설치된 claude를 실행해 터미널과 IDE가 하나의 설정을 공유하게 하기 때문입니다. 그래서 CLI를 먼저 설치하고 플러그인을 나중에 설치하는 순서가 필요합니다.
VS Code 확장을 재사용할 수 있나요? 아닙니다. VS Code / Cursor 확장은 별개 제품이고, 여기서 인터페이스는 IDE 터미널의 CLI입니다. 재사용할 수 있는 것은 ~/.claude/settings.json이고 양쪽 모두 이 파일을 읽습니다.
플러그인에 Anthropic 로그인이 필요한가요? 아닙니다. ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_BASE_URL을 설정하면 CLI가 로그인 화면을 건너뛰고 AI in IDE로 요청을 보냅니다.
어떤 IDE를 지원하나요? 문서화된 대상은 IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, GoLand, Android Studio입니다. 같은 플랫폼의 다른 IDE도 대개 동작하지만 플러그인은 베타이므로 의존하기 전에 diff와 /ide를 확인하세요.