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.
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
Interactive prompts for centralized config (API key, camera URL, notifications)
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:
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:
Check whether sub-skills are installed (any missing sub-skill directory means "not installed") → if missing, run bash {baseDir}/setup.sh
Check whether kamiclaw_api_key is empty in {baseDir}/kami_config.json → if so, prompt the user
Check whether cameras is empty in {baseDir}/kami_config.json → if so, guide the user to add cameras
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.
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.
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。
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
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)
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:
⚠️ 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:
Write the values back into the corresponding fields of {baseDir}/kami_config.json
Run distribution:
bash
bash {baseDir}/configure.sh --distribute
After distribution: tell the user that all skills are ready to use
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:
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.
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.
# 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
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)