@vauxr/openclaw 2026.4.1-2.3

package/.github/workflows/publish.yml

@@ -0,0 +1,89 @@
+name: Publish to npm + ClawHub
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+
+jobs:
+  # On push to main: compute version and create a draft release
+  draft-release:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Compute date-based version
+        id: version
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TODAY=$(date -u +"%Y.%m.%d")
+
+          EXISTING=$(gh api repos/${{ github.repository }}/git/refs/tags \
+            --paginate --jq '.[].ref' 2>/dev/null \
+            | grep "^refs/tags/v${TODAY}\." || true)
+
+          if [ -z "$EXISTING" ]; then
+            N=0
+          else
+            MAX_N=$(echo "$EXISTING" | sed "s|refs/tags/v${TODAY}\.||" | sort -n | tail -1)
+            N=$((MAX_N + 1))
+          fi
+
+          VERSION="${TODAY}.${N}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Computed version: $VERSION"
+
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "v${{ steps.version.outputs.version }}" \
+            --title "v${{ steps.version.outputs.version }}" \
+            --draft \
+            --notes "## What's Changed\n\n<!-- Add release notes here before publishing -->"
+
+  # On release published: publish to npm
+  publish:
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: Production
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          VERSION="${VERSION#v}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Update package.json version
+        run: npm version ${{ steps.version.outputs.version }} --no-git-tag-version
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish to ClawHub
+        run: |
+          npm i -g clawhub
+          clawhub login --token ${{ secrets.CLAWHUB_TOKEN }} --no-browser
+          clawhub package publish ${{ github.repository }}@${{ github.event.release.tag_name }} --json

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lillian Mikus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# vauxr-openclaw
+
+An OpenClaw channel plugin that bridges Vauxr voice devices into the OpenClaw agent loop. It connects to [Vauxr](https://github.com/vauxr-ai/vauxr) over WebSocket, dispatches inbound transcripts to the agent, and streams response deltas back for TTS playback.
+
+It also registers three agent tools for direct device control from any session.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## How it works
+
+### Channel Plugin Bridge (recommended)
+
+```
+Vauxr  <──WS (Vauxr protocol)──>  vauxr-openclaw plugin  <──>  OpenClaw agent loop
+```
+
+- The plugin opens an outbound WS connection to Vauxr on startup
+- Inbound transcripts from devices are dispatched into the agent loop as `vauxr:{device_id}` sessions
+- Agent response deltas stream back to Vauxr in real time for TTS playback
+- A `before_prompt_build` hook injects a voice-optimized system prompt for all vauxr sessions
+
+### Fallback: Direct Operator WS
+
+```
+Vauxr  <──WS (OpenClaw protocol)──>  OpenClaw gateway
+```
+
+If installing the plugin is undesirable, Vauxr can connect directly to the OpenClaw gateway as an operator. This still works but is limited:
+
+- No voice system prompt injection
+- No session detection for vauxr-specific behavior
+- No plugin-side control over prompt or session routing
+
+To use fallback mode, configure Vauxr with `OPENCLAW_URL` and `OPENCLAW_TOKEN` environment variables and do not install this plugin.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `vauxr_devices` | Lists all Vauxr devices connected to Vauxr, with their IDs, names, and connection state |
+| `vauxr_announce` | Synthesizes text via Piper TTS and plays it through a device's speaker |
+| `vauxr_control` | Sends a control command to a device (`set_volume`, `mute`, `unmute`, `reboot`) |
+
+These tools use the Vauxr REST API and work in any session, not just vauxr voice sessions.
+
+---
+
+## Requirements
+
+- OpenClaw gateway
+- [Vauxr](https://github.com/vauxr-ai/vauxr) running and reachable
+- At least one paired Vauxr device connected to Vauxr
+
+---
+
+## Installation
+
+Install from the repo directly:
+
+```bash
+openclaw plugins install path:/path/to/vauxr-openclaw
+```
+
+Then configure in your OpenClaw config:
+
+```json
+{
+  "channels": {
+    "vauxr": {
+      "url": "http://vauxr:8765",
+      "token": "your-channel-token",
+      "voiceSystemPrompt": "You are responding to a voice device. Use plain speech only — no emojis, no markdown, no code blocks. Keep replies concise."
+    }
+  },
+  "plugins": {
+    "entries": {
+      "vauxr": {
+        "enabled": true,
+        "hooks": {
+          "allowPromptInjection": true
+        }
+      }
+    }
+  }
+}
+```
+
+- `url` — Vauxr base URL (HTTP)
+- `token` — channel token generated in the Vauxr portal
+- `voiceSystemPrompt` — optional, appended to the system prompt for all vauxr sessions
+
+The `allowPromptInjection` hook permission is required for the voice system prompt to take effect.
+
+---
+
+## Usage
+
+Once installed, the plugin connects to Vauxr automatically. Voice turns from any device are routed through the plugin into the agent loop, and responses stream back for TTS playback.
+
+The agent tools are available in all sessions:
+
+**Announce something:**
+> "Announce through the living room speaker that dinner is ready."
+
+**Device control:**
+> "Mute the bedroom speaker."
+> "Turn the volume up on the kitchen device."
+
+---
+
+## Architecture
+
+```
+Vauxr device (mic)
+    │
+    │  voice.start / audio / voice.end
+    ▼
+Vauxr (STT: Whisper)
+    │
+    │  channel.transcript (WS)
+    ▼
+vauxr-openclaw plugin
+    │
+    │  subagent.run(sessionKey: "vauxr:{device_id}")
+    ▼
+OpenClaw agent loop
+    │
+    │  agent event deltas
+    ▼
+vauxr-openclaw plugin
+    │
+    │  channel.response.delta (WS)
+    ▼
+Vauxr (TTS: Piper)
+    │
+    │  0x02 audio frames
+    ▼
+Vauxr device (speaker)
+```
+
+---
+
+## License
+
+Vauxr OpenClaw is licensed under the [MIT License](LICENSE).

package/index.ts

@@ -0,0 +1,68 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { vauxrPlugin } from "./src/channel.js";
+import { VauxrAPIClient } from "./src/api-client.js";
+import { registerTools } from "./src/tools.js";
+import { VauxrBridge } from "./src/bridge.js";
+import { DEFAULT_VOICE_SYSTEM_PROMPT } from "./src/defaults.js";
+
+interface VauxrConfig {
+  url: string;
+  httpUrl?: string;
+  token?: string;
+  voiceSystemPrompt?: string;
+}
+
+function resolveConfig(api: OpenClawPluginApi): VauxrConfig {
+  if (api.pluginConfig && typeof api.pluginConfig === "object" && "url" in api.pluginConfig) {
+    return api.pluginConfig as unknown as VauxrConfig;
+  }
+  const cfg = api.config as Record<string, unknown>;
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  return (channels?.vauxr ?? {}) as VauxrConfig;
+}
+
+const entry = defineChannelPluginEntry({
+  id: "vauxr",
+  name: "Vauxr",
+  description: "Vauxr voice device channel plugin for OpenClaw",
+  plugin: vauxrPlugin,
+  registerFull(api) {
+    const config = resolveConfig(api);
+
+    // REST tools — use explicit httpUrl if set, otherwise derive from ws url
+    // (vauxr WS is on :8765, HTTP API is on :8080)
+    const httpBase = config.httpUrl ?? (config.url ? config.url.replace(/:8765(\/?$)/, ":8080") : "");
+
+    if (!httpBase) {
+      // config.url not available yet (early registration) — skip bridge/tools
+      return;
+    }
+
+    const client = new VauxrAPIClient(httpBase, config.token ?? "");
+    registerTools(api, client);
+
+    // WS bridge to vauxr — guard against double-registration.
+    // OpenClaw invokes registerFull from multiple subsystems in the same
+    // process; without this flag, both bridges would contend for the
+    // single active channel slot in vauxr and flap continuously.
+    const g = globalThis as { __vauxrBridgeStarted?: boolean };
+    if (!g.__vauxrBridgeStarted) {
+      g.__vauxrBridgeStarted = true;
+      const bridge = new VauxrBridge(api, config);
+      bridge.start();
+    }
+
+    // Voice system prompt injection for vauxr sessions
+    api.on("before_prompt_build", (_event, ctx) => {
+      if (ctx.sessionKey?.startsWith("vauxr:")) {
+        return {
+          appendSystemContext: config.voiceSystemPrompt ?? DEFAULT_VOICE_SYSTEM_PROMPT,
+        };
+      }
+      return undefined;
+    });
+  },
+});
+
+export default entry;

package/openclaw.plugin.json

@@ -0,0 +1,57 @@
+{
+  "id": "vauxr",
+  "kind": "channel",
+  "channels": ["vauxr"],
+  "name": "Vauxr",
+  "description": "Vauxr voice device channel plugin for OpenClaw",
+  "channelConfigs": {
+    "vauxr": {
+      "label": "Vauxr",
+      "description": "Vauxr voice device channel",
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["url", "token"],
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Vauxr base URL (e.g. http://192.168.1.100:8765)"
+          },
+          "token": {
+            "type": "string",
+            "description": "Channel token issued by Vauxr"
+          },
+          "voiceSystemPrompt": {
+            "type": "string",
+            "description": "System prompt appended to vauxr voice sessions"
+          }
+        }
+      }
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "vauxr": {
+        "type": "object",
+        "required": ["url"],
+        "additionalProperties": false,
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Vauxr base URL (e.g. http://vauxr:8765)"
+          },
+          "token": {
+            "type": "string",
+            "description": "Operator token for Vauxr API auth"
+          },
+          "voiceSystemPrompt": {
+            "type": "string",
+            "description": "Text appended to the system prompt for all vauxr sessions. Defaults to a voice-optimized instruction set."
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@vauxr/openclaw",
+  "version": "2026.4.1-2.3",
+  "type": "module",
+  "main": "./index.ts",
+  "openclaw": {
+    "extensions": [
+      "./index.ts",
+      "./setup-entry.ts"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.2",
+      "minGatewayVersion": "2026.4.2"
+    },
+    "build": {
+      "openclawVersion": "2026.4.2",
+      "pluginSdkVersion": "2026.4.2"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.32.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "openclaw": "^2026.4.2",
+    "typescript": "^5.0.0"
+  }
+}

package/setup-entry.ts

@@ -0,0 +1,4 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
+import { vauxrPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(vauxrPlugin);

package/src/api-client.ts

@@ -0,0 +1,76 @@
+export interface Device {
+  id: string;
+  name: string;
+  state: "idle" | "listening" | "processing" | "speaking" | "offline";
+  lastSeen: string;
+}
+
+export class VauxrAPIClient {
+  constructor(
+    private baseUrl: string,
+    private token: string,
+  ) {}
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.token}`,
+      "Content-Type": "application/json",
+    };
+
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    if (!res.ok) {
+      let message = `HTTP ${res.status}`;
+      try {
+        const errorBody = (await res.json()) as Record<string, unknown>;
+        const detail = errorBody.error ?? errorBody.message;
+        if (typeof detail === "string") {
+          message = detail;
+        }
+      } catch {
+        // response body wasn't JSON — keep generic message
+      }
+
+      if (res.status === 401) {
+        throw new Error(`Unauthorized: ${message}`);
+      }
+      if (res.status === 404) {
+        throw new Error(`Device not found: ${message}`);
+      }
+      if (res.status === 409) {
+        throw new Error(`Device busy: ${message}`);
+      }
+      throw new Error(message);
+    }
+
+    const text = await res.text();
+    if (!text) return undefined as T;
+    return JSON.parse(text) as T;
+  }
+
+  async listDevices(): Promise<Device[]> {
+    return this.request<Device[]>("GET", "/api/devices");
+  }
+
+  async announce(deviceId: string, text: string): Promise<void> {
+    await this.request<void>("POST", `/api/devices/${encodeURIComponent(deviceId)}/announce`, {
+      text,
+    });
+  }
+
+  async command(
+    deviceId: string,
+    command: string,
+    params?: Record<string, unknown>,
+  ): Promise<void> {
+    await this.request<void>("POST", `/api/devices/${encodeURIComponent(deviceId)}/command`, {
+      command,
+      params,
+    });
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,237 @@
+import WebSocket from "ws";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+
+/** Vauxr protocol frames sent by vauxr to the channel plugin */
+interface VauxrInboundFrame {
+  type: "channel.transcript" | "channel.device_state" | "channel.ready" | "error";
+  deviceId?: string;
+  text?: string;
+  state?: string;
+  name?: string;
+  code?: string;
+  message?: string;
+}
+
+/** Vauxr protocol frames sent by the channel plugin to vauxr */
+type VauxrOutboundFrame =
+  | { type: "channel.auth"; token: string }
+  | { type: "channel.response.delta"; deviceId: string; runId: string; text: string }
+  | { type: "channel.response.end"; deviceId: string; runId: string }
+  | { type: "channel.response.error"; deviceId: string; runId: string; message: string };
+
+interface VauxrBridgeConfig {
+  url: string;
+  token?: string;
+  voiceSystemPrompt?: string;
+}
+
+const INITIAL_RECONNECT_MS = 1000;
+const MAX_RECONNECT_MS = 30000;
+
+export class VauxrBridge {
+  private ws: WebSocket | null = null;
+  private reconnectMs = INITIAL_RECONNECT_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private unsubscribeEvents: (() => void) | null = null;
+  private activeRuns = new Map<string, string>(); // SDK runId → deviceId
+  private runIdMap = new Map<string, string>(); // SDK runId → protocol runId
+  private wsUrl: string;
+
+  constructor(
+    private api: OpenClawPluginApi,
+    private config: VauxrBridgeConfig,
+  ) {
+    // Derive WS URL from HTTP base URL
+    const base = config.url.replace(/\/$/, "");
+    this.wsUrl = base.replace(/^http/, "ws") + "/channel";
+  }
+
+  start(): void {
+    this.connect();
+    this.subscribeAgentEvents();
+  }
+
+  stop(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.unsubscribeEvents) {
+      this.unsubscribeEvents();
+      this.unsubscribeEvents = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  private connect(): void {
+    this.api.logger.info(`[vauxr-bridge] Connecting to vauxr: ${this.wsUrl}`);
+
+    const ws = new WebSocket(this.wsUrl);
+    this.ws = ws;
+
+    ws.on("open", () => {
+      this.api.logger.info("[vauxr-bridge] Connected to vauxr");
+      this.reconnectMs = INITIAL_RECONNECT_MS;
+
+      // Authenticate with channel token
+      if (this.config.token) {
+        this.send({ type: "channel.auth", token: this.config.token });
+      }
+    });
+
+    ws.on("message", (data) => {
+      try {
+        const frame = JSON.parse(String(data)) as VauxrInboundFrame;
+        this.handleFrame(frame);
+      } catch (err) {
+        this.api.logger.warn(`[vauxr-bridge] Failed to parse inbound frame: ${String(err)}`);
+      }
+    });
+
+    ws.on("close", () => {
+      this.api.logger.info("[vauxr-bridge] Disconnected from vauxr");
+      this.ws = null;
+      this.scheduleReconnect();
+    });
+
+    ws.on("error", (err) => {
+      this.api.logger.warn(`[vauxr-bridge] WS error: ${String(err)}`);
+      // 'close' event will fire after this — reconnect handled there
+    });
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+    this.api.logger.info(
+      `[vauxr-bridge] Reconnecting in ${this.reconnectMs}ms`,
+    );
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, this.reconnectMs);
+    this.reconnectMs = Math.min(this.reconnectMs * 2, MAX_RECONNECT_MS);
+  }
+
+  private handleFrame(frame: VauxrInboundFrame): void {
+    switch (frame.type) {
+      case "channel.transcript":
+        if (frame.deviceId && frame.text) {
+          void this.dispatchTranscript(frame.deviceId, frame.text);
+        }
+        break;
+      case "channel.device_state":
+        this.api.logger.info(
+          `[vauxr-bridge] Device ${frame.deviceId ?? "unknown"}: ${frame.state ?? "unknown"}`,
+        );
+        break;
+      case "channel.ready":
+        this.api.logger.info("[vauxr-bridge] Channel authenticated");
+        break;
+      case "error":
+        this.api.logger.warn(
+          `[vauxr-bridge] Error from vauxr: ${frame.code ?? "UNKNOWN"} — ${frame.message ?? "no details"}`,
+        );
+        break;
+      default:
+        this.api.logger.warn(
+          `[vauxr-bridge] Unknown frame type: ${String((frame as unknown as Record<string, unknown>).type)}`,
+        );
+    }
+  }
+
+  private async dispatchTranscript(deviceId: string, text: string): Promise<void> {
+    const sessionKey = `vauxr:${deviceId}`;
+    // Generate a protocol-level runId (sent to vauxr in response frames)
+    const protocolRunId = crypto.randomUUID();
+    this.api.logger.info(
+      `[vauxr-bridge] Dispatching transcript for ${sessionKey} (runId=${protocolRunId}): "${text}"`,
+    );
+
+    try {
+      const result = await this.api.runtime.subagent.run({
+        sessionKey,
+        message: text,
+        idempotencyKey: protocolRunId,
+        // Inject voice-formatting instructions so the model doesn't emit
+        // markdown, emojis, or lists — responses are spoken aloud by TTS.
+        // Uses the SDK's extraSystemPrompt field; omitted when not configured.
+        ...(this.config.voiceSystemPrompt
+          ? { extraSystemPrompt: this.config.voiceSystemPrompt }
+          : {}),
+      });
+      this.activeRuns.set(result.runId, deviceId);
+      this.runIdMap.set(result.runId, protocolRunId);
+    } catch (err) {
+      this.api.logger.warn(
+        `[vauxr-bridge] Failed to dispatch transcript for ${sessionKey}: ${String(err)}`,
+      );
+      this.send({
+        type: "channel.response.error",
+        deviceId,
+        runId: protocolRunId,
+        message: String(err),
+      });
+    }
+  }
+
+  private subscribeAgentEvents(): void {
+    this.unsubscribeEvents = this.api.runtime.events.onAgentEvent((event) => {
+      const deviceId = this.activeRuns.get(event.runId);
+      if (!deviceId) return; // Not a vauxr run
+
+      const runId = this.runIdMap.get(event.runId) ?? event.runId;
+
+      if (event.stream === "assistant") {
+        // data.delta is the incremental chunk for streaming sessions;
+        // data.text is the accumulated text (or full text for single-shot).
+        // Prefer delta when present, fall back to text.
+        const chunk =
+          (typeof event.data["delta"] === "string" && event.data["delta"]) ||
+          (typeof event.data["text"] === "string" && event.data["text"]) ||
+          null;
+        if (chunk) {
+          this.send({
+            type: "channel.response.delta",
+            deviceId,
+            runId,
+            text: chunk,
+          });
+        }
+      }
+
+      // Clean up when run ends
+      if (event.stream === "lifecycle" && event.data["phase"] === "end") {
+        this.send({
+          type: "channel.response.end",
+          deviceId,
+          runId,
+        });
+        this.activeRuns.delete(event.runId);
+        this.runIdMap.delete(event.runId);
+      }
+
+      if (event.stream === "error") {
+        this.api.logger.warn(
+          `[vauxr-bridge] Agent error for device ${deviceId}: ${JSON.stringify(event.data)}`,
+        );
+        this.send({
+          type: "channel.response.error",
+          deviceId,
+          runId,
+          message: String(event.data["message"] ?? "Agent error"),
+        });
+        this.activeRuns.delete(event.runId);
+        this.runIdMap.delete(event.runId);
+      }
+    });
+  }
+
+  private send(frame: VauxrOutboundFrame): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(frame));
+    }
+  }
+}

package/src/channel.ts

@@ -0,0 +1,107 @@
+import { createChatChannelPlugin, createChannelPluginBase } from "openclaw/plugin-sdk/core";
+import { DEFAULT_VOICE_SYSTEM_PROMPT } from "./defaults.js";
+import { createTopLevelChannelConfigBase } from "openclaw/plugin-sdk/channel-config-helpers";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+
+export interface VauxrAccount {
+  accountId?: string | null;
+}
+
+// Type assertion needed: createChannelPluginBase marks capabilities as Partial
+// in its return type, but createChatChannelPlugin requires it non-optional.
+// We always provide capabilities, so the assertion is safe.
+export const vauxrPlugin = createChatChannelPlugin<VauxrAccount>({
+  base: createChannelPluginBase<VauxrAccount>({
+    id: "vauxr",
+    meta: { label: "Vauxr" },
+    capabilities: {
+      chatTypes: ["direct"],
+    },
+    config: createTopLevelChannelConfigBase<VauxrAccount>({
+      sectionKey: "vauxr",
+      resolveAccount: (cfg) => {
+        const section = resolveSection(cfg);
+        const url = section?.url;
+        return {
+          accountId: url ?? "default",
+          // running/connected drive UI status indicators
+          ...(url ? { running: true, connected: true } : {}),
+        };
+      },
+      // Single-account channel — listAccountIds returns either the single
+      // resolved id or an empty array if the channel isn't configured.
+      listAccountIds: (cfg) => {
+        const section = resolveSection(cfg);
+        return section?.url ? [section.url] : [];
+      },
+      defaultAccountId: (cfg) => resolveSection(cfg)?.url ?? "default",
+    }),
+    setup: {
+      resolveAccountId({ cfg }) {
+        const section = resolveSection(cfg);
+        return section?.url ?? "default";
+      },
+      applyAccountConfig({ cfg, input }) {
+        const updated = structuredClone(cfg) as Record<string, unknown>;
+        const channels = (updated.channels ?? {}) as Record<string, unknown>;
+        channels.vauxr = {
+          // Seed default voice system prompt so it's populated on first install.
+          // Existing value (if any) takes precedence via spread order.
+          voiceSystemPrompt: DEFAULT_VOICE_SYSTEM_PROMPT,
+          ...((channels.vauxr ?? {}) as Record<string, unknown>),
+          ...(input as Record<string, unknown>),
+        };
+        updated.channels = channels;
+        return updated as OpenClawConfig;
+      },
+    },
+  }) as Parameters<typeof createChatChannelPlugin<VauxrAccount>>[0]["base"],
+  // No security/pairing — vauxr devices are trusted local hardware
+  outbound: {
+    // Outbound responses are delivered via the WS bridge, not the outbound adapter
+    // This stub satisfies the ChannelPlugin interface
+    base: {
+      deliveryMode: "direct",
+    },
+    attachedResults: {
+      channel: "vauxr",
+      sendText: async () => ({ messageId: "bridge" }),
+    },
+  },
+});
+
+// gateway.startAccount is required for OpenClaw to mark this channel as
+// "running" and "configured" in the UI. The actual bridge lifecycle is
+// managed by registerFull in index.ts (which has access to the full plugin
+// API). This stub holds the channel in running state until the gateway stops.
+// isConfigured: tells OpenClaw the channel is configured when url is set.
+vauxrPlugin.config.isConfigured = (_account: unknown, cfg: OpenClawConfig) => {
+  return Boolean(resolveSection(cfg)?.url);
+};
+
+vauxrPlugin.gateway = {
+  startAccount: async (ctx: { abortSignal: AbortSignal }) => {
+    await new Promise<void>((resolve) => {
+      ctx.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    });
+  },
+};
+
+interface VauxrSection {
+  url?: string;
+  token?: string;
+  voiceSystemPrompt?: string;
+}
+
+function resolveSection(cfg: OpenClawConfig): VauxrSection | undefined {
+  const raw = cfg as Record<string, unknown>;
+  const channelsCfg = (raw.channels as Record<string, unknown> | undefined)?.vauxr as
+    | VauxrSection
+    | undefined;
+  const pluginsCfg = (
+    (raw.plugins as Record<string, unknown> | undefined)?.entries as
+      | Record<string, unknown>
+      | undefined
+  )?.vauxr as { config?: VauxrSection } | undefined;
+  return channelsCfg ?? pluginsCfg?.config;
+}

package/src/defaults.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_VOICE_SYSTEM_PROMPT =
+  "You are responding to a voice device. Use plain speech only — no emojis, no markdown, no code blocks. Keep replies concise.";

package/src/tools.ts

@@ -0,0 +1,102 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { VauxrAPIClient, Device } from "./api-client.js";
+
+function formatDeviceList(devices: Device[]): string {
+  if (devices.length === 0) return "No devices connected.";
+  return devices
+    .map((d) => `• ${d.name} (id: ${d.id}) — ${d.state}, last seen ${d.lastSeen}`)
+    .join("\n");
+}
+
+export function registerTools(api: OpenClawPluginApi, client: VauxrAPIClient): void {
+  api.registerTool(
+    {
+      name: "vauxr_devices",
+      label: "Vauxr Devices",
+      description:
+        "List Vauxr voice devices currently connected to Vauxr, with their IDs, names, and connection state. Call this first if you don't know which device to target.",
+      parameters: Type.Object({}),
+      async execute() {
+        const devices = await client.listDevices();
+        return {
+          content: [{ type: "text" as const, text: formatDeviceList(devices) }],
+          details: { devices },
+        };
+      },
+    },
+    { optional: false },
+  );
+
+  api.registerTool(
+    {
+      name: "vauxr_announce",
+      label: "Vauxr Announce",
+      description:
+        "Announce a spoken message through a Vauxr voice device. The text will be synthesized to speech and played through the device's speaker. Use `vauxr_devices` first if you don't know the device ID.",
+      parameters: Type.Object({
+        device_id: Type.String({ description: "ID of the device to speak through" }),
+        text: Type.String({
+          description:
+            "Text to speak aloud — keep it concise, plain sentences only, no markdown or emojis",
+        }),
+      }),
+      async execute(_id, params) {
+        await client.announce(params.device_id, params.text);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Announced on device ${params.device_id}: "${params.text}"`,
+            },
+          ],
+          details: {},
+        };
+      },
+    },
+    { optional: false },
+  );
+
+  api.registerTool(
+    {
+      name: "vauxr_control",
+      label: "Vauxr Control",
+      description:
+        "Send a control command to a Vauxr voice device (set volume, mute, unmute, or reboot).",
+      parameters: Type.Object({
+        device_id: Type.String({ description: "ID of the device to control" }),
+        command: Type.Union(
+          [
+            Type.Literal("set_volume"),
+            Type.Literal("mute"),
+            Type.Literal("unmute"),
+            Type.Literal("reboot"),
+          ],
+          { description: "The control command to send" },
+        ),
+        volume: Type.Optional(
+          Type.Number({
+            description: "Volume level 0–100, required when command is set_volume",
+            minimum: 0,
+            maximum: 100,
+          }),
+        ),
+      }),
+      async execute(_id, params) {
+        const cmdParams: Record<string, unknown> | undefined =
+          params.command === "set_volume" ? { volume: params.volume } : undefined;
+        await client.command(params.device_id, params.command, cmdParams);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Sent ${params.command} to device ${params.device_id}${params.command === "set_volume" ? ` (volume: ${params.volume})` : ""}`,
+            },
+          ],
+          details: {},
+        };
+      },
+    },
+    { optional: false },
+  );
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": false
+  },
+  "include": ["index.ts", "setup-entry.ts", "src/**/*.ts"]
+}