ClawPTT

A voice bridge for OpenClaw. Puts your OpenClaw agents on push-to-talk radio via Zello Work — key up, ask a question, get a spoken answer. Everyone on the channel hears it.

Built as a stopgap until OpenClaw ships native voice on iOS. If you're reading this and OpenClaw already has a voice interface on mobile — you probably don't need ClawPTT. Use the real thing.

Until then: text in from Zello's server-side transcription, audio out via offline TTS. Single Node.js process, no cloud dependency for routine queries.

How it works

You (PTT radio) → Zello transcribes → ClawPTT → LLM agent → TTS → Opus audio → You hear the answer

Quick questions (weather, calendar, locations) are answered in 2-5 seconds on local inference. Complex questions are gated to a research agent that runs asynchronously and posts results to a text channel — the radio is never blocked.

Also includes a REST API (port 18790) for Zello Work admin operations: user management, GPS locations, message history, channel configuration.

Install

npm install clawptt

Or run directly:

npx clawptt

Quick start

As a CLI

npm install clawptt
npx clawptt init        # interactive setup: Zello creds, LLM, TTS, .env
npx clawptt             # start the bridge

The setup wizard will walk you through configuring Zello credentials, choosing an LLM backend, installing TTS dependencies, and downloading a voice model.

As a library

import { createBridge, ZelloAPI } from "clawptt";

const bridge = createBridge({
  zello: {
    network: "your-network",
    botUser: "bot-username",
    botPass: "bot-password",
    channels: ["AI-Dispatch"],
  },
  llm: {
    backend: "openclaw",
    token: "your-gateway-token",
    agent: "main",
  },
  tts: {
    voice: "en_US-lessac-high",
    python: ".venv/bin/python3",
  },
});

bridge.on("transcription", ({ user, channel, text }) => {
  console.log(`${user} on ${channel}: ${text}`);
});

bridge.on("response", ({ channel, text, audioSent }) => {
  if (audioSent) console.log(`Replied on ${channel}: ${text}`);
});

await bridge.start();

// Use the Zello REST API client directly
const zello = new ZelloAPI({
  network: "your-network",
  apiKey: "your-api-key",
  username: "admin",
  password: "admin-pass",
});
await zello.login();
const users = await zello.listUsers();

Requirements

• Node.js >= 18
• Python 3 with sherpa-onnx (TTS only — inbound STT is handled by Zello)
• ffmpeg
• Zello Work network with transcription enabled
• OpenClaw gateway or any OpenAI-compatible LLM endpoint

Documentation

See docs/INSTALLATION.md for the full guide:

• Why ClawPTT exists (design philosophy from HAM radio, tactical comms, cybersecurity)
• Architecture overview and component demarcation
• Zello Work setup (user, channel, subscription — step by step)
• Two-tier agent design (fast voice agent + async research agent)
• Model selection and latency budget (why vLLM >> Ollama on GPU)
• Skill filtering for voice performance (55 skills = timeouts, 9 skills = 1.5s)
• Gate protocol for deep research (async handoff to text channel)
• REST API reference (users, channels, locations, history, media)
• Production deployment (systemd, monitoring, capacity)

Configuration

All config via environment variables. Copy .env.example and edit:

# Minimum required
ZELLO_NETWORK=your-network
ZELLO_BOT_USER=your-bot
ZELLO_BOT_PASS=your-password
ZELLO_BRIDGE_CHANNELS=your-channel
GATEWAY_TOKEN=your-openclaw-token
OPENCLAW_AGENT=your-agent-id
VENV_PYTHON=.venv/bin/python3

See .env.example for all options (REST API, TTS voice, local LLM, conversation history).

Author

Idea and execution with Claude Code: Florian Gutzwiller

License

MIT