Codex Hooks 검토 필요 — 변경된 훅이 다시 신뢰할 때까지 실행되지 않는 이유와 SessionStart 훅이 모든 세션에 프로젝트 컨텍스트를 제공하는 방법 (2026)

OpenAI의 문서는 훅을 "Codex를 위한 확장성 프레임워크"로 설명합니다. 훅을 사용하면 대화의 특정 시점에서 스크립트나 MCP 도구를 실행할 수 있습니다.

문서에는 실수로 붙여넣은 API 키를 차단하기 위해 프롬프트를 스캔하는 것, 턴이 멈출 때 유효성 검사를 실행하는 것, 그리고 기억(memory)과 직접적으로 관련된 예시인 "영구적인 기억을 자동으로 생성하기 위해 채팅 요약하기" 등이 나열되어 있습니다.

훅은 이벤트에 연결됩니다. 주요 이벤트는 다음과 같습니다:

• SessionStart: 압축(compaction) 후를 포함하여 세션이 시작될 때 실행됩니다.
• PreToolUse 및 PostToolUse: 도구 호출 전후에 실행됩니다.
• PreCompact 및 PostCompact: 압축 전후에 실행됩니다.
• UserPromptSubmit: 프롬프트를 보낼 때 실행됩니다.
• Stop: 턴이 멈출 때 실행됩니다.

Codex는 hooks.json 파일이나 config.toml의 인라인 [hooks] 테이블에서 훅을 찾습니다. 문서는 가장 유용한 네 가지 위치를 명시합니다: ~/.codex/hooks.json, ~/.codex/config.toml, 그리고 <repo>/.codex/ 아래의 동일한 두 파일입니다. 활성화된 플러그인도 훅을 포함할 수 있습니다.

둘 이상의 소스에 훅이 있는 경우 Codex는 일치하는 모든 훅을 로드합니다. OpenAI는 우선순위가 높은 레이어가 "우선순위가 낮은 훅을 대체하지 않는다"고 설명합니다.

OpenAI 문서의 검토 섹션은 이 메커니즘을 두 문장으로 설명합니다. "관리되지 않는 훅이 실행되기 전에 Codex는 정확한 훅 정의를 검토하고 신뢰할 것을 요구합니다. Codex는 훅의 현재 해시(hash)를 기준으로 신뢰를 기록하므로, 새롭거나 변경된 훅은 검토 대상으로 표시되고 신뢰될 때까지 건너뜁니다."

핵심 단어는 정확한(exact)과 해시(hash)입니다. Codex는 파일 경로 나 스크립트 이름을 신뢰하는지 묻는 것이 아닙니다. 이 정확한 정의를 신뢰하는지 묻는 것입니다. 따라서 다음 중 하나라도 해당되면 훅이 다시 검토 상태로 돌아갈 수 있습니다.

• 새 훅을 추가한 경우. 한 번도 신뢰된 적이 없습니다.
• 훅을 편집한 경우. 정의가 변경되면 해시가 달라집니다.
• 팀원이 프로젝트 훅을 변경한 경우. 리포지토리의 .codex/hooks.json이 풀(pull) 요청으로 변경되었다면, 새 버전에 대한 검토가 필요합니다.

시작 시 훅 검토가 필요한 경우, 문서는 Codex가 "/hooks를 열라고 안내하는 경고를 출력한다"고 명시합니다. 그렇게 하기 전까지 해당 훅들은 건너뛰게 됩니다.

이 부분은 놓치기 쉽습니다. 건너뛴 훅이 세션을 중단시키지는 않기 때문입니다. 만약 그 훅이 컨텍스트를 로드하는 역할이었다면, 세션은 단순히 컨텍스트 없이 시작될 뿐입니다.

CLI에서는 /hooks가 훅을 관리하는 곳입니다. OpenAI 문서는 이를 통해 "훅 소스를 검사하고, 새롭거나 변경된 훅을 검토하며, 훅을 신뢰하거나 개별 관리되지 않는 훅을 비활성화"할 수 있다고 설명합니다.

데스크톱 앱에서는 컴포저에서 'Review hooks'를 선택하거나 'Settings > Hooks'를 열어 플러그인 훅을 검토할 수 있습니다.

검토할 때는 훅이 무엇을 실행하는지, 입력을 어디서 가져오는지 확인하십시오. 신뢰는 스크립트가 세션 내에서 실행되도록 허용하는 결정이므로, 승인하기 전에 명령을 읽어볼 가치가 있습니다. 특히 직접 작성하지 않은 프로젝트 훅의 경우 더욱 그렇습니다.

두 종류의 훅은 이 검토 과정을 거치지 않습니다.

• 관리형(Managed) 훅. 시스템, MDM, 클라우드 또는 requirements.toml 소스의 훅은 "관리형으로 표시되고 정책에 의해 신뢰되며, 사용자 훅 브라우저에서 비활성화할 수 없습니다."
• 일회성 우회. 다른 곳에서 이미 훅 소스를 검증하는 자동화의 경우, Codex는 해당 호출에 대해 지속적인 신뢰 없이 활성화된 훅을 실행하는 --dangerously-bypass-hook-trust 플래그를 제공합니다. 이름에서 알 수 있듯이 이는 제한적인 경우를 위한 것입니다.

훅은 기본적으로 켜져 있습니다. config.toml의 [features] 아래에 hooks = false를 설정하여 완전히 끌 수 있습니다.

때때로 프로젝트 훅이 검토 대상으로 나타나지 않는 경우가 있는데, 이는 Codex가 해당 훅을 아예 로드하지 않았기 때문입니다. 이는 훅 신뢰가 아니라 프로젝트 신뢰의 문제입니다.

OpenAI의 훅 문서는 다음과 같이 명시합니다: "프로젝트 로컬 훅은 프로젝트 .codex/ 레이어가 신뢰될 때만 로드됩니다." 설정 기본 페이지에는 프로젝트를 신뢰하지 않음으로 표시하면 Codex가 "프로젝트 로컬 설정, 훅, 규칙을 포함하여 프로젝트 범위의 .codex/ 레이어를 건너뛴다"고 덧붙여져 있습니다. 사용자 및 시스템 훅은 여전히 로드됩니다.

따라서 리포지토리의 훅에는 두 가지 관문이 있습니다.

1. 프로젝트가 신뢰되어야 Codex가 <repo>/.codex/를 읽습니다.
2. 훅 자체가 현재 해시에서 신뢰되어야 합니다.

훅이 포함된 리포지토리를 클론했는데 아무 일도 일어나지 않는다면, 두 번째 관문 이전에 첫 번째 관문을 확인하십시오.

플러그인은 자체 훅을 가져올 수 있습니다. 기본적으로 Codex는 플러그인 내부의 hooks/hooks.json을 찾으며, 플러그인 매니페스트가 다른 곳을 가리킬 수도 있습니다. OpenAI는 플러그인 훅이 "다른 관리되지 않는 훅과 동일한 신뢰 검토 흐름을 사용한다"고 말합니다.

플러그인에만 해당하는 세부 사항이 하나 있습니다. 문서는 다음과 같이 명시합니다: "플러그인 업데이트로 인해 번들 스크립트가 변경되면, 훅 정의가 동일하더라도 Codex는 새로운 검토를 요구합니다."

따라서 자신의 설정이 전혀 변경되지 않았더라도 플러그인 업데이트로 인해 훅이 다시 검토 상태로 돌아갈 수 있습니다. 업데이트 후 플러그인 훅이 작동하지 않는다면 /hooks를 가장 먼저 확인해야 합니다.

컨텍스트의 경우 SessionStart 이벤트를 가장 먼저 살펴봐야 합니다. 세션이 시작될 때 실행되며, 반환하는 내용은 모델이 볼 수 있도록 추가됩니다.

OpenAI 문서는 SessionStart의 경우 "stdout의 일반 텍스트가 추가 개발자 컨텍스트로 추가된다"고 설명합니다. 훅은 additionalContext 필드가 포함된 JSON을 반환할 수도 있으며, "해당 additionalContext 텍스트가 추가 개발자 컨텍스트로 추가됩니다."

이 이벤트는 훅에 세션이 어떻게 시작되었는지 알려줍니다. source 필드는 startup, resume, clear, compact, 또는 fork가 될 수 있습니다. 이를 매칭하여 상황에 따라 다른 컨텍스트를 로드할 수 있습니다.

긴 작업의 경우 compact 사례를 알아두어야 합니다. 문서에 따르면 Codex가 루트 세션을 압축한 후, compact와 일치하는 SessionStart 훅은 "다음 모델 요청 전에 실행"됩니다. 여기에는 턴 중간의 자동 압축도 포함됩니다. 따라서 요약이 이전 대화를 대체한 직후, 훅은 긴 작업에서 놓쳐서는 안 될 몇 가지 사실을 다시 명시할 수 있습니다. GPT-6.1 Sol의 Codex 500k 컨텍스트 가이드에서 압축에 대해 더 자세히 다룹니다.

타이밍에 관한 한 가지 세부 사항: OpenAI는 SessionStart 훅이 MCP 서버가 준비되기 전에 실행될 수 있다고 언급합니다. 이 경우 세션을 차단하지는 않습니다.

SessionStart 훅은 모든 세션에 컨텍스트를 제공할 수 있으므로 많은 양을 넣고 싶은 유혹이 생깁니다. 문서는 제한을 설정하고 그 이유를 설명합니다.

기본적으로 Codex는 모델이 보는 각 훅 출력 메시지를 약 2,500 토큰으로 제한합니다. 훅이 그 이상을 반환하면 Codex는 전체 텍스트를 파일로 저장하고 모델에게 파일 경로가 포함된 짧은 미리보기를 제공합니다. OpenAI는 이를 스필링(spilling)이라고 부릅니다.

핸들러에서 additionalContextLimit으로 임계값을 높일 수 있지만, 문서는 이에 의존하지 말라고 경고합니다: "여러 훅과 플러그인의 컨텍스트가 쌓이면 모델 성능이 저하될 수 있습니다. additionalContextLimit을 높이면 그 위험이 커집니다."

또한 개인정보 보호 측면도 지적합니다. 너무 큰 출력은 디스크에 기록될 수 있으므로 훅 출력에 비밀번호나 기타 민감한 데이터를 반환하지 않도록 주의해야 합니다.

따라서 좋은 SessionStart 훅은 전체 문서가 아니라 중요한 내용에 대한 짧고 최신화된 요약을 로드합니다. 변경되지 않는 컨벤션의 경우 AGENTS.md가 표준적인 위치입니다. Codex가 AGENTS.md 규칙을 건너뛰지 않게 하는 방법 가이드에서 이러한 파일이 로드되는 방식을 다룹니다.

훅이 고장 났다고 가정함. 단순히 변경 후 검토를 기다리고 있는 것일 수 있습니다.

읽지 않고 다시 신뢰함. 검토 절차가 존재하는 이유는 훅이 세션 내에서 스크립트를 실행하기 때문입니다.

디버깅 중에 훅을 편집하고 다시 신뢰하는 것을 잊음. 편집할 때마다 해시가 변경됩니다.

신뢰하지 않는 프로젝트에서 프로젝트 훅을 찾음. Codex는 해당 프로젝트의 .codex/ 레이어를 건너뜁니다.

SessionStart를 통해 전체 문서를 제공함. 큰 출력은 디스크로 스필링되며 모델에는 미리보기만 전달됩니다.

1단계: /hooks를 열고 대기 중인 항목 검토

Codex를 시작하고 /hooks를 엽니다. 검토 대상으로 표시된 훅을 찾고, 각 훅이 무엇을 실행하는지 읽어본 후 예상되는 훅을 신뢰하십시오. 데스크톱 앱에서는 플러그인 훅에 대해 'Review hooks' 또는 'Settings > Hooks'를 사용하십시오.

2단계: 프로젝트 관문 확인

리포지토리 훅이 전혀 나타나지 않으면 프로젝트가 신뢰되는지 확인하십시오. Codex는 신뢰할 수 있는 프로젝트에 대해서만 <repo>/.codex/를 로드합니다.

3단계: SessionStart 훅을 짧고 안정적으로 유지

훅이 additionalContext를 통해 짧은 요약을 반환하도록 하고, startup뿐만 아니라 compact도 매칭하여 압축 후에도 요약이 다시 제공되도록 하십시오. 훅 정의를 안정적으로 유지하여 약간의 수정 때마다 다시 검토 상태로 빠지지 않게 하십시오.

SessionStart 훅은 전달 메커니즘입니다. 컨텍스트가 세션에 도달하는 시점을 결정할 뿐, 그 컨텍스트가 무엇인지 또는 어디에 보관되는지는 결정하지 않습니다. 로드하는 요약이 한 리포지토리의 스크립트나 한 기기의 파일에만 있다면, 마지막으로 편집한 사람만큼만 최신 상태를 유지하며 해당 훅이 실행되는 곳에서만 사용할 수 있습니다. Codex memories v2 가이드에서는 Codex가 기기에 보관하는 로컬 메모리를 다룹니다.

MemoryLake는 해당 프로젝트 컨텍스트를 한 곳에서 관리하고 ChatGPT, Claude Code, Codex와 같이 연결된 어시스턴트에서 사용할 수 있게 해주는 메모리 레이어입니다.

항목은 자신의 언어로 직접 작성합니다. 훅, hooks.json 또는 config.toml 파일, AGENTS.md 파일, Codex 세션, Codex 메모리 또는 벤더의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. 훅 검토, 신뢰 및 SessionStart는 OpenAI가 설명하는 방식대로 작동합니다.

1단계: API 키 생성

로그인하고 대시보드에서 키를 생성합니다. 이 키는 MemoryLake 워크스페이스에 속하며 OpenAI 계정과는 별개입니다.

2단계: 첫 번째 메모리 업로드

세션이 시작될 때 필요한 짧은 요약부터 시작하십시오: 프로젝트의 목표, 현재 결정 사항 및 제약 조건입니다. 항목당 하나의 결정을 작성하여 나머지 부분을 다시 쓰지 않고도 하나만 업데이트할 수 있게 하십시오.

3단계: AI 및 에이전트 연결

Codex 및 사용하는 다른 어시스턴트를 연결하십시오. 동일한 항목을 여러 세션과 도구에서 사용할 수 있으며, 한 곳에서 업데이트할 수 있습니다.

첫 번째 차이점은 소리 없는 공백이 줄어든다는 것입니다. 의존하는 컨텍스트가 검토를 기다리고 있을지도 모르는 스크립트에만 머물지 않습니다.

두 번째는 안정적인 훅입니다. 요약이 다른 곳에 보관되면 훅 정의가 덜 자주 변경되므로 검토 상태로 돌아가는 빈도가 줄어듭니다.

세 번째는 도구 간의 일관성입니다. Codex와 연결된 다른 어시스턴트에서 동일한 결정 사항을 사용할 수 있습니다.

모든 변경 후에는 검토를 예상하십시오. 신뢰는 훅의 현재 해시에 연결되어 있습니다.

신뢰하기 전에 읽으십시오. 훅은 세션 내에서 스크립트를 실행합니다.

프로젝트를 먼저 신뢰하십시오. 리포지토리 훅은 신뢰되지 않은 프로젝트에서 로드되지 않습니다.

플러그인 업데이트 후 다시 확인하십시오. 변경된 번들 스크립트는 새로운 검토가 필요합니다.

SessionStart에서 compact를 매칭하십시오. 압축 직후 필수 사항을 복원합니다.

훅 출력을 짧게 유지하십시오. 큰 출력은 디스크로 스필링되며 컨텍스트는 누적됩니다.

훅 출력에서 비밀 정보를 제외하십시오. 너무 큰 출력은 디스크에 기록될 수 있습니다.

훅 검토가 필요하다는 것은 Codex가 현재 버전에서 신뢰되지 않은 새롭거나 변경된 훅을 발견했음을 의미합니다. OpenAI 문서는 Codex가 각 훅의 해시를 기준으로 신뢰를 기록하므로, /hooks에서 신뢰할 때까지 새 훅이나 변경된 훅은 건너뛴다고 설명합니다. 플러그인 훅도 동일한 규칙을 따르며, 번들 스크립트를 변경하는 플러그인 업데이트는 새로운 검토가 필요합니다. 프로젝트 훅 또한 로드되기 전에 프로젝트 신뢰가 선행되어야 합니다.

가장 제대로 설정해야 할 훅은 SessionStart입니다. 세션이 시작될 때 그 출력이 개발자 컨텍스트로 추가되며, compact와 일치하는 훅은 압축 후 다시 실행됩니다. 해당 컨텍스트를 짧게 유지하고, 훅을 안정적으로 관리하며, 세션에서 기대했던 내용이 보이지 않을 때마다 /hooks를 확인하십시오.