Claude Code Hooks가 원격 맥에서 실행되지 않을 때: 2026 점검 가이드

결론부터: 실행 단계별로 원인을 좁히세요

공식 문서에 따르면 command hook의 기본 시간 제한은 600초입니다(Claude Code Hooks 참고 문서). 따라서 Claude Code Hooks가 원격 맥에서 실행되지 않는다면 먼저 이벤트와 matcher를 확인하고, 다음으로 스크립트 실행 권한과 SSH 환경 변수 및 작업 디렉터리를 점검한 뒤, 종료 상태와 Hook 출력을 살펴보세요. 곧바로 Claude Code 장애로 단정하거나 권한 제어를 끄는 방식은 피해야 합니다.

이 글은 SSH로 원격 맥에서 Claude Code를 사용하는 개발자와 공유 Hook 설정을 관리하는 엔지니어를 위한 진단 절차입니다.
macOS 환경에서 포맷, 빌드, 테스트를 자동화하는 CI 담당자도 실행 환경 차이를 확인할 수 있습니다.

증상에 따라 실행 단계를 나누기

Hook 문제는 보통 서로 다른 상태를 한데 묶어 “실행되지 않는다”고 표현할 때 진단이 꼬입니다. 설정을 바꾸기 전에 Claude Code 버전, 세션 유형, 문제가 재현되는 작업을 기록하세요. 그리고 파일 변경이나 삭제 없이 로그 한 줄을 남기는 테스트 Hook을 사용해 실제 호출 여부를 확인합니다.

다음처럼 Hook이 시작됐는지와 스크립트 결과가 반영됐는지를 분리해 기록합니다.

#!/bin/sh
printf 'hook-started\n' >> "$HOME/claude-hook-check.log"
printf 'PWD=%s\nPATH=%s\n' "$PWD" "$PATH" >> "$HOME/claude-hook-check.log"

로그 파일에 기록이 없다면 이벤트, matcher, 설정 범위를 먼저 살펴봅니다. 기록은 있는데 작업 결과가 없다면 스크립트의 처리 내용과 종료 상태를 확인합니다. 이 구분만 해도 무관한 재설치나 권한 변경을 피할 수 있습니다.

이벤트와 matcher의 적용 범위

Claude Code Hooks가 실행되지 않는 원인: 이벤트와 matcher 확인

Hook은 설정한 이벤트가 발생할 때 동작합니다. 따라서 대상 작업이 해당 이벤트를 발생시키는지, matcher가 실제 도구 이름이나 조건에 맞는지부터 확인하세요. 이벤트 이름과 입력 형식은 공식 Hook 이벤트 참고 문서에서 확인하고, 구성 예시는 Hook 설정 안내와 대조합니다.

프로젝트 설정과 사용자 설정의 적용 범위도 구분해야 합니다. 프로젝트에서만 재현된다면 프로젝트 설정 파일이 올바른 위치에 있는지, 공유 설정을 쓰는 팀이라면 현재 작업 디렉터리에서 그 설정이 적용되는지 검사합니다. 설정 형식은 공식 설정 문서와 맞춰 보세요.

최소 구성으로 원인을 분리할 때는 실제로 검사할 작업에 맞는 이벤트와 matcher만 남깁니다. 예를 들어 파일 편집 뒤 검사를 실행하려는 경우, 파일 편집과 관계없는 이벤트를 지정하면 스크립트 자체가 정상이어도 호출되지 않습니다. 먼저 무해한 로그 기록만 연결하고, 호출이 확인된 뒤 실제 검사 명령을 추가하세요.

Hook 스크립트 권한과 작업 디렉터리 점검

원격 호스트에서 설정에 지정한 경로가 존재하는지 확인합니다. 셸에서 직접 입력한 상대 경로가 프로젝트 루트를 기준으로 해석된다고 가정하지 마세요. Hook이 시작될 때의 현재 디렉터리와 스크립트가 기대하는 기준 경로가 다르면 파일이나 실행 도구를 찾지 못할 수 있습니다.

pwd
ls -l ./scripts/check.sh
head -n 1 ./scripts/check.sh
command -v sh

파일이 존재해도 실행 권한이 없거나, 첫 줄의 shebang이 가리키는 해석기를 찾을 수 없다면 시작 단계에서 실패할 수 있습니다. ls -l 결과와 shebang을 확인하고, 설정에서 실행하는 경로와 검사한 경로가 같은지 대조하세요. 권한을 바꾸기 전에는 스크립트를 직접 실행해 실패 메시지를 확인합니다.

구성에서 Hook 명령을 호출하는 방식도 공식 예시와 비교하세요. 설정 형식이나 입력 전달 방식이 다르면 올바른 스크립트라도 기대한 인수를 받지 못할 수 있습니다. 명령 Hook의 동작과 입력 규칙은 공식 Hook 참고 자료에 정리되어 있습니다.

SSH 환경 변수와 종료 결과

SSH 연결 뒤 Hook이 명령을 찾지 못할 때

대화형 SSH 셸에서 성공한 명령이 Hook에서도 자동으로 발견된다는 보장은 없습니다. 셸 초기화 파일에서만 설정한 PATH, Homebrew 경로, 프로젝트별 환경 변수는 Hook 실행 환경과 다를 수 있습니다. Claude Code가 시작된 원격 세션에서 다음 값을 기록해 대화형 터미널 결과와 비교하세요.

printf 'PWD=%s\nPATH=%s\n' "$PWD" "$PATH"
command -v brew
command -v xcodebuild

명령이 발견되지 않으면 도구를 다시 설치하기 전에 실제 설치 경로를 확인하세요. Hook 설정에서 필요한 경로를 명시하거나, 환경 변수 설정을 Claude Code가 실행되는 세션에도 적용합니다. macOS의 도구 체인을 호출하는 경우에도 xcodebuild처럼 필요한 실행 파일이 해당 원격 사용자에게 보이는지 검사해야 합니다. 환경 변수의 전달과 설정 방식은 공식 환경 변수 문서를 기준으로 확인하세요.

Claude Code Hook 실행 실패 로그 확인

스크립트의 표준 출력과 표준 오류를 따로 확인하고, 종료 상태를 기록하세요. Claude Code는 Hook의 종료 상태와 반환 내용을 처리하므로, 스크립트가 실행됐다는 사실만으로 작업 결과가 적용됐다고 볼 수 없습니다. 종료 코드의 의미와 Hook 출력 처리 방식은 공식 Hook 참고 문서에서 해당 이벤트 기준으로 확인합니다.

./scripts/check.sh
result=$?
printf 'exit=%s\n' "$result"

직접 실행은 성공하지만 Claude Code에서만 실패한다면 설정 로딩, Hook 입력, 세션 환경 차이를 의심할 수 있습니다. 진단 로그를 켜는 절차는 설정 디버깅 안내를 따르고, 문제가 생긴 이벤트의 기록이 대화에 표시되는지 또는 로그에만 남는지 구분하세요. 민감한 입력이 기록될 가능성도 고려해 로그를 공유하기 전에 내용을 검토합니다.

원인별 선택표와 안전한 재검증

관찰 결과	우선 확인할 항목	다음 조치
테스트 기록이 생성되지 않음	이벤트, matcher, 설정 범위	무해한 기록 명령만 둔 최소 설정으로 호출 여부 확인
스크립트 경로 오류 또는 시작 실패	원격 경로, 실행 권한, shebang	원격 호스트에서 경로와 해석기를 직접 점검
도구를 찾지 못함	`PATH`, 환경 변수, 작업 디렉터리	Hook 실행 환경에서 명령 위치와 현재 경로 비교
스크립트는 실행되지만 결과가 반영되지 않음	표준 출력, 표준 오류, 종료 상태, Hook 반환 내용	디버그 로그와 이벤트별 출력 처리 방식 확인

비교 항목	대화형 SSH 터미널	Claude Code Hook
`PATH`	셸 초기화 파일의 설정이 적용될 수 있음	실제 Hook 실행 시 값을 별도로 확인해야 함
작업 디렉터리	로그인 후 이동한 위치일 수 있음	실행 시 기록한 `PWD`로 검증
명령 실행	사람이 직접 입력한 결과	Hook 입력과 설정에 따라 실행
오류 확인	터미널에 출력된 메시지	표준 오류와 디버그 로그를 함께 확인

수정이 끝나면 부작용 없는 로그 기록부터 다시 실행하고, 그 다음 프로젝트의 포맷 검사나 테스트처럼 되돌리기 쉬운 작업으로 검증합니다. 빌드 작업은 필요한 도구 체인이 원격 맥에서 확인된 뒤 추가하세요. 프로젝트 파일을 덮어쓰거나 삭제하는 명령, 자격 증명을 출력하는 스크립트는 진단 Hook에 넣지 않는 편이 안전합니다. Hook은 설정에 따라 셸 명령을 실행하므로, 권한 범위를 넓히기보다 공식 보안 안내와 권한 설정 문서를 참고해 최소 권한을 유지하세요.

선택지	적합한 경우	확인할 부담
현재 SSH 세션을 계속 사용	필요한 macOS 도구가 이미 있고 실행 환경을 통제할 수 있음	세션별 환경 차이와 호스트 접근 관리
원격 맥 개발 환경을 정비	macOS 빌드나 테스트를 지속적으로 수행해야 함	Hook 설정, 도구 체인, 보안 정책을 팀에서 관리
원격 맥을 임대	실제 macOS 환경을 필요할 때 사용하고 장비 구매를 미루려는 경우	접속 방식, 이용 기간, 프로젝트 요구 조건을 확인

원격 개발 환경에 맞춘 운영 판단

Linux 서버나 현재 SSH 환경만으로는 macOS 전용 도구 체인을 실행할 수 없고, 로컬 맥은 장시간 빌드 중 자원을 다른 작업과 나눠 써야 할 수 있습니다. 반대로 팀이 이미 관리하는 맥이 있고 지속적인 부하가 예측 가능하다면 자체 장비가 더 적절할 수 있습니다. 원격 개발 환경을 정할 때는 맥 환경 비교 안내와 한국 배포 환경 안내를 함께 살펴보고, 네트워크와 프로젝트 요구에 맞는지 판단하세요.

먼저 현재 환경에서 이벤트, matcher, 실행 경로, SSH 환경 변수, 종료 상태 순으로 확인하면 Hook 문제를 Claude Code 자체의 장애로 오판할 가능성을 낮출 수 있습니다. 프로젝트가 계속 macOS 빌드나 테스트를 요구하고 현재 장비의 접근성이나 도구 체인이 제약이라면, Linux 서버만으로 해결하려 하기보다 실제 macOS를 제공하는 OakVM 원격 맥 임대를 검토할 수 있습니다. 필요 기간과 접속 조건을 확인한 뒤 선택하고, Hook 설정과 권한 관리는 어느 환경에서도 팀의 책임으로 유지하세요.