configure-notifications

Configure OMX Notifications

Use this card for Discord, Telegram, Slack, generic command aliases, or OpenClaw. Shared safety, lifecycle, hook, team, autonomy, and cancellation rules live in templates/AGENTS.md.

1. Inspect and choose a path

CONFIG_FILE="$HOME/.codex/.omx-config.json"
if [ -f "$CONFIG_FILE" ]; then
  jq -r '{notifications_enabled:(.notifications.enabled // false), discord:(.notifications.discord.enabled // false), discord_bot:(.notifications["discord-bot"].enabled // false), telegram:(.notifications.telegram.enabled // false), slack:(.notifications.slack.enabled // false), openclaw:(.notifications.openclaw.enabled // false), custom_webhook_command:(.notifications.custom_webhook_command.enabled // false), custom_cli_command:(.notifications.custom_cli_command.enabled // false), verbosity:(.notifications.verbosity // "session"), idleCooldownSeconds:(.notifications.idleCooldownSeconds // 60), reply_enabled:(.notifications.reply.enabled // false)}' "$CONFIG_FILE"
else
  echo "NO_CONFIG_FILE"
fi

Use AskUserQuestion to choose: Discord native (webhook or bot), Telegram native (bot token + chat id), Slack native (incoming webhook), custom_webhook_command, custom_cli_command, cross-cutting settings, or disable all notifications.

2. Native providers

Collect and validate provider values, then write only these native keys: notifications.discord, notifications["discord-bot"], notifications.telegram, or notifications.slack. Do not represent native providers with generic aliases.

3. Generic aliases

For custom_webhook_command, collect URL, optional headers, method (POST default or PUT), events (session-end, ask-user-question, session-start, session-idle, stop), and an instruction template:

jq --arg url "$URL" --arg method "${METHOD:-POST}" --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" --argjson headers "${HEADERS_JSON:-{}}" '.notifications=(.notifications//{enabled:true})|.notifications.enabled=true|.notifications.custom_webhook_command={enabled:true,url:$url,headers:$headers,method:$method,instruction:$instruction,events:["session-end","ask-user-question"]}' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"

For custom_cli_command, collect a command template ({{event}}, {{instruction}}, {{sessionId}}, {{projectPath}}), optional events, and an instruction template:

jq --arg command "$COMMAND_TEMPLATE" --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" '.notifications=(.notifications//{enabled:true})|.notifications.enabled=true|.notifications.custom_cli_command={enabled:true,command:$command,instruction:$instruction,events:["session-end","ask-user-question"]}' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"

OpenClaw dispatch requires OMX_OPENCLAW=1; command gateways additionally require OMX_OPENCLAW_COMMAND=1; timeout precedence is gateways.<name>.timeout > OMX_OPENCLAW_COMMAND_TIMEOUT_MS > 5000 ms.

4. OpenClaw + Clawdbot agent mode

Use this only when the requested route is a clawdbot agent turn delivered to Discord. The session-stop notification intentionally maps to the OpenClaw stop hook. OMX shell-escapes substitutions; keep instructions short, avoid untrusted shell metacharacters, append || true, and append JSONL logs with >>.

jq --arg command "(clawdbot agent --session-id omx-hooks --message {{instruction}} --thinking minimal --deliver --reply-channel discord --reply-to 'channel:CHANNEL_ID' --timeout 120 --json >>/tmp/omx-openclaw-agent.jsonl 2>&1 || true)" '.notifications=(.notifications//{enabled:true})|.notifications.enabled=true|.notifications.verbosity="verbose"|.notifications.openclaw={enabled:true,gateways:{local:{type:"command",command:$command,timeout:120000}},hooks:{"session-start":{enabled:true,gateway:"local",instruction:"OMX hook=session-start project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 상태를 #omc-dev에 공유하고 SOUL.md를 참고하세요."},"session-idle":{enabled:true,gateway:"local",instruction:"OMX hook=session-idle session={{sessionId}} tmux={{tmuxSession}}. 한국어로 팔로업을 #omc-dev에 안내하세요."},"ask-user-question":{enabled:true,gateway:"local",instruction:"OMX hook=ask-user-question session={{sessionId}} tmux={{tmuxSession}} question={{question}}. 한국어로 응답 필요를 #omc-dev에 알리세요."},"stop":{enabled:true,gateway:"local",instruction:"OMX hook=session-stop session={{sessionId}} tmux={{tmuxSession}}. 한국어로 중단 상태를 전달하세요."},"session-end":{enabled:true,gateway:"local",instruction:"OMX hook=session-end session={{sessionId}} tmux={{tmuxSession}} reason={{reason}}. 한국어로 완료 요약을 #omc-dev에 남기세요."}}}' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"

Compatibility + precedence contract

Explicit notifications.openclaw wins when valid; generic aliases are ignored with a warning.

Verify this mode and inspect evidence without hiding output:

clawdbot agent --session-id omx-hooks --message "OMX hook test via clawdbot agent path" --thinking minimal --deliver --reply-channel discord --reply-to 'channel:CHANNEL_ID' --timeout 120 --json
tmux list-sessions -F '#{session_name}' | rg '^omx-' || true
jq '.notifications.openclaw.hooks' "$CONFIG_FILE"
tail -n 120 /tmp/omx-openclaw-agent.jsonl | jq -s '.[] | {timestamp:(.timestamp // .time),status:(.status // .error // "ok")}'
rg '"error"|"failed"|"timeout"' /tmp/omx-openclaw-agent.jsonl | tail -20

For HTTP integrations, run both a /hooks/wake smoke test and /hooks/agent delivery verification.

5. Cross-cutting settings and disable

• Verbosity: minimal, session (recommended), agent, or verbose.
• Idle cooldown: notifications.idleCooldownSeconds (environment override: OMX_IDLE_COOLDOWN_SECONDS).
• Profiles: notifications.profiles and notifications.defaultProfile.
• Reply listener: notifications.reply.enabled; gates are OMX_REPLY_ENABLED=true and, for Discord, OMX_REPLY_DISCORD_USER_IDS=.... An authorized Discord bot operator may exact-match status on a tracked notification for a bounded read-only session summary.

Disable all notifications:

jq '.notifications.enabled=false' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"

Exit evidence

Run jq empty "$CONFIG_FILE" after edits. Report the config path, enabled native providers, enabled aliases, whether valid notifications.openclaw overrides aliases, verbosity, idle cooldown, reply-listener state, and smoke-test results. Stop when the JSON parses and the selected path has its required evidence; do not claim delivery from configuration alone.