logo

Claude Code에서 GLM-5.2 사용하는 방법 (전체 설정)

마지막 업데이트: 2026-07-15 09:29:49

오늘 바로 Claude Code에서 GLM-5.2를 실행할 수 있으며, 설정은 약 2분 정도면 끝납니다. Claude Code는 Anthropic의 Messages API를 사용하는 어떤 엔드포인트와도 통신할 수 있고, Zhipu는 GLM을 위해 바로 그 방식으로 제공합니다 — Claude Code를 z.ai로 지정하면 끝입니다. 접근하는 방법은 두 가지입니다: 원클릭 전환 앱(가장 쉽고, 언제든지 Claude로 다시 전환할 수 있음) 또는 수동으로 편집하는 config 파일입니다. 이 가이드는 macOS, Windows, Linux 전반에서 두 방법 모두를 다루며, 필요할 때 Claude로 다시 전환하는 방법도 설명합니다.

가장 빠른 방법: CC 스위치

이미 둘 이상의 제공업체를 사용하고 있다면, 수동 설정은 건너뛰고 CC Switch(오픈 소스, MIT 라이선스, Windows/macOS/Linux)를 사용하세요. 이 앱은 Claude Code, Codex, Gemini CLI 및 몇 가지 다른 CLI의 제공업체 구성을 관리하는 데스크톱 앱이므로, JSON을 직접 편집할 필요가 없습니다.

1. ccswitch.io 또는 GitHub repo에서 CC Switch를 설치합니다. 메인 창 오른쪽 상단의 주황색 + 버튼을 클릭하여 Add Provider를 열고, Claude Provider 탭을 선택합니다. 2. preset 검색창에 zhipu를 입력합니다. 그러면 두 개의 preset — Zhipu GLM (중국 본토 엔드포인트)과 Zhipu GLM en — 이 표시됩니다. 중국 본토 외 지역에서는 국제 엔드포인트를 위해 Zhipu GLM en을 선택하세요.

CC Switch Add New Provider screen with "zhipu" typed in the preset search box, showing the Zhipu GLM and Zhipu GLM en presets under the Claude Provider tab

3. 아래로 스크롤하여 API Key 필드에 z.ai API 키를 붙여넣으세요. 프리셋이 나머지를 자동으로 채워줍니다: Anthropic Messages (Native) 형식, ANTHROPIC_AUTH_TOKEN 인증 필드, 그리고 기본 URL.

4. Model Mapping에서 Sonnet, Opus, Fable, Haiku의 각 역할마다 요청된 모델을 glm-5.2로 설정하여, Claude Code가 어떤 계층을 선택하든 모든 요청이 GLM으로 라우팅되도록 합니다. 역할에서 1M 상자를 선택하여 million-token 컨텍스트를 Claude Code에 선언합니다. 저장하세요.

CC Switch Edit Provider model-mapping table with Sonnet, Opus, Fable, and Haiku roles all set to glm-5.2, using Anthropic Messages Native format and ANTHROPIC_AUTH_TOKEN

5. provider 목록으로 돌아가서 Zhipu GLM 항목에서 Enable을 클릭하세요(Claude Official 같은 기존 provider는 나중에 다시 전환할 수 있도록 목록에 그대로 둘 수 있습니다). 그런 다음 Claude Code를 다시 시작해 새 provider가 적용되었는지 확인하세요. /status를 실행하여 모델이 glm-5.2로 표시되는지 확인합니다.

CC Switch provider list showing Zhipu GLM with its Enable button, alongside a Claude Official provider to switch back to

정적 config 대신 앱을 굳이 써야 하는 이유: Kimi, MiniMax, MiMo, Qwen, DeepSeek 등 시도해 보고 싶은 대부분의 provider에 대한 preset이 포함되어 있어, 각각을 config를 다시 쓰는 대신 preset과 key만 설정하면 되고, 이들 사이를 전환하거나(또는 Claude로 다시 돌아가거나) 하는 것도 몇 번의 클릭이면 됩니다. 이것이 아래 하이브리드 workflow의 실질적인 기반입니다.

settings.json을 사용한 수동 설정

직접 설정하는 것을 선호하시거나, GUI가 없는 CI 박스를 설정하시나요? 파일을 직접 편집하세요.

1. API 키를 받으세요 Z.AI API 콘솔에서. 종량제 키 또는 GLM Coding Plan 구독 키 모두 사용할 수 있습니다. 2. 이 env 블록을 Claude Code 설정 파일에 병합하세요 (기존 키는 유지하세요 — 전체 파일을 덮어쓰지 마세요). 이 블록은 모든 플랫폼에서 동일하며, 경로만 다릅니다: - macOS / Linux: ~/.claude/settings.json - Windows: %USERPROFILE%\.claude\settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_zai_api_key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-5.2",
    "API_TIMEOUT_MS": "3000000"
  }
}

3. Claude Code를 다시 시작한 다음 /status를 실행하세요. 모델 줄에는 glm-5.2가 표시되어야 합니다(백만 토큰 변형의 경우 glm-5.2[1m]). 여전히 Claude 모델이 표시된다면 파일이 반영되지 않은 것입니다 — JSON 구문 오류를 확인하고 경로를 다시 확인하세요.

파일을 건드리고 싶지 않다면, 셸 기반 대안 두 가지가 있습니다:

  • macOS / Linux — 일회성 세션을 위해 변수(bash/zsh)를 export한 다음 실행하세요:

export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="your_zai_api_key"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5.2"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-5.2"
claude

터미널을 닫으면 평소 설정으로 돌아갑니다.

  • Windows — PowerShell에서 지속적인 사용자 환경 변수를 설정한 다음 터미널을 다시 시작하세요:

setx ANTHROPIC_BASE_URL "https://api.z.ai/api/anthropic"
setx ANTHROPIC_AUTH_TOKEN "your_zai_api_key"
setx ANTHROPIC_DEFAULT_OPUS_MODEL "glm-5.2"
setx ANTHROPIC_DEFAULT_SONNET_MODEL "glm-5.2"
setx ANTHROPIC_DEFAULT_HAIKU_MODEL "glm-5.2"

ANTHROPIC_DEFAULT_* 변수는 Claude Code가 라우팅하는 모델 역할을 재매핑합니다 — Opus, Sonnet, 그리고 Haiku(새로운 빌드에서는 Fable 역할이 추가되며, CC Switch도 이를 노출합니다). 이들을 모두 glm-5.2로 설정하면 모든 요청이 GLM으로 전송됩니다. 백그라운드 작업을 저렴하고 빠르게 유지하고 싶다면, 대신 Haiku 슬롯을 glm-4.5-air로 지정하세요. 전체 100만 토큰 창을 사용하려면 glm-5.2[1m]을 사용하세요. 긴 API_TIMEOUT_MS는 보이는 것보다 더 중요합니다: GLM 응답은 종종 Claude보다 느리게 실행되며, 기본 타임아웃은 긴 생성 결과를 중간에서 끊어버립니다.

어떤 경로를 선택할까요: z.ai 네이티브, 프록시, 아니면 Coding Plan?

GLM-5.2를 Claude Code에 연결하는 세 가지 실용적인 방법이 있으며, 이들은 서로 대체할 수 없습니다.

z.ai 네이티브 엔드포인트(권장). 위의 https://api.z.ai/api/anthropic URL입니다. Anthropic 프로토콜을 지원하므로 Claude Code가 미들웨어 없이 연결됩니다 — 기본 선택입니다.

번역 프록시. 다른 호스트(Fireworks, NVIDIA NIM, self-hosted weights)는 OpenAI 호환 API로 GLM-5.2를 제공하지만 Claude Code가 이를 직접 읽을 수는 없으므로, 형식을 변환해 주는 프록시가 필요합니다. claude-code-router가 이를 처리합니다. 이미 해당 플랫폼 중 하나에서 크레딧이나 하드웨어를 보유하고 있을 때만 가치가 있습니다.

GLM Coding Plan 구독. 동일한 z.ai 엔드포인트를 사용하지만 토큰당 과금 대신 고정 요금을 부과하는 월정액 플랜입니다($18/월부터, z.ai의 구독 페이지 기준). Claude Code를 매일 사용한다면, 구독은 보통 토큰 사용량 기반 과금보다 더 저렴하고 예측 가능성이 높습니다. 손익분기점을 찾으려면 월간 토큰 사용량과 비교해 계산해 보세요. 사용량이 들쭉날쭉하다면, 사용한 만큼 내는 방식이 더 유리합니다.

GLM-5.2와 Claude 간 전환

Claude Code는 한 번에 하나의 활성 provider만 사용하므로, 슬롯을 나누기보다 *전환*합니다: 일반적인 대량 작업에는 GLM-5.2를 실행하고, 아키텍처, 보안 민감한 코드 또는 리뷰를 위해 Claude가 필요할 때는 CC Switch에서 Claude Official provider를 활성화하세요. Claude 쪽에는 Anthropic-compatible endpoint라면 무엇이든 사용할 수 있습니다 — Anthropic 계정이나 AIReiter와 같은 릴레이 등, 여러 विकल्प 중 하나입니다. provider 간 요청별 자동 라우팅을 원한다면, claude-code-router 같은 gateway가 디스패치를 처리합니다.

문제 해결

증상

가능한 원인

해결 방법

/status에 여전히 Claude 모델이 표시됨

settings.json이 로드되지 않음

JSON이 유효한지 확인하고, ~/.claude/settings.json을 수정했는지 확인하며, Claude Code를 다시 시작하세요

model not found 오류

잘못된 모델 ID(대소문자 구분)

glm-5.2, glm-5.2[1m], 또는 glm-4.5-air를 정확히 사용하세요

401 / 인증 실패

키/엔드포인트 불일치

OpenRouter 키를 z.ai URL과 함께 사용하지 마세요; 필요하면 키를 다시 생성하세요

긴 생성이 중간에 끊김

타임아웃이 너무 낮음

API_TIMEOUT_MS를 높게 설정하세요(예: 3000000)

도구 호출이 실패하거나 반복됨

형식이 잘못된 도구 JSON

병렬 서브에이전트를 줄이고; 다시 시도하고; 지시를 단순화하세요

자주 묻는 질문

Claude Code에서 GLM-5.2는 무료인가요?

무제한은 아니지만, z.ai는 GLM-5.2에 대해 기간 한정 무료 이용 기간을 운영한 적이 있으며, Coding Plan은 월 $18부터 시작합니다. 정가 사용량 기준 요금($1.40 / 100만, $4.40 / 100만)으로도, 가벼운 사용이라면 비용은 몇 센트에 불과합니다.

GLM-5.2는 Claude Code에서 1M 토큰 컨텍스트를 지원하나요?

예. ANTHROPIC_DEFAULT_* 변수에서 모델 ID를 glm-5.2 대신 glm-5.2[1m]으로 설정하면 Claude Code가 백만 토큰 윈도우를 사용합니다.

Claude Code에서 코딩하기에 GLM-5.2와 Claude 중 어느 것이 더 좋나요?

일반적이고 순차적인 편집에서는 가격 차이 때문에 GLM-5.2가 합리적인 기본 선택입니다. Claude는 다단계 아키텍처, 보안에 민감한 작업, 그리고 높은 동시성의 서브에이전트 워크플로에서 앞서는 경향이 있습니다. 전환 설정을 사용하면 하나를 고르는 대신 각 모델을 가장 강한 부분에 활용할 수 있습니다.

Claude Code 이외의 도구에서 GLM-5.2를 사용할 수 있나요?

네. 동일한 z.ai 엔드포인트와 키는 다른 agentic CLI와도 작동합니다. OpenCode, Cline, Kilo Code는 모두 사용자 지정 base URL을 지원하며, CC Switch는 그중 여러 항목의 프리셋을 관리합니다.

Claude Code에서 GLM-5.2를 사용하려면 유료 Claude 구독이 필요한가요?

아니요. Claude Code는 단지 클라이언트일 뿐입니다. z.ai로 연결하면 요금은 Anthropic이 아니라 z.ai에서 청구됩니다. Claude 계정이 필요한 경우는 Claude를 전환 가능한 제공자로 계속 사용할 때뿐입니다.

CC Switch에서 제공업체를 전환한 후 Claude Code를 다시 시작해야 하나요?

CC Switch의 문서에 따르면, Claude Code는 재시작 없이 제공자 데이터를 핫 스위칭할 수 있지만, 대부분의 다른 CLI 도구는 터미널이나 앱 재시작이 필요합니다. 실제로는 스위치가 적용되었는지 확실히 하려면 Claude Code를 재시작하는 것이 가장 신뢰할 수 있는 방법입니다.

CC Switch에서 Claude(공식 로그인)로 다시 전환하려면 어떻게 하나요?

프리셋 목록에서 Claude Official 공급자를 추가하고 활성화한 다음, Claude Code의 일반적인 로그아웃 / 로그인(OAuth) 절차를 한 번 실행하세요. 그 후에는 공식 Claude 로그인과 z.ai 같은 타사 공급자 사이를 자유롭게 전환할 수 있습니다.

CC Switch는 무료이고 사용해도 안전한가요?

네 — MIT 라이선스에 따라 오픈소스이며 무료입니다. 설정은 SQLite 데이터베이스에 로컬로 저장되고 원자적 쓰기를 사용하며, 설계상 각 도구 자체의 설정에는 최소한의 변경만 가하므로 앱을 제거해도 CLI는 평소처럼 계속 작동합니다.

관련 읽을거리