joelhooks OpenClaw Messaging
Three messaging layers, from user-facing to agent-internal.
1. System Events (Most Common for Agents)
Notify the active agent session (Grimlock) of state changes, completions, or discoveries.
# Immediate delivery — agent processes NOW
openclaw system event --mode now --text "Deployed atproto-agents to prod. CF Worker live at agents.joelhooks.com"
# Batched — delivered on next heartbeat (default 15m)
openclaw system event --text "Non-urgent: test suite passing, 47/47 green"
# Wait for agent response
openclaw system event --mode now --text "Need decision: use D1 or KV for session state?" --expect-final --json
When to use: After shipping to main, completing a task, discovering something important, or needing a decision routed through the system agent.
2. Direct Messages (External Channels)
Send to Telegram, Slack, Discord, WhatsApp, Signal, and 12+ other channels.
Send
# Telegram (most common)
openclaw message send --channel telegram --target @joelhooks -m "Build complete, PR ready for review"
# Telegram with chat ID
openclaw message send --channel telegram --target 123456789 -m "Deployment finished"
# Slack
openclaw message send --channel slack --target "#dev-ops" -m "CI green, merging to main"
# With media attachment
openclaw message send --channel telegram --target @joelhooks -m "Architecture diagram" --media ./diagram.png
# Silent (no notification sound, Telegram only)
openclaw message send --channel telegram --target @joelhooks -m "FYI: background job done" --silent
# Dry run (preview without sending)
openclaw message send --channel telegram --target @joelhooks -m "test" --dry-run
Broadcast
Same message to multiple targets:
openclaw message broadcast --channel telegram --targets @joelhooks 123456789 -m "System maintenance in 5 min"
Read
Fetch recent messages from a conversation:
openclaw message read --channel telegram --target @joelhooks --limit 10 --json
openclaw message read --channel slack --target "#general" --limit 5
React / Edit / Delete
openclaw message react --channel slack --target "#dev" --message-id 1234 --emoji thumbsup
openclaw message edit --channel telegram --target 123456789 --message-id 42 -m "Updated text"
openclaw message delete --channel telegram --target 123456789 --message-id 42
3. Agent Invocation
Trigger an agent turn and optionally deliver the response to a channel.
# Trigger agent, get response in terminal
openclaw agent -m "Summarize today's PRs" --json
# Trigger specific named agent
openclaw agent --agent ops -m "Check deployment status"
# Trigger agent AND deliver reply to Telegram
openclaw agent -m "Generate status report" --deliver --reply-channel telegram --reply-to @joelhooks
# With thinking level
openclaw agent -m "Analyze error logs" --thinking high
# Target existing session
openclaw agent --session-id abc123 -m "Continue from where we left off"
4. Swarmmail (Agent-to-Agent)
Internal message queue for coordinating between swarm workers. Available as MCP tools within agent sessions.
swarmmail_init — Start mail session (call once at session start)
swarmmail_send — Send message to another agent
swarmmail_inbox — Check incoming messages
swarmmail_reserve — Lock files for exclusive editing
swarmmail_release — Release file locks
swarmmail_ack — Acknowledge message receipt
swarmmail_health — Check session health
Swarmmail is for inter-agent coordination only. For user-facing notifications, use openclaw message send or openclaw system event.
5. Directory Lookups
Find targets before sending:
openclaw directory self --channel telegram # Your bot's info
openclaw directory peers --channel telegram # Known contacts
openclaw directory groups --channel telegram # Groups the bot is in
openclaw directory peers --channel slack # Slack users
Quick Reference
| Goal | Command |
|---|---|
| Notify system agent (urgent) | openclaw system event --mode now --text "..." |
| Notify system agent (can wait) | openclaw system event --text "..." |
| Message user on Telegram | openclaw message send --channel telegram --target @user -m "..." |
| Message Slack channel | openclaw message send --channel slack --target "#channel" -m "..." |
| Send to multiple people | openclaw message broadcast --channel telegram --targets @a @b -m "..." |
| Trigger agent + deliver reply | openclaw agent -m "..." --deliver --reply-channel telegram --reply-to @user |
| Read conversation history | openclaw message read --channel telegram --target @user --limit 10 |
| Preview without sending | Add --dry-run to any send/broadcast command |
| JSON output for scripting | Add --json to any command |
Channel Support
Telegram, Slack, Discord, WhatsApp, Signal, iMessage, Google Chat, MS Teams, Mattermost, Matrix, Nostr, Feishu, Nextcloud Talk, BlueBubbles, Line, Zalo, Tlon.
Check active channels: openclaw channels status
Common Patterns
Post-deploy notification
openclaw system event --mode now --text "Shipped v1.2.3 to prod. Changes: new auth flow, fixed rate limiter."
openclaw message send --channel telegram --target @joelhooks -m "v1.2.3 live on prod"
Agent handoff with context
openclaw system event --mode now --text "Completed Phase 1 encryption. All tests passing. Ready for Phase 2 HITL gate review."
Swarm worker status update
openclaw system event --mode now --text "Worker task-42 complete: implemented D1 schema migration. 12 tests added."