openclaw-sip-voice 0.1.0

package/INSTALL.md

@@ -0,0 +1,293 @@
+# Installation Guide - OpenClaw SIP Voice Plugin
+
+Complete installation instructions for the SIP Voice plugin.
+
+## Prerequisites
+
+Before installing, ensure you have:
+
+- ✅ **OpenClaw** ≥ 2026.0.0 installed and running
+- ✅ **Python** 3.9 or higher (`python3 --version`)
+- ✅ **pip** package manager (`pip3 --version`)
+- ✅ **ffmpeg** for audio conversion (`ffmpeg -version`)
+- ✅ **Whisper CLI** (optional, for local STT: `pip install openai-whisper`)
+
+## Installation
+
+### Simple One-Command Install ✨
+
+```bash
+openclaw plugins install openclaw-sip-voice
+openclaw gateway restart
+```
+
+**That's it!** The plugin automatically installs Python dependencies on first startup.
+
+---
+
+## Alternative Installation Methods
+
+### From npm (Recommended)
+
+```bash
+openclaw plugins install openclaw-sip-voice
+```
+
+### From GitHub (Development)
+
+```bash
+git clone https://github.com/chrishodgkins/openclaw-sip-voice.git
+cd openclaw-sip-voice/plugin
+npm install
+npm run build
+openclaw plugins install -l .
+```
+
+### From Tarball
+
+```bash
+# Download the tarball
+curl -L https://github.com/chrishodgkins/openclaw-sip-voice/releases/download/v0.1.0/openclaw-sip-voice-0.1.0.tgz -o sip-voice.tgz
+
+# Install
+openclaw plugins install ./sip-voice.tgz
+```
+
+## Auto-Install Details
+
+When you start the gateway after installing the plugin, it will:
+
+1. **Check** if Python dependencies are installed
+2. **Auto-install** them if needed (runs `pip3 install -e python/`)
+3. **Log progress** - First startup takes 30-60 seconds for dependency install
+4. **Start normally** on subsequent restarts (instant)
+
+**Requirements:**
+- Python 3.9 or higher must be installed
+- `pip3` must be available in PATH
+
+**Manual Install (if auto-install fails):**
+```bash
+cd ~/.openclaw/extensions/sip-voice/python
+pip3 install -e .
+```
+
+## Configuration
+
+Edit your OpenClaw config (`~/.openclaw/config.json`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "sip-voice": {
+        "enabled": true,
+        "config": {
+          "sip": {
+            "port": 5060,
+            "rtpPortBase": 20000,
+            "codec": "PCMA"
+          },
+          "stt": {
+            "model": "base",
+            "language": "en"
+          },
+          "greeting": "Hello! You've reached my AI assistant. How can I help you today?"
+        }
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `sip.port` | 5060 | SIP listen port (UDP) |
+| `sip.rtpPortBase` | 20000 | Base port for RTP media |
+| `sip.codec` | PCMA | Audio codec (PCMA or PCMU) |
+| `stt.model` | tiny | Whisper model (tiny/base/small/medium/large) |
+| `stt.language` | en | Transcription language |
+| `greeting` | "Hello!" | Initial greeting message |
+
+## Testing the Installation
+
+### Check Plugin Status
+
+```bash
+openclaw plugins list | grep sip-voice
+```
+
+You should see:
+```
+✓ sip-voice (enabled)
+```
+
+### Make a Test Call
+
+Use any SIP client (desk phone, softphone, or mobile app):
+
+1. Configure SIP client to call: `sip:test@YOUR_IP_ADDRESS:5060`
+2. Make the call
+3. The agent should answer with your greeting message
+4. Have a conversation!
+
+**Example SIP clients:**
+- **Desktop:** MicroSIP, Linphone, Zoiper
+- **Mobile:** Linphone (iOS/Android), Zoiper (iOS/Android)
+- **Web:** JsSIP
+
+### Check Logs
+
+If issues occur, check the OpenClaw logs:
+
+```bash
+# Gateway logs
+openclaw logs
+
+# Plugin-specific logs (if available)
+tail -f ~/.openclaw/logs/sip-voice.log
+```
+
+## Troubleshooting
+
+### "Module not found" or Import Errors
+
+**Problem:** Python dependencies not installed.
+
+**Solution:**
+```bash
+cd ~/.openclaw/extensions/sip-voice/python
+pip install -e .
+```
+
+### "Port 5060 already in use"
+
+**Problem:** Another SIP service is using port 5060.
+
+**Solution:** Change the port in config.json:
+```json
+{
+  "plugins": {
+    "entries": {
+      "sip-voice": {
+        "config": {
+          "sip": {
+            "port": 5061
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### "No audio" or "One-way audio"
+
+**Problem:** Firewall blocking RTP packets.
+
+**Solution:**
+- Open UDP ports 20000-20100 in your firewall
+- If behind NAT, forward these ports to your machine
+- Linux: `sudo ufw allow 20000:20100/udp`
+
+### "Whisper not found"
+
+**Problem:** Whisper CLI not installed.
+
+**Solution:**
+```bash
+# Install Whisper CLI
+pip install openai-whisper
+
+# Verify installation
+which whisper
+```
+
+**Alternative:** Use OpenAI Whisper API instead (requires API key).
+
+### "ffmpeg not found"
+
+**Problem:** ffmpeg not installed.
+
+**Solution:**
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Verify
+ffmpeg -version
+```
+
+## Platform-Specific Notes
+
+### macOS
+- ✅ Fully supported
+- ✅ Native TTS via `say` command available
+- ✅ All features tested
+
+### Linux
+- ✅ Fully supported
+- ⚠️ No native TTS (`say` command) - use cloud TTS (ElevenLabs/OpenAI)
+- ✅ All other features work
+
+### Windows
+- ⚠️ Untested
+- 💡 May require WSL (Windows Subsystem for Linux)
+
+## Advanced Setup
+
+### Using with SIP Trunk Providers
+
+Most SIP trunk providers (Twilio, Voip.ms, etc.) can route calls to your server:
+
+1. Get a phone number from your provider
+2. Configure routing to: `sip:YOUR_PUBLIC_IP:5060`
+3. Ensure port 5060 UDP is open to the internet
+4. Calls to that number will reach your agent!
+
+### Custom TTS Providers
+
+Configure in OpenClaw's main config (not plugin config):
+```json
+{
+  "tools": {
+    "media": {
+      "models": [
+        {
+          "provider": "elevenlabs",
+          "capabilities": ["audio"]
+        }
+      ]
+    }
+  }
+}
+```
+
+### Using Behind NAT/Firewall
+
+If your OpenClaw instance is behind a firewall or NAT:
+
+1. **Port forwarding:** Forward UDP 5060 and 20000-20100
+2. **External IP:** Plugin detects external IP automatically
+3. **Firewall rules:** Allow incoming UDP on those ports
+
+## Next Steps
+
+- 📖 Read the [main README](../README.md) for features and architecture
+- 🐛 Check [known issues](https://github.com/chrishodgkins/openclaw-sip-voice/issues)
+- 🤝 Contribute via [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## Getting Help
+
+- **Issues:** https://github.com/chrishodgkins/openclaw-sip-voice/issues
+- **OpenClaw Docs:** https://docs.openclaw.ai
+- **Discord:** https://discord.com/invite/clawd
+
+---
+
+**Installation complete!** 🎉 Make a test call and talk to your AI agent!

package/README.md

@@ -0,0 +1,76 @@
+# OpenClaw SIP Voice Plugin
+
+Answer SIP/VoIP calls with your OpenClaw AI agent.
+
+**Version:** 0.1.0 (Beta)  
+**Author:** Chris Hodgkins  
+**License:** MIT
+
+## Quick Install
+
+```bash
+# Install the plugin (Python dependencies auto-install on first run)
+openclaw plugins install openclaw-sip-voice
+
+# Restart gateway
+openclaw gateway restart
+```
+
+**That's it!** Python dependencies are automatically installed when the plugin starts for the first time.
+
+See [INSTALL.md](./INSTALL.md) for detailed setup instructions.
+
+## What It Does
+
+- 📞 Answers SIP calls with AI conversations
+- 🎙️ Whisper STT → OpenClaw Agent → TTS pipeline
+- 🔌 Full integration with OpenClaw tools and memory
+- 🐍 Pure Python SIP server (no PJSIP dependency)
+- 🎛️ G.711 PCMA/PCMU codec support
+
+## Requirements
+
+- **OpenClaw** ≥ 2026.0.0
+- **Python** ≥ 3.9
+- **ffmpeg** (audio conversion)
+- **Whisper CLI** (for local STT) OR OpenAI Whisper API
+
+## Configuration
+
+Add to `~/.openclaw/config.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "sip-voice": {
+        "enabled": true,
+        "config": {
+          "sip": {
+            "port": 5060,
+            "codec": "PCMA"
+          },
+          "greeting": "Hello! How can I help you?"
+        }
+      }
+    }
+  }
+}
+```
+
+## Documentation
+
+- Full README: [../README.md](../README.md)
+- Installation: [INSTALL.md](./INSTALL.md)
+- Changelog: [../CHANGELOG.md](../CHANGELOG.md)
+- Contributing: [../CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## Support
+
+- 🐛 [Report Issues](https://github.com/chrishodgkins/openclaw-sip-voice/issues)
+- 📖 [OpenClaw Docs](https://docs.openclaw.ai)
+- 💬 [OpenClaw Discord](https://discord.com/invite/clawd)
+
+## License
+
+MIT - See [../LICENSE](../LICENSE) for details.

package/dist/core-bridge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Core bridge for OpenClaw integration
+ *
+ * Provides access to OpenClaw's core agent functionality via dynamic import
+ * of the extension API.
+ */
+export type CoreConfig = Record<string, unknown>;
+export interface CoreAgentDeps {
+    resolveAgentWorkspaceDir: (cfg: CoreConfig, agentId: string) => string;
+    runEmbeddedPiAgent: (params: {
+        sessionId: string;
+        sessionFile: string;
+        workspaceDir: string;
+        config?: CoreConfig;
+        prompt: string;
+        timeoutMs: number;
+        runId: string;
+        lane?: string;
+        extraSystemPrompt?: string;
+    }) => Promise<{
+        payloads?: Array<{
+            text?: string;
+            isError?: boolean;
+        }>;
+        meta?: {
+            aborted?: boolean;
+        };
+    }>;
+    resolveAgentTimeoutMs: (opts: {
+        cfg: CoreConfig;
+    }) => number;
+    resolveSessionFilePath: (sessionId: string, entry: unknown, opts?: {
+        agentId?: string;
+    }) => string;
+}
+/**
+ * Load core agent dependencies (cached)
+ */
+export declare function loadCoreAgentDeps(): Promise<CoreAgentDeps>;

package/dist/core-bridge.js

@@ -0,0 +1,96 @@
+/**
+ * Core bridge for OpenClaw integration
+ *
+ * Provides access to OpenClaw's core agent functionality via dynamic import
+ * of the extension API.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import os from "node:os";
+let coreDepsPromise = null;
+let cachedOpenClawRoot = null;
+/**
+ * Find the OpenClaw installation root directory
+ */
+function findOpenClawRoot() {
+    // Check environment override first
+    const override = process.env.OPENCLAW_ROOT?.trim();
+    if (override && fs.existsSync(override)) {
+        return override;
+    }
+    // Common installation paths
+    const candidates = [
+        // Running from within OpenClaw
+        path.dirname(process.argv[1] || ""),
+        process.cwd(),
+        // Homebrew (macOS)
+        "/opt/homebrew/lib/node_modules/openclaw",
+        // Global npm
+        "/usr/local/lib/node_modules/openclaw",
+        // User-local npm
+        path.join(os.homedir(), ".npm/lib/node_modules/openclaw"),
+        path.join(os.homedir(), "node_modules/openclaw"),
+        // pnpm global
+        path.join(os.homedir(), ".local/share/pnpm/global/5/node_modules/openclaw"),
+    ];
+    // Walk up from script directory
+    let dir = path.dirname(process.argv[1] || process.cwd());
+    for (let i = 0; i < 10; i++) {
+        candidates.push(dir);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    for (const candidate of candidates) {
+        const pkgPath = path.join(candidate, "package.json");
+        try {
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+                if (pkg.name === "openclaw") {
+                    return candidate;
+                }
+            }
+        }
+        catch {
+            // Ignore errors and try next candidate
+        }
+    }
+    return null;
+}
+/**
+ * Import the OpenClaw extension API dynamically
+ */
+async function importCoreExtensionAPI() {
+    if (!cachedOpenClawRoot) {
+        cachedOpenClawRoot = findOpenClawRoot();
+    }
+    if (!cachedOpenClawRoot) {
+        throw new Error("OpenClaw installation not found. " +
+            "Ensure OpenClaw is installed globally or set OPENCLAW_ROOT environment variable.");
+    }
+    const distPath = path.join(cachedOpenClawRoot, "dist", "extensionAPI.js");
+    if (!fs.existsSync(distPath)) {
+        throw new Error(`Missing OpenClaw extension API at ${distPath}. ` +
+            "Ensure OpenClaw is properly installed.");
+    }
+    // Dynamic import using file URL
+    const api = await import(pathToFileURL(distPath).href);
+    return {
+        resolveAgentWorkspaceDir: api.resolveAgentWorkspaceDir,
+        runEmbeddedPiAgent: api.runEmbeddedPiAgent,
+        resolveAgentTimeoutMs: api.resolveAgentTimeoutMs,
+        resolveSessionFilePath: api.resolveSessionFilePath,
+    };
+}
+/**
+ * Load core agent dependencies (cached)
+ */
+export async function loadCoreAgentDeps() {
+    if (coreDepsPromise) {
+        return coreDepsPromise;
+    }
+    coreDepsPromise = importCoreExtensionAPI();
+    return coreDepsPromise;
+}

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * OpenClaw SIP Voice Plugin
+ *
+ * Answers SIP calls with AI-powered conversations.
+ * Uses a Python SIP server subprocess for telephony,
+ * routing conversations through OpenClaw's agent system.
+ */
+interface SipVoiceConfig {
+    enabled?: boolean;
+    sip?: {
+        port?: number;
+        rtpPortBase?: number;
+        codec?: "PCMA" | "PCMU";
+    };
+    stt?: {
+        model?: string;
+        language?: string;
+    };
+    greeting?: string;
+    pythonPath?: string;
+    sipServerPath?: string;
+}
+interface PluginApi {
+    config: Record<string, unknown>;
+    pluginConfig: unknown;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+        debug: (msg: string) => void;
+    };
+    runtime: {
+        tts: {
+            textToSpeechTelephony: (opts: {
+                text: string;
+                cfg: unknown;
+            }) => Promise<{
+                pcm: Buffer;
+                sampleRate: number;
+            } | null>;
+        };
+    };
+    registerService: (service: {
+        id: string;
+        start: () => void | Promise<void>;
+        stop: () => void | Promise<void>;
+    }) => void;
+    registerGatewayMethod: (method: string, handler: (ctx: {
+        params?: Record<string, unknown>;
+        respond: (success: boolean, data: unknown) => void;
+    }) => void | Promise<void>) => void;
+}
+/**
+ * Plugin definition
+ */
+declare const sipVoicePlugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        parse(value: unknown): SipVoiceConfig;
+    };
+    register(api: PluginApi): void;
+};
+export default sipVoicePlugin;