각 도구에서 훅이란 무엇인가
Codex의 문서는 훅을 "Codex를 위한 확장 프레임워크. 에이전트 루프 중에 스크립트나 MCP 도구를 실행할 수 있게 해준다"고 설명합니다. 예시 목록에는 "영구적인 memory를 자동으로 생성하기 위해 채팅 요약", "채팅 턴이 중지될 때 표준을 강제하기 위해 커스텀 유효성 검사 실행" 등이 포함됩니다.
Claude Code의 문서는 훅이 "JSON 설정 파일에 정의"되며 이벤트, 매처 그룹, 핸들러로 구성된다고 명시합니다. 핸들러는 셸 명령, HTTP 엔드포인트, MCP 도구, 프롬프트 또는 에이전트가 될 수 있습니다.
Codex는 더 적은 수의 핸들러 유형을 지원합니다. 문서에 따르면 "command 및 mcp_tool 핸들러가 지원됩니다. prompt 및 agent 핸들러는 파싱되지만 건너뜁니다."라고 되어 있습니다. Claude Code는 이 두 가지를 모두 지원하므로, Codex에서 실제로 실행되는 모든 핸들러는 Claude Code에서 일치하는 유형을 가집니다.
훅의 위치
Codex에서 훅은 hooks.json 파일에 들어가거나 config.toml 내에 인라인으로 작성됩니다. 문서는 hooks.json의 위치를 다음과 같이 나열합니다.
- 시스템: macOS 및 Linux의
/etc/codex/hooks.json. - 사용자:
$CODEX_HOME/hooks.json(설정되지 않은 경우~/.codex/hooks.json). - 신뢰할 수 있는 프로젝트:
.codex/hooks.json.
Codex는 또한 활성화된 플러그인과 함께 번들로 제공되는 훅도 로드합니다. 한 레이어에서 두 파일을 모두 사용하는 경우, 문서는 "Codex는 두 파일을 모두 로드하고 시작 시 경고를 표시합니다. 레이어당 하나의 형식을 선호하십시오."라고 명시합니다.
Claude Code에서 훅은 설정 파일에 들어갑니다. 문서의 표에는 주요 위치가 나열되어 있습니다.
- 모든 프로젝트를 위한
~/.claude/settings.json. - 단일 프로젝트를 위한
.claude/settings.json(저장소에 커밋 가능). - 단일 프로젝트를 위한 로컬 전용
.claude/settings.local.json. - 관리형 정책 설정, 플러그인, 기술 또는 하위 에이전트 프런트매터.
따라서 Codex의 사용자 수준 hooks.json은 ~/.claude/settings.json에 가장 가깝게 매핑되며, 프로젝트의 .codex/hooks.json은 최상위 hooks 키 아래의 .claude/settings.json에 매핑됩니다.
변경 없이 이전되는 항목
여러 부분은 변환이 필요하지 않습니다.
구조. 이벤트 이름, 매처 그룹, 그룹당 핸들러 목록.
공유 이벤트 이름. SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, Stop은 두 도구의 참조 문서에 모두 나타납니다.
SessionStart 소스. Codex는 startup, resume, clear, compact, fork를 나열합니다. Claude Code의 SessionStart 매처 표에도 동일한 5가지 값이 나열되어 있습니다.
공통 입력 필드. 둘 다 session_id, transcript_path, cwd, hook_event_name, permission_mode가 포함된 JSON을 stdin으로 보냅니다.
종료 코드 2. Codex에서 여러 이벤트는 "종료 코드 2를 사용하고 차단 이유를 stderr에 작성"할 수 있도록 허용합니다. Claude Code 또한 이를 지원하는 이벤트에서 종료 코드 2를 차단 신호로 처리하며, 이벤트별 동작을 문서화하고 있습니다.
기본 타임아웃. Codex는 대부분의 훅에 600초를 사용합니다. Claude Code 또한 명령 훅의 기본값으로 600초를 나열합니다.
변환이 필요한 항목
매처(Matchers). 둘 다 도구 이름이나 시작 소스로 필터링하기 위해 매처를 사용하지만, 평가 방식이 다릅니다. Codex는 매처가 "정규식 문자열"이라고 명시합니다. Claude Code는 문자, 숫자 및 몇 가지 구분 기호로만 구성된 매처는 정확한 이름으로 취급하고, 그 외의 것은 앵커가 없는 JavaScript 정규식으로 취급합니다. ^apply_patch$와 같은 Codex 매처는 Claude Code에서도 정규식으로 유지되지만, 그 안의 도구 이름은 변경해야 합니다.
도구 이름. Codex의 셸 도구는 Bash로 매칭되며, 이는 Claude Code의 이름과 동일합니다. 파일 편집은 다릅니다. Codex에서 apply_patch는 apply_patch, Edit, 또는 Write로 매칭될 수 있습니다. Claude Code에서 편집 도구는 Edit 및 Write와 같은 이름으로 매칭됩니다. Codex 훅이 이미 Edit|Write를 사용 중이라면 그대로 이전되지만, apply_patch를 사용 중이라면 변경하십시오.
MCP 도구 이름. 둘 다 예제에서 mcp__server__tool 패턴을 사용하므로 MCP 매처는 그대로 이전될 수 있습니다. 서버 이름이 두 도구에서 동일한지 확인하십시오.
스크립트 경로. Codex의 예제는 Git을 통해 .codex/hooks/ 아래의 경로로 프로젝트 스크립트를 참조합니다. Claude Code는 이를 위해 ${CLAUDE_PROJECT_DIR}("세션이 시작된 프로젝트 루트")라는 플레이스홀더를 제공합니다. 스크립트를 .claude/hooks/로 이동하는 경우 경로도 업데이트하십시오.
모델 필드. Codex는 model을 공통 입력 필드이자 "Codex 전용 확장"으로 나열합니다. Claude Code는 "SessionStart 훅만 model 필드를 받을 수 있으며, Claude Code가 항상 이를 포함하는 것은 아니다"라고 명시합니다. 모든 이벤트에서 모델을 읽는 Codex 스크립트에는 폴백(fallback)이 필요합니다.
턴 ID. Codex는 턴 범위 훅에 turn_id를 추가합니다. Claude Code의 공통 필드에는 처리 중인 사용자 프롬프트를 식별하는 prompt_id가 포함됩니다. 턴 ID를 키로 사용하는 로깅 스크립트는 조정이 필요합니다.
컨텍스트 제한. Codex의 additionalContextLimit 필드는 Codex가 전체 텍스트를 디스크에 저장하기 전에 훅이 보낼 수 있는 컨텍스트 양을 제어합니다. Claude Code의 핸들러 필드 표에는 이 필드가 없으므로 핸들러를 복사할 때 제거하십시오.
한쪽에만 존재하는 이벤트
Codex는 Claude Code의 훅 참조 문서에 동일한 이름으로 포함되지 않은 세 가지 이벤트를 나열합니다: PreModelRequest, PostModelRequest, Interrupt. Codex는 처음 두 개를 "각 모델 요청 시도 시" 실행하고, Interrupt는 활성 턴을 중단할 때 실행합니다.
이러한 이벤트에 의존하고 있다면 가장 유사한 Claude Code 이벤트를 찾거나 해당 동작이 이전되지 않음을 수용해야 합니다. 반대로 Claude Code에는 PostToolUseFailure, Notification, FileChanged, PreModelSwitch 등 Codex에 없는 많은 이벤트가 있습니다. 마이그레이션은 이러한 이벤트 중 하나가 작업을 더 잘 수행할 수 있는지 확인할 좋은 기회입니다.
각 도구의 신뢰 작동 방식
Codex는 훅을 개별적으로 신뢰합니다. 문서에 따르면: "관리되지 않는 훅이 실행되기 전에 Codex는 사용자가 정확한 훅 정의를 검토하고 신뢰할 것을 요구합니다. Codex는 훅의 현재 해시를 기준으로 신뢰를 기록하므로, 새롭거나 변경된 훅은 검토 대상으로 표시되고 신뢰될 때까지 건너뜁니다."
Claude Code는 대신 워크스페이스 신뢰를 확인합니다. 대화형 세션에서 Claude Code는 "사용자의 ~/.claude/settings.json을 포함하여 모든 설정 파일의 훅 실행을 보류하며, 폴더에 대한 워크스페이스 신뢰 대화 상자를 수락할 때까지 기다립니다." -p 또는 SDK 세션에서는 "폴더를 신뢰할 수 있는 것으로 취급"합니다.
Claude Code의 /hooks 메뉴는 각 훅과 그 출처를 보여주는 읽기 전용 브라우저입니다. 마이그레이션 후 이를 사용하여 모든 훅이 예상한 위치에 배치되었는지 확인하십시오.
플러그인, 관리형 및 비활성화된 훅
모든 훅을 직접 이동할 수 있는 것은 아닙니다.
플러그인 훅은 해당 플러그인과 함께 이동합니다. Codex는 활성화된 플러그인이 매니페스트 또는 기본적으로 플러그인 루트의 hooks/hooks.json을 통해 훅을 제공할 수 있다고 명시합니다. Claude Code는 플러그인 내부에서 동일한 파일 이름을 사용하며, 문서에 따르면 "플러그인이 활성화되면 해당 훅이 사용자 및 프로젝트 훅과 병합됩니다." 훅이 플러그인에서 온 것이라면 훅을 복사하는 대신 해당 플러그인의 Claude Code 버전을 설치하십시오.
관리형 훅은 관리자의 소유입니다. Codex는 시스템, MDM, 클라우드 또는 requirements.toml 소스의 훅을 정책에 의해 관리되고 신뢰되는 것으로 표시합니다. Claude Code에는 관리형 정책 설정과 사용자, 프로젝트, 로컬 및 플러그인 훅을 차단하는 allowManagedHooksOnly 설정이 있습니다. 관리형 훅을 직접 재생성하기 전에 관리자에게 확인하십시오.
훅 비활성화 방식도 다릅니다. Codex에서 훅은 기본적으로 활성화되어 있으며 config.toml의 기능 플래그로 비활성화합니다. Claude Code에서 문서화된 스위치는 설정 파일의 disableAllHooks이며, 이는 관리형 설정 외부에서 관리형 훅을 비활성화할 수 없습니다.
컨텍스트 로딩 훅 이동하기
컨텍스트를 로드하는 SessionStart 훅은 에이전트가 첫 번째 턴부터 알고 있는 내용을 결정하기 때문에 가장 정확하게 설정해야 합니다.
Codex에서 "stdout의 일반 텍스트는 추가 개발자 컨텍스트로 추가"되며, JSON additionalContext 필드도 동일하게 작동합니다. Codex는 또한 세션을 압축한 후 compact와 일치하는 SessionStart 훅을 실행하므로 요약 후에도 컨텍스트가 다시 돌아옵니다.
Claude Code도 유사하게 작동합니다. 문서에 따르면 SessionStart의 경우 "Claude Code는 Claude가 보고 조치를 취할 수 있는 컨텍스트로 일반 텍스트 stdout을 추가합니다." 또한 compact 소스는 "자동 또는 수동 압축" 후에 실행됩니다.
Claude Code는 훅에 무엇이 포함되어야 하는지에 대한 조언을 추가합니다. SessionStart 섹션에서는 이 이벤트가 "기존 이슈나 코드베이스의 최근 변경 사항과 같은 개발 컨텍스트를 로드하는 데 유용하다"고 언급한 후, "스크립트가 필요하지 않은 정적 컨텍스트의 경우 CLAUDE.md를 사용하십시오"라고 덧붙입니다.
따라서 Codex 훅이 매번 동일한 규칙을 출력하기만 한다면, 마이그레이션은 해당 텍스트를 CLAUDE.md로 옮기고 훅은 변경되는 컨텍스트를 위해서만 유지할 기회입니다. 어떤 Claude Code 훅이 컨텍스트를 추가할 수 있는지, 그리고 언제 CLAUDE.md가 더 나은 장소인지는 Claude Code hooks 가이드에서 다루었습니다.
사람들이 처음에 시도하는 것들
/import codex가 훅을 가져올 것이라고 기대함. 문서화된 목록에는 지침 파일, MCP 서버, 명령, 하위 에이전트 및 기술만 포함됩니다.
hooks.json을 .claude/에 복사함. Claude Code의 문서화된 위치는 설정 파일, 플러그인, 기술 또는 하위 에이전트 프런트매터입니다.
매처에 apply_patch를 유지함. Claude Code의 편집 도구는 다른 이름을 사용합니다.
모든 이벤트에서 model을 읽음. Claude Code에서는 SessionStart만 이를 받을 수 있습니다.
훅에 정적 규칙을 유지함. Claude Code는 정적 컨텍스트를 위해 CLAUDE.md를 권장합니다.
수동 마이그레이션
1단계: Codex 훅 목록 작성
Codex CLI에서 /hooks를 열고 각 훅의 소스, 이벤트, 매처 및 명령을 기록합니다.
2단계: Claude Code 설정 파일 선택
개인용 훅은 ~/.claude/settings.json을, 공유 프로젝트 훅은 .claude/settings.json을 사용합니다.
3단계: 구조 복사
hooks 키 아래에 각 이벤트 및 매처 그룹을 재생성하고, TOML 형식의 훅은 JSON으로 변환합니다.
4단계: 매처 및 경로 변환
apply_patch를 교체하고, 정규식 매처를 확인하며, 스크립트 경로가 ${CLAUDE_PROJECT_DIR}을 가리키도록 수정합니다.
5단계: Codex 전용 필드를 읽는 스크립트 조정
model 및 turn_id에 대한 폴백을 추가하고 additionalContextLimit을 제거합니다.
6단계: 정적 컨텍스트를 CLAUDE.md로 이동
변경되는 컨텍스트를 위해서만 훅을 유지하십시오. 고정된 규칙은 CLAUDE.md에 넣습니다.
7단계: 폴더 신뢰 및 확인
워크스페이스 신뢰 대화 상자를 수락한 다음, /hooks를 확인하고 각 이벤트를 한 번씩 트리거해 봅니다.
더 나은 방법: 훅이 강제하는 내용을 한곳에 유지하기
훅은 규칙을 강제하고 컨텍스트를 로드합니다. 명령이 차단된 이유, 검사가 구현하는 정책, 또는 세션 노트에 포함되어야 하는 내용과 같은 그 이면의 이유는 프로젝트 컨텍스트입니다. 훅이 도구 간에 이동할 때 스크립트는 따라오지만, 그 이면의 논리는 누군가의 기억 속에만 남을 수 있습니다.
MemoryLake는 정책, 규칙 및 검사 이면의 이유와 같은 프로젝트 컨텍스트를 위한 memory 레이어입니다. 이를 한곳에서 유지 관리하고 ChatGPT, Claude Code, Codex와 같이 연결된 어시스턴트에서 사용할 수 있습니다.
사용자는 자신의 언어로 직접 항목을 작성합니다. hooks.json 파일, 설정 파일, 훅 스크립트, Codex 또는 Claude Code 세션, 또는 어떤 벤더의 저장소에서도 내용을 읽거나 쓰거나 삭제하지 않습니다. 훅은 OpenAI와 Anthropic이 설명하는 방식 그대로 작동합니다.
1단계: API 키 생성
로그인하고 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 저장소 외부에 보관하십시오.

2단계: 첫 번째 memory 업로드
수동 마이그레이션의 1단계에서 나열한 훅부터 시작하십시오. 각 훅에 대해 무엇을 강제하는지, 그리고 그 이유가 무엇인지 작성합니다. 항목당 하나의 훅을 작성합니다.

3단계: AI 및 에이전트 연결
Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결합니다. 어떤 도구가 훅을 실행하든 동일한 근거를 활용할 수 있습니다.

실제적인 변화
첫 번째 차이점은 더 쉬운 변환입니다. 훅의 목적이 기록되어 있으면 이름이 다르더라도 올바른 Claude Code 이벤트를 선택할 수 있습니다.
두 번째는 중복 감소입니다. 변경되지 않는 컨텍스트는 매 세션마다 출력하는 스크립트가 아니라 CLAUDE.md에 한 번만 작성됩니다.
세 번째는 도구 간의 일관성입니다. Claude Code와 Codex 모두에서 동일한 정책과 근거를 사용할 수 있습니다.
Codex 훅을 Claude Code로 이동하기 위한 모범 사례
먼저 인벤토리 작성. Codex에서 /hooks를 사용하여 모든 소스를 확인하십시오.
의도적으로 파일 매핑. 사용자 훅은 ~/.claude/settings.json으로, 프로젝트 훅은 .claude/settings.json으로 보냅니다.
도구 이름 변환. apply_patch는 Edit 또는 Write가 됩니다.
스크립트에 ${CLAUDE_PROJECT_DIR} 사용. 세션이 시작된 프로젝트 루트를 가리킵니다.
Codex 전용 이벤트 확인. PreModelRequest, PostModelRequest, Interrupt에 대한 계획이 필요합니다.
정적 텍스트를 CLAUDE.md로 이동. 변경되는 컨텍스트를 위해서만 훅을 유지하십시오.
스크립트 실행 전 .claude/ 검토. -p 세션은 폴더를 신뢰할 수 있는 것으로 취급합니다.
결론
Claude Code의 /import codex는 지침 파일, MCP 서버, 명령, 하위 에이전트 및 기술을 가져오지만, 훅은 해당 목록에 없습니다. 두 도구 모두 이벤트, 매처 그룹, 핸들러라는 동일한 세 가지 수준을 사용하므로 수동 이동은 대부분 변환 작업입니다. 대부분의 이벤트 이름, SessionStart 소스, 공통 입력 필드, 종료 코드 2 및 기본 타임아웃은 그대로 유지됩니다.
세부 사항에서 변화가 있습니다. 매처 평가 방식이 다르고, apply_patch는 Claude Code 도구 이름이 필요하며, 스크립트 경로는 ${CLAUDE_PROJECT_DIR}을 사용해야 하고, model, turn_id 또는 additionalContextLimit을 읽는 스크립트는 조정이 필요합니다. Codex는 각 훅을 해시로 신뢰하는 반면, Claude Code는 워크스페이스 신뢰를 확인합니다. 이번 이동을 계기로 정적 컨텍스트는 CLAUDE.md에 넣고, 훅은 변화하는 내용을 위해서만 활용해 보십시오.