Kami Smarthome Suite

Kami SmartHome skill bundle. One-click installer for the entire Kami SmartHome ecosystem with centralized configuration (API key, cameras, notifications) — no more configuring each skill individually.

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

text

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)

bash

# 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:

bash

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
   

3. After distribution: tell the user that all skills are ready to use
4. 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:

bash

# 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:

text

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

json

{
  "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:

bash

# 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

bash

# 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

text

clawhub: command not found

→ Install the ClawHub CLI first.

A skill failed to install

text

[!] 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