Discord Integration Hub
Discord is OpenClaw’s primary ops alerting channel — every automated monitoring system in the platform posts alerts here before anywhere else. The Aurora bot (guild 1473795019575132222, 31 channels) handles both structured embeds for cron/monitoring alerts and interactive slash commands for operator tasks. Read this hub when wiring any new alert source or modifying existing alert routing.
Quick reference
| Field | Value |
|---|---|
| Vendor | Discord Inc |
| URL | https://discord.com / https://discord.com/developers/applications |
| KB doc | API · WEBHOOKS |
| Auth method | Bot token (Authorization: Bot <token> header); Ed25519 sig for interaction webhooks |
| Auth credential | op://Aurora/discord/bot-token |
| Cred-proxy port | n/a (until B1-B6 ratified) |
| Webhook port | n/a (outbound-only; Discord posts to our server for interactions only) |
| Webhook handler | n/a (no inbound webhook handler running for alerts) |
| Webhook dedup table | n/a |
| Tunnel path | n/a |
| Outbound API base | https://discord.com/api/v10 |
| Rate limits | 50 req/s global per bot token; 30 req/60s per webhook URL; ~5 msg/5s per channel |
| Rate-limit action | 429 → exponential backoff (3 retries) using retry_after from response body |
| Cost | Free (no API call costs) |
| Backup/recovery | Vendor-owned (Discord cloud); message history retained per guild retention settings |
| Discord alert channel | ops (primary) · incidents (P0/P1 escalations) |
| Drift cadence | On bot token rotation; after guild permission changes |
| Status | production |
Guild + channel map
| Channel | Purpose | Alert sources |
|---|---|---|
| ops | Primary ops alerts — all monitoring systems | All sources listed below |
| incidents | P0/P1 escalation — requires immediate response | Failed services, cost-overage threshold breaches |
| aurora-build | Aurora agent status updates, crash notifications | notify-service-crash.sh (OnFailure systemd hook) |
Guild ID: 1473795019575132222
Alert sources (complete enumeration — PF-A)
All of the following systems post to Discord ops as their primary alert channel:
| Source | Schedule | Trigger condition | Alert severity |
|---|---|---|---|
vault-sync (openclaw-vault-sync.timer) | Every 15 min | rsync failure, git commit error, push failure | warn |
security-audit-funnel (security-audit-funnel.timer) | Monday 06:00 America/Los_Angeles | Unregistered live paths, missing approved paths, sig failure rate >5%, zero-event endpoints, stale WAF rules | P0/P1 |
| friction-report (nightly cron) | Daily 02:00 America/Los_Angeles | Frustration signal detection, P0/P1/P2 fix backlog | P0-P2 |
cost-overage (cost-monitor) | On threshold breach | LLM spend exceeds configured budget ceiling | P1 |
tool-calls-health-check (tool-calls-health-check.timer) | Every 5 min | >10% delta between Portkey call count and tool_calls table inserts (CHOKEPOINT-1 drift) | P0 |
| failed-service MTTR (daily cron) | Daily | Any service in failed state >24h (G-FAILED-SERVICE-MTTR) | P1 |
governance-log-freshness (weekly-index-audit.timer) | Weekly | WORKFLOW-PATTERNS.md, SYSTEM-FRICTION-LOG.md, CHANGELOG.md, AUDIT-LOG.md stale >14 days (G-GOVERNANCE-LOG-FRESHNESS) | P1 |
| notify-service-crash | On systemd OnFailure= event | Any systemd unit with OnFailure=notify-crash@.service configured crashes | P0 |
Components
/home/opsadmin/.openclaw/workspace/scripts/discord-send-webhook.sh— CLI wrapper; callsdiscord-webhook-sender.jswith agent ID + message/home/opsadmin/.openclaw/workspace/scripts/discord-webhook-sender.js— Node.js webhook sender; reads channel map from config/home/opsadmin/.openclaw/workspace/config/discord-webhooks.json— channel ID → webhook URL map (20+ channels); credential stored as URL (G-NO-PLAINTEXT-CREDS: webhook tokens in this file must be rotated if exposed)/home/opsadmin/.openclaw/tools/hooks/notify-service-crash.sh— systemd OnFailure handler; posts crash embeds to aurora-build channel/home/opsadmin/.openclaw/workspace/scripts/discord-add-to-existing-threads.js— thread management utility/home/opsadmin/.openclaw/workspace/scripts/discord-thread-auto-add-bot.js— auto-adds bot to new threads/home/opsadmin/.openclaw/workspace/scripts/discord-assign-core-team.js— guild role assignment~/.openclaw/.discord-keys— legacy key file; must migrate toop://Aurora/discord/bot-tokenpattern
How it’s used
- Trigger: any monitoring script, cron job, or systemd OnFailure handler with an alert to send calls
discord-send-webhook.sh <agent-id> <message>or posts directly via the REST API with the bot token - Workflow: script →
discord-webhook-sender.jsreadsdiscord-webhooks.json→ selects channel by agent ID →POST /channels/{id}/messageswith structured embed - Agents involved: _summary orchestrates most Discord interactions; all 36 agents can route alerts via the gateway’s Discord channel map
- Failure mode: if
discord-webhooks.jsonis missing or malformed, all alert delivery silently fails; if bot token is expired/revoked (401), embeds fail with no fallback; 429 rate limit on high-volume alert bursts (>5 msg/5s per channel) - Success criteria:
POST /channels/{id}/messagesreturns 200 with message object; embed appears in channel within 1s
Interaction webhooks (inbound — slash commands)
Discord sends interaction payloads to a configured HTTPS endpoint when users invoke slash commands. Auth method: Ed25519 signature (X-Signature-Ed25519 + X-Signature-Timestamp headers). Public key stored at op://Aurora/discord/public-key.
- Respond within 3 seconds or defer with
deferReply()(up to 15 min toeditReply) - Verify signature with
discord-interactionsnpm package before processing any payload - No interaction endpoint is currently registered in cloudflare FUNNEL-REGISTRY — add before exposing slash commands to production
/discord skill
The /discord skill (~/.claude/skills/discord/) wraps the message tool with channel=discord routing. Invoke via Skill("discord") for structured ops notifications from Claude Code sessions.
Related: Webhook/tunnel cluster
Discord is a notification sink in the webhook/tunnel cluster — it receives alerts from all other integration hubs via bot token POST, but does not itself require a public tunnel endpoint for normal alerting operations.
| Hub | Relationship |
|---|---|
| cloudflare | Tunnel + WAF govern any future interaction webhook endpoint; FUNNEL-REGISTRY required before exposing |
| hetzner | VPS is the compute host for all Discord alerting scripts |
| slack | Parallel comms channel; Aurora uses both but Discord is primary for ops alerts |
| github | vault-sync posts to ops on push failure; traewayrer/openclaw-vault commit activity visible |
Related: Credential layer cluster
| Credential | Reference | Status |
|---|---|---|
| Bot token | op://Aurora/discord/bot-token | P1 — rotate after any session exposure |
| Public key (interaction sig) | op://Aurora/discord/public-key | Verify exists in 1Password Aurora vault |
| Webhook URLs (per-channel) | discord-webhooks.json (webhook token embedded in URL) | P1 — audit for plaintext exposure |
See 1password for Aurora vault structure and rotation procedures.
Cross-links
Agents that touch this
- _summary — primary Discord bot operator; handles slash commands, embeds, thread management
- All 36 agents via
discord-send-webhook.shfor automated ops alerts
Skills that invoke this
- discord —
/discordskill; wraps message tool with channel=discord routing
Plans that govern this
- openclaw-fragmentation-fix-2026-05-01 — G-FAILED-SERVICE-MTTR daily cron posts to ops; G-GOVERNANCE-LOG-FRESHNESS weekly audit posts to ops
- openclaw-self-improvement-layer-2026-05-03 — OSIL monitoring tiers will add new alert categories to ops
- openclaw-obsidian-vault-2026-05-02 — vault-sync timer posts rsync/push failures to ops
Feedback rules
- feedback_aurora_slack_behavior — Aurora Discord behavior constraints (parallel to Slack rules)
- feedback_no_plaintext_creds — G-NO-PLAINTEXT-CREDS: webhook URLs in
discord-webhooks.jsoncontain tokens; never commit to public repo - feedback_action_gate_violation_repeated — posting to Discord is a side-effect action; requires authorization
KB / source docs
- API — Discord API v10 reference (last verified 2026-03-04); guild ID, rate limits, embed schema
- WEBHOOKS — Incoming webhook execution, Ed25519 signature verification, Slack/GitHub compat formats
System maps
- infrastructure-layer — shows VPS alerting flow to Discord
- agent-communication — agent-to-channel routing map
Open issues / TODOs
- P1:
~/.openclaw/.discord-keyslegacy key file — verify it’s not git-tracked and migrate toop://Aurora/discord/bot-tokenpattern - P1:
discord-webhooks.jsoncontains webhook URLs with embedded tokens — confirm file is chmod 600 and not in any tracked repo; rotate any exposed webhook URLs - P1:
discord-thread-auto-add.serviceis infailedstate (token undefined) per G-FAILED-SERVICE-MTTR audit — fix or disable - P2: No interaction endpoint registered in FUNNEL-REGISTRY — if slash commands are to be exposed publicly, register endpoint and add Ed25519 sig verification before going live
- P2: Alert dedup — high-frequency events (tool-calls-health-check fires every 5 min) could flood ops; consider rate-limiting to 1 alert per 15 min per alert type
Recent activity
- 2026-05-03: Hub created by W1-S6 (Wave 1 hub authoring pass)
- 2026-05-03:
notify-service-crash.shwired to systemd OnFailure for max-plan stack services - 2026-05-01: G-FAILED-SERVICE-MTTR daily cron added; Discord ops is primary alert target
- 2026-05-01: G-GOVERNANCE-LOG-FRESHNESS weekly audit cron added; Discord ops is alert target
- 2026-03-04: KB docs (API.md + WEBHOOKS.md) last verified