---
name: kimi-tts-custom
description: Custom TTS handler for Kimi that generates voice messages with custom filenames (Kimi-XXX.ogg) and optionally suppresses text output. Use when user wants voice-only responses with branded filenames instead of default OpenClaw TTS behavior.
---

# Kimi TTS Custom

## Overview

Custom TTS wrapper for local Kokoro that:
- Generates voice with custom filenames (Kimi-XXX.ogg)
- Can send voice-only (no text transcript)
- Uses local Kokoro TTS at 10.0.0.228:8880

## When to Use

- User wants voice responses with "Kimi-" prefixed filenames
- User wants voice-only mode (no text displayed)
- Default TTS behavior needs customization

## Voice-Only Mode

**⚠️ CRITICAL: Generation ≠ Delivery**

Simply generating a voice file does NOT send it. You must use proper delivery method:

### Correct Way: Use voice_reply.py
```bash
python3 /root/.openclaw/workspace/skills/kimi-tts-custom/scripts/voice_reply.py "1544075739" "Your message here"
```

This script:
1. Generates voice file with Kimi-XXX.ogg filename
2. Sends via Telegram API immediately
3. Cleans up temp file

### Wrong Way: Text Reference
❌ Do NOT do this:
```
[Voice message attached: Kimi-20260205-185016.ogg]
```
This does not attach the actual audio file — user receives no voice message.

### Alternative: Manual Send (if needed)
If you already generated the file:
```bash
# Use OpenClaw CLI
openclaw message send --channel telegram --target 1544075739 --media /path/to/Kimi-XXX.ogg
```

## Configuration

Set in `messages.tts.custom`:
```json
{
  "messages": {
    "tts": {
      "custom": {
        "enabled": true,
        "voiceOnly": true,
        "filenamePrefix": "Kimi",
        "kokoroUrl": "http://10.0.0.228:8880/v1/audio/speech",
        "voice": "af_bella"
      }
    }
  }
}
```

## Scripts

### scripts/generate_voice.py
Generates voice file with custom filename and returns path for sending.

**⚠️ Note**: This only creates the file. Does NOT send to Telegram.

Usage:
```bash
python3 generate_voice.py "Text to speak" [--voice af_bella] [--output-dir /tmp]
```

Returns: JSON with `filepath`, `filename`, `duration`

### scripts/voice_reply.py (RECOMMENDED)
Combined script: generates voice + sends via Telegram in one command.

**This is the correct way to send voice replies.**

Usage:
```bash
python3 voice_reply.py "1544075739" "Your message here" [--voice af_bella]
```

This generates the voice file and sends it immediately (voice-only, no text).

## Key Rule

| Task | Use |
|------|-----|
| Generate voice file only | `generate_voice.py` |
| Send voice reply to user | `voice_reply.py` |
| Text reference to file | ❌ Does NOT work |

**Remember**: Generation and delivery are separate steps. Use `voice_reply.py` for complete voice reply workflow.