GLM 사용법: Claude Code에 Coding Plan 연결하기

Windows의 Claude Code에서 GLM Coding Plan을 쓰려면 사용자 설정 파일에 플랜 키, Anthropic 호환 URL, 사용할 GLM 모델을 넣는다. glm-5.3-flash[1m]을 지정해 저장한 뒤, 새 터미널에서 모델 상태와 작은 파일 읽기까지 확인한다.

Claude Code라는 프로그램에 GLM을 연결하는 과정이다. Z.AI 구독만으로 Anthropic의 Claude 모델 사용권이 생기는 것은 아니다. 자신의 Python 앱이나 웹서비스에서 GLM을 부르려면 일반 GLM API 가이드를 사용한다.

1. 플랜 키와 설치 환경을 준비한다

Z.AI Coding Plan 시작 문서에서 구독을 준비한다. 개인 플랜 키는 Individual Coding Plan → Plan Overview, 팀 키는 Team Coding Plan → My Plan에서 얻는다. 팀의 사용량을 쓰려면 팀 키여야 한다. (Z.AI — Usage Policy)

Claude Code가 이미 있다면 PowerShell에서 claude --version으로 설치를 확인하고 다음 절로 넘어간다. 없다면 Claude Code 자체의 현재 Windows 공식 설치 안내를 먼저 따른다. Anthropic은 네이티브 설치를 권장한다. (Claude Code Quickstart)

PowerShell에서 설치하려면:

irm https://claude.ai/install.ps1 | iex
claude --version

패키지 관리자를 선호하면 WinGet도 사용할 수 있다.

winget install Anthropic.ClaudeCode
claude --version

네이티브 설치는 백그라운드 자동 업데이트를 지원하고, WinGet 설치는 기본적으로 winget upgrade Anthropic.ClaudeCode로 직접 갱신한다. Git for Windows는 네이티브 Windows에서 권장되지만 필수는 아니다. 설치하지 않으면 Claude Code가 셸 도구로 PowerShell을 사용한다. (Claude Code Windows 설치 조건) GLM 연결에 Node.js 18과 npm 설치는 필수가 아니다.

Z.AI의 Claude Code 연결 문서에는 npm 설치 예가 남아 있을 수 있지만, Claude Code 프로그램 설치 조건은 Anthropic의 현재 문서를, GLM Coding Plan endpoint·키·모델 매핑은 Z.AI 문서를 각각 따른다. claude --version이 실제 버전을 출력한 뒤에만 다음 설정으로 넘어간다.

2. 기존 설정을 보관하고 필요한 값만 바꾼다

설정 파일은 %USERPROFILE%\.claude\settings.json이다. 다른 연결에 쓰던 파일이 있다면 사본을 별도 위치에 보관한다. PowerShell에서 파일을 연다. (Z.AI — Claude Code 연결)

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude" | Out-Null
notepad "$env:USERPROFILE\.claude\settings.json"

새 파일이면 아래 JSON을 붙여 넣고 YOUR_CODING_PLAN_KEY만 자신의 키로 바꾼다. 기존 파일이 있다면 전체를 덮어쓰지 말고 기존 env 안의 해당 항목만 추가·수정한다. 같은 키를 두 번 만들거나 JSON 마지막 항목 뒤에 쉼표를 붙이지 않는다.

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_CODING_PLAN_KEY",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-5.3-flash[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.3-flash[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.3-flash[1m]"
  }
}

여기서는 세 별칭을 같은 Flash 모델로 명시했다. 별칭별 모델을 다르게 배치하려면 현재 모델 전환 문서의 지원 ID를 적용한다. 이 고정 설정은 향후 Z.AI의 자동 기본 모델 변경을 따라가는 설정과 다르다.

설정을 저장한 뒤 PowerShell에서 JSON 문법만 검사할 수 있다. 아래 명령은 키 내용을 화면에 출력하지 않는다.

Get-Content -Raw "$env:USERPROFILE\.claude\settings.json" | ConvertFrom-Json | Out-Null

오류가 나오면 괄호·따옴표·쉼표를 고친다. 문법 검사가 통과하면 다음 절에서 키와 모델 연결을 확인한다.

3. 새 터미널에서 상태와 파일 읽기를 확인한다

기존 Claude Code를 종료하고 새 PowerShell을 연다. 시험 폴더와 짧은 파일을 만든 뒤 Claude Code를 시작한다.

New-Item -ItemType Directory -Force "$env:USERPROFILE\glm-code-test" | Out-Null
Set-Location "$env:USERPROFILE\glm-code-test"
Set-Content -LiteralPath note.txt -Value 'test-total=3000' -Encoding utf8
claude

처음 표시되는 폴더 신뢰·권한 안내는 방금 만든 시험 폴더인지 보고 선택한다. 대화창에서 /status를 입력해 불러온 설정 파일과 모델 상태를 본다. 다른 프로젝트의 설정이나 예전 모델이 적용됐다면 실제로 읽힌 파일을 먼저 확인한다.

이어서 요청한다.

현재 폴더의 note.txt를 읽고 test-total 값을 답해줘.
파일을 수정하거나 명령을 실행할 필요는 없어.

기대 결과는 3000이다. 응답이 그 값을 읽었는지, 원본 파일이 그대로인지 확인한다. 설정 파일을 저장했다는 사실뿐 아니라 모델이 파일 도구의 결과를 받아 응답하는 흐름까지 확인하는 작은 시험이다.

화면에 sonnet·opus 같은 별칭이 남아 있으면 실제 settings.json 매핑과 /status, Z.AI 플랜의 사용 기록을 함께 대조해 호출된 모델을 확인한다.

연결 오류는 이 순서로 좁힌다

증상	해결 순서
설정 파일 읽기 오류	JSON 검사로 문법을 고친 뒤 새 터미널에서 재실행
예전 모델·공급자가 계속 표시됨	/status의 실제 설정 파일과 남아 있는 모델 매핑 확인
인증 실패	플랜 키 종류와 ANTHROPIC_AUTH_TOKEN 값 대조. 팀이면 팀 키 사용
[1m] 모델 표기를 처리하지 못함	먼저 claude --version을 확인한다. 네이티브 설치는 업데이트 상태를 확인하고, WinGet이면 winget upgrade Anthropic.ClaudeCode 후 현재 Z.AI 모델 전환 문서와 대조
HTTP 429	상세 코드·메시지를 읽고 사용량, 갱신 시각, 플랜 만료, 모델 이용 자격을 구분

인증 실패는 실제로 이렇게 보인다. Techies Note가 9월 25일 Claude Code 설정에 넣는 Anthropic 호환 주소(https://api.z.ai/api/anthropic)에 일부러 틀린 키로 요청하니 HTTP 401과 함께 다음 본문이 돌아왔다.

{"error":{"message":"token expired or incorrect","type":"401"}}

Claude Code 화면에 이 문구가 보이면 ANTHROPIC_AUTH_TOKEN에 넣은 키를 먼저 본다. 키가 만료됐거나 잘못 들어간 경우이며, 앞뒤에 공백·따옴표가 함께 들어간 경우도 흔하다. 같은 키로 코딩 플랜용 OpenAI 호환 주소(https://api.z.ai/api/coding/paas/v4)를 호출해도 같은 문구가 나왔다.

429 오류는 상세 코드로 원인을 구분한다. Z.AI의 1309는 플랜 만료, 1310은 주간·월간 한도, 1311은 해당 모델의 이용 자격을 가리킨다. 한도가 원인이면 Coding Plan quota 관리에서 자신의 갱신 창과 모델별 소비량을 확인한다. (Z.AI — 오류 코드)

연결을 되돌릴 때는 실행 중인 Claude Code를 종료하고 처음 보관한 설정에서 이번에 바꾼 항목을 복원한 뒤 새 터미널을 연다. 작업 중 다른 설정까지 바꿨다면 파일 전체를 과거 사본으로 덮지 않는다. 현재 글의 키가 남은 설정 파일이나 사본은 공개 저장소와 화면 공유에 노출하지 않는다.