TOOLS.md - Local Notes

Skills define how tools work. This file is for your specifics — the stuff that's unique to your setup.

What Goes Here

Things like:

Camera names and locations
SSH hosts and aliases
Preferred voices for TTS
Speaker/room names
Device nicknames
Anything environment-specific

Examples

### Cameras

- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod

Why Separate?

Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.

LAN Services (Will)

Host LAN IPs observed:
- 192.168.153.113 (wlan0)
- 192.168.153.117 (eth0)
Tailscale IP:
- 100.123.88.127

Session routing notes

Current TUI conversations arrive with inbound metadata like:
- channel: webchat
- provider: webchat
- surface: webchat
Telegram DMs route into a separate main session when session.dmScope = "per-channel-peer".
Verified 2026-03-10:
- TUI/webchat session remained separate from Telegram DM session
- Telegram outbound + inbound both worked
- Telegram inbound landed in its own main session file rather than the active TUI session

Search routing

Default page-reading tool: native web_fetch
Default search path: skills/local-meta-search/scripts/search.sh
Routing policy:
- use SearXNG first for normal web lookups
- fall back to Brave MCP if SearXNG fails or returns weak/empty results
- use Brave MCP directly when Will explicitly asks for Brave / a second opinion
Backend labels should be called out in research answers when relevant

Search cheat sheet

General/local-first search:
- skills/local-meta-search/scripts/search.sh "query"
Direct SearXNG:
- skills/searxng-local-search/scripts/search.sh "query"
Direct Brave MCP:
- skills/brave-mcp-search/scripts/search.sh "query"
Native fetch:
- use tool web_fetch(url=...)

Docker services

searxng
- Image: searxng/searxng:latest
- Container: searxng
- Port: 18803 -> 8080
- URL(s):
  - http://192.168.153.113:18803
  - http://192.168.153.117:18803
- API: JSON enabled (search.formats includes html,json)
- Runtime env: SEARXNG_URL=http://192.168.153.113:18803 (workspace .env)
- Role: preferred local-first search backend
- Smoke test:
  - skills/searxng-local-search/scripts/smoke.sh openclaw
whisper-server
- Image: ghcr.io/ggml-org/whisper.cpp:main
- Container: whisper-server
- Port: 18801 -> 8080
- Health: healthy
- URL(s):
  - http://192.168.153.113:18801
  - http://192.168.153.117:18801
brave-search (MCP)
- Image: mcp/brave-search:latest
- Container: brave-search
- Port: 18802 -> 8000
- URL(s):
  - http://192.168.153.113:18802
  - http://192.168.153.117:18802
- MCP endpoint: http://192.168.153.113:18802/mcp
- Note: Will confirmed Brave search port is 18802 on 2026-03-10.
- Verified 2026-03-10: reachable via mcporter as tool brave_web_search.
- Native Brave Search API (web_search) configured on 2026-03-10.
- Plan/rate note: Brave free plan hit rate_limit: 1; serialize requests instead of parallel bursts.

Embeddings (local)

Runtime: Ollama
Active model: nomic-embed-text:latest
Model id: 0a109f422b47
Size: 595 MB
Processor: 100% GPU
Context: 2048
Loaded until: Forever
Ollama embeddings endpoint: http://192.168.153.113:18807
OpenClaw memory search: configured to use provider ollama with model nomic-embed-text
OpenClaw memory index verified working on 2026-03-10 (45 files, 160 chunks, vector dims 768)

Object storage (assistant bucket)

Provider: MinIO
Endpoint: http://192.168.153.253:9000
Bucket: zap
Credentials file: ~/.openclaw/credentials/minio-zap.env (mode 600)
Backup script: scripts/backup-to-minio.sh
Backup scope: full archive of ~/.openclaw (tar.gz) + sha256 + manifest.txt
Backup schedule: system cron every 6 hours at minute 17
- 17 */6 * * * /home/openclaw/.openclaw/workspace/scripts/backup-to-minio.sh >> /home/openclaw/.openclaw/workspace/memory/minio-backup.log 2>&1
Bucket versioning: enabled
Lifecycle rule (prefix workspace-backups/):
- expire noncurrent versions after 90 days
- keep 3 newer noncurrent versions
- expire delete markers enabled

Kubernetes (homelab)

Cluster access: available
Shared namespace: swarm
Kubeconfig: ~/.openclaw/credentials/kubeconfig-swarm.yaml (mode 600)
Usage note: deploy assistant workloads into swarm; namespace is shared with other agents
Cluster profile: small Raspberry Pi cluster — prefer lightweight images, low CPU/memory requests, and minimal replicas by default

Local custom skills (security-reviewed)

skills/swarm-kubectl-safe
- Purpose: safe kubectl operations scoped to swarm
- Script: skills/swarm-kubectl-safe/scripts/kubectl-swarm.sh
skills/whisper-local-safe
- Purpose: local whisper-server transcription on LAN only
- Script: skills/whisper-local-safe/scripts/transcribe-local.sh

Why local equivalents were built:

Candidate ClawHub skills kubectl and faster-whisper-transcribe were flagged as suspicious by ClawHub/VirusTotal checks.
We intentionally avoided force-installing flagged skills for safety.
Decision: use minimal local skills for now; revisit those ClawHub skills later if we perform a manual security review and explicitly approve.

Add whatever helps you do your job. This is your cheat sheet.

5.7 KiB Raw Blame History