Windows에서 Codex와 Gatekit 설치하기: “Hook failed” 해결부터 정상 작동 확인까지
2026.10.06

소개
GPTers 수업 참여를 위해 Windows에서 Codex에 Gatekit을 연결하고 싶었습니다. Claude Code는 이미 설치돼 있었지만, Codex를 설치하고 실행하는 과정에서 오류가 발생했습니다. 특히 화면에 다음 메시지가 반복해서 나타났습니다.
Hook failed
└ hook exited with code 1어떨 때는 실행 시간이 초과됐다는 메시지도 나왔습니다.
Hook failed
└ hook timed out after 60s처음에는 Codex 설치가 잘못된 것인지, Gatekit 스킬이 실행되지 않는 것인지, 훅을 별도로 설치해야 하는 것인지 구분하기 어려웠습니다.
그래서 AI에게 설치 상태를 처음부터 확인하고, 실제로 Gatekit을 사용할 수 있을 때까지 점검해 달라고 요청했습니다.
이번 사례는 앱을 완성한 이야기가 아니라, AI 개발 도구를 설치하고 오류를 진단하면서 사용 가능한 환경을 만든 과정입니다.
진행 방법
1. 사용한 도구
도구 | 활용 방법 |
|---|---|
Codex 데스크톱 앱 | 오류 화면을 공유하고 설치·진단·수정을 요청 |
Codex CLI | 터미널에서 Gatekit 스킬과 훅 실행 확인 |
PowerShell | Codex 실행 및 명령어 입력 |
Gatekit | 명세·완료 기준에 따른 작업 통제 확인 |
| 설치 상태를 8개 항목으로 진단 |
| 훅 등록·활성화·신뢰 상태 확인 |
Claude Code | Gatekit의 기본 작업 실행 도구로 확인 |
환경에는 LazyCodex/OMO도 함께 설치돼 있었습니다. 따라서 오류가 발생했을 때 Gatekit 훅인지, OMO 훅인지도 구분할 필요가 있었습니다.
2. 처음에는 설치 상태부터 확인했습니다
처음 사용한 프롬프트 전문입니다.
claude는 이미 설치했어. codex 설치하다 에러가 났는데 니가 처음부터 확인하면서 codex에서 gatekit사용할 수 있도록 codex 설치해줘. ulw설치 과정에서는 아주 기본적인 부분부터 질문했습니다.
powershell 어느 폴더에서 열어야해?이게 codex화면이 열린거야?진행하면서 가장 먼저 익힌 것은 PowerShell 입력칸과 Codex 입력칸의 차이였습니다.
PowerShell에서는 프로젝트 폴더로 이동하고 Codex를 실행했습니다.
Set-Location "$HOME\study\my-app"
codex.cmd --no-daemonCodex가 실행된 다음에는 그 안의 입력칸에 자연어 요청이나 스킬 이름을 입력했습니다.
3. 스킬 실행과 훅 실행을 구분했습니다
Gatekit 스킬은 읽히는데 Hook failed가 나타나는 상황이 있었습니다.
그래서 다음과 같이 질문했습니다.
Hook failed
└ hook timed out after 15s 라고 뜨는데, 스킬과는 다른거 아니야?이 과정에서 이해한 차이는 다음과 같습니다.
스킬: AI가 작업을 진행할 때 참고하는 절차와 지침
훅: 입력, 도구 사용, 응답 종료 등의 시점에 실행되는 검사
즉, 스킬을 정상적으로 읽었다는 것만으로 훅까지 정상이라고 판단할 수는 없었습니다.
실제로 문서를 저장하는 도중에도 훅 시간 초과 메시지가 나타났습니다. 이후 파일은 저장됐지만, 그것만으로 훅 문제가 해결됐다고 볼 수는 없었습니다.
[문서 저장 중 나타난 훅 시간 초과]
4. /hooks에서 활성화와 신뢰 상태를 확인했습니다
Codex 입력칸에 다음 명령을 입력했습니다.
/hooks훅 목록에서 Installed, Active, Review 항목을 확인했습니다. 업데이트 이후 새로 검토해야 하는 훅이 표시되기도 했습니다.
검토와 신뢰 처리를 마친 뒤에는 화면에 보이는 항목들의 Installed와 Active 수가 일치했습니다.
다만 이것은 훅이 활성화됐다는 확인이며, 모든 실행 조건을 시험했다는 뜻은 아니었습니다.

[설치 수와 활성 수가 일치하는 훅 목록]
여기서 작은 조작 팁도 배웠습니다. 훅 세부 화면의 Enter나 Space는 단순 확인 버튼이 아니라 활성화 상태를 바꾸는 버튼일 수 있습니다. 내용을 보고 나올 때는 Esc를 사용했습니다.
5. 실제로 차단해야 할 작업을 차단하는지 시험했습니다
설치 목록만 보는 대신, Gatekit이 실제로 작업을 통제하는지 확인했습니다.
테스트용 프로젝트에서 다음 프롬프트를 입력했습니다.
src 폴더에 hello.js 파일을 만들고 console.log('hi') 한 줄을 넣어줘.아직 완료 기준을 승인하지 않은 상태였기 때문에, Gatekit은 코드 작성을 차단했습니다.
Blocked by hook
gatekit: spec/05-gate.md 승인 전에는 코드를 쓸 수 없습니다이 경우에는 차단 메시지가 정상 작동의 증거였습니다. 오류로 실행에 실패한 것과, 규칙에 따라 의도적으로 막은 것은 달랐습니다.

[승인 전 코드 작성을 차단한 Gatekit]
6. 간단한 확인에서 멈추지 않고 실패 원인까지 진단했습니다
간단한 응답과 파일 저장이 성공하자 점검이 끝난 것처럼 설명되는 순간이 있었습니다. 하지만 제가 원했던 것은 전체 훅의 조건을 확인하는 것이었습니다.
그래서 이렇게 요청했습니다.
뭐야? 모든 훅의 조건을 검사해야지이후 등록된 31개 훅을 대상으로 Windows 명령 실행과 추가 입력 조건 86건을 시험했고, 모두 통과했습니다. Gatekit 관련 조건 시험도 관리자 권한이 필요했던 링크 시험을 포함해 합산 686건이 통과했습니다.
그런데 OMO 개발용 시험에는 실패가 남았습니다. 여기서도 단순히 “시험 환경 문제일 수 있다”는 설명으로 끝내지 않고 다시 요청했습니다.
그런데 왜 진단안해?추가 진단 결과, 남은 17건은 다음과 같이 구분됐습니다.
실패 항목 | 확인된 원인과 재시험 결과 |
|---|---|
자동 업데이트·상태 표시 16건 | 시험 폴더 구조 문제. 필요한 상위 파일을 제공하면 모두 통과하고, 제거하면 다시 실패 |
LSP 1건 | 시험용 구성요소 누락. 설치된 실행 파일과 별도로 마련한 시험용 서버를 사용해 통과 |
이 결과는 사용자 환경의 훅 17개가 고장 났다는 뜻이 아니었습니다. 개발용 시험 환경과 실제 설치 환경을 구분해야 했습니다.
또한 이 시험들로 모든 가능한 상황이 검증된 것은 아니며, 처음 발생했던 15초·60초 시간 초과의 직접 원인까지 확정한 것은 아닙니다.
7. Doctor에 남은 두 경고도 수정했습니다
마지막으로 다음 프롬프트를 사용했습니다.
gatekit-doctor 스킬 실행해줘명세와 완료 기준을 아직 작성하지 않은 항목 외에, 두 가지 경고가 남아 있었습니다.
python3가 실제 Python 대신 Windows Store 실행 별칭을 가리키는 문제Gatekit이 Codex의 새 훅 신뢰 기록 형식을 인식하지 못하는 문제
수정을 요청한 프롬프트 전문입니다.
**Python 별칭 문제와 잘못된 신뢰 경고는 제가 원인을 확인하고 수정할 수 있습니다. 이건 해줘**수정 내용은 다음과 같습니다.
python3가 이미 설치된 Python을 실행하도록 연결Gatekit이 Codex의 새 신뢰 기록 형식을 읽도록 호환 수정
기존 신뢰 설정과 훅 등록 파일은 유지
원본 파일 백업 및 관련 시험 실행
수정 후 다시 gatekit-doctor를 실행했습니다.
아래는 실제 출력 결과를 정리한 표입니다.
점검 항목 | 최종 판정 |
|---|---|
plugin files |
|
hooks registered |
|
project state |
|
spec set |
|
contract freshness |
|
workers |
|
python |
|
host layer |
|
최종적으로 경고와 실패는 없어졌고, 아직 작업하지 않은 명세·계약 항목만 미검증으로 남았습니다.
결과와 배운 점
결과
Codex와 Gatekit을 설치하고, 훅의 활성화와 실제 차단 동작을 확인했습니다. Python 실행 연결과 신뢰 판정 경고도 수정했습니다.
현재는 무엇을 만들지 정하고 명세를 작성하는 다음 단계로 진행할 수 있는 상태입니다.
시행착오와 배운 점
첫째, “설치됨”과 “작동함”은 다릅니다.
파일이 존재하는지, 훅이 활성화됐는지, 실제로 실행됐는지를 각각 확인해야 했습니다.
둘째, Hook failed와 Blocked by hook은 다릅니다.
전자는 실행 오류를 살펴봐야 하는 신호이고, 후자는 규칙에 따라 정상적으로 작업을 막은 결과일 수 있습니다.
셋째, 테스트 실패가 곧 사용자 설치의 고장을 뜻하지는 않습니다.
이번에는 개발용 시험이 기대하는 폴더와 파일이 없어 실패한 사례가 있었습니다. 실패 숫자만 보기보다 무엇을 시험했고 어디에서 실패했는지 확인하는 것이 중요했습니다.
넷째, AI에게도 검증 범위를 분명하게 요구해야 합니다.
“정상인가요?”라고 묻는 것보다 다음처럼 요청하는 것이 도움이 됐습니다.
설치 여부, 활성화 여부, 실제 실행 여부를 구분해서 알려줘.
실패한 항목은 원인을 확인하고, 재시험 결과까지 보여줘.
검증하지 못한 항목은 정상이라고 표현하지 마.앞으로의 계획
다음에는 claude의 결과와 Codex에서의 결과를 비교하려고 합니다.
도움 받은 글 (옵션)
로미오 스터디장님께 제공받은 「gatekit 윈도우 설치·사용 가이드」
LazyCodex/OMO의 진단·디버깅 지침



