Codex 알림: 작업이 끝나거나 승인을 기다릴 때 알림 받기

Codex는 턴이 끝났을 때와 승인이 필요할 때 알려 줄 수 있습니다. 함정은 구성 파일의 두 가지 메커니즘이 서로 다른 이벤트를 다룬다는 점, 그리고 대부분의 터미널에서 "데스크톱 알림"이 조용히 벨로 바뀐다는 점입니다.

작성: Aslan, Pet Island 팀 · 업데이트: 2026년 10월 26일 · 읽는 데 3분

핵심 요약

[tui] 섹션을 사용하세요. notifications = ["agent-turn-complete", "approval-requested"]로 설정하고, 터미널에 포커스가 있을 때도 알림을 원한다면 notification_condition = "always"를 추가합니다. Codex는 Ghostty, iTerm2, Kitty, Warp, WezTerm에서만 데스크톱 알림(OSC 9)을 보냅니다. Windows Terminal을 포함한 그 밖의 모든 곳에서는 벨을 울립니다. 최상위 notify 설정은 직접 지정한 프로그램을 실행하지만, agent-turn-complete에만 해당하며 승인에는 절대 실행되지 않습니다.

서로 다른 두 설정

	[tui] notifications	notify
기능	Codex CLI의 터미널 알림	선택한 프로그램 실행
턴 완료	지원(`agent-turn-complete`)	지원(`agent-turn-complete`)
승인 요청	지원(`approval-requested`)	미지원
계획/질문 프롬프트	지원(`plan-mode-prompt`, `async-question`)	미지원
기본값	켜짐	꺼짐

Codex가 언제 나를 기다리는지 알고 싶다면 notify만으로는 절대 안 됩니다. 이 용도에는 TUI 알림을 사용하세요.

TUI 알림

OpenAI 샘플 구성에서 관련된 부분은 다음과 같습니다.

~/.codex/config.toml복사

[tui]

# Desktop notifications from the TUI: boolean or filtered list. Default: true

notifications = ["agent-turn-complete", "approval-requested"]

# Notification mechanism for terminal alerts: auto | osc9 | bel. Default: "auto"

notification_method = "auto"

# When notifications fire: unfocused (default) | always

notification_condition = "unfocused"

notifications: true, false 또는 이벤트 목록입니다. approval-requested는 명령, 파일 편집, MCP 승인 요청을 모두 포함합니다.
notification_condition: 기본적으로 알림은 터미널에 포커스가 없을 때만 발생합니다. 다른 모니터에 터미널을 띄워 두고 있다면 always로 설정하세요.
notification_method: auto, osc9, bel 중 하나입니다.

메시지는 "Approval requested: <command>", "Codex wants to edit <file>", "Agent turn complete"와 같은 형태입니다.

비프음만 들리는 이유(Windows Terminal 등)

auto 모드에서 Codex는 Ghostty, iTerm2, Kitty, Warp, WezTerm을 인식했을 때만 데스크톱 알림(OSC 9 이스케이프 시퀀스)을 보냅니다. 그 밖의 모든 터미널(Windows Terminal, VS Code 터미널, Apple Terminal)에는 터미널 벨이 울립니다. 이 내용은 Codex 소스 코드(tui/src/notifications/mod.rs)에서 나온 것이며, 문서에는 auto가 "prefers OSC 9"(OSC 9를 우선함)라고만 적혀 있습니다.

Windows Terminal에서는 벨을 더 눈에 띄게 만들 수 있습니다. 프로필 설정에서 bellStyle을 all로 설정하면 소리가 나고 작업 표시줄 아이콘이 깜박입니다(기본값은 audible).

Windows Terminal settings.json(프로필)복사

{

"bellStyle": "all"

}

notification_method = "osc9"를 강제로 지정할 수도 있습니다. 이를 시스템 알림으로 바꿀지는 터미널에 따라 다릅니다.

notify로 직접 만든 프로그램 실행하기

notify는 턴이 완료되면 외부 프로그램을 실행하고 type, thread-id, turn-id, cwd, input-messages, last-assistant-message가 담긴 JSON 인수 하나를 전달합니다. 그래서 휴대폰 푸시, 웹훅, 로그처럼 터미널 밖의 용도에 적합합니다. 최상위 키이므로 모든 [section]보다 위에 두세요.

~/.codex/config.toml복사

notify = ["python3", "/Users/you/.codex/notify.py"]

OpenAI 문서의 예시를 따른 최소한의 스크립트입니다.

~/.codex/notify.py복사

import json, subprocess, sys

notification = json.loads(sys.argv[1])

if notification.get("type") == "agent-turn-complete":

message = (notification.get("last-assistant-message") or "Turn complete")[:120]

# macOS: a system notification. On Linux use ["notify-send", "Codex", message].

subprocess.run(["osascript", "-e", f'display notification {json.dumps(message)} with title "Codex"'])

프로젝트의 .codex/config.toml에서는 notify를 설정할 수 없습니다. 반드시 사용자 구성에 있어야 합니다.
Codex 소스 코드는 notify를 레거시로 표시하고 훅으로 대체할 계획입니다. 지금은 작동하지만 변경 로그를 주시하세요.

훅은 어떤가요?

Codex에도 훅이 있습니다. 기본적으로 켜져 있고 PermissionRequest와 Stop 이벤트를 포함하며, ~/.codex/hooks.json이나 [hooks] 테이블에서 구성합니다. 관리형이 아닌 모든 훅은 실행 전에 /hooks에서 검토하고 신뢰해야 합니다. Notification 이벤트는 없으며, OpenAI 문서에도 알림 훅 예시는 없습니다. 알림을 받으려면 문서에 나온 대로 위의 TUI 설정을 사용하세요.

Codex 앱과 IDE 확장

Codex 데스크톱 앱에는 자체 컨트롤이 있습니다. 턴 완료 알림을 사용 안 함, 앱이 백그라운드에 있을 때만, 항상 중에서 설정할 수 있고, 권한 알림과 질문 알림은 별도의 스위치로 켜고 끕니다. IDE 확장에는 자체 알림 설정이 없습니다. OpenAI 문서는 대신 notify를 사용하도록 안내합니다.

ChatGPT 앱을 통해 휴대폰에서 승인하는 경우, 이슈 #39346에는 휴대폰에 "approval waiting"(승인 대기 중)이 표시되지만 응답할 카드가 없는 사례가 보고되어 있습니다.

보고, 바로 응답하기

벨은 어느 터미널에서 무언가 일어났다는 것만 알려 줍니다. Pet Island는 화면 상단의 작은 아일랜드에 Codex 상태(작업 중, 대기 중, 완료)를 보여 주며, Codex가 명령 실행이나 파일 편집을 요청하면 명령이나 diff와 함께 요청이 그곳에 나타납니다. 창을 전환하지 않고 허용하거나 거부할 수 있고, 질문이 오면 클릭 한 번으로 해당 터미널로 이동할 수 있습니다. Codex CLI와 Codex 앱에서 작동하며, Claude Code, Cursor 및 다른 에이전트와 함께 사용할 수 있습니다.

자주 묻는 질문

Codex가 끝났을 때 알림을 받으려면 어떻게 하나요?

Codex의 TUI 알림은 agent-turn-complete에 대해 기본으로 켜져 있지만, 기본적으로 터미널에 포커스가 없을 때만 발생합니다. 포커스가 있을 때도 받으려면 [tui]에 notification_condition = "always"를 설정하세요.

Codex가 승인을 필요로 할 때 알림을 받으려면 어떻게 하나요?

~/.codex/config.toml의 [tui] 섹션에서 notifications에 "approval-requested"를 추가하세요. notify 설정은 승인에 대해 실행되지 않습니다.

Codex가 알림을 표시하지 않고 비프음만 내는 이유는 무엇인가요?

auto 모드에서 Codex는 Ghostty, iTerm2, Kitty, Warp, WezTerm에서만 데스크톱 알림을 보냅니다. Windows Terminal을 포함한 다른 터미널에서는 벨이 울립니다.

프로젝트의 .codex/config.toml에 notify를 넣을 수 있나요?

아니요. 프로젝트 구성에서는 notify를 설정할 수 없으니 ~/.codex/config.toml에 넣으세요.

Codex에 Notification 훅이 있나요?

아니요. Codex 훅에는 PermissionRequest와 Stop이 있지만, Notification 이벤트나 문서화된 알림 훅은 없습니다.

출처

이 페이지의 모든 설정과 동작은 2026년 10월 26일에 아래 페이지와 대조해 확인했습니다. 에이전트는 빠르게 바뀌므로, 내용이 더 이상 맞지 않으면 공식 페이지를 따르세요.

더 읽어보기

Codex