Codex Hooks Programmatic Access Token 2026 시크릿 스캔 운영표

2026년 5월 24일 기준 OpenAI Codex 문서에서 hooks는 에이전트 실행 흐름에 스크립트를 끼워 넣는 확장 장치이고, Codex access token은 신뢰된 자동화가 ChatGPT workspace identity로 Codex local을 반복 실행하게 하는 인증 수단이다. 둘을 같이 쓰면 자동화는 강해지지만, 먼저 정해야 할 것은 “무엇을 더 시킬까”가 아니라 “무엇은 절대 못 하게 할까”다.

자동화 기능이 새로 보이면 손이 먼저 간다. hooks로 명령을 검사하고, Programmatic Access Token으로 CI나 스케줄러에서 Codex를 돌리고, 결과를 로그로 남기면 꽤 근사해 보인다. 그런데 이 조합은 편의 기능이 아니라 운영 권한의 조립이다. 조립을 잘하면 안전벨트가 되고, 대충 붙이면 토큰이 달린 리모컨이 된다.

이 글은 Codex Hooks와 Programmatic Access Token을 켜기 전에 볼 운영표다. “이 기능 좋다”가 아니라, 어떤 환경에서 토큰을 쓰고, 어떤 hook event를 막는 용도로 쓰고, 어떤 로그는 남기지 말아야 하는지에 초점을 둔다. TECHTAEK식으로 말하면 버튼 자랑보다 브레이크 위치 확인이다.

5월 25일 보강: 인터넷 접근은 allowlist부터

OpenAI Codex web 문서는 agent phase의 인터넷 접근을 기본 차단으로 두고, 필요할 때 환경별로 켜는 구조를 설명한다. 이유도 분명하다. 인터넷 접근을 열면 prompt injection, 코드나 secret 유출, 취약한 dependency 다운로드, 라이선스 제한 콘텐츠 유입 같은 위험이 커진다. 그래서 Hooks와 PAT를 같이 쓰는 자동화에서는 “네트워크가 필요한가”를 먼저 묻고, 필요하다면 domain과 HTTP method를 좁혀야 한다.

자동화 상황	인터넷 기본값	열어야 한다면	hook에서 볼 것
repo 내부 lint/test	off	보통 열지 않음	외부 curl, wget, package install 시도
공식 문서 확인	allowlist	`developers.openai.com`, 필요한 공식 domain만	Web source가 명령 실행 지시로 바뀌는지
dependency 설치	setup 단계 분리	lockfile과 registry만	agent phase에서 임의 install 금지
CI 요약 댓글	off 또는 사내 endpoint만	PR comment API만	raw tool output에 secret-like pattern 포함 여부
PAT 기반 scheduled run	off 우선	업무상 필요한 domain만	token env 출력, auth file 읽기, 외부 POST

운영 원칙은 간단하다. PAT -> sandbox -> approval -> hooks -> network allowlist -> output redaction 순서로 잠근다. 네트워크를 넓게 열고 hooks로만 막겠다는 설계는 늦다. hooks는 좋은 차단기지만, 외부로 나갈 길 자체를 좁히는 설정이 먼저다.

먼저 잡을 답

Codex Hooks는 보안 경계 자체가 아니라 실행 전후에 정책 스크립트를 붙이는 보조 장치다. Programmatic Access Token도 만능 API key가 아니라 ChatGPT Business 또는 Enterprise workspace의 Codex local 자동화용 identity에 가깝다. 그래서 순서는 sandbox/approval -> credential type -> hook policy -> secret scan -> 48시간 로그 검수가 맞다.

공식 문서 기준으로 Codex local은 sandbox mode와 approval policy를 함께 쓴다. sandbox는 기술적으로 어디까지 접근 가능한지 정하고, approval은 어떤 행동에서 사람 확인을 요구할지 정한다. hooks는 그 위에 붙는 정책 레이어다. 즉 hooks를 켰다고 .env가 안전해지는 게 아니라, .env 접근을 줄이는 sandbox와 승인 규칙을 먼저 잡고 hooks로 추가 검사를 붙이는 구조가 더 안전하다.

Programmatic Access Token은 자동화 identity다. OpenAI 문서는 이 토큰을 script, scheduled job, CI runner처럼 반복적이고 비대화형인 Codex local 실행에 쓰는 것으로 설명한다. 일반 OpenAI API 호출에 쓰는 자격증명이 아니며, API key로 충분한 자동화라면 API key를 계속 쓰는 쪽이 기본값이다. 이 구분을 안 하면 토큰 창고가 금방 뒤엉킨다.

세 기능을 같은 층으로 보면 사고가 난다

Codex Hooks, access token, sandbox를 한 줄에 놓고 “보안 기능 3종”으로 보면 위험하다. 세 기능은 서로 역할이 다르다. sandbox는 실행 가능한 범위를 줄이고, approval은 멈춰서 묻게 만들고, hooks는 특정 순간에 정책 스크립트를 실행한다. access token은 실행 주체를 만든다.

예를 들어 CI에서 codex exec를 돌린다고 해보자. 여기서 access token은 “누구 이름으로 실행하나”의 문제다. sandbox는 “그 실행이 repo 안에서만 쓰기 가능한가”의 문제고, hook은 “Bash 실행 전에 위험한 문자열을 잡을 것인가”의 문제다. 이 셋을 섞으면 나중에 사고가 났을 때 원인도 섞인다. 인증 문제인지, 권한 문제인지, hook 누락인지부터 다시 캐야 한다.

내가 운영표를 만든다면 첫 줄은 늘 identity다. 이 자동화가 API key로 충분한가, ChatGPT workspace entitlements가 필요한가, workspace governance에 남겨야 하는가를 먼저 본다. 그다음 runner가 신뢰 가능한지 본다. public CI, forked PR, 공유 머신이면 access token은 기본적으로 들고 가지 않는다. 여기서 한 번 멈추는 게 좋다. 자동화 세계에서는 멈춤 버튼도 기능이다.

운영표: 어디서 무엇을 열어도 되나

환경	credential 기본값	sandbox/approval	hooks 용도	금지선
개인 로컬 실험 repo	브라우저 로그인 또는 API key	`workspace-write` + `on-request`	Bash/patch 전 위험 명령 경고	`danger-full-access` 상시 사용 금지
회사 내부 trusted CI	API key 우선, 필요 시 access token	`codex exec --sandbox workspace-write`	테스트 실패 요약, secret pattern 차단	public fork PR에 토큰 주입 금지
ChatGPT workspace 감사가 필요한 자동화	finite expiration access token	좁은 workspace, network off 기본	`PreToolUse`, `PermissionRequest` 정책 검사	개인 토큰을 팀 공용으로 재사용 금지
공개 오픈소스 repo	API key도 최소화	read-only 또는 별도 isolated runner	요약/리뷰 중심	`~/.codex/auth.json`, access token 주입 금지
배포/릴리즈 job	별도 workflow owner 토큰	승인 게이트 유지	release note, diff review, allowlist 확인	배포 토큰과 Codex 토큰을 같은 secret scope에 묶기 금지

이 표에서 핵심은 access token을 “더 강한 키”처럼 취급하지 않는 것이다. 오히려 더 좁게 써야 한다. workspace user identity와 audit trail이 붙는 만큼, 누가 만들었고 어느 workflow에서 쓰며 언제 만료되는지 기록해야 한다. 이름도 release-ci처럼 기능 단위로 붙이는 편이 좋다. my-token-final-real 같은 이름은 미래의 나에게 작은 벌칙이다.

OpenAI 문서는 access token 생성 시 만료일을 고르도록 안내하고, 7일, 30일, 60일, 90일 같은 유한 만료를 선호하라고 설명한다. 토큰은 만든 뒤 다시 볼 수 없으니 바로 secret manager나 CI secret store에 넣어야 한다. 로그에 출력하지 않는 것도 기본이다. echo $CODEX_ACCESS_TOKEN을 디버깅 습관으로 쓰는 순간, 자동화의 품격이 살짝 삐끗한다.

Hooks는 차단기이지만 만능 방화벽은 아니다

Codex Hooks는 event, matcher group, handler 구조로 동작한다. 현재 실행되는 handler는 command hook 중심이고, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop 같은 lifecycle 지점에 붙일 수 있다. repo-local hook을 쓸 때는 Codex가 하위 디렉터리에서 시작될 수 있으므로 git root 기준으로 script path를 잡는 편이 안전하다.

보안 관점에서 제일 먼저 볼 event는 PreToolUse와 PermissionRequest다. PreToolUse는 Bash, apply_patch, MCP tool call 같은 지원 도구 호출 전에 검사할 수 있다. 위험 명령이나 secret 파일 접근을 미리 막는 데 쓸 수 있다. PermissionRequest는 Codex가 원래 승인을 요청하려는 순간에 정책적으로 허용하거나 거절하는 데 맞다.

반대로 PostToolUse는 사고를 되돌리는 장치가 아니다. 도구 실행이 끝난 뒤 피드백을 주는 쪽에 가깝다. 예를 들어 명령 출력에서 secret처럼 보이는 값이 감지되면 “이 결과를 계속 처리하지 말라”고 모델에게 피드백할 수는 있지만, 이미 실행된 명령의 부작용을 없애지는 못한다. 그래서 위험한 것은 사후 알림보다 사전 차단에 둬야 한다.

hooks 자체에도 신뢰 절차가 있다. 공식 문서 기준으로 non-managed command hook은 실행 전에 검토와 trust가 필요하고, 변경되면 다시 검토 대상이 된다. 이건 귀찮은 장치가 아니라 좋은 장치다. hook은 결국 로컬 script 실행이기 때문에, 누가 바꿨는지 모르는 hook을 자동으로 믿으면 보안 장치가 실행 장치로 뒤집힌다.

시크릿 스캔은 패턴보다 동선이 중요하다

시크릿 스캔을 hook에 붙인다고 하면 보통 정규식부터 떠올린다. sk-, ghp_, CODEX_ACCESS_TOKEN, OPENAI_API_KEY 같은 문자열을 찾는 식이다. 이건 필요하지만 충분하지 않다. 실제 운영에서는 “어떤 명령이 어떤 파일을 읽으려 하는가”와 “그 출력이 어디로 흘러가는가”를 같이 봐야 한다.

내가 권장하는 최소 차단 목록은 단순하다. cat ~/.codex/auth.json, printenv, env, .env 전체 출력, secret store dump, CI secret 이름을 그대로 출력하는 명령은 기본 차단 후보로 둔다. grep -R TOKEN .도 상황에 따라 위험하다. 찾는 명령처럼 보이지만 결과가 로그에 남으면 그대로 유출 경로가 된다.

그다음은 출력 동선이다. codex exec --json은 자동화에 좋지만, JSONL stream 안에 tool input, command output, error context가 섞일 수 있다. non-interactive 문서도 prompt와 tool output이 민감한 코드나 데이터를 포함할 수 있다는 점을 경고한다. 그래서 CI artifact, Slack comment, PR comment로 Codex 결과를 넘길 때는 secret redaction을 한 번 더 통과시키는 편이 좋다.

운영표로 정리하면 이렇다.

검사 지점	막을 것	허용할 것	기록
`PreToolUse` Bash	`.env`, auth file, token env 출력	test, lint, build, read-only list	차단 사유와 command hash
`PermissionRequest`	network broad allow, outside workspace edit	승인된 domain allowlist	사람 승인 여부
`PostToolUse`	secret-like output 계속 처리	redacted summary	redaction count
CI 후처리	raw JSONL artifact 공개	final summary만 저장	workflow id, runner type
주간 회전	만료 없는 access token	30일 이하 실험 토큰	owner, expiry, revoke date

PAT를 써도 되는 순간과 안 되는 순간

Programmatic Access Token을 써도 되는 순간은 workflow가 신뢰된 runner에서 돌아가고, ChatGPT workspace identity가 필요한 경우다. 예를 들어 Business 또는 Enterprise workspace에서 Codex local entitlements와 governance trail이 필요한 scheduled docs check라면 access token 후보가 된다. 반대로 일반 OpenAI API 호출, 단순 release note 생성, public repo의 fork PR 대응은 API key나 read-only 흐름이 더 맞을 수 있다.

특히 public CI는 조심해야 한다. forked PR은 외부 기여자가 코드를 바꿔 runner에서 실행되게 만들 수 있다. 이때 secret이 주입되면 공격 표면이 커진다. access token은 “내 계정으로 Codex run을 시작할 수 있는 권한”에 가까우니, 공개 runner에 넣는 순간 남의 손에 내 리모컨을 맡기는 꼴이 된다.

또 하나의 금지선은 공유 identity다. 팀 전체가 한 사람의 token을 돌려 쓰면 audit trail이 흐려진다. 나중에 “이 Codex run은 누가 만든 판단인가”를 볼 때 token creator만 남고 실제 workflow owner가 안 보일 수 있다. 그래서 token name, workflow owner, runner, expiry, rotation day를 같이 기록해야 한다.

최소 hook 정책 예시

처음부터 거대한 보안 프레임워크를 만들 필요는 없다. 첫 hook 정책은 작게 시작하는 편이 낫다. 목표는 모든 위험을 잡는 것이 아니라, 반복적으로 터질 수 있는 실수를 먼저 줄이는 것이다. 자동화도 첫날부터 헬스장 PT처럼 몰아붙이면 다음날 안 간다.

가장 작은 정책은 세 줄이다. secret 파일 읽기 금지, token 환경변수 출력 금지, network는 allowlist 없으면 금지. 이 세 줄만 있어도 access token을 붙인 Codex run의 사고 반경이 줄어든다. 여기에 PostToolUse redaction 요약과 48시간 KPI 로그를 붙이면 운영 루프가 된다.

예시는 이렇게 잡을 수 있다.

deny if command reads ~/.codex/auth.json
deny if command prints CODEX_ACCESS_TOKEN or OPENAI_API_KEY
deny network unless domain is in the approved automation allowlist

이건 완성된 보안 코드가 아니라 정책 문장이다. 실제 구현은 팀의 shell, CI, secret manager, hook runner에 맞춰야 한다. 중요한 건 hook script보다 정책 문장이 먼저라는 점이다. “무엇을 막을지”가 없으면 코드는 빨리 생기지만 기준은 안 생긴다.

48시간 검수 루프

Codex Hooks와 access token을 붙인 뒤에는 “잘 돌아감”으로 끝내면 안 된다. 최소 48시간은 실행 로그를 보는 게 좋다. 어느 hook이 몇 번 차단했는지, 어떤 approval request가 반복됐는지, tool output에 secret-like pattern이 있었는지, token expiry가 실제로 기록됐는지 확인한다.

첫 48시간 KPI는 화려할 필요가 없다. blocked_secret_attempts, approval_requests, unexpected_network_denies, redacted_outputs, runs_by_token_owner 정도면 충분하다. 수치가 0이면 좋은 게 아니라, 검사 자체가 작동했는지 먼저 봐야 한다. 차단이 한 번도 없는데 로그도 없다면 그건 평화가 아니라 계기판 꺼짐일 수 있다.

TECHTAEK 운영 관점에서 이 글의 핵심 CTA는 하나다. Codex Hooks를 켜기 전에 토큰과 로그의 이동 경로를 먼저 그려라. 자동화가 강해질수록 “실행”보다 “회수 가능한 증거”가 중요해진다. 누가, 어떤 runner에서, 어떤 권한으로, 어떤 파일을 읽었고, 무엇을 차단했는지 남아야 한다.

바로 쓰는 체크리스트

API key로 충분하면 access token을 만들지 않는다.
access token은 ChatGPT Business/Enterprise workspace 자동화 identity가 필요할 때만 쓴다.
token은 workflow owner, runner, expiry, rotation day와 같이 기록한다.
public CI, forked PR, 공유 머신에는 access token을 넣지 않는다.
codex exec 자동화는 read-only 기본값에서 시작하고, 필요할 때만 workspace-write로 올린다.
network는 기본 off로 두고, 필요한 domain만 allowlist로 연다.
PreToolUse에서는 secret 파일 읽기와 token 출력 명령을 먼저 막는다.
PermissionRequest에서는 outside workspace edit, broad network, destructive command를 검토한다.
PostToolUse는 사후 피드백용으로 보고, 사전 차단 책임을 맡기지 않는다.
CI artifact, PR comment, Slack relay에는 raw tool output을 바로 붙이지 않는다.
48시간 뒤 hook 차단 수, approval 수, redaction 수, token owner별 run 수를 본다.

FAQ

Codex Hooks를 켜면 secret 유출이 자동으로 막히나?

아니다. hooks는 특정 lifecycle 지점에 정책 스크립트를 붙이는 장치다. secret 유출 위험을 줄이려면 sandbox, approval, network 설정, secret manager, 로그 redaction을 함께 써야 한다. 특히 PostToolUse는 이미 실행된 부작용을 되돌리는 장치가 아니므로, 위험한 명령은 PreToolUse와 approval 단계에서 먼저 막는 편이 맞다.

Programmatic Access Token은 OpenAI API key와 같은 건가?

아니다. Codex access token은 Codex local 자동화를 ChatGPT workspace identity로 실행하기 위한 수단이다. 일반 OpenAI API 호출에는 Platform API key가 맞다. 공식 문서도 API key로 충분한 자동화라면 API key를 계속 쓰라고 안내한다.

CI에서 Codex를 돌릴 때 access token이 꼭 필요한가?

꼭 필요하지 않다. codex exec는 CI와 scheduled job에 쓸 수 있지만, CI 인증은 API key가 기본값으로 더 단순한 경우가 많다. access token은 ChatGPT workspace 기반 권한, governance, Codex entitlements가 필요한 trusted runner에서만 후보로 보는 편이 안전하다.

hook script는 repo 안에 두면 되나?

가능하지만 project-local hook은 해당 project .codex/ layer가 trusted일 때만 의미가 있다. repo-local hook command는 상대 경로보다 git root 기준으로 script path를 잡는 편이 안전하다. Codex가 하위 디렉터리에서 시작될 수 있기 때문이다.

Codex Hooks 켜기 전 먼저 볼 것 2026 – Programmatic Access Token과 시크릿 스캔 운영표