Real-time web dashboard for monitoring OpenClaw agent sessions. Track token usage, view live transcripts, and debug conversations across all your agents in one place.
- Quick Start
- Features
- Using the Viewer
- Installation
- Running as a Service
- API Reference
- Requirements
- License
# Install
pip install flask
# Run
python session-viewer.py
# Open browser
http://localhost:8766That's it! The viewer auto-discovers all OpenClaw sessions from ~/.openclaw/agents/.
- 📊 Multi-agent view - See all active sessions across every agent
- 💯 Token tracking - Real-time context usage with color-coded warnings
- 🎯 Smart filtering - Toggle tool calls, focus on conversations
- ⚡ Live tail mode - Auto-refresh every 2 seconds for active debugging
- 🕐 Timestamps - See exactly when each message was sent
- 🎨 Role highlighting - Color-coded user/assistant/tool entries
- 📏 Token estimates - Character count and estimated tokens per entry
- 🔄 Newest first - Latest messages at the top, scroll for history
- 🚀 Zero config - Works out of the box with any OpenClaw setup
- 📦 Single file - Just one Python file, no complex installation
- 🌐 Web-based - Access from any browser, even mobile
- 🔌 REST API - JSON endpoints for custom integrations
Each session card shows:
| Metric | What it means |
|---|---|
| Tokens | Current token count (green < 70%, amber 70-84%, red 85%+) |
| Context | Percentage of model's context window used |
| File | Session file size on disk |
| Model | Which AI model this session is using |
- Click any session to open its transcript
- Newest messages appear at top - scroll down for history
- Entry colors:
- 🔵 Blue - User messages
- 🟢 Green - Assistant responses
- 🟡 Amber - Tool calls
- 🟣 Purple - Tool results
- ⚪ Gray - System events
- 📡 Live Tail - Auto-refresh every 2 seconds (great for debugging active conversations)
- 🔄 Refresh - Manually refresh current transcript
- Show Tools - Toggle tool use/result visibility for cleaner reading
- Python 3.8 or higher
- OpenClaw installed and running
- Active sessions in
~/.openclaw/agents/
-
Clone or download this repo:
git clone https://github.com/rodbland2021/claw-session-viewer.git cd claw-session-viewer -
Install Flask:
pip install flask # or pip install -r requirements.txt -
Run the viewer:
python session-viewer.py
-
Open your browser:
http://localhost:8766
python session-viewer.py --port 9000To access from other machines on your network:
python session-viewer.py --host 0.0.0.0 --port 8766Then open http://your-server-ip:8766 from any device.
Create /etc/systemd/system/session-viewer.service:
[Unit]
Description=Claw Session Viewer
After=network.target
[Service]
Type=simple
User=yourusername
WorkingDirectory=/path/to/claw-session-viewer
ExecStart=/usr/bin/python3 session-viewer.py --host 0.0.0.0 --port 8766
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.targetEnable and start:
sudo systemctl enable session-viewer
sudo systemctl start session-viewer
sudo systemctl status session-viewer# Run in container
docker run -d \
--name session-viewer \
-p 8766:8766 \
-v ~/.openclaw:/root/.openclaw:ro \
-e PYTHONUNBUFFERED=1 \
python:3.11-slim \
sh -c "pip install flask && python session-viewer.py --host 0.0.0.0"The viewer exposes REST endpoints for custom integrations:
Returns all active sessions with metadata.
Response:
[
{
"key": "agent:main:main",
"displayName": "Main Agent",
"totalTokens": 156430,
"contextTokens": 1000000,
"inputTokens": 142100,
"outputTokens": 14330,
"model": "claude-sonnet-4-5",
"fileSize": 1153024,
"updatedAt": 1707289123
}
]Returns transcript entries for a specific session.
Parameters:
key(required) - Session key from/api/sessionstools(optional) - Include tool calls (true/false, defaulttrue)
Response:
{
"displayName": "Main Agent",
"entries": [
{
"role": "user",
"content": "Hello!",
"chars": 6,
"estimatedTokens": 1,
"timestamp": "2026-02-07T10:30:00.000Z",
"toolName": null
},
{
"role": "assistant",
"content": "Hi! How can I help you today?",
"chars": 30,
"estimatedTokens": 7,
"timestamp": "2026-02-07T10:30:02.000Z",
"toolName": null
}
]
}import requests
# Get all sessions
sessions = requests.get('http://localhost:8766/api/sessions').json()
# Find high-usage sessions
for session in sessions:
usage_pct = (session['totalTokens'] / session['contextTokens']) * 100
if usage_pct > 80:
print(f"⚠️ {session['displayName']} at {usage_pct:.1f}% capacity")- Python 3.8 or higher
- Flask 3.0+ (only dependency)
- OpenClaw with active sessions
That's it! No database, no complex setup.
Future enhancements:
- Session comparison view (diff two transcripts)
- Export transcripts to markdown/JSON
- Token usage graphs over time
- Dark/light theme toggle
- Search within transcripts
- Browser notifications for context warnings
Want to contribute? PRs welcome! Open an issue to discuss new features.
✅ Check OpenClaw is running
# If using systemd
systemctl status openclaw✅ Verify session files exist
ls ~/.openclaw/agents/*/sessions/*.jsonl✅ Check file permissions
# Session viewer must be able to read these directories
chmod -R u+r ~/.openclaw/agents/# Check what's using the port
sudo lsof -i :8766
# Use a different port
python session-viewer.py --port 9000Make sure you're binding to all interfaces:
python session-viewer.py --host 0.0.0.0Check your firewall allows the port:
# Ubuntu/Debian
sudo ufw allow 8766
# CentOS/RHEL
sudo firewall-cmd --add-port=8766/tcp --permanent
sudo firewall-cmd --reloadMIT License - see LICENSE file for details.
Free for personal and commercial use. Attribution appreciated but not required.
Built for the OpenClaw community.
- 💬 GitHub Discussions
- 🐛 Report Issues
- ⭐ Star this repo if you find it useful!
Made with ❤️ for the OpenClaw community