🦞 35. OpenClaw + CCR 연결하기: Claude CLI 설치, endpoint 설정, Hook은 나중에

이 글은 원래 hook 이야기부터 시작하면 안 된다. 실제로 이번 구성의 핵심 흐름은 아래다.

OpenClaw → ACPX → Claude Agent Adapter → CCR(Claude Code Router) → GLM API

즉 겉으로는 claude 하니스를 쓰는 것처럼 보여도, 실제 모델 요청은 CCR이 뒤에서 GLM endpoint로 다시 라우팅하는 구조다. 그래서 먼저 필요한 것은 Node/npm 준비 → OpenClaw/CCR/Claude 설치 → CCR의 GLM endpoint 설정 → OpenClaw가 wrapper를 통해 ACPX를 CCR 환경에서 실행하게 연결하는 일이고, hook은 그다음에 붙이는 선택형 하드닝이다.

가장 많이 헷갈리는 지점도 딱 여기다. api_base_url은 CCR이 바깥 모델 제공자에게 요청을 보내는 upstream endpoint이고, ANTHROPIC_BASE_URL은 Claude Code가 로컬 CCR로 붙는 local endpoint다. 이 둘을 섞어 생각하면 “CCR을 깔았는데도 왜 그냥 기본 Claude처럼 가지?” 같은 문제가 바로 생긴다.

flowchart LR
A[OpenClaw] --> B[ACPX]
B --> C[Claude Agent Adapter]
C --> D[CCR local endpoint<br/>127.0.0.1:3456]
D --> E[GLM API<br/>api.z.ai]
E --> F[선택: Claude Hook]

🧠 칠판 치트시트

• 1단계는 hook이 아니라 Claude CLI 설치다.
• 2단계는 CCR 설치 + config.json 작성이다.
• 3단계는 ccr activate로 local endpoint를 Claude에 주입하는 것이다.
• OpenClaw는 CCR에 직접 붙는 게 아니라, CCR이 주입된 Claude Code 하니스를 통해 우회한다.
• hook은 연결이 안정화된 뒤에만 붙여도 늦지 않다.

먼저 결론부터

OpenClaw + CCR 세팅은 아래 순서로 보면 가장 덜 꼬인다.

1. Node/npm을 확인하고 openclaw + ccr + claude CLI를 같이 설치한다.
2. ~/.claude-code-router/config.json에서 GLM endpoint를 설정한다.
3. ccr start + ccr activate로 Claude가 로컬 CCR endpoint를 보게 만든다.
4. OpenClaw가 wrapper를 통해 acpx를 CCR 환경에서 실행하게 맞춘다.
5. 그 뒤에만 hook으로 감시/차단을 얇게 추가한다.

핵심은 “OpenClaw를 뜯어고친다”가 아니라, Claude Code 런타임이 어떤 endpoint를 바라보는지 정확히 맞춘다는 데 있다.

Windows에서도 가능한가?

결론부터 말하면: 가능하다. 단, 구간마다 설정 방식이 다르고 꼬이는 포인트도 다르다.

구간별 Windows 가능 여부

• Claude Code 단독 + GLM-5 직결: 가능하다. npm i -g @anthropic-ai/claude-code 후 PowerShell에서 환경변수를 직접 설정하면 된다. CCR 없이 이 조합만 쓰는 경우 가장 단순하다.
• CCR 설치/실행: 가능하다. npm 전역 설치 후 ccr start까지는 같다. 다만 셸 활성화 명령 방식이 다르다(eval "$(ccr activate)"는 bash 전용이라 PowerShell/Cmd에서는 직접 쓸 수 없다).
• OpenClaw + CCR + acpx 전체 조합: 가능하지만 wrapper를 .sh 대신 .cmd 또는 .ps1로 만들어야 하고, acpx 경로도 Windows npm 전역 경로 스타일로 맞춰야 한다.
• WSL2 경유: 전체 조합에서 가장 덜 꼬인다. Linux 경로 그대로 써도 되고, eval "$(ccr activate)" 같은 bash 문법도 그냥 쓴다. Windows 네이티브 파일과 WSL2 파일 경계만 주의하면 된다.

Windows에서 ccr activate를 쓰는 방법

bash의 eval "$(ccr activate)"에 해당하는 PowerShell 방식은 아래처럼 된다.

# PowerShell에서 CCR이 내보내는 환경변수를 수동으로 직접 설정하는 방법
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:3456"
$env:ANTHROPIC_AUTH_TOKEN = "ccr-local-token"
$env:NO_PROXY = "127.0.0.1"

또는 ccr activate가 출력하는 내용을 확인해서 그에 맞는 PowerShell 형태로 변환해도 된다.

# 현재 PowerShell 세션에서 환경변수 확인
Get-ChildItem Env: | Where-Object { $_.Name -like "ANTHROPIC_*" }

Cmd(명령 프롬프트)에서 설정하려면:

set ANTHROPIC_BASE_URL=http://127.0.0.1:3456
set ANTHROPIC_AUTH_TOKEN=ccr-local-token
set NO_PROXY=127.0.0.1

단, set으로 설정한 값은 해당 Cmd 창에서만 유효하다. 시스템 전역으로 고정하려면 setx를 쓰거나 시스템 환경변수 설정에서 직접 추가해야 한다.

setx ANTHROPIC_BASE_URL "http://127.0.0.1:3456"

주의: setx는 현재 창에는 즉시 반영이 안 된다. 새 창에서 확인해야 한다.

Git Bash vs PowerShell vs WSL2 비교

• Git Bash: bash 문법(eval, export, chmod +x)이 그대로 통한다. 단, npm 전역 경로가 Windows 스타일(C:/Users/...)이어서 acpx 경로를 거기에 맞게 써야 한다. which acpx나 where acpx로 먼저 위치를 잡는다.
• PowerShell: 환경변수 설정이 $env: 문법이고, eval이 없다. wrapper는 .ps1로 만드는 게 자연스럽다. 실행 정책(ExecutionPolicy) 문제로 .ps1이 막히는 경우가 있으니, 필요하면 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser로 미리 풀어 둔다.
• Cmd: set/setx로 환경변수를 쓰고, wrapper는 .cmd나 .bat로 만든다. bash 문법은 전혀 통하지 않는다.
• WSL2: Linux 환경 그대로라 bash 문법, .sh wrapper, chmod +x 모두 그냥 된다. Windows 네이티브 파일에 접근할 때 /mnt/c/... 경로를 써야 하는 점만 주의한다.

이 구조를 먼저 이해하면 덜 헷갈린다

CCR은 Claude Code 앞에 놓이는 작은 라우터다. Claude Code는 원래 Anthropic 쪽으로 바로 가려는 CLI인데, CCR을 켜고 local endpoint를 주입하면 먼저 로컬 127.0.0.1:3456으로 들어간다. 그다음 CCR이 실제 provider(OpenRouter, DeepSeek, Gemini, Ollama, GLM 등)로 다시 보내 준다.

즉 역할은 이렇게 나뉜다.

• Claude Code: 실제 코딩 에이전트 CLI
• CCR: 어떤 모델/제공자로 보낼지 고르는 라우터
• OpenClaw: 채널, 세션, ACP 하니스 실행을 관리하는 상위 오케스트레이터
• Hook: Claude Code 툴 실행 전후를 감시하거나 차단하는 선택형 보안 레이어

이 순서를 놓치면 hook을 잘 달아도, 정작 요청은 CCR을 안 타고 기본 경로로 빠질 수 있다.

1) 사전 준비: Node / npm부터 확인한다

이 경로는 openclaw, ccr, claude, acpx가 다 CLI 기반으로 연결되므로 먼저 런타임부터 맞춰야 한다.

Linux/macOS/Git Bash/WSL2:

node -v
npm -v

PowerShell/Cmd에서도 동일하게 입력하면 된다. 실무 기준으로는 Node 20+ 를 먼저 맞춰 두는 편이 안전하다.

2) 필수 설치

이번 흐름에서는 아래 3개가 한 세트다.

npm i -g openclaw @musistudio/claude-code-router @anthropic-ai/claude-code

PowerShell/Cmd에서도 동일하게 쓴다. 단, Windows에서 npm 전역 설치 시 권한 오류가 나면 관리자 권한으로 터미널을 열어서 실행하거나, npm config get prefix로 설치 경로를 확인한 뒤 해당 경로가 PATH에 잡혀 있는지 본다.

설치 확인:

openclaw --version
ccr --help
claude --version

여기서 하나라도 안 잡히면 다음 단계로 넘어가지 않는 편이 낫다.

Windows에서 명령이 안 잡힐 경우 체크포인트:

• npm config get prefix로 전역 설치 경로를 확인한다. 보통 C:\Users\<user>\AppData\Roaming\npm이다.
• 이 경로가 시스템 PATH에 있는지 확인한다 (PowerShell: $env:PATH -split ';').
• 없으면 직접 추가하거나, 해당 경로를 풀패스로 써서 실행한다.

참고: Claude 공식 문서는 native install도 권장하지만, 이번 OpenClaw + ACPX + CCR + GLM 라우팅 흐름은 npm 전역 설치 기준으로 맞춰 두면 wrapper/acpx 경로를 설명하기가 더 단순하다. 중요한 건 설치 방식 하나를 정하면 끝까지 일관되게 가는 것이다.

3) config.json에서 GLM provider endpoint를 설정한다

CCR의 핵심 파일은 보통 아래 경로다.

Linux/macOS/WSL2:

~/.claude-code-router/config.json

Windows 네이티브:

C:\Users\<user>\.claude-code-router\config.json

이번 글의 기준 시나리오는 CCR이 GLM API로 라우팅하는 구조다. 아래처럼 핵심만 두고 시작하는 편이 좋다.

{
  "Providers": [
    {
      "name": "zhipu",
      "api_base_url": "https://api.z.ai/api/coding/paas/v4/chat/completions",
      "api_key": "YOUR_ZHIPU_API_KEY",
      "models": ["glm-4-plus", "glm-4-air", "glm-4-flash", "glm-5"]
    }
  ],
  "Router": {
    "default": "zhipu,glm-5",
    "background": "zhipu,glm-4-flash",
    "think": "zhipu,glm-5"
  }
}

포인트는 두 가지다.

• 글로벌 기준으로는 api.z.ai endpoint를 쓴다.
• API 키는 절대 공유하거나 커밋하지 않는다.

GLM-5 플랜 제약 사항

GLM-5 모델은 **Z.AI의 유료 플랜(Max 이상)**에서만 접근 가능하다. config.json에 "glm-5"를 넣어도 플랜이 맞지 않으면 API 오류가 반환된다. 무료/기본 플랜에서는 glm-4-flash 또는 glm-4-air부터 테스트해서 연결부터 확인하는 게 낫다. CCR settings.json에서 Router.default를 플랜에 맞는 모델로 먼저 설정해 두고, 플랜을 올린 뒤 glm-5로 바꾸는 방식을 권장한다.

여기서 꼭 구분해야 할 게 세 가지다.

api_base_url

이건 CCR이 바깥으로 요청을 보낼 실제 provider endpoint다.

이번 GLM 라우팅 시나리오에서는 보통 아래처럼 이해하면 된다.

• Z.ai / GLM → https://api.z.ai/api/coding/paas/v4/chat/completions
• OpenRouter → https://openrouter.ai/api/v1/chat/completions
• DeepSeek → https://api.deepseek.com/chat/completions
• Ollama → http://localhost:11434/v1/chat/completions

즉, 이 값은 로컬 CCR 주소가 아니다. provider 주소다.

transformer

provider마다 요청/응답 형태가 달라서, CCR은 transformer로 포맷을 맞춘다. OpenRouter면 openrouter, DeepSeek면 deepseek, Gemini면 gemini 같은 식이다.

Router

여기서 기본 모델과 상황별 라우팅 규칙을 정한다.

• default: 일반 작업
• think: 더 생각 많이 쓰는 작업
• longContext: 긴 문맥 작업
• webSearch: 검색형 작업

처음에는 default 하나만 잘 되는지 확인하고, 그다음에 think나 longContext를 얹는 게 안전하다.

4) local endpoint를 Claude에 주입해야 비로소 CCR을 탄다

여기가 실전에서 가장 많이 빠지는 부분이다.

CCR 설정 파일만 만들었다고 Claude가 자동으로 CCR을 타는 건 아니다. Claude CLI가 Anthropic 기본 경로 대신 로컬 CCR endpoint를 보게 만들어야 한다.

먼저 라우터를 켠다 (모든 환경 공통).

ccr start
ccr status

여기서 Status: Running이 보여야 다음 단계로 넘어가는 게 안전하다.

Linux/macOS/WSL2/Git Bash

eval "$(ccr activate)"
env | grep '^ANTHROPIC_'

Windows PowerShell

eval 문법이 없으므로 환경변수를 직접 설정한다.

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:3456"
$env:ANTHROPIC_AUTH_TOKEN = "ccr-local-token"
$env:NO_PROXY = "127.0.0.1"
 
# 확인
Get-ChildItem Env: | Where-Object { $_.Name -like "ANTHROPIC_*" }

또는 ccr activate가 어떤 출력을 내는지 먼저 확인해서 맞는 형태로 변환한다.

ccr activate

Windows Cmd

set ANTHROPIC_BASE_URL=http://127.0.0.1:3456
set ANTHROPIC_AUTH_TOKEN=ccr-local-token
set NO_PROXY=127.0.0.1
 
rem 확인
set ANTHROPIC

공통

주입이 잘 됐다면 Claude Code를 바로 실행하거나:

claude

또는 아래처럼 CCR을 통한 직접 실행도 된다.

ccr code

이건 CCR을 통하는 Claude Code 실행 경로라, 터미널 단독 사용이라면 가장 덜 헷갈린다.

5) OpenClaw에서는 acpx를 CCR wrapper로 감싸는 게 핵심이다

OpenClaw는 ACP 세션으로 Claude Code 같은 외부 하니스를 실행할 수 있다. 그런데 여기서 중요한 건 OpenClaw가 CCR에 직접 붙는 게 아니라, OpenClaw가 띄우는 acpx 프로세스가 CCR이 활성화된 셸 환경에서 실행되도록 만드는 것이다.

즉 아래 두 경우는 완전히 다르다.

• acpx를 그냥 실행 → Claude가 CCR을 우회할 수 있음
• CCR 환경변수를 먼저 주입한 wrapper를 통해 acpx 실행 → Claude가 CCR 경유

OpenClaw 쪽 설정 예시

보통 ~/.openclaw/openclaw.json에서 아래 개념이 살아 있어야 한다.

• "acp.enabled": true
• "acp.backend": "acpx"
• "plugins.entries.acpx.enabled": true
• "plugins.entries.acpx.config.command": "wrapper 경로"

예시 구조:

{
  "acp": {
    "enabled": true,
    "backend": "acpx"
  },
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "./acpx-ccr.sh"  // Linux/macOS/WSL2
          // Windows: "C:\\Users\\<user>\\.openclaw\\workspace\\acpx-ccr.cmd"
        }
      }
    }
  }
}

Linux/macOS/WSL2: acpx-ccr.sh

경로 예시:

~/.openclaw/workspace/acpx-ccr.sh

스크립트:

#!/bin/sh
if command -v ccr >/dev/null 2>&1; then
  eval "$(ccr activate)"
fi
exec /path/to/acpx "$@"

acpx 경로 확인:

which acpx
# 또는 npm 전역 경로로: $(npm root -g)/.bin/acpx

실행 권한:

chmod +x ~/.openclaw/workspace/acpx-ccr.sh

Windows: acpx-ccr.cmd

Windows Cmd 기반 wrapper:

@echo off
set ANTHROPIC_BASE_URL=http://127.0.0.1:3456
set ANTHROPIC_AUTH_TOKEN=ccr-local-token
set NO_PROXY=127.0.0.1
 
rem acpx 경로는 npm global prefix 확인 후 맞게 수정
"%APPDATA%\npm\acpx.cmd" %*

acpx 경로 확인 (Cmd/PowerShell):

where acpx

(npm root -g) + "\..\.bin\acpx"
# 또는
Get-Command acpx | Select-Object -ExpandProperty Source

Windows: acpx-ccr.ps1

PowerShell 기반 wrapper (더 유연하게 오류 처리가 가능하다):

# acpx-ccr.ps1
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:3456"
$env:ANTHROPIC_AUTH_TOKEN = "ccr-local-token"
$env:NO_PROXY = "127.0.0.1"
 
$acpxPath = (Get-Command acpx -ErrorAction SilentlyContinue).Source
if (-not $acpxPath) {
    $acpxPath = "$env:APPDATA\npm\acpx.cmd"
}
 
& $acpxPath @args

openclaw.json에서 .ps1을 가리킬 때는 PowerShell로 명시적으로 실행하게 설정해야 한다.

"command": "powershell -ExecutionPolicy Bypass -File C:\\Users\\<user>\\.openclaw\\workspace\\acpx-ccr.ps1"

wrapper의 역할 요약

1. CCR 환경변수(ANTHROPIC_BASE_URL 등)를 현재 프로세스에 주입한다.
2. 그 상태로 실제 acpx를 실행한다.
3. 결과적으로 OpenClaw가 띄운 Claude 하니스도 CCR을 타게 된다.

OpenClaw 내부를 건드리지 않고, acpx 실행 직전 한 번만 CCR 환경을 주입하면 된다는 점에서 실무에서 가장 덜 헷갈리는 방식이다.

6) endpoint 설정과 OpenClaw 연결에서 가장 자주 나는 실수

실수 1) api_base_url과 ANTHROPIC_BASE_URL을 같은 의미로 본다

이 둘은 완전히 다르다.

• api_base_url: CCR → provider 로 가는 주소
• ANTHROPIC_BASE_URL: Claude → CCR 로 가는 주소

이걸 뒤집으면 라우터는 설치돼 있는데 실제로 안 탄다.

실수 2) config.json 수정 후 ccr restart를 안 한다

README도 이 점을 따로 적고 있다. 설정을 바꿨으면 재시작해야 반영된다.

ccr restart

실수 3) ccr activate는 했는데 OpenClaw가 다른 셸/다른 서비스 환경에서 Claude를 띄운다

터미널에서는 잘 되는데 OpenClaw ACP 세션에서는 안 되는 대표 원인이다. 이 경우는 거의 항상 OpenClaw가 실행한 Claude 프로세스가 그 환경변수를 못 보고 있기 때문이다. Windows에서는 특히 각 터미널 창마다 환경변수가 별도로 유지되므로, wrapper에서 명시적으로 변수를 설정하는 방식이 더 확실하다.

실수 4) Windows에서 .ps1 wrapper가 실행 정책 오류로 막힌다

실행 정책이 이 시스템에서 스크립트 실행을 방지하고 있습니다.

이 경우:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

또는 openclaw.json에서 -ExecutionPolicy Bypass 플래그를 포함한 명령으로 호출한다.

실수 5) HOST=0.0.0.0만 열고 APIKEY를 안 건다

CCR README는 APIKEY가 없으면 보안상 host를 로컬로 강제하는 쪽을 설명한다. 로컬 단독 사용이면 굳이 외부 개방을 열 이유가 거의 없다.

실수 6) Windows에서 acpx 경로에 공백이 있다

C:\Users\Kim Min Joon\AppData\... 같은 경로는 .cmd wrapper에서 반드시 따옴표로 감싸야 한다.

"%APPDATA%\npm\acpx.cmd" %*

실수 7) provider endpoint를 잘못 넣어 의도하지 않은 공급자로 빠진다

GLM 글로벌 기준이라면 api.z.ai를 쓰고 있는지부터 먼저 확인하는 게 빠르다.

7) OpenClaw 상태 확인 + 스모크 테스트까지 한 번에 본다

설치가 끝났으면 아래 순서로 점검하는 편이 제일 안전하다.

점검 1) Claude 설치 확인

Linux/macOS/WSL2/Git Bash:

claude --version
which claude

Windows PowerShell:

claude --version
Get-Command claude | Select-Object -ExpandProperty Source

점검 2) CCR 설치와 상태 확인

ccr --help
ccr status

필요하면 먼저:

ccr start

점검 3) OpenClaw 상태 확인

openclaw status

여기서는 최소한 OpenClaw가 살아 있고, ACP 관련 플러그인/런타임이 이상 없이 뜨는지 본다.

점검 4) local endpoint 주입 확인

Linux/macOS/WSL2/Git Bash:

eval "$(ccr activate)"
env | grep '^ANTHROPIC_'

Windows PowerShell:

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:3456"
Get-ChildItem Env: | Where-Object { $_.Name -like "ANTHROPIC_*" }

점검 5) wrapper 스크립트 단독 실행 확인

OpenClaw를 통하기 전에 wrapper 자체가 제대로 동작하는지 보는 스모크 테스트다.

Linux/macOS/WSL2:

cd ~/.openclaw/workspace
./acpx-ccr.sh claude exec "Respond exactly with PONG"

Windows PowerShell:

cd C:\Users\<user>\.openclaw\workspace
powershell -ExecutionPolicy Bypass -File acpx-ccr.ps1 claude exec "Respond exactly with PONG"

Windows Cmd:

cd C:\Users\<user>\.openclaw\workspace
acpx-ccr.cmd claude exec "Respond exactly with PONG"

정상이라면 응답이 아래처럼 떨어져야 한다.

PONG

이 테스트가 중요한 이유는 단순하다. OpenClaw 전체를 의심하기 전에, wrapper + CCR + acpx + Claude 연결이 독립적으로 먼저 되는지 확인할 수 있기 때문이다.

점검 6) 로그 확인

Linux/macOS/WSL2:

tail -f ~/.claude-code-router/claude-code-router.log

Windows PowerShell:

Get-Content "$env:USERPROFILE\.claude-code-router\claude-code-router.log" -Wait -Tail 50

8) 자주 생기는 문제

문제 1) CCR Not Running

• 증상: wrapper는 실행되는데 실제 라우팅이 안 된다.
• 조치: ccr start 후 재시도한다.

문제 2) 중국 endpoint로 간다

• 증상: 내가 기대한 글로벌 GLM 경로가 아니라 다른 endpoint로 빠진다.
• 조치: ~/.claude-code-router/config.json의 api_base_url을 다시 확인한다. 글로벌 기준이면 api.z.ai여야 한다.

문제 3) 권한/쓰기 거부가 난다

• 증상: Claude 또는 acpx 실행은 되는데 작업 승인이 막힌다.
• 조치: acpx 실행 정책이나 승인 옵션을 다시 확인한다. 환경에 따라 승인 정책(--approve-all 등)을 어떻게 둘지 같이 봐야 한다.

문제 4) 설정을 바꿨는데 반영이 안 된다

• 증상: config.json을 바꿨는데 계속 이전 모델/endpoint를 쓴다.
• 조치: 아래처럼 재시작한다.

ccr restart

필요하면 더 확실하게:

ccr stop && ccr start

문제 5) Windows에서 npm 전역 명령이 안 잡힌다

• 증상: ccr나 claude를 쳐도 “명령을 찾을 수 없음” 오류가 난다.
• 조치: npm config get prefix로 경로 확인 후 해당 경로를 PATH에 추가한다.

$npmPrefix = npm config get prefix
$env:PATH += ";$npmPrefix"

현장 미니 사례 2개

사례 A) CCR은 설치했는데 요청이 계속 기본 Claude처럼 보이던 경우

• 상황: config.json은 잘 써 놨는데 모델 라우팅이 안 바뀌었다.
• 원인: ccr activate를 하지 않았거나, 한 셸에서는 했는데 실제 실행은 다른 셸/서비스에서 이뤄졌다.
• 해결: env | grep '^ANTHROPIC_'(또는 PowerShell에서 Get-ChildItem Env: | Where-Object { $_.Name -like "ANTHROPIC_*" })로 현재 실행 환경을 먼저 확인하고, OpenClaw 쪽은 wrapper 경로로 통일했다.

핵심은 “CCR 설치 여부”보다 Claude 프로세스가 어떤 endpoint를 보고 실행되느냐였다.

사례 B) hook을 먼저 달았다가 원인 추적이 더 어려워진 경우

• 상황: 툴 차단은 보이는데, 애초에 요청이 CCR을 탔는지부터 불명확했다.
• 원인: 라우팅 구조가 먼저 안정화되지 않은 상태에서 hook부터 붙였다.
• 해결: hook을 잠시 빼고 claude → CCR local endpoint → provider endpoint 흐름이 먼저 정상인지 확인했다.

보안/감시는 마지막 10%고, 연결 구조는 처음 90%다.

9) hook은 마지막에 붙인다

여기까지가 안정화된 뒤에만 Claude Hook을 붙이는 게 좋다. 이유는 단순하다. hook은 실행 감시/차단 레이어이지, 라우팅 문제를 해결하는 도구가 아니기 때문이다.

처음 붙일 이벤트는 이 4개면 충분하다.

• PreToolUse
• PostToolUse
• PostToolUseFailure
• UserPromptSubmit

권장 순서는 이렇다.

1. Bash만 대상으로 감시-only 시작
2. JSONL 로그가 쌓이는지 확인
3. 정상 명령 오탐이 없는지 확인
4. 그 뒤에만 위험 명령 차단을 추가

최소 설정의 느낌은 아래 정도로 이해하면 된다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.openclaw/workspace/claude-hooks/pre_tool_use.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.openclaw/workspace/claude-hooks/post_tool_use.py"
          }
        ]
      }
    ]
  }
}

Windows에서 hook 명령 경로는 Windows 스타일 절대 경로로 써야 한다.

"command": "python C:\\Users\\<user>\\.openclaw\\workspace\\claude-hooks\\pre_tool_use.py"

권장 경로 2가지

A. 제일 쉬움: Windows에서 Claude Code + GLM-5 직결

CCR 없이 Claude Code에서 직접 GLM endpoint를 바라보게 만드는 경우다. OpenClaw 연동이 아직 필요 없고, GLM-5로 코딩만 먼저 써 보고 싶다면 이 경로가 가장 빠르다.

Z.AI 공식 문서 기준으로는 Claude Code 직결 경로에서 아래 두 값을 먼저 맞춘다.

# 설치
npm i -g @anthropic-ai/claude-code
 
# 환경변수 설정 (PowerShell)
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_ZHIPU_API_KEY"
$env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic"
$env:API_TIMEOUT_MS = "3000000"
 
# 실행
claude

GLM-5를 쓰려면 여기에 더해 Claude Code 쪽 모델 매핑을 명시해 두는 편이 안전하다.

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_ZHIPU_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5"
  }
}

GLM-5를 쓰려면 Z.AI Max 이상 플랜이 필요하다. 없으면 glm-4.7이나 glm-4.5-air로 먼저 연결부터 확인하는 편이 낫다.

B. OpenClaw까지 엮음: WSL2 또는 Windows wrapper 기반 CCR 경유

전체 흐름 OpenClaw → acpx → CCR → GLM을 한 PC에서 붙이는 경우다.

• WSL2 권장: bash 문법과 .sh wrapper를 그대로 쓸 수 있어 가장 덜 꼬인다. Windows 파일 접근이 필요할 때만 /mnt/c/... 경로를 쓴다.
• Windows 네이티브: CCR ccr activate 대신 환경변수 직접 설정 + .cmd/.ps1 wrapper 방식으로 동일한 효과를 낸다. 경로에 공백이 있으면 따옴표를 꼭 챙긴다. PowerShell 실행 정책도 미리 확인한다.

한 줄 결론

OpenClaw + CCR에서 제일 먼저 볼 것은 hook이 아니라 Claude CLI 설치, CCR 설치, provider endpoint 설정, 그리고 CCR 환경변수가 실제 Claude 하니스에 반영됐는지다. Windows에서도 이 흐름은 그대로이고, 달라지는 건 셸 활성화 문법과 wrapper 확장자뿐이다.

다음 읽기

• 🦞 12. 브라우저 릴레이 연동 구조
• 🦞 13. Subagents 설계와 프롬프트
• 🦞 28. 듀얼 릴레이 운영 가이드
• 🦞 34. 세션툴로 블로그 검수 자동화
• 49. Claude Code Best Practice 운영 가이드
• 72. Claude Skills V2

※ 이 문서는 생성형 AI를 활용해 작성되었습니다.