Kami Fall Detection (Cloud)

Detect fall events from RTSP camera streams using the KamiClaw cloud API. No local GPU needed — all inference runs server-side.

🚀 Quick Start

1. Get API key → https://kamiclaw-skill.kamihome.com (200 free credits for new users)
2. Tell the agent: Your API key + RTSP camera URL
3. Choose notifications: Feishu / Telegram / Discord (any combination)
4. Agent configures everything automatically
5. Run! → Monitors 24/7, alerts instantly on fall detection

What It Does

• 🎥 Monitors RTSP camera streams continuously
• 🧠 Uses cloud AI to detect fall events (active falling, fallen posture, etc.)
• 📱 Sends instant notifications via Feishu, Telegram, or Discord
• 💾 Saves alarm video clips for review (optional)
• 🔄 Auto-reconnects if stream drops

🔒 Privacy & Data Policy

In short: Only 8-second alarm clips are sent to the cloud for AI analysis. No continuous streaming, no audio, no full video.

> 📄 Full details: Read our Privacy Policy for complete information on data handling, retention, and your rights.

Quick Tips

• Disable local storage: Set save_alarm_clips: false to not save clips locally
• Clean up old files: find logs/clips/ -type f -mtime +30 -delete
• Protect your API key: Never commit config.json to git

> ℹ️ AI analysis requires sending alarm clips to the cloud API. Processed clips are retained per the provider's data retention policy.

Configuration

All settings are in config.json. The agent auto-fills this when you provide values in chat.

Essential Settings

Camera Setup

All cameras are declared in the cameras array. Each entry has just two fields: name and rtsp_url.

Single camera (one entry). name is optional — if omitted it defaults to "default":

{
  "cameras": [
    { "rtsp_url": "rtsp://192.168.1.100/live/stream" }
  ]
}

Multiple cameras (two or more entries). Every entry must have a unique, non-empty name. Strongly recommended: pick a meaningful location label so the operator immediately knows which camera triggered.

{
  "cameras": [
    { "name": "front_door", "rtsp_url": "rtsp://192.168.1.101/live/stream" },
    { "name": "backyard",   "rtsp_url": "rtsp://192.168.1.102/live/stream" }
  ]
}

• name is shown in every Feishu / Telegram / Discord push and tags every log line.
• One worker thread per camera; a single stream loss does not affect the others.
• The skill refuses to start if cameras is empty, or if multiple entries are missing/sharing a name.

Common Brand RTSP Templates

MUST show this table to the user when configuring cameras, so they can pick a URL pattern based on their brand:

Advanced Settings

Notification Setup

Tell the agent which channels you want. They'll guide you through setup.

Quick Guide

> 💡 Discord: Bot token + channel ID gives you full two-way capability. Webhook is simpler for push-only.

> 💡 Need help? Ask OpenClaw for guidance.

Running

# With config.json (recommended)
.venv/bin/python fall_detect_cloud_skill.py

# Or override the API key on the CLI
.venv/bin/python fall_detect_cloud_skill.py \
    --api_key sk_live_xxxxxxxx

Cameras are always declared in config.json under the cameras array — there is no CLI flag for the RTSP URL.

The skill runs continuously. It does NOT stop after an alarm — it resets and keeps monitoring.

Output Format

Fall detected:

{
  "alarm": true,
  "type": "fall",
  "camera_name": "front_door",
  "fall_type": "active_falling",
  "num_persons": 1,
  "confidence": 0.92,
  "reason": "Person collapsed from standing to floor near bed",
  "frame": 87,
  "source": "rtsp://192.168.1.101/live/stream",
  "clip": "logs/clips/alarm_fall_20260429_143201.mp4"
}

Normal exit (run time reached):

{
  "alarm": false,
  "type": null,
  "detail": "Run time limit reached, no fall detected",
  "frames_processed": 3600,
  "source": "rtsp://192.168.1.100/live/stream"
}

Exit Codes

Advanced: How It Works

Agent Setup Flow

For agents configuring this skill:

1. Read config.json — check whether api_key is set and whether cameras is a non-empty array.
2. If api_key is empty, ask the user: "Please provide your KamiClaw API key. Register at https://kamiclaw-skill.kamihome.com".
3. If cameras is empty, ask: "How many RTSP cameras do you want to monitor?"
• One camera: ask only for the RTSP URL. Write [ { "rtsp_url": "..." } ] — name will default to "default" automatically.
• Two or more cameras: for each one, ask both the RTSP URL and a unique short location label (e.g. front_door, backyard, living_room). Strongly recommend the user picks meaningful labels — they are shown in every alarm notification. Write [ { "name": "front_door", "rtsp_url": "..." }, { "name": "backyard", "rtsp_url": "..." } ].
4. Ask: "Save alarm video clips? (yes/no, default: yes)" → set save_alarm_clips.
5. Ask about each notification channel (Feishu / Telegram / Discord) — guide setup if yes.
6. Write all values to config.json (read existing, merge, write back).
7. Optionally run python fall_detect_cloud_skill.py --list_cameras to confirm the resolved camera list.
8. Run the skill.

Never run with an empty api_key. Never run with cameras empty. When the user has multiple cameras, never accept missing/duplicate names — re-prompt until each camera has a unique label. Never ask the user to manually edit config.json.

Troubleshooting & Analysis

Log Files

Quick Analysis Commands

# Count alarms today
grep '"alarm"' logs/alarms.jsonl | grep "$(date +%Y-%m-%d)" | wc -l

# Transitions vs alarms (false positive rate)
wc -l logs/transitions.jsonl logs/alarms.jsonl

# Export alarms as CSV
cat logs/alarms.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    obj = json.loads(line)
    if obj.get('event') == 'alarm':
        print(f\"{obj['_ts']},{obj.get('type','')},{obj.get('fall_type','')},{obj.get('confidence',0)},{obj.get('frame',0)}\")
"

Common Issues

File Structure

kami-fall-detection/
├── SKILL.md                      # Documentation
├── config.json                   # Configuration (auto-managed by agent)
├── fall_detect_cloud_skill.py    # Production entry point
├── setup.sh                      # Installer
└── requirements.txt              # Dependencies