qwen3-tts

OpenClaw Qwen3-TTS Plugin

A text-to-speech plugin for OpenClaw that adds support for the Qwen3-TTS server.

Features

• 🔊 OpenAI-compatible TTS API
• 🎤 Multiple voices (Chinese, English, Japanese, Korean)
• 🏥 Health check with automatic caching
• 🔄 Fallback support when server unavailable
• 🤖 Agent tool for TTS generation
• ⚡ GPU-accelerated (CUDA support)

Prerequisites

• Qwen3-TTS server running and accessible
• Default URL: http://192.168.2.198:8101
• API: OpenAI-compatible /v1/audio/speech
• Health: GET /health

Installation

Option 1: From source

# Clone or copy the plugin
cd ~/Dev/openclaw-qwen3-tts

# Install dependencies
npm install

# Build
npm run build

Option 2: Link for development

cd ~/Dev/openclaw-qwen3-tts
npm install
npm run build
npm link

Configuration

Add the plugin to your OpenClaw configuration (~/.openclaw/openclaw.json):

{
  "plugins": {
    "load": {
      "paths": [
        "~/Dev/openclaw-qwen3-tts"
      ]
    },
    "entries": {
      "qwen3-tts": {
        "enabled": true,
        "config": {
          "baseUrl": "http://192.168.2.198:8101",
          "voice": "vivian",
          "responseFormat": "mp3",
          "speed": 1.0,
          "fallbackEnabled": true
        }
      }
    }
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | http://192.168.2.198:8101 | Qwen3-TTS server URL | | voice | string | vivian | Default voice | | model | string | qwen3-tts | Model ID (future use) | | responseFormat | string | mp3 | Audio format: wav, mp3, flac, ogg | | speed | number | 1.0 | Speech speed (0.25 - 4.0) | | enabled | boolean | true | Enable the plugin | | fallbackEnabled | boolean | true | Fall back to built-in TTS when unavailable | | healthCheckTimeoutMs | number | 3000 | Health check timeout | | requestTimeoutMs | number | 30000 | TTS request timeout |

Available Voices

Native Qwen3-TTS Voices

| Voice | Language | Description | |-------|----------|-------------| | vivian | Chinese | Female, warm and expressive | | serena | Chinese | Female, gentle and soothing | | uncle_fu | Chinese | Male, mature and authoritative | | dylan | English | Male, clear and professional | | eric | English | Male, friendly and casual | | ryan | English | Male, energetic and youthful | | aiden | English | Male, calm and measured | | ono_anna | Japanese | Female, cute and expressive | | sohee | Korean | Female, bright and cheerful |

OpenAI Aliases

These voices are mapped to similar Qwen3-TTS voices:

| Alias | Maps To | |-------|---------| | alloy | vivian | | echo | dylan | | fable | serena | | onyx | uncle_fu | | nova | ono_anna | | shimmer | sohee |

Usage

Chat Commands

/qwen-tts status     # Show server status and health
/qwen-tts voices     # List available voices
/qwen-tts help       # Show help

Agent Tool

The plugin registers a qwen_tts tool that agents can use:

Generate speech saying "Hello, world!" using the vivian voice in mp3 format.

The agent will call:

{
  "tool": "qwen_tts",
  "params": {
    "text": "Hello, world!",
    "voice": "vivian",
    "format": "mp3"
  }
}

Programmatic API

import { speak, getHealth, listVoices } from 'openclaw-qwen3-tts';

// Check health
const health = await getHealth();
console.log(health.healthy ? 'Server is ready' : 'Server unavailable');

// Generate speech
const result = await speak('Hello, world!', {
  voice: 'dylan',
  format: 'mp3',
  speed: 1.0,
});

if (result.success) {
  console.log(`Audio saved to: ${result.audioPath}`);
  console.log(`Latency: ${result.latencyMs}ms`);
}

// List voices
console.log('Available voices:', listVoices());

API Reference

Qwen3-TTS Server API

Health Check:

curl http://192.168.2.198:8101/health
# Response: {"status":"ok","model_loaded":true,"cuda":true}

Text-to-Speech:

curl -X POST http://192.168.2.198:8101/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello, world!",
    "voice": "vivian",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  -o speech.mp3

Troubleshooting

Server Unavailable

1. Check if the Qwen3-TTS server is running:

   curl http://192.168.2.198:8101/health

2. Check network connectivity to the server

3. Verify the baseUrl in configuration

Audio Generation Failed

1. Check server logs for errors 2. Verify CUDA is available (cuda: true in health check) 3. Ensure model is loaded (model_loaded: true)

Slow Generation

1. Check network latency to the server 2. Reduce text length for faster generation 3. Use a simpler voice (some voices are more complex)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Clean
npm run clean

License

MIT

Credits

• Qwen3-TTS - The underlying TTS model
• OpenClaw - The AI agent framework