# TOOLS.md - Local Notes & Tool Syntax

---

## 🔧 `read` — Read File Contents

**Syntax:**
```javascript
read({ file_path: "/path/to/file"[, offset: N, limit: N] })
```

**When to use:** Read text files or view images (jpg, png, gif, webp).

**Required:** `file_path` — NEVER use `path`

**Correct:**
```javascript
await read({ file_path: "/path/to/file" })
await read({ file_path: "/path/to/file", offset: 1, limit: 50 })
```

**Wrong:**
```javascript
await read({ path: "/path/to/file" })  // ❌ 'path' is wrong, use 'file_path'
await read({})  // ❌ missing file_path entirely
```

**Notes:**
- Output truncated at 2000 lines or 50KB
- Use `offset` + `limit` for files >100 lines
- Images sent as attachments automatically

---

## 🔧 `edit` — Edit File Contents

**Syntax:**
```javascript
edit({ file_path: "/path", old_string: "exact text", new_string: "replacement" })
```

**When to use:** Precise text replacement. Old text must match exactly (including whitespace).

**Required:** BOTH `old_string` AND `new_string` (not `oldText`/`newText`)

**Correct:**
```javascript
await edit({ 
  file_path: "/path/to/file",
  old_string: "text to replace",
  new_string: "replacement text"
})
```

**Wrong:**
```javascript
await edit({ file_path: "/path/file", old_string: "text" })  // ❌ missing new_string
await edit({ file_path: "/path/file", new_string: "text" })  // ❌ missing old_string
await edit({ file_path: "/path/file", oldText: "x", newText: "y" })  // ❌ wrong param names
```

**Recovery:** After 2 failed edit attempts → use `write` to rewrite the file completely.

---

## 🔧 `write` — Write File Contents

**Syntax:**
```javascript
write({ file_path: "/path", content: "complete file content" })
```

**When to use:** Creating new files or rewriting entire files after failed edits.

**Required:** `file_path` AND complete `content` (overwrites everything)

**Correct:**
```javascript
await write({ 
  file_path: "/path/to/file",
  content: "complete file content here"
})
```

**Wrong:**
```javascript
await write({ content: "text" })  // ❌ missing file_path
await write({ path: "/file", content: "text" })  // ❌ use file_path not path
```

**⚠️ Caution:** Overwrites entire file — make sure you have the full content.

---

## 🔧 `exec` — Execute Shell Commands

**Syntax:**
```javascript
exec({ command: "shell command"[, timeout: 30, workdir: "/path"] })
```

**When to use:** Run shell commands, background processes, or TTY-required CLIs.

**Required:** `command`

**Correct:**
```javascript
await exec({ command: "ls -la" })
await exec({ command: "python3 script.py", timeout: 60 })
await exec({ command: "./script.sh", workdir: "/path/to/dir" })
```

**Cron Scripts — CRITICAL:**
```python
# Always exit 0 for cron jobs
import sys
sys.exit(0)
```

**Why:** OpenClaw logs non-zero exits as failures. Use stdout presence for signaling:
```python
if significant_update:
    print(notification)  # Output triggers notification
# No output = silent success
```

---

## 🔧 `browser` — Browser Control

**Syntax:**
```javascript
browser({ action: "navigate|snapshot|click|...", targetUrl: "..." })
```

**When to use:** Navigate, screenshot, or interact with web pages.

**Required:** `action`

**Requirements:**
- Gateway must be running
- Chrome extension must be attached (click extension icon on tab)

**Correct:**
```javascript
await browser({ action: "navigate", targetUrl: "https://example.com" })
await browser({ action: "snapshot" })
await browser({ action: "click", ref: "button-name" })
```

---

## Quick Reference Summary

| Tool | Required Parameters | Common Errors |
|------|---------------------|---------------|
| `read` | `file_path` | Using `path` |
| `edit` | `file_path`, `old_string`, `new_string` | Using `newText`/`oldText`, missing one param |
| `write` | `file_path`, `content` | Partial content, missing `file_path` |
| `exec` | `command` | Non-zero exit codes for cron |
| `browser` | `action` | Using without gateway check |

**Critical rules:** Use `file_path` not `path`. Use `old_string`/`new_string` not `oldText`/`newText`.

**Quality over speed. Verify before executing. Get it right.**

---

## Unified Search — Perplexity Primary, SearXNG Fallback

**Primary:** Perplexity API (cloud, AI-curated, paid)  
**Fallback:** SearXNG (local, raw results, free)

### Usage
```bash
# Default: Perplexity primary, SearXNG fallback on error
search "your query"

# Perplexity only (p = perplexity)
search p "your query"
search perplexity "your query"

# SearXNG only (local = searxng)
search local "your query"
search searxng "your query"

# With citations (Perplexity)
search --citations "your query"

# Pro model for complex queries
search --model sonar-pro "your query"
search --model sonar-deep-research "comprehensive research"
```

### Models
| Model | Best For | Search Context |
|-------|----------|----------------|
| sonar | Quick answers, simple queries | Low/Medium/High |
| sonar-pro | Complex queries, coding | Medium/High |
| sonar-reasoning | Step-by-step reasoning | Medium/High |
| sonar-deep-research | Comprehensive research | High |

### When to Use Each
- **Perplexity**: Complex queries, research, current events, anything needing synthesis
- **SearXNG**: Privacy-sensitive searches, simple factual lookups, bulk operations, rate limit fallback

### Scripts
- **Unified**: `skills/perplexity/scripts/search.py`
- **Perplexity-only**: `skills/perplexity/scripts/query.py`

---

## Perplexity API

- **Location**: `/root/.openclaw/workspace/skills/perplexity/`
- **Key**: `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`
- **Endpoint**: `https://api.perplexity.ai/chat/completions`
- **Models**: sonar, sonar-pro, sonar-reasoning, sonar-deep-research
- **Format**: OpenAI-compatible
- **Cost**: ~$0.005 per query (shown in output)
- **Features**: AI-synthesized answers, citations, real-time search
- **Note**: Sends queries to Perplexity servers (cloud)

---

### Voice/Text Reply Rules
- **Voice message received** → Reply with **voice** (using Kimi-XXX.ogg filename)
  - Transcribe internally for understanding
  - **DO NOT send transcript text to Telegram**
  - **DO NOT include any text with voice messages** — voice-only, completely silent text
  - Reply with voice-only, no text
- **Text message received** → Reply with **text**
- **Never** send both voice + text for the same reply
- **ENFORCED 2026-02-07:** Voice messages must be sent alone without accompanying text

### Voice Settings
- **TTS Provider**: Local Kokoro @ `http://10.0.0.228:8880`
- **Voice**: `af_bella` (American Female)
- **Filename format**: `Kimi-YYYYMMDD-HHMMSS.ogg`
- **Mode**: Voice-only (no text transcript when sending voice)

### Web Search
- **Primary**: Perplexity API (unified search, AI-curated)
- **Fallback**: SearXNG (local instance at `http://10.0.0.8:8888/`)
- **Manual fallback**: Use `search local "query"` for privacy-sensitive searches
- **Browser tool**: Only when gateway running and extension attached

### Core Values
- **Best accuracy** — No compromises on quality
- **Best performance** — Optimize for speed where possible
- **Privacy first** — Always prioritize privacy in all decisions
- **Always research before install** — Search web for details, docs, best practices
- **Local docs exception** — If docs are local (OpenClaw, ClawHub), use those first

### Search Preferences
- **Search first** — Try SearXNG before asking clarifying questions
- **Prioritize sites**: *(to be filled in)*
  - GitHub / GitLab — For code, repos, technical docs
  - Stack Overflow — For programming Q&A
  - Wikipedia — For general knowledge
  - Arch Wiki — For Linux/system admin topics
  - Official docs — project.readthedocs.io, docs.project.org
- **Avoid/deprioritize**: *(to be filled in)*
  - SEO spam sites
  - Outdated forums (pre-2020 unless historical)
- **Search language**: English preferred, unless query is non-English
- **Time bias**: Prefer recent results for tech topics, timeless for facts

### Search-First Sites (Priority Order)
When searching, prefer results from:
1. **docs.openclaw.ai** / **OpenClaw docs** — OpenClaw documentation
2. **clawhub.com** / **ClawHub** — OpenClaw skills registry
3. **docs.*.org** / **readthedocs.io** — Official documentation
4. **github.com** / **gitlab.com** — Source code, issues, READMEs
5. **stackoverflow.com** — Programming solutions
6. **wikipedia.org** — General reference
7. **archlinux.org/wiki** — Linux/system administration
8. **reddit.com/r/* —** Community discussions (for opinions/experiences)
9. **news.ycombinator.com** — Tech news and discussions
10. **medium.com** / **dev.to** — Developer blogs (verify date)

## SSH Hosts

- **epyc-debian-SSH (deb)** — `n8n@10.0.0.38`
  - Auth: SSH key (no password)
  - Key: `~/.ssh/id_ed25519`
  - Sudo password: `passw0rd`
  - Usage: `ssh n8n@10.0.0.38`
  - Status: OpenClaw removed 2026-02-07

- **epyc-debian2-SSH (deb2)** — `n8n@10.0.0.39`
  - Auth: SSH key (same as deb)
  - Key: `~/.ssh/id_ed25519`
  - Sudo password: `passw0rd`
  - Usage: `ssh n8n@10.0.0.39`

## Existing Software Stack

**⚠️ ALREADY INSTALLED — Do not recommend these:**

- **n8n** — Workflow automation
- **ollama** — Local LLM runner
- **openclaw** — AI agent platform (this system)
- **openwebui** — LLM chat interface
- **anythingllm** — RAG/chat with documents
- **searxng** — Privacy-focused search engine
- **flowise** — Low-code LLM workflow builder
- **plex** — Media server
- **radarr** — Movie management
- **sonarr** — TV show management
- **sabnzbd** — Usenet downloader
- **comfyui** — Stable Diffusion UI

**When recommending software, ALWAYS check this list first and omit any matches.**

## Skills

### Local Whisper STT
- **Location**: `/root/.openclaw/workspace/skills/local-whisper-stt/`
- **Purpose**: Transcribe inbound voice messages
- **Model**: `base` (CPU-only)
- **Usage**: Auto-transcribes when voice message received
- **Correct path**: `scripts/transcribe.py` (not root level)

### Kimi TTS Custom
- **Location**: `/root/.openclaw/workspace/skills/kimi-tts-custom/`
- **Purpose**: Generate voice with custom filenames and send voice-only replies
- **Scripts**:
  - `scripts/generate_voice.py` — Generate voice file (returns path, does NOT send)
  - `scripts/voice_reply.py` — Generate + send voice-only reply (USE THIS for voice replies)
- **Usage**: `python3 scripts/voice_reply.py <chat_id> "text"`
- **⚠️ CRITICAL**: Text reference to voice file does NOT send audio. Must use `voice_reply.py` or proper Telegram API delivery. Generation ≠ Delivery.

### Qdrant Memory
- **Location**: `/root/.openclaw/workspace/skills/qdrant-memory/`
- **Mode**: MANUAL ONLY — No automatic storage
- **Collections**:
  - `kimi_memories` (personal) — Identity, rules, preferences, lessons
  - `kimi_kb` (knowledge base) — Web data, documents, reference materials
- **Vector size**: 1024 (snowflake-arctic-embed2)
- **Distance**: Cosine
- **Qdrant URL**: `http://10.0.0.40:6333`

**Personal Memory Scripts (kimi_memories):**
- `scripts/store_memory.py` — Manual storage with metadata
- `scripts/search_memories.py` — Semantic search
- `scripts/hybrid_search.py` — Search files + vectors

**Knowledge Base Scripts (kimi_kb):**
- `scripts/kb_store.py` — Store web/docs to KB
- `scripts/kb_search.py` — Search knowledge base

**Usage:**
```bash
# Personal memories ("q remember", "q recall")
python3 store_memory.py "Memory" --importance high --tags "preference"
python3 search_memories.py "voice settings"

# Knowledge base (manual document/web storage)
python3 kb_store.py "Content" --title "X" --domain "Docker" --tags "container"
python3 kb_search.py "docker volumes" --domain "Docker"
```

**⚠️ CRITICAL**: Never auto-store. Only when user explicitly requests with "q" prefix.

## Infrastructure

### Container Limits
- **No GPUs attached** — All ML workloads run on CPU
- **Whisper**: Use `tiny` or `base` models for speed

### Local Services
- **Kokoro TTS**: `http://10.0.0.228:8880` (OpenAI-compatible)
- **Ollama**: `http://10.0.0.10:11434`
- **SearXNG**: `http://10.0.0.8:8888` (web search via curl)
- **Qdrant**: `http://10.0.0.40:6333` (vector database for memory + KB)
  - **Collections**: `kimi_memories` (personal), `kimi_kb` (knowledge base)
  - **Vector size**: 1024 (snowflake-arctic-embed2)
  - **Distance**: Cosine similarity
- **Redis**: `10.0.0.36:6379` (task queue, available for future use)

## Cron Jobs

- **Default:** Always check `openclaw cron list` first when asked about cron jobs
- Rob's scheduled tasks live in OpenClaw's cron system, not system crontab
- Only check system crontab (`crontab -l`, `/etc/cron.d/`) if specifically asked about system-level jobs

---

## Lessons Learned & Workarounds

### Embedded Session Tool Errors
**Issue:** `read tool called without path` errors occur in embedded sessions even when parameter syntax is correct in workspace scripts.

**Workarounds:**
1. **Double-check parameters manually** — Don't trust the model to pass them correctly in embedded contexts
2. **Avoid embedded tool calls when possible** — Use workspace scripts instead
3. **Edit fails twice → Use write immediately** — Don't retry edit tool more than once
4. **Verify file exists before read** — Prevents ENOENT errors
5. **No redis-cli in container** — Use Python redis module instead
6. **Browser tool unreliable** — Use curl/SearXNG as primary web access

### Common Parameter Errors to Avoid
| Wrong | Right | Notes |
|-------|-------|-------|
| `path` | `file_path` | Most common error |
| `newText`/`oldText` | `new_string`/`new_string` | Edit tool only |
| Missing `new_string` | Include both params | Edit requires both |
| Using `write` for small edits | Use `edit` first | Edit is safer for small changes |

### Environment-Specific Gotchas
- **Qdrant Python module** — Must use scripts with proper sys.path setup
- **Playwright browsers** — Not installed, use curl/SearXNG for web scraping
- **Browser gateway** — Requires Chrome extension attached; rarely available
- **Redis CLI** — Not available; use `python3 -c "import redis..."` instead