Назад в блог

Уведомления Codex CLI: push-уведомление на телефон, когда задача готова

Уведомления Codex CLI: push-уведомление на телефон, когда задача готова

Codex CLI уже сообщает о завершении, но только если вы смотрите в терминал. Встроенные уведомления работают через управляющие последовательности терминала: это баннер на рабочем столе, если терминал их поддерживает, или звуковой сигнал, если нет. Ни то, ни другое не последует за вами на кухню.

Codex также умеет запускать ваши команды в определённые моменты своего жизненного цикла, и для push-уведомления на телефон этого достаточно. В этом руководстве настроены два уведомления: одно отправляется, когда Codex завершает ход, другое, когда он останавливается и просит подтверждения.

Два способа, которыми Codex запускает вашу команду

  • Хуки, текущий механизм. Настраиваются в 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 Keys и приложение на телефоне. Для работы хватит бесплатного тарифа.

Сохраните 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 в stdout, а код выхода 2 говорит ему продолжить работу вместо остановки. Поэтому весь вывод curl уходит в /dev/null, а скрипт всегда завершается с exit 0.

Хуки PermissionRequest могут также одобрить или отклонить действие от имени Codex. Этот скрипт не делает ни того, ни другого: он ничего не выводит, поэтому Codex показывает обычный запрос подтверждения, а вы получаете push-уведомление о том, что он ждёт ответа.

Или с 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, а не позиционные аргументы: ответ, который начинается с дефиса, например Markdown-список, иначе будет принят за опцию.

Шаг 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 доставляется как критичное по времени, поэтому уведомление о подтверждении проходит через Фокусирование, а обычные уведомления о завершении остаются тихими. Оба сохраняются в истории приложения и в веб-панели.

Старый способ: notify

Если ваша версия Codex старше хуков или вы уже используете notify, он работает с небольшими изменениями. Codex передаёт событие последним аргументом, а не через stdin, использует ключи в kebab-case и сообщает только о завершённых ходах:

#!/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 заблокирован, используйте хуки.

Или пусть Codex отправляет через MCP

Хуки срабатывают на фиксированные события. Чтобы Codex сам решал, что вам сообщить, добавьте MCP-сервер Pocket Alert в ~/.codex/config.toml:

[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

Экспортируйте POCKETALERT_API_KEY в шелле, из которого запускаете Codex. Тогда запрос вида «запусти тесты и пришли мне ошибки» завершится тем, что Codex вызовет create_message с написанным им резюме. Инструмент принимает также level и actions.

Если ничего не приходит

  • Запустите тестовую команду. Если она работает, проблема в регистрации хуков. Если нет, уберите >/dev/null 2>&1, чтобы увидеть ошибку curl. 401 означает неверный ключ.
  • Проверьте, что хуки доверенные. Откройте /hooks в Codex: непроверенные или изменённые хуки пропускаются.
  • Проверьте, что проект доверенный, если hooks.json лежит в репозитории.
  • Проверьте, что jq есть в PATH, который видит Codex. Команды хуков выполняются с окружением Codex и рабочим каталогом сессии.
  • Проверьте дневной лимит. Бесплатный тариф отправляет 50 сообщений в день, а Stop срабатывает после каждого хода.

Частые вопросы

Что насчёт [tui] notifications?

Это встроенное терминальное уведомление Codex. Оно включено по умолчанию и может покрывать и завершённые ходы, и запросы подтверждения, но появляется на компьютере, через терминал. Push-уведомление доходит до телефона и сохраняет историю.

Работает ли это в расширении Codex для IDE?

Расширение запускает агента Codex на вашей машине с той же конфигурацией ~/.codex, поэтому сначала настройте хуки и подтвердите их в CLI. Облачные задачи Codex выполняются на серверах OpenAI и не запускают ваши локальные хуки.

Можно ли подтверждать действия с телефона?

Не с этим скриптом: он только сообщает, что Codex ждёт. Хук PermissionRequest может вернуть решение allow или deny, поэтому поверх него можно построить подтверждения через эндпоинт, который вызывает ваш телефон. В статье Уведомления с участием человека описан этот подход.

Это бесплатно?

Да. Хуки встроены в Codex, а бесплатный тариф Pocket Alert покрывает 50 сообщений в день на одном устройстве.

Получите API-ключ, добавьте хук и перестаньте проверять терминал.

Поделиться статьёй