Claude Code에 GLM과 ZAI를 연동하면 더욱 강력한 AI 개발 환경을 구축할 수 있습니다.
초기 설정과 환경 변수 등록만으로 즉각적인 성능 향상을 즉시 경험할 수 있습니다.
이러한 설정은 실무 환경에서 즉시 효과를 발휘하며 시스템의 안정성을 크게 높여줍니다.
왜 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 출시)을 다룹니다.
자주 묻는 질문 (FAQ)
Q1. Anthropic 계정이나 Claude 구독이 없어도 쓸 수 있나요?
Claude Code 프로그램은 그대로 두고 settings.json의 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN만 Z.ai 값으로 바꾸면 됩니다. 요청이 Anthropic이 아니라 Z.ai 서버로 가기 때문에 Z.ai 계정과 API 키만 있으면 동작합니다.
Q2. 설정을 바꿨는데 예전 그대로 동작합니다.?
새 터미널을 열지 않았을 가능성이 큽니다. 환경변수는 터미널이 켜질 때 한 번만 읽히므로, settings.json을 저장한 뒤에는 터미널을 완전히 닫고 새로 열어야 적용됩니다.
Q3. GLM-5.2와 1M 컨텍스트를 쓰려면 추가 설정이 필요한가요?
기본 설정으로는 한 단계 이전 모델에 연결됩니다. ANTHROPIC_DEFAULT_SONNET_MODEL과 ANTHROPIC_DEFAULT_OPUS_MODEL을 glm-5.2[1m]으로 지정하고 CLAUDE_CODE_AUTO_COMPACT_WINDOW를 1000000으로 맞춰야, Claude Code가 대화를 중간에 요약하지 않고 100만 토큰 컨텍스트를 실제로 활용합니다.
Q4. 인증 오류가 계속 납니다.?
ANTHROPIC_AUTH_TOKEN에 Anthropic 키가 아니라 Z.ai에서 발급받은 키가 들어 있는지 확인하세요. 두 회사의 키는 호환되지 않습니다. Z.ai 계정에 결제 수단이 등록되어 잔액이 있는지도 함께 확인이 필요합니다.
관련 글
- GLM(Z.ai) 실전 활용 꿀팁 모음 — Claude Code 연결 후 이렇게 쓰세요
- Z.ai 신규 API·모델 소개 — ZCode 출시로 달라진 것들
- 2026년 최고의 AI 코딩 도구 10선 — 무료/유료 완벽 가이드 (Cursor, Claude, Copilot)
