왜 Claude Code에 GLM을 연결할까?
Claude Code는 터미널에서 코드를 대신 짜고 고쳐주는 AI 코딩 도구입니다. 기본 설정 그대로 쓰면 Anthropic의 Claude 모델이 동작하지만, 설정 파일 하나만 고치면 중국 Zhipu AI의 GLM 시리즈(Z.ai 제공) 같은 다른 회사 모델로도 똑같이 쓸 수 있습니다.
왜 굳이 바꿀까요? 이유는 단순합니다.
- 비용 — GLM Coding Plan은 월 $18부터 시작합니다. Claude의 상위 요금제(월 $100대)와 비교하면 약 5분의 1 수준입니다.
- 성능 — 최신 GLM-5.2는 코딩 벤치마크에서 Claude Opus 바로 아래급 성능을 냅니다. 일반적인 개발 작업에는 충분합니다.
- 컨텍스트 — GLM-5.2는 최대 100만(1M) 토큰까지 다루는 긴 컨텍스트를 지원합니다. 큰 코드베이스를 통째로 넣고 작업할 때 유리합니다.
핵심 원리: Claude Code가 하는 일을 단순하게 보면, 요청을 어떤 주소로 보내고 그 서비스의 열쇠(API 키)로 인증하는 것뿐입니다. 이 주소와 열쇠 두 가지만 바꾸면 화면은 그대로인 채 속만 다른 모델로 바뀝니다.
시작 전 준비물
- Claude Code가 이미 설치되어 있어야 합니다 (터미널에서
claude --version입력 시 버전이 나오면 설치된 상태) - Node.js 18 이상
- Z.ai(Zhipu AI)에 가입하고 API 키를 발급받아 복사해 둘 것
- Windows 터미널에서 쓰는지, WSL(리눅스) 안에서 쓰는지 미리 정해둘 것 (설정 파일 위치가 다릅니다)
1단계: 설정 파일(settings.json) 위치 찾기
Windows에서 쓰는 경우
사용자 홈 폴더 아래 .claude 폴더에 있습니다.
C:\Users\사용자이름\.claude\settings.json파일이 없다면 새로 만들어도 됩니다. 메모장이나 VS Code로 열면 됩니다.
WSL(리눅스)에서 쓰는 경우
홈 디렉터리 기준 경로입니다.
~/.claude/settings.json터미널에서 nano ~/.claude/settings.json 또는 code ~/.claude/settings.json으로 열 수 있습니다.
2단계: 주소와 열쇠 넣기 (핵심 단계)
settings.json 파일에 아래 내용을 넣습니다. 파일이 비어 있지 않다면 기존 내용을 지우지 말고 env 항목만 추가/병합하세요.
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
"ANTHROPIC_AUTH_TOKEN": "여기에-발급받은-Z.ai-키를-붙여넣기",
"API_TIMEOUT_MS": "3000000"
}
}| 키 | 의미 |
|---|---|
ANTHROPIC_BASE_URL |
요청을 보낼 주소. Z.ai 호환 주소로 교체합니다. |
ANTHROPIC_AUTH_TOKEN |
Z.ai에서 발급받은 API 키. Anthropic 키와는 호환되지 않으니 반드시 Z.ai 키를 넣어야 합니다. |
API_TIMEOUT_MS |
응답을 기다리는 최대 시간(밀리초). 다른 회사 모델은 가끔 응답이 느릴 수 있어 넉넉히 잡아두는 편이 안전합니다. |
모델 이름을 직접 지정하는 옵션(ANTHROPIC_DEFAULT_SONNET_MODEL 등)도 있지만, 처음에는 적지 않는 것을 권장합니다. 비워두면 Z.ai 서버가 알아서 자기네 기본 모델로 연결해주기 때문에, 모델 이름이 바뀌어도 신경 쓸 필요가 없습니다.
3단계: 새 터미널에서 확인하기
설정 파일을 저장한 뒤에는 반드시 새 터미널 창을 열어야 적용됩니다. 기존에 열려 있던 터미널은 예전 설정을 그대로 들고 있습니다.
claude "간단한 파이썬 함수 하나 짜줘"정상적으로 응답이 오면 연결 성공입니다. 응답 속도나 말투가 평소와 다르게 느껴진다면, 이미 GLM으로 잘 연결된 것입니다.
최신 GLM-5.2와 1M 컨텍스트 켜기
GLM의 최신 모델은 GLM-5.2입니다. 2026년 6월 공개됐고, 최대 100만 토큰까지 다루는 긴 컨텍스트를 지원합니다. 기본 설정으로는 한 단계 이전 모델에 연결되므로, 최신 모델과 1M 컨텍스트를 쓰려면 모델을 직접 지정해야 합니다.
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
"ANTHROPIC_AUTH_TOKEN": "여기에-발급받은-키",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000"
}
}모델 이름 뒤의 [1m]이 100만 토큰 컨텍스트를 켜는 표시입니다. CLAUDE_CODE_AUTO_COMPACT_WINDOW를 1000000으로 맞춰야 Claude Code가 대화를 중간에 요약해서 줄이지 않고 그 큰 컨텍스트를 실제로 활용합니다.
Z.ai가 제공하는 모델 라인업
Z.ai 플랫폼에서 API로 쓸 수 있는 주요 모델은 다음과 같습니다.
| 모델 | 용도 |
|---|---|
| GLM-5.2 | 코딩용 최상위 모델. 최대 1M 토큰 컨텍스트 지원. |
| GLM-5V-Turbo | 이미지를 이해하는 멀티모달 모델. 화면 캡처 보고 코딩하는 용도에 적합. |
| GLM-Image | 텍스트로 이미지를 생성하는 모델. |
| CogVideoX-3 | 영상/프레임 생성 모델. |
REST API, 공식 Python SDK(zai-sdk), Java SDK 외에도 OpenAI SDK 호환 방식(Python/Node.js/Java)을 그대로 지원해서, 기존에 OpenAI SDK로 짜둔 코드가 있다면 주소만 바꿔서 재사용할 수 있습니다.
자주 막히는 문제
설정을 바꿨는데 그대로예요
새 터미널을 열지 않고 기존 터미널을 계속 쓰고 있을 확률이 높습니다. 환경변수는 터미널이 켜질 때 한 번 읽히기 때문에, 파일을 고친 뒤에는 반드시 터미널을 완전히 닫고 새로 열어야 합니다.
인증 오류가 나요
ANTHROPIC_AUTH_TOKEN에 Anthropic 키가 아니라 Z.ai에서 발급받은 키가 들어 있는지 확인하세요. 두 회사의 키는 서로 호환되지 않습니다. 또한 Z.ai 계정에 결제 수단이 등록되어 잔액이 있는지도 확인이 필요합니다.
응답이 중간에 끊겨요
API_TIMEOUT_MS 값을 늘려보세요. 다른 회사 모델은 트래픽이 몰릴 때 Anthropic보다 응답이 느릴 수 있습니다.
다시 원래 Claude로 돌아가고 싶어요
settings.json에 추가했던 env 항목을 지우거나, 파일 자체를 원래 상태로 되돌리면 됩니다. 별도 프로그램을 설치한 게 아니기 때문에 되돌리기도 파일 하나만 고치면 끝입니다.
마무리
여기까지 따라오셨다면, 설정 파일 하나를 고치는 것만으로 Claude Code에 GLM 모델을 연결할 수 있다는 걸 확인하셨을 겁니다. 핵심은 주소와 열쇠 두 가지뿐이고, 이 원리는 다른 회사 모델을 쓸 때도 동일하게 적용됩니다.
이어지는 2탄에서는 GLM을 실제로 쓰면서 도움이 되는 실전 꿀팁 모음을 다룹니다. 3탄에서는 Z.ai가 새로 공개한 신규 API·모델 소식(ZCode 출시)을 다룹니다.
