> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Claude Code
> Claude Code에서 AIHubMix를 사용하여 하나의 API 키로 여러 공급자의 모델을 호출하는 설정 가이드입니다.
## 빠른 시작
이 가이드는 AIHubMix를 통해 Claude Code를 몇 분 안에 사용할 수 있도록 도와줍니다.
### 1. Claude Code 설치
#### 로컬 설치
```shellscript macOS theme={null}
curl -fsSL https://claude.ai/install.sh | bash
```
```shellscript Windows theme={null}
irm https://claude.ai/install.ps1 | iex
```
#### npm으로 설치
[Node.js 18 이상](https://nodejs.org/en/download/)이 필요합니다.
```shellscript theme={null}
npm install -g @anthropic-ai/claude-code
```
### 2. AIHubMix API 구성
Anthropic 호환 API 방식으로 AIHubMix 모델 서비스에 연결하려면 다음 환경 변수를 설정합니다.
1. `ANTHROPIC_BASE_URL`을 `https://aihubmix.com`으로 설정합니다
2. `ANTHROPIC_AUTH_TOKEN`을 [AIHubMix 플랫폼](https://console.aihubmix.com/token)에서 받은 API Key로 설정합니다
3. `ANTHROPIC_MODEL`을 [모델 목록](https://aihubmix.com/models)에서 지원되는 Claude 모델로 설정합니다. 예: `claude-sonnet-4-5`
`AIHUBMIX_API_KEY`는 예시용 자리 표시자입니다. 반드시 본인의 실제 Key(보통 `sk-`로 시작)로 바꾸세요. 그대로 복사하면 Claude Code가 이를 실제 Key로 처리하고 `401 invalid key: AIHUBMIX_API_KEY`를 반환합니다.
1. 터미널에서 다음 명령을 실행해 기본 Shell을 확인합니다.
```shellscript theme={null}
echo $SHELL
```
2. Shell 유형에 맞게 환경 변수를 설정합니다.
```shellscript Zsh theme={null}
# 를 AIHubMix에서 받은 실제 Key로 바꾸세요
echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=""' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.zshrc
```
```shellscript Bash theme={null}
# 를 AIHubMix에서 받은 실제 Key로 바꾸세요
echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.bash_profile
echo 'export ANTHROPIC_AUTH_TOKEN=""' >> ~/.bash_profile
echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.bash_profile
```
3. 설정을 적용합니다.
```shellscript Zsh theme={null}
source ~/.zshrc
```
```shellscript Bash theme={null}
source ~/.bash_profile
```
4. 새 터미널을 열고 환경 변수가 적용되었는지 확인합니다.
```shellscript theme={null}
echo $ANTHROPIC_BASE_URL
test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set"
echo $ANTHROPIC_MODEL
```
Windows에서는 CMD 또는 PowerShell로 AIHubMix Base URL과 [API Key](https://console.aihubmix.com/token)를 환경 변수로 설정할 수 있습니다.
1. CMD에서 다음 명령을 실행합니다.
```shellscript theme={null}
REM 를 AIHubMix에서 받은 실제 Key로 바꾸세요
setx ANTHROPIC_AUTH_TOKEN ""
setx ANTHROPIC_BASE_URL "https://aihubmix.com"
setx ANTHROPIC_MODEL "claude-sonnet-4-5"
```
2. 새 CMD 창을 열고 환경 변수를 확인합니다.
```shellscript theme={null}
if defined ANTHROPIC_AUTH_TOKEN echo ANTHROPIC_AUTH_TOKEN is set
echo %ANTHROPIC_BASE_URL%
echo %ANTHROPIC_MODEL%
```
1. PowerShell에서 다음 명령을 실행합니다.
```shellscript theme={null}
# 를 AIHubMix에서 받은 실제 Key로 바꾸세요
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://aihubmix.com", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-5", [EnvironmentVariableTarget]::User)
```
2. 새 PowerShell 창을 열고 환경 변수를 확인합니다.
```shellscript theme={null}
if ($env:ANTHROPIC_AUTH_TOKEN) { "ANTHROPIC_AUTH_TOKEN is set" }
echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_MODEL
```
CC Switch로 Claude Code를 관리하려면 전역 `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`을 별도로 설정하지 않는 것이 좋습니다. 시스템 또는 사용자 환경 변수가 CC Switch가 작성한 Provider 구성을 덮어쓸 수 있어, UI에서 올바른 Provider를 선택해도 Claude Code가 이전 Key나 이전 모델을 계속 사용할 수 있습니다.
### 3. 구성 검증
환경 변수 또는 CC Switch 구성을 마친 뒤 긴 세션을 시작하기 전에 최소 요청으로 Key, 모델, Anthropic 호환 엔드포인트가 사용 가능한지 확인하세요.
```bash macOS/Linux theme={null}
curl https://aihubmix.com/v1/messages \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 16,
"messages": [{"role": "user", "content": "1+1, 답만 출력"}]
}'
```
```powershell Windows theme={null}
curl.exe https://aihubmix.com/v1/messages `
-H "content-type: application/json" `
-H "anthropic-version: 2023-06-01" `
-H "x-api-key: $env:ANTHROPIC_AUTH_TOKEN" `
-d "{\"model\":\"claude-sonnet-4-5\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"1+1, output only the answer\"}]}"
```
요청이 `200`을 반환하고 내용이 `2`라면 AIHubMix Key와 Claude 모델을 사용할 수 있습니다. 이어서 다음을 실행합니다.
```bash theme={null}
claude -p "1+1, 답만 출력" --model claude-sonnet-4-5
```
`2`가 반환되면 Claude Code가 엔드투엔드로 올바르게 구성된 것입니다.
### 4. 사용 시작
구성이 끝나면 작업 디렉터리로 이동해 터미널에서 `claude`를 실행합니다.
```bash theme={null}
$ cd /path/your-project
> claude
```
시작 시 `Not logged in · Please run /login`이 표시되거나 Anthropic 로그인 옵션이 열리면, 보통 Claude Code가 사용 가능한 AIHubMix 구성을 읽지 못했거나 최초 온보딩이 완료되지 않은 상태입니다. 먼저 위 최소 요청이 `2`를 반환하는지 확인하고, 오래된 전역 환경 변수 `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`이 현재 구성을 덮어쓰고 있지 않은지 확인하세요. Key가 사용 가능한데도 로그인 흐름으로 들어가면 다음 단계로 최초 온보딩을 건너뜁니다.
1. 사용자 홈 디렉터리의 `.claude.json` 파일을 찾습니다.
* macOS / Linux: `~/.claude.json`
* Windows: `C:\Users\%USERNAME%\.claude.json`
2. `hasCompletedOnboarding` 값을 `true`로 설정합니다.
```json theme={null}
{
"hasCompletedOnboarding": true
}
```
3. 파일을 저장한 뒤 터미널에서 `claude`를 다시 실행합니다.
#### (선택) 추가 모델 구성 방법
Claude Code는 다음 모델 구성 방법을 지원합니다. **우선순위는 위에서 아래 순서**이며, 높은 우선순위가 낮은 우선순위를 덮어씁니다.
1. **대화 중:** `/model <모델명>` 명령으로 임시 전환합니다.
```text theme={null}
/model claude-sonnet-4-5
```
2. **Claude Code 시작 시:** `claude --model <모델명>`으로 단일 세션의 모델을 지정합니다.
```text theme={null}
claude --model claude-sonnet-4-5
```
3. **환경 변수:** 작업 복잡도에 따라 모델 계층을 설정합니다.
```shellscript theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
```
* `ANTHROPIC_DEFAULT_OPUS_MODEL`: 복잡한 추론과 아키텍처 설계.
* `ANTHROPIC_DEFAULT_SONNET_MODEL`: 코딩과 기능 구현.
* `ANTHROPIC_DEFAULT_HAIKU_MODEL`: 간단한 검사, 파일 검색, 가벼운 작업.
4. **`settings.json`:** Claude Code 사용자 설정 파일(macOS/Linux는 `~/.claude/settings.json`, Windows는 `C:\Users\%USERNAME%\.claude\settings.json`) 또는 프로젝트 설정에 작성합니다.
**대체 설정:** `/model`, 시작 인자, 환경 변수 또는 CC Switch 설정이 적용되지 않거나 Claude Code가 계속 이전 모델을 읽는 경우 `settings.json`을 직접 수정하세요. 아래 예시는 `ANTHROPIC_MODEL`과 최상위 `model`을 동시에 설정하고, Opus, Sonnet, Haiku 슬롯의 모델 이름도 유지합니다.
```json theme={null}
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "",
"ANTHROPIC_BASE_URL": "https://aihubmix.com",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.5-flash",
"ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "gemini-3.5-flash",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-3.5-flash",
"ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "gemini-3.5-flash",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-3.5-flash",
"ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "gemini-3.5-flash",
"ANTHROPIC_MODEL": "gpt-5.5"
},
"model": "gpt-5.5"
}
```
``를 실제 Key로 바꾸세요. 저장 후 Claude Code를 다시 시작하고 `/models`로 현재 세션에서 사용할 수 있는 모델을 확인합니다.
## CC Switch에서는 어떻게 구성하나요?
1. CC Switch를 실행하고 왼쪽에서 **Claude Code**를 선택한 뒤 "Add Vendor"를 클릭합니다.
2. preset 목록에서 "AiHubMix"를 선택합니다. Claude Code 쪽 Provider를 구성 중인지 확인하세요.
3. "API Key" 입력란에 실제 Key를 입력합니다.
4. 설정 후 먼저 `claude-sonnet-4-5`를 모델 ID로 사용하고 "Add"를 클릭해 저장합니다. health check가 통과하면 Claude Code에서 `/models` 또는 `/model`로 다른 Claude 모델로 전환할 수 있습니다.
5. 홈으로 돌아가 Provider 목록에서 "AiHubMix"를 선택하고 "Start"를 클릭합니다.
CC Switch가 시스템 환경 변수 충돌을 표시하면 먼저 `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`을 확인하세요. 이 전역 변수들은 현재 Provider 구성을 덮어쓸 수 있습니다. `ANTHROPIC_AUTH_TOKEN=AIHUBMIX_API_KEY` 같은 자리 표시자 값은 인증 실패의 직접 원인입니다. 전역 변수가 더 필요 없음을 확인한 뒤 CC Switch에서 충돌 항목을 삭제하거나 시스템/사용자 환경 변수를 직접 삭제하고 터미널을 다시 시작하세요.
문제를 빠르게 분리하려면 다음 checklist를 순서대로 확인하세요: Base URL, Auth Token, API Key, Model ID, Provider, Health Check, User Environment, System Environment, Project Settings, User Settings, Startup Argument, Conversation Model, CC Switch Provider, API Key Permission, Model Permission, Quota, Balance, Expiration, Terminal Restart, Claude Code Restart. 이 항목들은 Claude Code가 실제로 어떤 설정을 읽는지 확인하는 데 도움이 됩니다.
검색이나 내부 공유용으로는 다음 English keywords도 함께 남겨두면 좋습니다: Claude Code AIHubMix setup, Anthropic compatible endpoint, custom API key, authentication token, environment variable conflict, provider override, model routing, model permission, invalid key, no token provided, incorrect model ID, bad request, health check, settings json fallback, user settings, system settings, terminal session, restart required, model list, model family, quota check, balance check.
## VS Code 플러그인에서는 어떻게 구성하나요?
1. VS Code를 실행하고 플러그인을 설치합니다.
2. `Ctrl + Shift + P` 또는 `Cmd + Shift + P`를 누르고 `Settings`를 입력합니다.
3. `Claude Code`를 검색하고 `Claude Code: Environment Variable` -> `Edit in settings.json`을 엽니다.
4. `claudeCode.environmentVariables`에 AIHubMix 정보를 입력합니다.
## [Wechat-Agent-SDK](https://github.com/AIhubmix/wechat-agent-sdk)
간단한 API 호출로 Claude Code, Codex, Kimi 같은 AI 에이전트를 WeChat에 연결할 수 있습니다. ACP 프로토콜을 지원하며 서버나 데이터베이스 없이 로컬에서 실행되고, 재개와 자동 재연결 기능을 제공합니다.
> 설치 링크: [https://github.com/AIhubmix/wechat-agent-sdk](https://github.com/AIhubmix/wechat-agent-sdk)
## FAQ
### Q: `401` 인증 오류가 표시되면 어떻게 해야 하나요?
`401`은 인증에 실패했다는 뜻이지만, 정확한 원인은 전체 오류 메시지에 따라 다릅니다.
* `No token provided`: Key가 전송되지 않았습니다. Claude Code에서 `/config`를 열고 `Use custom API key`의 Token 설정을 확인하세요.
* `invalid key: AIHUBMIX_API_KEY`: 예시 자리 표시자를 그대로 복사했을 가능성이 큽니다. AIHubMix 콘솔에서 실제 Key를 다시 복사하고 `ANTHROPIC_AUTH_TOKEN`을 업데이트하세요.
* `this key is not enabled`: 요청은 AIHubMix에 도달했지만 현재 Key가 활성화되지 않았거나 권한이 없습니다. [AIHubMix 콘솔](https://console.aihubmix.com/token)에서 Key 활성화 상태, 만료 여부, 잔액, 선택한 Claude 모델 호출 권한을 확인하세요.
Windows에서는 사용자 또는 시스템 환경 변수에 이전 값이 남아 있는지도 확인하세요.
```powershell theme={null}
[Environment]::GetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_MODEL", "User")
```
CC Switch로 구성을 관리한다면 이 전역 `ANTHROPIC_*` 변수를 삭제해 현재 CC Switch Provider가 구성을 맡도록 하세요.
참고: `/v1/models`는 유효한 Key가 없어도 모델 목록을 반환할 수 있으므로 Key 사용 가능 여부 판단에 쓰지 마세요. 위의 "구성 검증" 섹션의 최소 메시지 요청을 사용하세요. `200`과 `2`가 반환되면 Key와 모델을 사용할 수 있습니다. 이후 Claude Code를 다시 시작하거나 CC Switch에서 다시 시작하세요.
문제가 계속되면 같은 Key로 먼저 터미널의 `curl` 요청을 확인한 다음 Claude Code를 확인하세요. `curl`은 성공하지만 Claude Code만 실패한다면 Key 자체보다는 로컬 설정 우선순위, 오래된 사용자 환경 변수, CC Switch Provider 선택, 또는 `settings.json`에 남아 있는 이전 모델 값이 원인일 가능성이 큽니다. 반대로 `curl`도 실패한다면 Claude Code를 수정하기 전에 AIHubMix 콘솔에서 Key 상태와 모델 권한을 먼저 확인하는 것이 좋습니다.
### Q: `400 Incorrect model ID` 또는 `Bad request (400)`가 표시되면 어떻게 해야 하나요?
보통 요청은 Provider 측에 도달했지만 모델 ID가 올바르지 않거나, 모델 이름이 인터페이스와 맞지 않거나, 현재 Key에 해당 모델 호출 권한이 없는 상태입니다. [AIHubMix 모델 목록](https://aihubmix.com/models)에서 전체 모델 ID를 다시 복사하고 철자, 대소문자, 모델 계열을 확인하세요.
CC Switch로 구성한 경우 해당 Provider로 돌아가 모델 ID를 업데이트하고 저장한 뒤 Claude Code를 다시 시작하세요. 오류가 계속되면 모델 목록에서 사용 가능하다고 확인된 Claude 모델로 먼저 health check를 통과시킨 다음 목표 모델로 전환하세요.
모델 이름은 화면에 보이는 표시명과 실제 호출용 ID가 다를 수 있습니다. 직접 입력하기보다 모델 목록에서 전체 ID를 복사하고, 앞뒤 공백이나 잘못된 하이픈, 대소문자 차이가 없는지 확인하세요. 같은 모델을 여러 곳에서 설정했다면 `/model`, 시작 인자, 환경 변수, CC Switch, `settings.json` 중 어느 값이 최종 적용되는지도 함께 확인해야 합니다.
### Q: macOS에서 설치 후에도 `zsh: command not found: claude`가 표시되면 어떻게 하나요?
Claude CLI는 설치되었지만 실행 파일 디렉터리가 `PATH`에 추가되지 않은 상태입니다.
1. 설치 경로를 확인합니다. 공식 스크립트는 보통 다음 중 하나에 설치됩니다.
* `~/.claude/bin`
* `~/.local/bin`
```bash theme={null}
ls -l ~/.claude/bin
or
ls -l ~/.local/bin | grep claude
```
2. 설치 위치를 `PATH`에 추가합니다.
#### 경우 A: `~/.claude/bin`에 설치된 경우
```shellscript theme={null}
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
#### 경우 B: `~/.local/bin`에 설치된 경우
```shellscript theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
3. 확인합니다.
```shellscript theme={null}
which claude
claude -v
```
`claude` 경로와 버전이 보이면 설치가 완료된 것입니다.
### Q: Claude Code가 Anthropic 서비스에 연결할 수 없으면 어떻게 하나요?
Claude Code를 최신 버전으로 업데이트한 뒤 연결 또는 인증 실패가 발생하면 인증 요청 헤더 이름 변경이 원인일 수 있습니다. 새 버전에서는 `ANTHROPIC_API_KEY` 대신 `ANTHROPIC_AUTH_TOKEN`이 필요합니다. API Key 값은 바꿀 필요가 없으며, 변수 이름만 업데이트하고 구성을 다시 로드하세요.
## 추가 리소스
* [Github](https://github.com/inferera/aihubmix/blob/main/packages/claude-code/README.md)
* [npm 패키지](https://www.npmjs.com/package/@aihubmix/claude-code)
* [공식 베스트 프랙티스](https://www.anthropic.com/engineering/claude-code-best-practices)
* [공식 설정 가이드](https://docs.anthropic.com/en/docs/claude-code/settings#settings-files)
Happy coding!
Last updated: 2026-06-10