Session Monitor

Real-time OpenClaw session monitor that tails JSONL transcripts and pushes formatted updates to Telegram as a persistent background process. Use when asked to monitor, watch, observe, track, spy on, or tail agent sessions, set up a live feed or dashboard of agent activity, deploy a background monitor with Telegram push notifications, or restart/stop/check the monitor. Triggers: monitor sessions, watch agent, start monitor, restart monitor, stop monitor, monitor status, session dashboard, live feed, tail sessions, what is the agent doing, observe agent, track activity, spy on agent, background monitor, push notifications, 监控session, 监控agent, 盯着agent, 看看agent在干嘛, 实时监控, 后台监控, 订阅session, agent活动推送, 重启监控, 停止监控, 监控状态. NOT for one-shot session inspection (use built-in sessions_list / sessions_history for that).

Persistent background process that polls all JSONL transcript files in an agent's session directory, parses new entries, and pushes formatted HTML updates to a Telegram chat. Messages within the same time window are merged via editMessageText to avoid spam.

When to Use

• User wants continuous, push-based monitoring of agent activity
• User wants a live dashboard in a Telegram chat showing what the agent does
• NOT for one-shot queries — use sessions_list / sessions_history instead

Quick Start

bash

# 1. Configure
cp scripts/.env.example scripts/.env
# Edit scripts/.env with bot token, chat ID, session dir, user/group mappings

# 2. Dry-run (verify parsing works)
node scripts/test.js

# 3. Start (exec session safe — won't die when agent session ends)
node scripts/index.js > scripts/monitor.log 2>&1 &

⚠️ Agent exec sessions: Processes started via nohup & inside an agent's exec tool may be killed when the exec session is cleaned up. Add a watchdog to your HEARTBEAT.md to auto-restart:

bash

PID=$(cat scripts/.pid 2>/dev/null)
if [ -z "$PID" ] || ! ps -p "$PID" > /dev/null 2>&1; then
  cd scripts && node index.js > monitor.log 2>&1 &
fi

Configuration (.env)

Variable	Required	Description
BOT_TOKEN	✅	Telegram bot token for sending updates
CHAT_ID	✅	Target Telegram chat ID (group or DM)
AGENTS	❌	Multi-agent: Name|/path/to/sessions,Name2|/path2
AGENT_NAME	❌	Single-agent display name (fallback when AGENTS unset)
SESSIONS_DIR	❌	Single-agent session dir (default: ~/.openclaw/agents/main/sessions)
DIRECT_USERS	❌	Direct chat mappings: userId:Name,userId2:Name2
GROUPS	❌	Group chat mappings: groupId:Name,groupId2:Name2

Display format: direct chats show as ✈ AgentName↔UserName, groups as ✈ GroupName.

Architecture

text

scripts/
├── index.js      — Main loop: poll JSONL, accumulate, send/edit Telegram messages
├── parser.js     — Parse JSONL entries into {sender, text} display objects
├── formatter.js  — Merge same-sender messages, sort sessions, build HTML
├── sender.js     — Telegram API: sendMessage / editMessageText with queue
├── sessions.js   — Session key lookup, tag formatting, subagent name resolution
├── config.js     — Load .env configuration
├── test.js       — Dry-run: parse recent entries and print to stdout
├── .env.example  — Configuration template
└── .env          — Local config (gitignored)

Tuning

In scripts/index.js:

• POLL = 3000 — Poll interval in ms (default 3s)
• MERGE_WINDOW = 1 — Merge edits within N minutes into one Telegram message
• NEW_MSG_THRESHOLD = 3000 — Start a new message when current exceeds this many chars

Message Format

See references/REFERENCE.md for detailed format specification including:

• Sender icons (🤖 assistant, 👤 user, ⚡ system, ↩️ tool result)
• Tool call formatting and truncation rules
• Session tag formatting and sort order
• Telegram delivery and rate limiting

Management

PID file at scripts/.pid is written on startup, cleaned on exit. Always use the full path to avoid cross-monitor conflicts on shared machines:

bash

# Check if running
SKILL_DIR=/path/to/session-monitor
cat "$SKILL_DIR/scripts/.pid" && ps -p $(cat "$SKILL_DIR/scripts/.pid") -o pid,command

# Stop
kill $(cat "$SKILL_DIR/scripts/.pid")

# View logs
tail -f "$SKILL_DIR/scripts/monitor.log"

⚠️ Multiple monitors may coexist on the same machine (each with its own .env, .pid, and log). Always reference the correct skill directory.

Restart / Stop / Status

Resolve SKILL_DIR to this skill's directory (parent of scripts/).

bash

# Status — is monitor running?
SKILL_DIR=/absolute/path/to/session-monitor
PID=$(cat "$SKILL_DIR/scripts/.pid" 2>/dev/null)
if [ -n "$PID" ] && ps -p "$PID" > /dev/null 2>&1; then
  echo "✅ Monitor running (PID $PID)"
else
  echo "❌ Monitor not running"
fi

# Stop
kill $(cat "$SKILL_DIR/scripts/.pid")

# Start
cd "$SKILL_DIR/scripts" && node index.js > monitor.log 2>&1 &

# Restart (stop + start)
kill $(cat "$SKILL_DIR/scripts/.pid") 2>/dev/null; sleep 1
cd "$SKILL_DIR/scripts" && node index.js > monitor.log 2>&1 &

Notes

• Zero dependencies — pure Node.js standard library
• Startup sends a sample banner message to verify connectivity
• Messages > 4000 chars are truncated and force a new message next poll
• Rate limit: 3s gap between Telegram API calls