블로그로 돌아가기

Codex CLI 알림 설정: 작업이 끝나면 푸시 알림 받기

Codex CLI 알림 설정: 작업이 끝나면 푸시 알림 받기

Codex CLI는 터미널을 보고 있는 동안이라면 작업이 끝났다고 알려줍니다. 기본 제공 알림은 터미널 이스케이프 코드를 쓰는 방식이라서, 터미널이 지원하면 데스크톱 배너가 뜨고 지원하지 않으면 벨 소리가 나는 정도입니다. 둘 다 자리를 떠나면 소용이 없어요.

Codex는 수명 주기의 특정 시점에 사용자가 정한 명령을 실행할 수 있습니다. 휴대폰 푸시 알림을 보내는 데는 이것으로 충분해요. 이 가이드에서는 Codex가 턴을 마칠 때 한 번, 승인을 요청하며 멈출 때 한 번 알림을 보내도록 설정합니다.

Codex가 명령을 실행하는 두 가지 방법

  • 훅(hooks), 현재 사용하는 방식입니다. hooks.json에서 설정하며 기본으로 켜져 있습니다. Stop, PermissionRequest, PreToolUse, SessionEnd 같은 이벤트를 지원합니다. 명령은 이벤트 정보를 JSON 형식으로 표준 입력(stdin)에서 받습니다.
  • notify, config.toml에 있는 이전 설정입니다. agent-turn-complete 이벤트 하나에서만 실행되며, JSON을 명령줄의 마지막 인자로 넘겨줍니다. 여전히 동작하지만 Codex 소스 코드에서는 레거시로 표시되어 있습니다.

훅을 사용하세요. notify 방식은 이전 설정을 쓰는 경우를 위해 마지막에 다룹니다.

준비물

  • 훅을 지원하는 최신 버전의 Codex CLI
  • jq와 curl
  • Pocket Alert 계정, API 키 페이지에서 발급받은 API 키, 그리고 휴대폰에 설치한 앱. 무료 플랜으로도 충분합니다.

API 키는 본인만 읽을 수 있는 파일에 저장하세요. 그래야 셸 기록이나 환경 변수에 남지 않습니다.

mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key

1단계. 훅 스크립트 작성

다음 내용을 ~/.codex/hooks/pocketalert.sh로 저장합니다.

#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Codex finished · $project"
    message=$(jq -r '.last_assistant_message // "Turn complete"' <<<"$payload")
    level=default ;;
  PermissionRequest)
    title="Codex needs approval · $project"
    message=$(jq -r '"Wants to run " + (.tool_name // "a tool")' <<<"$payload")
    level=high ;;
  *) exit 0 ;;
esac

jq -n --arg t "$title" --arg m "${message:0:300}" --arg l "$level" \
  '{title: $t, message: $m, level: $l}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true

exit 0
chmod +x ~/.codex/hooks/pocketalert.sh

Codex는 훅의 출력에 까다롭습니다. Stop 훅은 표준 출력에 아무것도 없거나 JSON만 나오기를 기대하며, 종료 코드 2를 반환하면 멈추지 않고 계속 진행하라는 뜻이 됩니다. 그래서 curl의 출력은 모두 /dev/null로 보내고, 스크립트는 항상 exit 0으로 끝납니다.

PermissionRequest 훅은 Codex를 대신해 승인하거나 거부할 수도 있습니다. 이 스크립트는 둘 다 하지 않습니다. 아무것도 출력하지 않으므로 Codex는 평소처럼 승인 프롬프트를 띄우고, 사용자는 승인을 기다리고 있다는 푸시 알림을 받습니다.

Pocket Alert CLI 사용하기

Pocket Alert CLI 2.0 이상이 설치되어 있다면 curl 블록을 명령 한 줄로 줄일 수 있습니다. CLI가 텍스트 이스케이프를 직접 처리하고 키도 pocketalert auth에서 읽어 오므로 키 파일도 필요 없습니다.

pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true

위치 인자 대신 -t와 -m 옵션을 쓰세요. 마크다운 목록처럼 대시(-)로 시작하는 응답은 옵션으로 잘못 해석될 수 있습니다.

2단계. 훅 등록

~/.codex/hooks.json 파일을 만듭니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

홈 디렉터리에 있는 파일은 모든 프로젝트에 적용됩니다. 저장소 안의 .codex/hooks.json은 해당 프로젝트에만 적용되며, 프로젝트를 신뢰할 수 있는 것으로 표시한 뒤에야 동작합니다.

훅은 기본적으로 켜져 있습니다. 이전에 꺼 둔 적이 있다면 hooks = false의 [features] 테이블에서 ~/.codex/config.toml를 지우세요.

Codex는 사용자가 검토하고 신뢰한 훅만 실행합니다. 처음 시작할 때 새 훅은 검토가 필요하다는 경고가 뜹니다. /hooks를 열어 두 항목을 확인하고 신뢰하세요. 나중에 훅을 수정하면 다시 신뢰하기 전까지 Codex가 해당 훅을 건너뜁니다.

3단계. 테스트

아무 프로젝트에서 Codex를 실행하고 짧은 작업을 맡겨 보세요.

> Summarise README.md in one sentence.

턴이 끝나면 휴대폰에 요약과 함께 Codex finished · your-project 알림이 옵니다. 승인이 필요한 명령을 실행하라고 하면, 우선순위가 높은 두 번째 푸시 알림 Codex needs approval이 도착합니다.

Codex 없이 스크립트만 테스트하려면 다음을 실행하세요.

echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | ~/.codex/hooks/pocketalert.sh

휴대폰에 도착하는 알림

이벤트제목본문우선순위
턴 완료Codex finished · api마지막 응답의 처음 300자default
승인 필요Codex needs approval · apiWants to run Bashhigh

high는 iPhone에서 시간 민감 알림으로 전달되므로, 승인 알림은 집중 모드에서도 전달되고 일반적인 "finished" 알림은 조용히 처리됩니다. 두 알림 모두 앱의 기록과 웹 대시보드에 남습니다.

이전 방식: notify

사용 중인 Codex 버전이 훅을 지원하기 전 버전이거나 이미 notify를 쓰고 있다면, 몇 가지만 바꾸면 그대로 쓸 수 있습니다. Codex는 이벤트를 표준 입력 대신 마지막 인자로 넘기고, 키 이름은 케밥 케이스를 쓰며, 완료된 턴만 알려 줍니다.

#!/usr/bin/env bash
event="${@: -1}"
[ "$(jq -r '.type' <<<"$event")" = "agent-turn-complete" ] || exit 0

jq -n --arg m "$(jq -r '."last-assistant-message" // "Turn complete"' <<<"$event" | cut -c1-300)" \
  '{title: "Codex finished", message: $m}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true
# ~/.codex/config.toml
notify = ["/Users/you/.codex/notify-pocketalert.sh"]

notify에는 승인 이벤트가 없습니다. Codex가 차단되어 멈춘 상황을 알고 싶다면 훅을 사용하세요.

또는 MCP로 Codex가 직접 보내기

훅은 정해진 이벤트에서만 실행됩니다. Codex가 무엇을 알릴지 직접 판단하게 하려면 ~/.codex/config.toml에 Pocket Alert MCP 서버를 추가하세요.

[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"

또는 명령줄에서 추가할 수 있습니다.

codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
  --bearer-token-env-var POCKETALERT_API_KEY

Codex를 시작하는 셸에서 POCKETALERT_API_KEY를 내보내세요(export). 그러면 "테스트 스위트를 실행하고 실패한 항목을 푸시로 보내 줘" 같은 프롬프트의 끝에서 Codex가 직접 작성한 요약과 함께 create_message를 호출합니다. 이 도구는 level과 actions 인자도 받습니다.

알림이 오지 않을 때

  • 테스트 명령을 실행해 보세요. 여기서 동작한다면 문제는 훅 등록에 있습니다. 동작하지 않는다면 >/dev/null 2>&1을 지워 curl 오류를 확인하세요. 401이면 키가 잘못된 것입니다.
  • 훅이 신뢰되었는지 확인하세요. Codex에서 /hooks를 열어 보세요. 신뢰되지 않았거나 변경된 훅은 건너뜁니다.
  • 프로젝트가 신뢰되었는지 확인하세요. hooks.json을 저장소 안에 두었다면 필요합니다.
  • Codex 환경의 PATH에 jq가 있는지 확인하세요. 훅 명령은 Codex의 환경과 세션의 작업 디렉터리에서 실행됩니다.
  • 일일 한도를 확인하세요. 무료 플랜은 하루 50건을 보낼 수 있으며, Stop 훅은 턴마다 실행됩니다.

자주 묻는 질문

[tui] notifications는 어떤가요?

Codex의 기본 제공 터미널 알림입니다. 기본으로 켜져 있고 완료된 턴과 승인 요청을 모두 다룰 수 있지만, 터미널을 통해 컴퓨터에 표시됩니다. 푸시 알림은 휴대폰에 도착하고 기록도 남습니다.

Codex IDE 확장 프로그램에서도 되나요?

확장 프로그램은 같은 ~/.codex 설정으로 내 컴퓨터에서 Codex 에이전트를 실행합니다. 따라서 먼저 CLI에서 훅을 설정하고 신뢰하세요. Codex 클라우드 작업은 OpenAI 서버에서 실행되므로 로컬 훅을 실행하지 않습니다.

휴대폰에서 승인할 수 있나요?

이 스크립트로는 안 됩니다. Codex가 기다리고 있다는 사실만 알려 줍니다. PermissionRequest 훅은 허용 또는 거부 결정을 반환할 수 있으므로, 휴대폰이 호출하는 엔드포인트를 만들어 승인 기능을 직접 구현할 수 있습니다. 사람이 개입하는 알림에서 이 패턴을 소개합니다.

무료인가요?

네. 훅은 Codex에 기본으로 포함되어 있고, Pocket Alert 무료 플랜은 기기 한 대에서 하루 50건의 메시지를 제공합니다.

API 키 발급받기를 하고 훅을 추가한 뒤, 이제 터미널을 계속 들여다보지 않아도 됩니다.

이 글 공유하기