Claude Code에 Qwen4 연결하기: 모델 설정과 연결 오류 해결
QwenCloud 엔드포인트, 키, 모델 매핑으로 Claude Code에 Qwen4-Max를 설정합니다. 401·403 오류와 CC Switch 모델 목록 오류를 구분해 진단합니다.
Claude Code에서 Qwen4-Max를 사용하려면 QwenCloud의 Anthropic 호환 Base URL, 해당 경로의 키, 명시적인 qwen4-max 모델 매핑을 설정해야 합니다. 모델 표시 이름만 바꿔서는 공급자가 바뀌지 않습니다. 모델 목록 확인이 성공해야만 대화를 할 수 있는 것도 아닙니다.
이 글은 2026년 11월 17일 확인한 QwenCloud 문서를 기준으로 합니다. qwen4-max-preview가 아닌 정식 모델을 다룹니다. 버전 구분이 필요하다면 Qwen4 API 연결 및 마이그레이션 가이드부터 확인하세요. 여기서는 코딩 클라이언트를 의도한 경로로 연결하고 어느 계층에서 실패했는지 찾는 데 집중합니다.
아래 셸 설정은 실제 모델 대신 설정 이름을 기록하는 가짜 클라이언트로 로컬 검증했습니다. 이 튜토리얼을 위해 유료 Qwen4 호출을 실행하지 않았습니다. 마지막 대화 및 공급자 과금 확인은 사용 권한이 있는 본인 계정에서 직접 수행해야 합니다.
키를 입력하기 전에 경로 선택하기
QwenCloud는 Token Plan과 지역별 종량제 경로를 구분해 안내합니다. 먼저 하나를 선택하세요. 한 경로의 키를 다른 경로에서 가져온 Base URL과 조합하면 안 됩니다.
| 사용할 경로 | Claude Code Base URL | 확인 사항 |
|---|---|---|
| QwenCloud Token Plan | https://token-plan.maas.qwencloudapi.com/apps/anthropic | 플랜 키와 선택한 모델의 이용 권한 |
| QwenCloud 종량제, 싱가포르 | https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic | 해당 지역에서 발급한 키와 모델 접근 권한 |
| 다른 QwenCloud 지역 | 해당 지역 문서의 Anthropic 호환 URL 사용 | 지역, 서비스 제공 여부, 키 적용 범위 |
이 주소들은 Base URL이며 완전한 메시지 요청 URL이 아닙니다. 이 설정에서는 QwenCloud Base URL에 /v1을 붙이지 마세요. 클라이언트가 그 아래 메시지 경로를 사용합니다. 연결 규칙은 QwenCloud Claude Code 가이드 (영문)와 지역 문서 (영문)를 기준으로 합니다.
Ofox API 키는 QwenCloud 키가 아닙니다. Ofox가 지원하는 다른 모델을 선택한다면 Ofox 인증 문서와 해당 통합 설정을 사용하세요. Ofox 키를 위 QwenCloud 주소에 입력하지 마세요. 이 글은 Ofox를 통한 Qwen4 제공 여부를 입증하지 않습니다. 최신 Ofox 모델 목록을 별도로 확인하세요.
Qwen4 설정이 명확한 별도 세션 실행하기
첫 진단에는 새 터미널 세션과 작은 합성 프로젝트를 사용하세요. 평소 설정은 백업해 둡니다. 다음 Bash 실행 스크립트가 내보내는 환경 변수는 자신의 프로세스와 하위 클라이언트에만 적용됩니다. 전역 설정 파일을 덮어쓰거나 키를 출력하거나 스크립트에 저장하지 않습니다.
launch-qwen4.sh로 저장하세요.
#!/usr/bin/env bash
set -euo pipefail
# Singapore pay-as-you-go. For Token Plan, replace only this route
# and enter the matching Token Plan key when prompted.
export ANTHROPIC_BASE_URL="https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic"
unset ANTHROPIC_API_KEY
read -r -s -p "QwenCloud key for this route: " ANTHROPIC_AUTH_TOKEN
printf '\n'
if [[ -z "$ANTHROPIC_AUTH_TOKEN" ]]; then
printf 'No key entered; no request sent.\n' >&2
exit 1
fi
export ANTHROPIC_AUTH_TOKEN
# Deliberately use one model while diagnosing routing.
export ANTHROPIC_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen4-max"
export CLAUDE_CODE_SUBAGENT_MODEL="qwen4-max"
export CLAUDE_CODE_MAX_CONTEXT_TOKENS="983616"
exec claude "$@"
테스트 프로젝트에서 bash launch-qwen4.sh를 실행합니다. Token Plan을 시험하려면 Base URL을 표의 Token Plan 주소로 바꾸고 그에 맞는 키를 입력하세요. 해당 경로에서 제공되는지 확인하기 전에 임의의 저렴한 모델 ID를 넣지 마세요.
모든 별칭을 Qwen4-Max로 매핑하는 것은 진단용 선택이며 비용 절감 권장이 아닙니다. 백그라운드 작업이나 하위 에이전트가 다른 설정 모델을 선택했는지에 대한 불확실성을 줄여 줍니다. 경로를 검증한 뒤에는 가벼운 작업을 다른 지원 모델로 명시적으로 매핑하고 별도 시험할 수 있습니다.
이 스크립트가 모든 관리 설정, 래퍼, IDE 확장 설정을 덮어쓰는 것은 아닙니다. 조직이 클라이언트를 관리한다면 해당 정책을 따르세요. IDE 설정이 다른 환경을 몰래 주입하지 않도록 이번 시험은 CLI를 직접 실행합니다. Windows에서는 맞는 WSL 또는 Git Bash 환경에서 이 Bash 예제를 실행하세요. 기본 PowerShell은 환경 변수 문법이 다릅니다. Windows CLI와 WSL 설치가 같은 설정을 읽는다고 가정하면 안 됩니다.
공급자와 작업 결과를 따로 검증하기
새 Claude Code 세션에서 /status를 실행합니다. 공급자 URL과 선택한 모델을 의도한 값과 대조하세요. 인증 정보가 담긴 원시 설정 덤프나 스크린샷은 공개하지 마세요. 경로가 비어 있거나 다른 곳을 가리킨다면 모델을 다시 바꾸기 전에 해당 클라이언트 프로세스가 읽은 설정부터 조사하세요.
비공개 저장소 내용이 필요 없는 작은 요청을 사용합니다.
Create a Python function named normalize_code(value).
It must accept a string, trim surrounding spaces and preserve leading zeros.
Raise TypeError for non-string input.
Add tests for " 0017 ", "", and the integer 17.
Do not install dependencies or access the network.
Show which files you changed and how to run the tests.
검증 기록은 다음 세 부분을 구분하면 유용합니다.
- 경로: 세션이 예상 공급자와 매핑을 표시하며, 공급자 요청 기록이 제공된다면 의도한 모델이 기록되어 있어야 합니다. 모델의 자기소개는 경로 증거가 아닙니다.
- 결과물: 파일이 존재하고
" 0017 "은"0017"로 바뀌며, 빈 문자열은 그대로이고, 정수 입력은TypeError를 발생시켜야 합니다. 생성된 테스트를 실행하고 diff를 살펴보세요. - 사용량 및 과금: 의도한 계정이나 플랜의 사용량 화면에 호출이 나타나야 합니다. 도구에 표시된 모델 이름으로 과금 출처를 추정하지 마세요.
답변이 좋아도 다른 계정에 청구되었다면 설정 검증에 통과한 것이 아닙니다. 경로는 맞지만 테스트가 실패한다면 연결 문제 대신 작업 실패로 기록하세요. 첫 실험은 작게 유지하고, 그다음 저장소 수정 범위를 넓히거나 긴 작업을 허용합니다.
증상으로 실패 계층 구분하기
공식 문제 해결 절 (영문)은 흔히 “Qwen이 안 된다”로 묶이는 여러 오류를 구분합니다.
| 증상 | 우선 확인 | 다음 조치 |
|---|---|---|
401 invalid_api_key | 키의 경로·지역과 실제 공급자 URL | 일치하는 QwenCloud 키로 수정하고 클라이언트를 재시작합니다. 로그에 키를 노출하지 마세요 |
| Claude Code가 계속 Anthropic에 연결됨 | /status와 이 프로세스가 읽은 설정 | 공급자 환경 변수·설정을 수정하고 래퍼 또는 충돌하는 인증을 확인합니다 |
| CC Switch가 모델 목록 엔드포인트를 찾지 못함 | 메시지가 아닌 모델 검색을 확인하는 요청인지 | 모델 매핑을 수동 지정한 뒤 문서에 나온 경로에서 실제 메시지를 시험합니다 |
모델 변경 후 403 AccessDenied | QwenCloud 갤러리의 모델 권한과 수명 주기 표시 | 사용할 수 없거나 폐기된 매핑을 현재 이용 가능한 모델로 바꾸고 오류·요청 ID를 보관합니다 |
| 구형 경로에서 모델을 바꿔도 변화 없음 | Base URL에 claude-code-proxy가 포함되는지 | 문서화된 /apps/anthropic 인터페이스로 이전합니다 |
| 긴 답변이 일찍 중단됨 | 클라이언트의 출력 제한과 응답 종료 사유 | 모델별 제한을 확인하고 작업을 줄이거나 클라이언트 한도를 의도적으로 조정합니다 |
사용자 지정 공급자 경로가 맞는데도 시작 시 공식 Anthropic 로그인을 요구한다면, QwenCloud FAQ에 따라 ~/.claude.json의 hasCompletedOnboarding: true도 확인하세요. 이는 ~/.claude/settings.json과 다른 파일입니다. JSON을 먼저 백업하고 필요한 필드만 병합하세요. 파일 전체를 교체하거나 조직 관리 설정을 바꾸지 마세요. 새 터미널에서 재시작합니다. 문서대로 설정해도 실패한다면 공식 설치 방법으로 클라이언트를 업데이트하고 실제 읽힌 설정을 다시 확인하세요.
모델 목록 오류는 특히 주의할 만합니다. QwenCloud 문서에 따르면 Anthropic 호환 경로는 /v1/messages를 제공하지만 모델 목록 엔드포인트는 제공하지 않습니다. 따라서 CC Switch의 검색 확인이 실패해도 실제 대화 경로는 사용 가능할 수 있습니다. 그렇다고 모든 404를 무시해도 된다는 뜻은 아닙니다. 메시지 URL 오류, 불필요한 경로 조각, 지원하지 않는 모델은 여전히 수정해야 합니다. 어떤 요청이 실패했는지 확인하세요.
직접 요청은 되는데 코딩 클라이언트만 계속 실패한다면 Claude Code 연결 문제 해결 가이드를 사용하세요. 정확한 모델 식별자를 사용할 수 없다면 OpenAI model-not-found 확인 절차 (영문)의 공급자·엔드포인트 확인 방법을 참고하세요. 인증서 오류는 모델 매핑이 아니라 TLS 및 인증서 문제 해결 (영문)의 대상입니다. 손쉬운 우회책으로 인증서 검증을 끄지 마세요.
컨텍스트와 출력 한도를 의도적으로 설정하기
현재 QwenCloud 가이드는 Qwen4-Max에서 CLAUDE_CODE_MAX_CONTEXT_TOKENS를 983616으로 유지하도록 안내합니다. 이 클라이언트 설정은 모델의 100만 토큰 컨텍스트와 같은 수치가 아니며, 값을 설정했다고 긴 작업의 성공이 입증되는 것도 아닙니다.
11월 17일판 가이드는 Qwen4-Max 출력이 잘릴 때 CLAUDE_CODE_MAX_OUTPUT_TOKENS=131072를 권장합니다. 같은 페이지의 프리뷰 안내는 64000을 사용합니다. 프리뷰 권장값을 정식 모델 설정에 섞지 마세요. 첫 연결 시험부터 최댓값을 지정할 필요는 없습니다. 허용 출력이 크면 실행 시간과 사용량이 늘 수 있습니다. 종료 사유를 살펴보고 작업에 맞는 한도를 선택하세요.
에이전트가 큰 참고 문서를 반복한다면 Qwen4 명시적 캐시 튜토리얼로 이어서 확인하세요. 큰 컨텍스트 창은 수용량 설정이고 캐시는 별도의 요청 규칙입니다. 관련 사용량 필드가 없다면 어느 쪽도 캐시 적중의 증거가 아닙니다.
복구 가능한 설정 기록 남기기
시험을 통과한 뒤 클라이언트 버전, 공급자 Base URL, 모델 매핑, 키의 유형과 지역, 시험 결과와 시각을 기록합니다. 키 자체는 평소 사용하는 비밀 정보 관리 수단에 저장하세요. 영구 설정을 바꿀 때는 기존 파일에 필요한 필드를 병합하고, 관련 없는 권한과 설정을 덮어쓰지 마세요.
이후 문제가 생기면 한 번에 변수 하나만 바꾸고 비밀 정보를 제거한 요청 ID, HTTP 상태, 오류 코드, 모델 ID를 남깁니다. 이 실행 스크립트의 효과를 되돌리려면 실행한 세션을 종료하고 부모 터미널에서 평소 클라이언트를 시작하면 됩니다. 부모 환경이나 설정 파일은 바뀌지 않았습니다. 영구 설정을 별도로 수정했다면 저장해 둔 버전도 복원하세요.
의도한 경로, 전달된 파일, 사용량 기록이 일치해야 설정이 완료됩니다. 이렇게 해야 매번 다른 경로를 디버깅하는 대신 실제 코딩 작업으로 모델을 비교할 수 있습니다.
자주 묻는 질문
- Claude Code에서 Qwen 모델 목록 엔드포인트가 필요한가요?
- 아니요. QwenCloud 문서에 따르면 Anthropic 호환 엔드포인트는 메시지를 제공하지만 모델 검색은 지원하지 않습니다. CC Switch의 모델 목록 확인 실패와 메시지 요청 실패는 다릅니다.
- Opus를 선택하면 Anthropic 모델이 실행되나요?
- 반드시 그렇지는 않습니다. 사용자 지정 공급자에서는 Opus 별칭이 Qwen4-Max에 매핑될 수 있습니다. 공급자, 정확한 모델 매핑, 공급자의 요청 기록을 확인하세요.


