🤖 24. CCR + GLM-5.1 자동 연결 설정

Claude Code를 그냥 실행하는 단계와, CCR(Claude Code Router) + GLM Coding Plan + zsh alias까지 묶어 두는 단계는 체감이 꽤 다릅니다. 전자는 “그때그때 들어가서 쓰는 도구”에 가깝고, 후자는 새 터미널을 열면 바로 코딩 에이전트가 붙는 작업 환경에 가깝습니다.

특히 여러 모델을 바꿔 끼울 가능성이 있거나, 평소에는 claude처럼 익숙하게 쓰되 실제 백엔드는 GLM 계열로 연결하고 싶다면 CCR을 한 번 껴 두는 편이 관리가 쉽습니다. Z.AI 문서에는 Claude Code에 GLM Coding Plan을 직접 붙이는 공식 경로도 있고, CCR README는 로컬 라우터를 통해 claude 명령 자체를 다른 모델로 보낼 수 있는 구조를 설명합니다. 두 문서를 같이 보면, 설치는 단순하게 하고 나중 확장은 열어 두는 구성이 가장 덜 흔들립니다.

flowchart LR
A[Claude Code 설치] --> B[CCR 설치]
B --> C[Z.AI API Key 발급]
C --> D[CCR config에 GLM-5.1 연결]
D --> E[.zshrc에 activate + alias 추가]
E --> F[ccr start]
F --> G[새 터미널에서 cc 실행]

🧠 칠판 치트시트

• Claude Code와 CCR은 같이 npm 전역 설치하면 관리가 편하다.
• GLM Coding Plan은 API Key를 만든 뒤 CCR provider에 연결하면 된다.
• eval "$(ccr activate)"가 들어가야 claude 명령이 로컬 라우터를 탄다.
• alias cc='claude --dangerously-skip-permissions'를 넣으면 손가락 습관까지 줄일 수 있다.
• 단, --dangerously-skip-permissions는 신뢰하는 프로젝트 폴더에서만 쓰는 게 안전하다.

왜 direct 설정 대신 CCR을 같이 쓰는가

Z.AI 공식 문서만 따라가면 ~/.claude/settings.json에 ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic를 넣는 direct 경로가 가장 짧습니다. 실제로 **“나는 GLM만 바로 붙으면 끝”**인 사람에게는 이 경로가 가장 빠릅니다.

그런데 실무에서는 조금만 지나도 요구가 늘어납니다. 평소 기본 모델은 하나로 쓰되, 긴 문맥 작업은 다른 모델로 보내고 싶을 수 있고, background 작업만 더 싼 모델로 돌리고 싶을 수도 있습니다. 바로 여기서 CCR이 편합니다. CCR은 provider와 router를 나눠 관리하기 때문에, 오늘은 GLM-5.1만 붙여 두고 나중에 다른 provider를 덧대도 claude 습관을 바꿀 필요가 없습니다.

현장형으로 보면 차이는 더 분명합니다.

• Before: Claude Code는 붙였는데, 모델을 바꾸려면 설정 파일을 다시 열고 환경 변수를 다시 만져야 한다.
• After: ccr model 또는 config.json만 조정해서 기본/think/background 경로를 바꾼다.

또 하나는 팀 전달성입니다. ~/.claude/settings.json은 개인 설정으로 끝나기 쉽지만, CCR의 config.json은 “우리 팀은 기본은 이 모델, 긴 문맥은 이 모델”처럼 운영 정책을 문서화하기 좋습니다.

1) Claude Code부터 설치한다

Anthropic 공식 문서 기준으로 Claude Code는 터미널에서 쓰는 에이전트형 코딩 도구입니다. 코드베이스를 읽고, 파일을 바꾸고, 명령을 실행하고, 개발 도구와 연결됩니다.

• 공식 개요: https://code.claude.com/docs/en/overview

Anthropic은 macOS/Linux에서 native install도 권장하지만, 이번 구성은 CCR도 같이 npm 전역 설치할 예정이라 둘 다 같은 방식으로 설치하는 편이 관리가 단순합니다.

npm install -g @anthropic-ai/claude-code
claude --version

여기서 claude --version이 정상으로 뜨면 첫 관문은 통과입니다.

작은 실패 사례도 많이 나옵니다. Node 버전이 너무 낮거나, 예전 글로벌 패키지 캐시가 꼬여 있으면 설치는 됐는데 claude: command not found가 뜰 수 있습니다. 이럴 때는 Claude Code를 의심하기보다 현재 셸의 npm global bin 경로가 PATH에 잡혀 있는지부터 보는 편이 빠릅니다.

2) CCR(Claude Code Router)을 설치한다

CCR의 핵심은 단순합니다. Claude Code를 그대로 버리지 않고, 그 앞에 모델 라우터를 하나 두는 방식입니다. README 기준으로 ccr code, ccr model, ccr activate 같은 명령이 제공되고, 특히 ccr activate는 현재 셸에서 claude 명령이 자동으로 로컬 라우터를 타게 만드는 역할을 합니다.

• CCR README: https://github.com/musistudio/claude-code-router

설치는 한 줄입니다.

npm install -g @musistudio/claude-code-router
ccr --help

여기서 ccr --help가 뜨면 설치는 끝입니다. 이 시점에는 아직 GLM이 연결된 게 아니라, 길만 만든 상태라고 보면 됩니다.

3) GLM Coding Plan을 준비한다

Z.AI 문서 기준으로 Claude Code에 GLM Coding Plan을 연결하는 방법은 두 가지 결로 읽힙니다.

1. Claude Code에 직접 Z.AI의 Anthropic-compatible endpoint를 연결하는 공식 경로
2. 다른 도구에서도 재활용할 수 있게 API Key를 만들고 라우터에서 관리하는 경로

이번 글은 두 번째 경로를 택합니다. 이유는 명확합니다. CCR과 같이 쓸 때는 provider를 한 곳에서 관리하는 편이 나중에 안 헷갈리기 때문입니다.

먼저 Z.AI에서 해야 할 일은 세 가지입니다.

• GLM Coding Plan 구독 상태 확인
• API Key 발급
• 내 플랜에서 GLM-5.1 사용 가능 여부 확인

중요한 점이 하나 있습니다. Z.AI GLM-5.1 문서에는 GLM-5.1 access is currently available for GLM Coding Plan Pro and Max라고 적혀 있습니다. 즉, 플랜에 따라 기본 매핑이 GLM-4.7로 남아 있을 수 있습니다.

• GLM-5.1 문서: https://docs.z.ai/guides/llm/glm-5.1
• Claude Code 연동 문서: https://docs.z.ai/scenario-example/develop-tools/claude
• 구독 페이지: https://z.ai/subscribe

따라서 설정 전에 먼저 확인할 질문은 이것입니다.

• 나는 Pro/Max 플랜인가?
• 아니면 현재 계정에서 glm-5.1 대신 glm-4.7 또는 glm-5-turbo만 보이는가?

이걸 먼저 확인해 두면, 설정은 했는데 왜 기대한 모델이 안 붙는지 헤매는 시간을 줄일 수 있습니다.

4) CCR config에 GLM-5.1를 연결한다

CCR README는 provider마다 api_base_url, api_key, models, Router를 넣는 구조를 설명합니다. Z.AI는 Chat Completion API와 function calling 문서를 공개하고 있으므로, CCR에서는 Z.AI Chat Completions endpoint를 provider로 두고 라우팅하는 방식이 이해하기 쉽습니다.

먼저 ~/.claude-code-router/config.json을 만듭니다.

{
  "API_TIMEOUT_MS": 3000000,
  "Providers": [
    {
      "name": "zai",
      "api_base_url": "https://api.z.ai/api/paas/v4/chat/completions",
      "api_key": "$ZAI_API_KEY",
      "models": ["glm-5.1", "glm-5.1"]
    }
  ],
  "Router": {
    "default": "zai,glm-5.1",
    "think": "zai,glm-5.1",
    "background": "zai,glm-5.1",
    "longContext": "zai,glm-5.1",
    "longContextThreshold": 60000
  }
}

이 구성이 좋은 이유는 단순합니다.

• 평소 작업은 glm-5.1
• 백그라운드성 작업은 glm-5-turbo
• 긴 문맥도 일단 glm-5.1로 유지

즉, 처음부터 복잡하게 쪼개기보다 가장 많이 쓰는 흐름만 먼저 나누는 방식입니다.

여기서도 실무 미니 사례가 나옵니다.

• 작게 시작한 경우: default와 background만 나눠 두고 한 주 써본다. 체감 차이가 생기면 think/longContext를 조정한다.
• 처음부터 다 쪼갠 경우: 나중에 어느 라우트가 왜 그 모델인지 기억이 안 나고, 이상 동작이 나와도 원인 추적이 길어진다.

만약 내 플랜이 아직 glm-5.1를 못 쓰는 상태라면, 여기서 모델 이름만 glm-4.7 또는 계정에서 허용된 값으로 바꾸면 됩니다. 중요한 건 구조를 먼저 안정화하는 것이지, 첫날부터 최고 사양 이름을 박아 넣는 게 아닙니다.

5) .zshrc에 자동 연결과 alias를 넣는다

이제 사용감이 갈리는 구간입니다. CCR README는 eval "$(ccr activate)"를 현재 셸에 적용하면, 이후 claude 명령이 로컬 라우터를 타도록 환경 변수를 세팅한다고 설명합니다. 즉, 사용 습관은 그대로 두고 뒤쪽 배선만 바꾸는 셈입니다.

여기에 또우가 원하는 alias까지 넣으면 아래처럼 됩니다.

export ZAI_API_KEY="여기에_발급한_API_KEY"
 
if command -v ccr >/dev/null 2>&1; then
  eval "$(ccr activate)"
fi
 
alias cc='claude --dangerously-skip-permissions'

이 블록을 ~/.zshrc에 넣고 적용합니다.

source ~/.zshrc

이제 새 터미널 기준으로는 흐름이 이렇게 바뀝니다.

• claude → CCR이 활성화된 경로를 탄다
• cc → claude --dangerously-skip-permissions로 실행된다

다만 여기에는 반드시 붙는 주의점이 있습니다. --dangerously-skip-permissions는 이름 그대로 권한 확인 단계를 건너뛰는 옵션입니다. 프로젝트 폴더 안에서 빠르게 실험할 때는 매우 편하지만, 홈 디렉터리 전체나 민감한 운영 서버 디렉터리에서 습관적으로 쓰면 사고 반경이 커집니다.

실전에서는 이렇게 나누는 편이 좋습니다.

• 성공 사례: 샘플 앱, 개인 실험 repo, throwaway 브랜치에서는 cc를 써서 속도를 높인다.
• 실패 사례: 프로덕션 인프라 폴더나 개인 문서가 섞인 작업공간에서 무심코 cc를 쓴다.

그래서 alias는 편하지만, 쓰는 위치는 더 엄격해야 합니다.

6) 진짜로 자동 연결됐는지 검증한다

이 단계에서 가장 흔한 착각은 두 가지입니다. 하나는 .zshrc를 고쳤으니 다 끝났다고 생각하는 것, 다른 하나는 ccr activate만 했는데 router 프로세스는 안 띄운 상태입니다. CCR README에도 activate 전에 서비스가 실행 중이어야 한다는 취지의 설명이 있습니다.

먼저 router를 시작합니다.

ccr start

그 다음 새 터미널을 열거나 source ~/.zshrc를 다시 적용한 뒤 아래 순서로 확인합니다.

ccr model
cc

ccr model에서는 최소한 다음이 보여야 합니다.

• default → zai,glm-5.1
• background → zai,glm-5.1

그 다음 cc로 Claude Code에 들어가서 가볍게 이렇게 던져보면 됩니다.

현재 프로젝트 구조를 5줄로 요약하고, 먼저 손대면 좋은 파일 3개만 골라줘.

검증 포인트는 단순합니다.

1. cc 명령이 바로 뜨는가
2. API 인증 오류 없이 세션이 열리는가
3. CCR 쪽 라우팅이 살아 있는가
4. 작은 질의 하나를 정상 처리하는가

여기까지 되면 “설치 완료”보다 더 중요한 반복 가능한 작업 환경 완료입니다.

7) 자주 막히는 지점 4개

1. ccr activate는 했는데 연결이 안 된다

가장 흔한 경우입니다. 보통 ccr start를 안 했거나, 예전 터미널 창에서 계속 테스트하는 상황입니다. 새 셸을 열어서 다시 확인하는 게 빠릅니다.

2. ZAI_API_KEY를 넣었는데 인증이 안 된다

환경 변수 이름 오타, 따옴표 누락, 예전 세션 캐시가 흔한 원인입니다. echo $ZAI_API_KEY로 값이 실제 잡히는지부터 봅니다.

3. config.json은 맞아 보이는데 CCR이 못 읽는다

JSON 뒤에 쉼표 하나 남아 있는 경우가 많습니다. 수동 편집할수록 이런 실수가 자주 납니다. 작은 파일일수록 JSON validator 한 번 거치는 편이 시간을 아낍니다.

4. GLM-5.1가 안 붙는다

이 경우는 대부분 설정 문제보다 플랜/모델 가용성 문제인 경우가 많습니다. Z.AI 문서처럼 계정 기준 기본 매핑이 아직 GLM-4.7일 수 있으니, 먼저 현재 플랜과 허용 모델부터 확인하는 게 맞습니다.

내 기준 추천 순서

처음부터 완벽한 자동화를 만들려 하기보다, 아래 순서가 덜 흔들립니다.

1. Claude Code 설치
2. CCR 설치
3. Z.AI API Key 발급
4. CCR config.json에 GLM 연결
5. .zshrc에 eval "$(ccr activate)"
6. alias cc='claude --dangerously-skip-permissions'
7. ccr start 후 실제 질의 1회 검증

이 순서가 좋은 이유는, 문제가 나도 어디서 막혔는지 바로 역추적이 되기 때문입니다. 반대로 한 번에 helper, alias, config, model mapping을 다 얹으면 실패 지점이 겹쳐서 원인을 분리하기가 어려워집니다.

다음 읽기

• 01. Claude Code 시작 실전 워크플로우
• 03. Claude Code 운영 스택
• 20. 속도·토큰·MCP 최적화
• 23. 하니스 운영 실전

참고 메타

• Anthropic Claude Code overview: https://code.claude.com/docs/en/overview
• Claude Code Router README: https://github.com/musistudio/claude-code-router
• Z.AI Claude Code integration: https://docs.z.ai/scenario-example/develop-tools/claude
• Z.AI GLM-5.1 guide: https://docs.z.ai/guides/llm/glm-5.1
• GLM Coding Plan page: https://z.ai/subscribe

이 문서는 생성형 AI를 활용해 초안을 구성했고, Anthropic 공식 문서·CCR 원문 README·Z.AI 공식 문서를 교차 확인해 실무형으로 재정리했습니다.