Claude Code CLI 프록시 연결 Pattern

Claude Code CLI 프록시 연결 Pattern — 실전 적용 구조와 코드 예시

언제 쓰나 · 새 서버에서 Claude Code CLI를 실행하되, 자체 구독 없이 플랫폼 API Key(`cpk_`)로 사용할 때 · 플랫폼이 인증/과금을 중계하고, CLI는 로컬처럼 동작하게 만들 때

# Claude Code CLI 프록시 연결 Pattern

## 언제 쓰는가
- 새 서버에서 Claude Code CLI를 실행하되, 자체 구독 없이 플랫폼 API Key(`cpk_`)로 사용할 때
- 플랫폼이 인증/과금을 중계하고, CLI는 로컬처럼 동작하게 만들 때

## 전제 조건
- Node.js 18+ 설치
- 플랫폼 서버 구동 중
- 플랫폼에서 발급받은 API Key (`cpk_...`)

## 설치

### 1. Claude Code CLI 설치
```bash
npm install -g @anthropic-ai/claude-code@latest
```

### 2. 환경변수 설정
```bash
# 쉘 프로필에 추가 (~/.bashrc 또는 ~/.zshrc)
export ANTHROPIC_BASE_URL="http://134.185.113.46:9090/proxy"
export ANTHROPIC_API_KEY="cpk_발급받은키"
```

### 3. 로그인 우회 (.config.json 생성)

CLI 첫 실행 시 로그인 화면이 뜨는데, 플랫폼 API Key는 CLI가 인식 못 함.
`.config.json`을 직접 생성해서 우회해야 한다.

```bash
mkdir -p ~/.claude
KEY_HASH=$(echo -n "$ANTHROPIC_API_KEY" | tail -c 20)
cat > ~/.claude/.config.json << EOF
{
  "hasCompletedOnboarding": true,
  "theme": "dark",
  "customApiKeyResponses": {
    "approved": ["$KEY_HASH"],
    "rejected": []
  }
}
EOF
```

**원리:**
- CLI는 API 키의 마지막 20자를 해시로 사용 (`key.slice(-20)`)
- `hasCompletedOnboarding: true` → 온보딩(로그인 선택) 화면 건너뜀
- `customApiKeyResponses.approved` → 해당 키를 승인된 키로 등록

### 4. 실행
```bash
claude
```
> 첫 실행 시 "Do you want to proceed?" 등이 2~3회 나올 수 있으나 반복 실행하면 사라짐

## 원라이너 (자동 설치)
```bash
curl -fsSL http://134.185.113.46:9090/install.sh | sh
```
Node.js 확인 → CLI 설치 → API Key 입력 → 환경변수 설정 → 연결 테스트까지 자동 처리

## Base URL 구분

| 방식 | Base URL | 최종 호출 경로 | 용도 |
|------|----------|----------------|------|
| **Anthropic 네이티브** | `http://134.185.113.46:9090/proxy` | `/proxy/v1/messages` | Claude Code CLI |
| **OpenAI 호환** | `http://134.185.113.46:9090/v1` | `/v1/chat/completions` | Cursor, Continue 등 |

- Claude Code CLI는 `ANTHROPIC_BASE_URL` 뒤에 자동으로 `/v1/messages`를 붙임
- OpenAI 호환 도구는 Base URL 뒤에 `/chat/completions`를 붙임

## 동작 구조
```
[로컬 Claude CLI] → /proxy/v1/messages → [Nginx] → [Spring ProxyController]
                                                         ↓ API Key 인증
                                                         ↓ 셀러 자동 배정
                                                         ↓ 크레딧 확인
                                                    [Python proxy.py]
                                                         ↓ OAuth 토큰 로드
                                                    [api.anthropic.com]
```

## 주의사항
- CLI 로그인 화면의 3개 옵션(OAuth, sk-ant-, 3rd-party) 모두 플랫폼 프록시와 호환 안 됨
- 반드시 `.config.json` 우회 필요
- Claude Code CLI용 `ANTHROPIC_BASE_URL`은 `/proxy`로 끝나야 함 (`/v1` 아님)
- OpenAI 호환 도구 사용 시에만 `http://134.185.113.46:9090/v1`로 변경

## 트러블슈팅
| 증상 | 원인 | 해결 |
|------|------|------|
| 로그인 화면이 뜸 | `.config.json` 없음 | 3단계 실행 |
| 401 Unauthorized | API Key 오류 또는 미인증 | `cpk_` 접두사 확인, 키 재발급 |
| 연결 안 됨 | 서버 URL 오류 | `curl http://134.185.113.46:9090/actuator/health` 테스트 |
| 크레딧 부족 | 잔액 < 100 토큰 | 플랫폼 웹에서 크레딧 충전 |

## 재사용
- 새 서버/PC마다 동일 절차 반복
- API Key 하나로 여러 머신에서 사용 가능