--- title: "Claude Code 연결" description: "Claude Code를 1折AI에 연결: ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN(환경 변수 또는 settings.json), Windows 작성법, 모델 매핑, VS Code 플러그인 및 자주 발생하는 오류 포함." headingIds: {"최단 경로":"section-1","전체 단계":"section-2","ANTHROPIC_AUTH_TOKEN을 쓰는 이유":"section-3","모델 매핑":"section-4","VS Code 플러그인":"section-5","선택 설정":"section-6","자주 발생하는 문제":"section-7"} --- Claude Code에는 두 개의 변수만 필요합니다. `ANTHROPIC_BASE_URL` 은 우리를 가리키고, `ANTHROPIC_AUTH_TOKEN` 에는 API 키(API key)를 입력합니다. Anthropic 계정 로그인은 필요하지 않습니다. ## 최단 경로 Claude Code가 이미 설치되어 있고 API 키가 있다면, 아래 두 줄을 `~/.claude/settings.json` 에 작성한 다음 `claude` 을 실행하세요: ```json title="~/.claude/settings.json" { "env": { "ANTHROPIC_BASE_URL": "https://1zheai.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" } } ``` 파일이 이미 존재한다면, 이 두 항목을 기존 `env` 에 병합하고 다른 설정은 덮어쓰지 마세요. ## 전체 단계 이미 설치했다면 건너뛰어도 됩니다. 다음 명령은 [Claude Code 공식 설치 문서](https://code.claude.com/docs/en/setup) 에서 가져왔습니다: ```bash title="macOS / Linux" curl -fsSL https://claude.ai/install.sh | bash ``` ```powershell title="Windows PowerShell" irm https://claude.ai/install.ps1 | iex ``` ```bash title="Homebrew" brew install --cask claude-code ``` ```bash title="npm（需要 Node.js 22+）" npm install -g @anthropic-ai/claude-code ``` npm으로 설치할 때는 `sudo` 을 붙이지 마세요. [콘솔](https://1zheai.com/console?lng=ko) 에서 새 API 키를 만드세요. 이 기기의 Claude Code 전용으로 쓰는 것을 권장합니다. [API 키 가져오기 및 관리](/ko/docs/api-keys/) 참조. settings.json 위치: macOS / Linux는 `~/.claude/settings.json`, Windows는 `%USERPROFILE%\.claude\settings.json` 입니다. ```json title="settings.json（推荐）" { "env": { "ANTHROPIC_BASE_URL": "https://1zheai.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" } } ``` ```bash title="macOS / Linux 环境变量" # 写进 ~/.zshrc 或 ~/.bashrc，然后重开终端 export ANTHROPIC_BASE_URL="https://1zheai.com" export ANTHROPIC_AUTH_TOKEN="sk-你的Key" ``` ```powershell title="Windows PowerShell" # 持久写入当前用户，重开终端后生效 [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://1zheai.com", "User") [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的Key", "User") # 只在当前窗口生效 $env:ANTHROPIC_BASE_URL = "https://1zheai.com" $env:ANTHROPIC_AUTH_TOKEN = "sk-你的Key" ``` ```bat title="Windows CMD" setx ANTHROPIC_BASE_URL "https://1zheai.com" setx ANTHROPIC_AUTH_TOKEN "sk-你的Key" ``` `ANTHROPIC_BASE_URL` 에는 루트 주소를 입력하고, `/v1` 을 붙이지 마세요. Claude Code가 알아서 `/v1/messages` 을 조합합니다. 프로젝트 디렉터리에서 `claude` 을 실행한 뒤 `/status` 을 입력하세요. 두 줄을 확인합니다: - base URL 행에 `https://1zheai.com` 이 표시됨 - 자격 증명 행에 출처가 `ANTHROPIC_AUTH_TOKEN` 로 표시됨 그런 다음 한 문장을 입력하고 [호출 로그](/ko/docs/usage-logs/) 에 새 기록이 있는지 확인하세요. 있으면 연결된 것입니다. 대화형 인터페이스에 들어가고 싶지 않다면 비대화형 모드로 한 번 시도해 볼 수 있습니다(2026-10-15 실제 테스트 반환값 `ok`): ```bash claude -p "say ok" --model claude-sonnet-4-6 ``` ## ANTHROPIC_AUTH_TOKEN을 쓰는 이유 Claude Code에는 API 키를 넣을 수 있는 두 변수가 있으며, 차이는 다음과 같습니다([공식 설명](https://code.claude.com/docs/en/authentication)): | 변수 | 전송 방식 | 동작 | |---|---|---| | `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <值>` | 설정 즉시 적용, 확인 창 없음 | | `ANTHROPIC_API_KEY` | `x-api-key: <值>` | 대화형 모드에서 처음 실행 시 이 API 키를 사용할지 확인하는 창이 뜸 | 두 방식 모두 지원하며, `ANTHROPIC_AUTH_TOKEN` 을 권장합니다. **둘 중 하나만 설정하세요**: 시스템에 이전 공식용 `ANTHROPIC_API_KEY` 이 남아 있다면 삭제하세요. 혼용하면 401이 발생할 수 있습니다. 또한 자주 걸리는 규칙 두 가지: - `settings.json` 의 `env` 과 터미널 export에서 같은 변수를 설정한 경우, **settings.json이 우선**합니다. 터미널 변수를 바꿨는데 안 되면 먼저 settings.json을 확인하세요. - API 키를 프로젝트의 `.claude/settings.json` 에 쓰지 마세요. 이 파일은 보통 저장소에 커밋됩니다. 프로젝트별로 구분하려면 커밋하지 않는 `.claude/settings.local.json` 을 사용하세요. ## 모델 매핑 Claude Code의 `opus`, `sonnet`, `haiku`, `fable` 은 별칭이며, 환경 변수로 각각 대응하는 실제 모델을 지정할 수 있습니다. Haiku 등급은 Claude Code가 일부 백그라운드 소형 작업을 실행하는 데도 사용됩니다. | 변수 | 역할 | 예시 값 | |---|---|---| | `ANTHROPIC_MODEL` | 시작 시 사용하는 모델 | `claude-sonnet-5-5` | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 별칭이 가리키는 모델 | `claude-opus-5-5` | | `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 별칭이 가리키는 모델 | `claude-sonnet-5-5` | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 별칭과 백그라운드 작업에 쓰는 모델 | `claude-haiku-5-5` | | `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 별칭이 가리키는 모델 | `claude-fable-5-1` | ```json title="~/.claude/settings.json（带模型映射）" { "env": { "ANTHROPIC_BASE_URL": "https://1zheai.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-5-5", "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5", "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5" } } ``` 모델 ID는 [지원 모델](/ko/docs/models/) 목록에 있는 것이어야 합니다. 실행 중에도 `/model claude-opus-5-5` 으로 임시 전환할 수 있습니다. ## VS Code 플러그인 Claude Code의 VS Code 플러그인은 시작 전에 자격 증명을 확인하며, 공식적으로는 변수를 VS Code 자체 사용자 설정에 작성할 것을 권장합니다(명령 팔레트 → Preferences: Open User Settings (JSON)): ```json title="VS Code settings.json" { "claudeCode.environmentVariables": [ { "name": "ANTHROPIC_BASE_URL", "value": "https://1zheai.com" }, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-你的Key" } ] } ``` `~/.claude/settings.json` 에만 작성하면 플러그인 자체의 로그인 확인이 읽지 못할 수 있습니다. ## 선택 설정 | 변수 | 역할 | |---|---| | `API_TIMEOUT_MS` | 요청 타임아웃, 기본값 600000(10분). 긴 작업이 자주 타임아웃되면 키우세요 | | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | 자동 업데이트, 텔레메트리, 오류 보고 등 불필요한 트래픽을 끕니다. `0` 또는 `false` 로 설정해도 켜진 것으로 간주되며, 끄려면 이 변수를 삭제해야 합니다 | | `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | "Extra inputs are not permitted"류 400 오류 발생 시 사용 | | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` | `/model` 목록을 `/v1/models` 에서 가져오도록 함 | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 은 실제 테스트로 사용 가능함이 확인되었습니다(Claude Code 2.1.296, 2026-10-15): 시작 후 debug 로그에 `[gatewayDiscovery] cached 14 models` 이 나타나며, 14개 모델이 [지원 모델](/ko/docs/models/) 과 일치합니다. `DISABLE_PROMPT_CACHING` 은 설정하지 마세요. 캐시를 끄게 되어 청구액이 눈에 띄게 증가합니다. [Prompt Caching](/ko/docs/prompt-caching/) 참조. ## 자주 발생하는 문제 Claude Code가 API 키를 읽지 못했습니다. 변수명 철자를 확인하세요. 환경 변수를 쓴다면 새로 연 터미널에서 시작했는지 확인하고, settings.json을 쓴다면 JSON 형식이 올바른지 확인하세요(쉼표 하나가 많아도 전체가 무효화됩니다). API 키가 복사되지 않았거나, `ANTHROPIC_API_KEY` 과 `ANTHROPIC_AUTH_TOKEN` 이 동시에 존재하고 그중 하나가 이전 값입니다. 둘 중 하나만 남기세요. 자세한 내용은 [오류 코드 및 문제 해결](/ko/docs/troubleshooting/) 참조. `ANTHROPIC_BASE_URL` 에 `/v1` 을 잘못 추가했습니다. `https://1zheai.com` 으로 바꾸세요. Claude Code가 Haiku 등급으로 백그라운드 소형 작업을 실행하는 것입니다. 다른 모델로 바꾸려면 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 을 설정하세요. 위 두 변수를 삭제하거나(주석 처리하면) 공식 로그인으로 돌아갑니다. 자주 전환한다면 [CC Switch](/ko/docs/quickstart-cc-switch/) 을 사용하세요. 클릭 한 번으로 전환됩니다. 연결되지 않습니다. 1折AI에 연결할 때 Claude Code는 우리의 API 키를 사용하며, 당신의 Anthropic 계정에 로그인하지 않습니다.