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

Claude Code에서 GLM-5.2를 바로 쓸 수 있다. 설정에 걸리는 시간도 약 2분이면 충분하다. Claude Code는 Anthropic Messages API를 지원하는 엔드포인트와 통신하며, Zhipu는 GLM용으로 해당 API를 제공한다. 즉, Claude Code의 연결 주소를 z.ai로 바꾸기만 하면 된다. 가장 간단한 방법은 클릭 몇 번으로 전환할 수 있는 앱을 쓰는 것이고, 직접 설정 파일을 수정하는 방법도 있다. 이 글에서는 macOS, Windows, Linux에서 두 방식을 모두 설정하고, 필요할 때 Claude로 돌아가는 방법까지 정리한다.

가장 간단한 방법: CC Switch

여러 AI 제공업체를 오가며 쓴다면 수동 설정 대신 CC Switch를 쓰는 편이 편하다. Windows/macOS/Linux에서 동작하는 MIT 라이선스 오픈소스 데스크톱 앱으로, Claude Code뿐 아니라 Codex, Gemini CLI 등 여러 CLI의 제공업체 설정을 관리한다. JSON 파일을 매번 직접 고칠 필요가 없다.

1. ccswitch.io 또는 GitHub repo에서 CC Switch를 설치한다. 메인 창 오른쪽 위의 주황색 + 버튼을 눌러 Add Provider를 열고, Claude Provider 탭을 선택한다.
2. 프리셋 검색창에 zhipu를 입력한다. Zhipu GLM(중국 본토 엔드포인트)과 Zhipu GLM en 두 프리셋이 표시된다. 중국 본토 외 지역에서는 국제 엔드포인트용 Zhipu GLM en을 선택하면 된다.

1. 아래로 스크롤한 뒤 API Key 필드에 z.ai API 키를 붙여 넣는다. 프리셋이 Anthropic Messages (Native) 형식, ANTHROPIC_AUTH_TOKEN 인증 필드, 베이스 URL을 자동으로 채운다.
2. Model Mapping에서 Sonnet, Opus, Fable, Haiku 각 역할의 요청 모델을 모두 glm-5.2로 설정한다. 이렇게 하면 Claude Code가 어느 티어를 선택하든 모든 요청이 GLM으로 전송된다. 해당 역할에 100만 토큰 컨텍스트를 선언하려면 1M 상자를 체크한다. 이후 저장한다.

1. 제공업체 목록으로 돌아가 Zhipu GLM 항목의 Enable을 클릭한다. 나중에 다시 전환할 수 있도록 Claude Official 같은 기존 제공업체는 목록에 남겨둬도 된다. 새 제공업체가 확실히 반영되도록 Claude Code를 재시작한 뒤 /status를 실행한다. 모델이 glm-5.2로 표시되면 정상이다.

고정된 설정 파일 대신 앱을 쓸 이유는 명확하다. Kimi, MiniMax, MiMo, Qwen, DeepSeek 등 시험해 볼 만한 대부분의 제공업체에 프리셋이 준비되어 있다. 설정을 처음부터 다시 작성할 필요 없이 프리셋을 고르고 키만 넣으면 되며, 제공업체 간 전환이나 Claude 복귀도 몇 번의 클릭으로 끝난다. 아래에서 설명할 하이브리드 워크플로의 기반이기도 하다.

settings.json으로 직접 설정하기

직접 구성하고 싶거나 GUI 없는 CI 환경에서 설정해야 한다면 파일을 바로 편집하면 된다.

1. Z.AI API console에서 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"
  }
}

1. Claude Code를 재시작하고 /status를 실행한다. 모델 줄에 glm-5.2 또는 100만 토큰 버전인 glm-5.2[1m]가 표시되어야 한다. 여전히 Claude 모델이 나온다면 파일을 불러오지 못한 것이다. JSON 문법 오류가 없는지, 경로가 맞는지 확인한다.

파일을 수정하고 싶지 않다면 셸에서 설정하는 방법도 두 가지가 있다.

• macOS / Linux — 일회성 세션용으로 변수를 export한 다음 실행한다(bash/zsh).

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이며, 최신 빌드에는 CC Switch에서도 노출하는 Fable 역할이 추가된다. 모두 glm-5.2로 지정하면 모든 요청이 GLM으로 향한다. 백그라운드 작업은 저렴하고 빠르게 처리하고 싶다면 Haiku 슬롯만 glm-4.5-air로 지정하는 방법도 있다. 전체 100만 토큰 컨텍스트 창을 쓰려면 glm-5.2[1m]을 사용한다. 길게 잡은 API_TIMEOUT_MS도 생각보다 중요하다. GLM 응답은 Claude보다 느린 경우가 많고, 기본 타임아웃에서는 긴 생성 작업이 중간에 끊길 수 있다.

z.ai 직접 연결, 프록시, Coding Plan 중 무엇을 써야 할까

Claude Code에 GLM-5.2를 연결하는 실용적인 방법은 세 가지이며, 서로 완전히 대체되는 방식은 아니다.

z.ai 네이티브 엔드포인트(권장). 위에서 사용한 https://api.z.ai/api/anthropic URL이다. Anthropic 프로토콜을 그대로 지원하므로 미들웨어 없이 Claude Code가 연결할 수 있다. 기본 선택지로 가장 적합하다.

형식 변환 프록시. Fireworks, NVIDIA NIM, 자체 호스팅 가중치 등 다른 호스트는 GLM-5.2를 OpenAI 호환 API로 제공한다. Claude Code는 이를 직접 읽지 못하므로 포맷을 변환하는 프록시가 필요하다. claude-code-router가 이 역할을 한다. 이미 해당 플랫폼에 크레딧이나 하드웨어가 있는 경우에만 고려할 만하다.

GLM Coding Plan 구독. z.ai의 구독 페이지 기준 월 $18부터 시작하는 정액제다. 같은 z.ai 엔드포인트를 쓰지만 토큰당 과금 대신 고정 요금을 낸다. Claude Code로 매일 코딩한다면 대체로 종량제보다 비용 예측이 쉽고 저렴하다. 월간 토큰 사용량과 비교해 손익분기점을 계산해 보면 된다. 사용량이 들쭉날쭉하다면 종량제가 유리하다.

GLM-5.2와 Claude를 오가는 방법

Claude Code는 한 번에 하나의 활성 제공업체만 사용한다. 슬롯을 나눠 쓰는 방식이 아니라 전환하는 방식이다. 일상적인 대량 작업은 GLM-5.2로 처리하고, 아키텍처 설계나 보안에 민감한 코드, 리뷰가 필요할 때는 CC Switch에서 Claude Official 제공업체를 활성화하면 된다. Claude 측에는 Anthropic 계정이나 여러 선택지 중 하나인 AIReiter 같은 릴레이 등, Anthropic 호환 엔드포인트라면 무엇이든 사용할 수 있다. 제공업체별 요청 자동 라우팅이 필요하다면 claude-code-router 같은 게이트웨이가 분배를 맡는다.

문제 해결

자주 묻는 질문

Claude Code에서 GLM-5.2를 무료로 쓸 수 있나?

무제한 무료는 아니다. 다만 z.ai는 GLM-5.2에 한시적 무료 이용 기간을 제공한 적이 있으며, Coding Plan은 월 $18부터 시작한다. 종량제 정가도 100만 토큰당 $1.40 / $4.40이므로 가벼운 사용량이라면 비용은 몇 센트 수준이다.

Claude Code에서 GLM-5.2의 100만 토큰 컨텍스트를 지원하나?

지원한다. ANTHROPIC_DEFAULT_* 변수에서 모델 ID를 glm-5.2 대신 glm-5.2[1m]로 설정하면 Claude Code가 100만 토큰 컨텍스트 창을 사용한다.

Claude Code 코딩에는 GLM-5.2와 Claude 중 어느 쪽이 더 나은가?

일상적인 순차 편집 작업에서는 가격 차이 때문에 GLM-5.2가 합리적인 기본 선택이다. 반면 여러 단계가 얽힌 아키텍처 작업, 보안에 민감한 업무, 높은 동시성의 서브에이전트 워크플로에서는 Claude가 앞서는 경향이 있다. 전환 설정을 해두면 하나만 고르지 않고 각 모델이 강한 작업에 맞춰 쓸 수 있다.

Claude Code 외 다른 도구에서도 GLM-5.2를 쓸 수 있나?

가능하다. 동일한 z.ai 엔드포인트와 키를 다른 에이전트형 CLI에서도 사용할 수 있다. OpenCode, Cline, Kilo Code는 모두 사용자 지정 베이스 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는 정상적으로 계속 동작한다.

함께 읽으면 좋은 글

• GLM-5.2 API: 접근 방법과 가격
• 코딩용 GLM-5.2 vs Opus 4.6
• Codex vs Claude Code