Kami SmartHome Suite

Overview

Kami SmartHome Suite is the one-stop installer for the kami-smarthome ecosystem. By installing this single skill, users get:

1. Batch download — install all 6 ecosystem skills from ClawHub in one go
2. Guided configuration — interactive setup for API key and notification channels; all skills are ready to use immediately after configuration
3. Centralized config management — to change anything later, edit one file and run configure.sh --distribute to sync

> Configure once, run everywhere — one config file controls all skills.

Included Skills

This suite bundles the following 6 standalone skills:

| # | Skill | Emoji | Description | Use case |

|---|-------|-------|-------------|----------|

| 1 | kami-package-detection | 📦 | Continuous package/parcel monitoring on RTSP streams using YOLO-World ONNX with smart notification | Doorstep delivery alerts |

| 2 | kami-image-search | 🔍 | Periodic frame capture + VLM captioning + FAISS index for natural-language image search | Search historical frames |

| 3 | kami-video-search | 📹 | Continuous video segmentation + VLM scene description + natural-language clip search | Search historical clips |

| 4 | kami-fall-detection | 🚨 | Frame-difference detection + KamiClaw cloud inference for fall events | Elder / lone-resident care |

| 5 | kami-conflict-detection | 🥊 | Multi-person physical conflict (fight/shove) detection with event-driven alarm JSON | Security alerting |

| 6 | kami-suspicious-person | 🕵️ | Stranger recognition via SCRFD + ArcFace, detects unregistered face loitering | Doorway / stranger-loiter alerts |

Skill Map

kami-smarthome-suite (this skill — installer entry point)
├── kami-package-detection    ── Package / delivery detection
├── kami-image-search         ── Image search
├── kami-video-search         ── Video recording & search
├── kami-fall-detection       ── Fall detection (cloud API)
├── kami-conflict-detection   ── Conflict / fight detection
└── kami-suspicious-person    ── Stranger / suspicious-person detection

Installation

All Kami SmartHome skills are published on ClawHub and installed via clawhub install.

Option 1: One-click install (recommended)

# Install the suite
clawhub install kami-smarthome-suite

# Run setup.sh — auto-installs all 6 skills + guides centralized config
bash {baseDir}/setup.sh

setup.sh performs:

1. One-shot install of all 6 Kami ecosystem skills from ClawHub
2. Detect / install Python 3.10:
• Debian/Ubuntu: prefer conda → pyenv → system python3.10 (avoids python3.10-venv sudo dependency)
• Other systems: prefer system python3.10 → pyenv → conda
• If none found: auto-install (conda preferred → pyenv as fallback), no sudo required; only pyenv source build will ask for sudo when build-deps are missing
3. Interactive prompts for centralized config (API key, camera URL, notifications)
4. Auto-distribute the centralized config to each skill's local config files

> Idempotent — re-running will not reinstall skills that are already present.

Option 2: Install individually

You can also install specific skills directly from ClawHub:

clawhub install kami-package-detection
clawhub install kami-image-search
clawhub install kami-video-search
clawhub install kami-fall-detection
clawhub install kami-conflict-detection
clawhub install kami-suspicious-person

After individual installs, run bash {baseDir}/configure.sh to apply unified configuration.

Guided Setup (read this on first use)

> Agent behavior: when this skill is triggered, follow this order:

> 1. Check whether sub-skills are installed (any missing sub-skill directory means "not installed") → if missing, run bash {baseDir}/setup.sh

> 2. Check whether kamiclaw_api_key is empty in {baseDir}/kami_config.json → if so, prompt the user

> 3. Check whether cameras is empty in {baseDir}/kami_config.json → if so, guide the user to add cameras

> 4. ALWAYS render the full RTSP brand template table below (all 6 rows) whenever presenting the setup summary or guiding camera configuration. Do NOT abbreviate it to a single sentence like "supports Hikvision, Dahua..." — the user needs to see the actual URL patterns to fill in.

> 5. ALWAYS show the warning: ⚠️ Max 2 skills per camera — each skill opens an independent RTSP connection; most consumer cameras support only 2–4 concurrent sessions. Exceeding this causes stream disconnection.

> 6. ALWAYS present BOTH Feishu config tiers upfront when asking about notifications. Do NOT just say "Feishu Webhook URL" — list both tiers explicitly so the user can choose:

> - Tier 1 (basic): only feishu_webhook_url (+ optional feishu_webhook_secret for signed bots) → alarm snapshots are pushed as clickable image-host links

> - Tier 2 (inline images): above + feishu_app_id + feishu_app_secret (self-built app) → snapshots embed INLINE inside the Feishu card (best UX). Provide a one-line hint on how to get them: 飞书开发者后台 → 创建自建应用 → 拿 App ID / App Secret。

> 7. If all checks pass, skip the wizard and execute the user's request directly

Step 0: Install sub-skills

• Check: look for sibling directories kami-image-search, kami-video-search, etc. next to {baseDir}
• If missing: run the one-click install:

```bash

bash {baseDir}/setup.sh

```

This script will: download all 6 sub-skills from ClawHub + create venvs + install dependencies

• If present: skip and proceed to config check

Step 1: Configure KamiClaw API key

• Check: read the kamiclaw_api_key field from {baseDir}/kami_config.json
• If empty: tell the user 4 of the 6 skills require an API key, and prompt for one
• How to obtain: register at https://kamiclaw-skill.kamihome.com (free 200 credits)
• API-dependent skills: image-search, video-search, fall-detection, conflict-detection
• 2 fully-local skills (package-detection, suspicious-person) do not need an API key

Step 2: Configure notification channels

• Check: read the notifications section of {baseDir}/kami_config.json
• If all empty: ask the user whether to set up alarm push (any combination is allowed)
• Supported channels (alarm skills fall-detection / package-detection / conflict-detection / suspicious-person push automatically when events fire):
• Feishu Webhook: feishu_webhook_url (+ optional feishu_webhook_secret for signed webhooks) — supported by all 4 alarm skills
• Feishu self-built app (optional, for inline snapshot images): feishu_app_id + feishu_app_secret — when provided, all 4 alarm skills upload the alarm snapshot via Feishu OpenAPI and embed it INLINE inside the card. Without them, the snapshot falls back to a clickable image-host URL
• Telegram Bot: telegram_bot_token + telegram_chat_id — supported by all 4 alarm skills (snapshot pushed inline via sendPhoto)
• Discord Webhook: discord_webhook_url (push-only) — supported by all 4 alarm skills (snapshot attached as multipart, renders inline)
• Discord Bot: discord_bot_token + discord_channel_id (two-way) — fall-detection & package-detection
• All channels are optional; skipped channels just fall back to JSON output without push
• ⚠️ Discord / Telegram may be unreachable from some regions. If a proxy is needed, set HTTPS_PROXY in your shell rc (e.g. ~/.bashrc) yourself — the suite intentionally does NOT manage proxy settings

Step 3: Configure cameras

• Check: read the cameras section of {baseDir}/kami_config.json
• If empty or user wants to add: ask for camera name + RTSP URL
• MUST render the full brand table below verbatim (all 6 rows with actual URL patterns). Do NOT condense into a one-liner like "supports Hikvision, Dahua..." — users need the full URL patterns to copy-paste:

| Brand | URL pattern |

|-------|-------------|

| Hikvision | rtsp://{user}:{pwd}@{ip}:554/Streaming/Channels/101 (101=ch1 main, 102=ch1 sub) |

| Dahua | rtsp://{user}:{pwd}@{ip}:554/cam/realmonitor?channel=1&subtype=0 (subtype=0 main, 1 sub) |

| TP-Link | rtsp://{user}:{pwd}@{ip}:554/stream1 (stream1 main, stream2 sub) |

| EZVIZ | rtsp://admin:{verify_code}@{ip}:554/H264/ch1/main/av_stream |

| Uniview | rtsp://{user}:{pwd}@{ip}:554/media/video1 |

| Reolink | rtsp://{user}:{pwd}@{ip}:554/h264Preview_01_main |

> ⚠️ Max 2 skills per camera. Each skill opens an independent RTSP connection; most consumer cameras support only 2–4 concurrent sessions. Exceeding this causes stream disconnection. If you need more coverage, add a second camera or use the sub-stream.

• After the user provides camera info, write it into kami_config.json under cameras
• Naming tip: use short, lowercase names (e.g. front, back, garage); names must be unique
• If the brand is not listed, the user can type the raw RTSP URL directly

Configuration complete → all skills ready

After the user provides values:

1. Write the values back into the corresponding fields of {baseDir}/kami_config.json
2. Run distribution:

```bash

bash {baseDir}/configure.sh --distribute

```

1. After distribution: tell the user that all skills are ready to use
2. MUST show the user the Included Skills capability table (see Included Skills above) so the user knows what is now available and which trigger phrases to use. This step is mandatory — do not end the turn until the table has been presented. The configure.sh --distribute command also prints the same summary to stdout; relay it verbatim if you do not want to retype the table.

Updating configuration later

To change the API key or notification channels later:

# Re-run the interactive wizard
bash {baseDir}/configure.sh

# Or edit directly and redistribute
vim {baseDir}/kami_config.json
bash {baseDir}/configure.sh --distribute

Prerequisites

• clawhub CLI installed (used to pull skills from ClawHub)
• Network access (for skill download + KamiClaw API calls from some skills)

> Python 3.10 is required. setup.sh selects detection priority by OS family (Debian/Ubuntu prefers conda/pyenv; other systems prefer system python3.10) and auto-installs via conda when missing. Other dependencies are managed by each sub-skill.

Hardware Requirements

Recommended minimum hardware for each skill:

| Skill | CPU | Memory (RAM) | Storage | GPU | Notes |

|-------|-----|--------------|---------|-----|-------|

| kami-package-detection | 2+ cores | 2 GB | 500 MB | not required | YOLO-World ONNX, CPU-only |

| kami-image-search | 2+ cores | 2 GB | 5 GB+ | not required | FAISS index + SQLite frame history |

| kami-video-search | 2+ cores | 2 GB | 10 GB+ | not required | Stores video segments, scales with retention |

| kami-fall-detection | 1+ core | 1 GB | 200 MB | not required | Local does frame-diff only; inference runs in cloud |

| kami-conflict-detection | 4+ cores | 4 GB | 1 GB | optional (accelerates) | Local YOLO person detection + multi-frame analysis |

| kami-suspicious-person | 4+ cores | 4 GB | 1.5 GB | optional (accelerates) | SCRFD + ArcFace ONNX (~1 GB) |

Recommended config to run all 6 skills concurrently:

• CPU: 4+ cores (x86_64 / ARM64)
• Memory: 8 GB+
• Storage: 20 GB+ free space
• Network: stable connection (RTSP pull + API calls)
• OS: Linux (Ubuntu 20.04+ recommended)

> If you only enable a subset of skills, refer to the corresponding rows above.

Centralized Configuration

Design

The suite uses a central config + auto-distribute model:

kami_config.json (Single Source of Truth)
       │
       ▼  configure.py --distribute
       ├── kami-image-search/image_config.json
       ├── kami-video-search/stream_config.json
       ├── kami-fall-detection/config.json
       ├── kami-package-detection/config.json
       ├── kami-conflict-detection/config.json
       ├── kami-suspicious-person/config.json
       └── ~/.kami/credentials.json + cameras.json (cached for any skill)

Central config file kami_config.json

Located in the suite directory, it contains the following sections:

| Section | Description | Skills affected |

|---------|-------------|-----------------|

| kamiclaw_api_key | KamiClaw API key | The 4 cloud-API skills |

| cameras | Map of named cameras (name -> {stream_url}) | All 6 skills (auto-distributed) |

| notifications | Feishu / Telegram / Discord push settings | fall-detection, package-detection, conflict-detection, suspicious-person |

| skills..cameras | Per-skill camera selector: [] = all, ["front"] = filter by name | Selects which cameras each skill receives |

| skills. | Per-skill tuning parameters | The corresponding skill |

Edit this file once and every skill is configured.

Multi-Camera Support

The suite manages multiple cameras under the top-level cameras map. Give each camera a short, unique name (the dict key); each skill references cameras by that name.

{
  "cameras": {
    "front":  { "stream_url": "rtsp://..." },
    "back":   { "stream_url": "rtsp://..." },
    "garage": { "stream_url": "rtsp://..." }
  },
  "skills": {
    "kami-image-search":      { "cameras": [] },                  // all cameras
    "kami-package-detection": { "cameras": ["front", "garage"] }  // filter by name
  }
}

Naming tip. Use short, lowercase, meaningful names (room or location, e.g. front, back, garage). Names must be unique inside cameras. If you skip naming, the suite auto-assigns cam1, cam2, ... in order.

• Interactive mode: the wizard asks for a name, press Enter to auto-assign.
• CLI mode: --add-camera NAME=URL (explicit) or --add-camera URL (auto-assigned).

All 6 skills support native multi-camera: each selected camera runs as an independent background process.

> ⚠️ Max 2 skills per camera. Each skill opens an independent RTSP connection; most consumer cameras support only 2–4 concurrent sessions. Exceeding this causes stream disconnection. If you need more coverage, add a second camera or use the sub-stream.

Recommended combos per camera placement:

| Camera position | Suggested skills (pick up to 2) |

|----------------|------------------|

| Front door / porch | package-detection + suspicious-person |

| Living room / hallway | fall-detection + conflict-detection |

| Garage / warehouse | package-detection + image-search |

| General coverage | image-search + video-search (full archival) |

image-search vs video-search:

| | image-search | video-search |

|--|--|--|

| Capture | Periodic snapshots (every N seconds) | 24/7 continuous video recording |

| Storage | Light (~5 GB) | Heavy (30 GB+) |

| Search result | Single matching frame | Video clip with context |

| Best for | "Was there a package?" quick lookups | "What happened yesterday afternoon?" full replay |

Use image-search alone for lightweight event spot-checks; add video-search when you need complete footage for evidence or review.

Common Brand RTSP Templates

Don't remember your camera's RTSP path? The wizard ships built-in templates for the most common IP-camera brands. Pick [t]emplate-add instead of [a]dd and just fill in IP / username / password.

| Brand key | Brand | URL pattern |

|-----------|-------|-------------|

| hikvision | Hikvision | rtsp://{user}:{pwd}@{ip}:554/Streaming/Channels/101 (101=ch1 main, 102=ch1 sub) |

| dahua | Dahua | rtsp://{user}:{pwd}@{ip}:554/cam/realmonitor?channel=1&subtype=0 (subtype=0 main, 1 sub) |

| tplink | TP-Link | rtsp://{user}:{pwd}@{ip}:554/stream1 (stream1 main, stream2 sub) |

| ezviz | EZVIZ | rtsp://admin:{verify_code}@{ip}:554/H264/ch1/main/av_stream |

| uniview | Uniview | rtsp://{user}:{pwd}@{ip}:554/media/video1 |

| reolink | Reolink | rtsp://{user}:{pwd}@{ip}:554/h264Preview_01_main |

Usage:

# List all built-in templates
bash {baseDir}/configure.sh --list-templates

# Interactive: pick a brand, fill in fields, the URL is rendered for you
bash {baseDir}/configure.sh
#   Choice: t
#   Pick: 1 (hikvision)
#   Camera IP: 192.168.1.64
#   Username: admin
#   Password: pass@123      (special chars are auto URL-encoded)
#   Built URL: rtsp://admin:pass%40123@192.168.1.64:554/Streaming/Channels/101

> Special characters in user / password (e.g. @, :, #) are automatically URL-encoded so the resulting RTSP URL is always valid. If your camera brand isn't listed, just type the raw RTSP URL via [a]dd or --add-camera.

Usage

# Mode 1: interactive wizard (prompts each field, supports add/edit/delete cameras)
bash {baseDir}/configure.sh

# Mode 2: set API key directly
bash {baseDir}/configure.sh sk_live_xxxxxxxx

# Mode 3: edit manually then distribute
vim {baseDir}/kami_config.json
bash {baseDir}/configure.sh --distribute

# Mode 4: show current config
bash {baseDir}/configure.sh --show

# Mode 5: add / remove cameras non-interactively (repeatable)
bash {baseDir}/configure.sh --add-camera rtsp://10.0.0.1/stream             # auto-named cam1
bash {baseDir}/configure.sh --add-camera front=rtsp://10.0.0.1/stream       # explicit name
bash {baseDir}/configure.sh --remove-camera front

# Mode 6: list common-brand RTSP URL templates
bash {baseDir}/configure.sh --list-templates

Distribution Map

| Skill | Target file | Distributed fields |

|-------|-------------|--------------------|

| kami-image-search | image_config.json | cameras: [{STREAM_URL, DEVICE_ID}, ...] (all selected cameras), KAMIVISION_API_KEY, CAPTURE_INTERVAL, RETENTION_DAYS |

| kami-video-search | stream_config.json | cameras: [{STREAM_URL, DEVICE_ID}, ...] (all selected cameras), KAMI_API_KEY, SEGMENT_DURATION, RETENTION_DAYS |

| kami-fall-detection | config.json | cameras: [{rtsp_url, name}, ...] (all selected cameras), api_key, feishu_webhook_url, feishu_app_id, feishu_app_secret, telegram_bot_token, telegram_chat_id, discord_webhook_url, discord_bot_token, discord_channel_id, pre_seconds, post_seconds, save_alarm_clips |

| kami-package-detection | config.json | cameras: [{rtsp_url, device_id}, ...] (all selected cameras), conf_threshold, run_time, alarm_cooldown, feishu_webhook_url, feishu_app_id, feishu_app_secret, telegram_bot_token, telegram_chat_id, discord_webhook_url, discord_bot_token, discord_channel_id (pure local inference, no API key) |

| kami-conflict-detection | config.json | cameras: [{rtsp_url, name}, ...] (all selected cameras), kami_api_key, feishu_webhook, feishu_app_id, feishu_app_secret, discord_webhook, telegram_bot_token, telegram_chat_id |

| kami-suspicious-person | config.json | cameras: [{rtsp_url, name}, ...] (all selected cameras), feishu_webhook, feishu_app_id, feishu_app_secret, discord_webhook, telegram_bot_token, telegram_chat_id (pure local inference, no API key) |

> Power-user tip: each skill's argparse also accepts env vars (KAMI_API_KEY, FEISHU_WEBHOOK_URL, TELEGRAM_*, DISCORD_WEBHOOK_URL, HTTPS_PROXY) as a fallback. If you need an HTTPS proxy for Discord / Telegram, export HTTPS_PROXY in your shell rc — proxy settings are out of scope for kami_config.json.

Integration with setup.sh

setup.sh automatically enters the centralized config flow after installing all skills. If skipped, run bash configure.sh later anytime.

Exit Codes

| Exit code | Meaning |

|-----------|---------|

| 0 | All skills installed successfully |

| 1 | Some skills failed to install (check logs) |

| 2 | Prerequisite missing (no clawhub, or neither conda nor pyenv is usable and Python 3.10 cannot be installed) |

Troubleshooting

clawhub CLI not available

clawhub: command not found

→ Install the ClawHub CLI first.

A skill failed to install

[!] kami-xxx (failed, exit 1)

→ Retry: clawhub install kami-xxx

KamiClaw API key not configured

→ Run bash configure.sh or register at https://kamiclaw-skill.kamihome.com

Config changes have no effect

→ After editing kami_config.json, run bash configure.sh --distribute to push the changes to each skill.

Privacy Notice

This suite involves camera streams, image capture and face recognition. Please review the following privacy notes before use:

Cloud API calls

• 4 skills depend on KamiClaw API (image-search, video-search, fall-detection, conflict-detection); 2 skills (package-detection, suspicious-person) run fully locally
• Data sent to the cloud is used only for real-time inference and is not persisted nor used for model training
• API traffic uses HTTPS encryption

Local data storage

• Captured frames, video segments, etc. are stored under each skill's working directory and can be cleaned manually
• image-search and video-search honor a retention_days parameter for automatic expiry
• The API key and camera list are cached in ~/.kami/ (mode 600, current user only)

Face data (kami-suspicious-person)

• The face feature database is built and matched fully locally — nothing is uploaded to any server
• Files are stored under face_db/, fully under user control
• Removing the face_db/ directory wipes all face data

User control

• Users freely choose which skills to enable; disabled skills collect nothing
• All camera URLs are user-supplied; skills do not auto-discover or auto-connect cameras
• Users can stop a skill, delete local data, or revoke the API key at any time

> Privacy policy details: https://kamiclaw-skill.kamihome.com/privacy