@sdamarketing/qwen-tts-client 1.0.0

package/.env.example

@@ -0,0 +1,17 @@
+CENTRAL_TTS_BASE_URL=https://qwen-tts-118.tailf26c2b.ts.net
+CENTRAL_TTS_API_KEY=change_me_same_value_as_server_tts_api_key
+SMOKE_TEXT=Проверка подключения Qwen TTS Client к удаленному серверу.
+CENTRAL_TTS_TARGET=voice-note
+CENTRAL_TTS_TIMEOUT_SEC=120
+CENTRAL_TTS_RETRIES=2
+CENTRAL_TTS_RETRY_BACKOFF_MS=350
+# When the server returns WAV/MP3/etc. but OpenClaw expects *.opus, runtime transcodes via ffmpeg:
+CENTRAL_TTS_FFMPEG_TIMEOUT_SEC=120
+# Set to 1 only if CENTRAL_TTS_BASE_URL must be reached via HTTP_PROXY/HTTPS_PROXY (default: direct, no proxy).
+CENTRAL_TTS_USE_SYSTEM_PROXY=
+
+# Optional OpenClaw 2026.4.25+ hints
+CENTRAL_TTS_VOICE=
+CENTRAL_TTS_MODEL=
+CENTRAL_TTS_PERSONA=
+CENTRAL_TTS_SESSION_HINTS_JSON=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sdamarketing
+
+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,100 @@
+# Qwen TTS Client
+
+Production-клиент для OpenClaw `tts-local-cli`, который проксирует синтез на удаленный `Qwen TTS Server`.
+
+Базовый путь:
+
+- `OpenClaw (tts-local-cli)`
+- `qwen_tts_proxy_opus.sh` (тонкий launcher)
+- `qwen_tts_runtime.py` (валидация/retry/diagnostics)
+- `Qwen TTS Server /tts`
+- возврат `OGG/Opus` или `WAV` (по настройке сервера)
+
+## Что делает проект
+
+- интерактивно запрашивает endpoint и API key удаленного TTS;
+- генерирует `~/.openclaw/qwen_tts_client.env` с retry/timeout/hints настройками;
+- настраивает `~/.openclaw/openclaw.json` под `tts-local-cli` без удаления других providers;
+- мигрирует legacy-ключи (`audioAsVoice`, `textLimit`) в `maxTextLength`;
+- выполняет smoke-test и проверяет выходной аудиофайл.
+
+## Быстрый запуск
+
+### Установка из npm (npmjs.com)
+
+После `npm run publish:all` пакет доступен на обоих реестрах. С npmjs.com ставится **без** `.npmrc`:
+
+```bash
+npm install -g @sdamarketing/qwen-tts-client
+qwen-tts-install
+```
+
+### Установка из GitHub Packages
+
+Скопируй `.npmrc.github.example` в `~/.npmrc` и задай `GITHUB_TOKEN` (`read:packages`), либо:
+
+```bash
+npm install -g @sdamarketing/qwen-tts-client --registry=https://npm.pkg.github.com
+```
+
+### Публикация в оба реестра (maintainers)
+
+Один tarball, два реестра (имя и версия совпадают):
+
+```bash
+# npmjs.com — нужен OTP или NPM_TOKEN с publish
+npm run publish:npm
+
+# GitHub Packages — GITHUB_TOKEN с write:packages
+export NODE_AUTH_TOKEN="$GITHUB_TOKEN"
+npm run publish:github
+
+# или оба подряд
+npm run publish:all
+```
+
+На npmjs.com для scoped-пакета обязателен `--access public` (уже в скрипте `publish:npm`).
+
+CI: при Release workflow `.github/workflows/publish.yml` публикует в npmjs и GitHub Packages **параллельно**.
+
+**npmjs.com:** Trusted Publisher на пакете (workflow `publish.yml`, OIDC) — секрет `NPM_TOKEN` не нужен. Ошибки `403`/`EOTP` — см. [docs/02-npm-ci-token.md](docs/02-npm-ci-token.md).
+
+Прокси для ручного smoke-test:
+
+```bash
+qwen-tts-proxy "Проверка TTS" /tmp/qwen-tts-smoke.ogg
+```
+
+### Установка из git
+
+```bash
+git clone https://github.com/sdamarketing/qwen-tts-client.git
+cd qwen-tts-client
+chmod +x ./scripts/install_qwen_tts_client.sh
+./scripts/install_qwen_tts_client.sh
+```
+
+После установки проверь в чате OpenClaw:
+
+- `/tts status`
+- `/tts latest`
+- `/tts chat on`
+- `/tts persona off`
+
+## Новые возможности OpenClaw 2026.4.25+
+
+Клиент совместим с расширенным TTS workflow:
+
+- chat-level override: `/tts chat on|off|default`;
+- ручная озвучка последнего ответа: `/tts latest`;
+- persona override: `/tts persona <id>|off`;
+- per-agent/per-channel overlays через OpenClaw-конфиг (`agents.list[].tts`, `channels.<channel>.accounts.<id>.tts`).
+
+## Структура
+
+- `scripts/install_qwen_tts_client.sh` — интерактивный установщик;
+- `scripts/qwen_tts_proxy_opus.sh` — shell launcher для Local CLI;
+- `scripts/qwen_tts_runtime.py` — runtime транспорт в удаленный `/tts`;
+- `deploy/openclaw/profiles/remote-api` — готовый профиль OpenClaw для remote TTS;
+- `.env.example` — шаблон клиентских переменных;
+- `docs/` — production runbook клиента.

package/deploy/openclaw/profiles/README.md

@@ -0,0 +1,17 @@
+# OpenClaw Profile (Remote API)
+
+Этот проект использует один production-профиль клиента:
+
+- `remote-api` — OpenClaw не запускает локальный TTS и получает финальный `OGG/Opus` от удаленного сервера.
+
+## Файлы
+
+- `remote-api/openclaw.tts.json5` — фрагмент для `messages.tts`;
+- `remote-api/openclaw-node.env.example` — пример переменных окружения gateway.
+
+## Принцип
+
+- `tts-local-cli` активируется как primary provider;
+- `qwen_tts_proxy_opus.sh` запускает `qwen_tts_runtime.py`;
+- runtime делает HTTPS вызов в удаленный `/tts` и поддерживает retry/timeout/diagnostics;
+- локальная генерация отсутствует, локальная конверсия не выполняется.

package/deploy/openclaw/profiles/remote-api/openclaw-node.env.example

@@ -0,0 +1,22 @@
+# OpenClaw gateway runtime
+OPENCLAW_GATEWAY_PORT=18789
+OPENCLAW_DISABLE_BONJOUR=1
+OPENCLAW_NO_RESPAWN=1
+NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
+NODE_OPTIONS=--dns-result-order=ipv4first
+
+# Remote Qwen TTS endpoint
+CENTRAL_TTS_BASE_URL=https://qwen-tts-118.tailf26c2b.ts.net
+CENTRAL_TTS_API_KEY=change_me_same_value_as_server_tts_api_key
+CENTRAL_TTS_TARGET=voice-note
+CENTRAL_TTS_TIMEOUT_SEC=120
+CENTRAL_TTS_RETRIES=2
+CENTRAL_TTS_RETRY_BACKOFF_MS=350
+CENTRAL_TTS_FFMPEG_TIMEOUT_SEC=120
+CENTRAL_TTS_USE_SYSTEM_PROXY=
+
+# Optional OpenClaw 2026.4.25+ hints
+CENTRAL_TTS_VOICE=
+CENTRAL_TTS_MODEL=
+CENTRAL_TTS_PERSONA=
+CENTRAL_TTS_SESSION_HINTS_JSON=

package/deploy/openclaw/profiles/remote-api/openclaw.tts.json5

@@ -0,0 +1,25 @@
+{
+  // Merge this fragment into ~/.openclaw/openclaw.json
+  messages: {
+    tts: {
+      enabled: true,
+      provider: "tts-local-cli",
+      auto: "off",
+      persona: "",
+      personas: {},
+      maxTextLength: 1500,
+      providers: {
+        "tts-local-cli": {
+          enabled: true,
+          command: "/home/alekhm/.openclaw/bin/qwen_tts_proxy_opus.sh",
+          args: ["{{Text}}", "{{OutputPath}}"],
+          outputFormat: "opus",
+          timeoutMs: 120000,
+          env: {
+            QWEN_TTS_RUNTIME_SCRIPT: "/home/alekhm/.openclaw/bin/qwen_tts_runtime.py"
+          }
+        }
+      }
+    }
+  }
+}

package/docs/01-production-setup.md

@@ -0,0 +1,65 @@
+# 01. Production Setup
+
+## Цель
+
+Подключить OpenClaw-клиент к удаленному `Qwen TTS Server` через `tts-local-cli`, без локальной генерации.
+
+## Предпосылки
+
+- установлен и хотя бы один раз запущен OpenClaw (должен существовать `~/.openclaw/openclaw.json`);
+- есть рабочий endpoint сервера `/tts`;
+- есть API key сервера.
+
+## Установка
+
+```bash
+cd products/qwen-tts-client
+chmod +x ./scripts/install_qwen_tts_client.sh
+./scripts/install_qwen_tts_client.sh
+```
+
+Скрипт:
+
+- создаёт `~/.openclaw/qwen_tts_client.env`;
+- устанавливает `qwen_tts_proxy_opus.sh` и `qwen_tts_runtime.py` в `~/.openclaw/bin`;
+- патчит `~/.openclaw/openclaw.json` на `tts-local-cli` без удаления остальных providers;
+- чистит legacy-ключи `audioAsVoice` / `textLimit`;
+- выполняет smoke-test.
+
+## Проверка в OpenClaw
+
+- `/tts status`
+- `/tts latest`
+- `/tts chat on`
+- `/tts persona off`
+- отправить тестовое сообщение для озвучки
+
+Если после обновления OpenClaw видишь ошибку `Unrecognized keys: "audioAsVoice", "textLimit"`, значит остались старые ключи в `messages.tts`. Удалить их и оставить `maxTextLength`.
+
+Если `/tts status` показывает лимит 1500, а синтез падает с **`max 600`**, в `~/.openclaw/openclaw.json` в `messages.tts` всё ещё стоит `maxTextLength: 600`. Поставь **не меньше 1500** (или перезапусти актуальный `install_qwen_tts_client.sh` — он поднимет лимит минимум до 1500, не урезая более высокий, если ты его задавал).
+
+## Ручной профиль (без установщика)
+
+Если нужно применить настройки вручную:
+
+- взять фрагмент `deploy/openclaw/profiles/remote-api/openclaw.tts.json5`;
+- использовать пример env `deploy/openclaw/profiles/remote-api/openclaw-node.env.example`.
+
+## Архитектура
+
+`OpenClaw` -> `tts-local-cli` -> `qwen_tts_proxy_opus.sh` -> `qwen_tts_runtime.py` -> `https://<server>/tts` -> `OGG/Opus | WAV`
+
+OpenClaw для `outputFormat: opus` передаёт путь вида `…/speech.opus` и **считает формат по расширению**: если записать туда WAV, озвучка падает с `provider_error`. `qwen_tts_runtime.py` проверяет сигнатуру `OpusHead` в Ogg и при необходимости **транскодирует в Opus через `ffmpeg`**. На gateway/host должен быть доступен `ffmpeg`, если сервер отдаёт не Opus-in-Ogg.
+
+Если `tts-local-cli` стабильно падает с `provider_error`, а с ноутбука `curl` до `/tts` работает: у процесса gateway часто заданы `HTTP_PROXY`/`HTTPS_PROXY`. Рантайм по умолчанию **не** использует системный прокси для `CENTRAL_TTS_BASE_URL` (Tailscale и приватные URL так не ломаются). Если TTS доступен **только** через прокси — выставь `CENTRAL_TTS_USE_SYSTEM_PROXY=1` в `qwen_tts_client.env`.
+
+Если в логах видно **`503` / `no tunnel here`** на URL вида `*.lhr.life` / `trycloudflare.com` — временный туннель к машине с TTS **умер**; подними туннель заново или переключи `CENTRAL_TTS_BASE_URL` на постоянный хост (например Tailscale `*.ts.net`), затем перезапусти gateway.
+
+## Расширенный payload `/tts`
+
+`qwen_tts_runtime.py` отправляет backward-compatible тело:
+
+- обязательно: `text`
+- опционально: `voice`, `model`, `persona`, `target`, `requestId`, `sessionHints`
+
+Старый контракт (только `text`) продолжает работать.

package/docs/02-npm-ci-token.md

@@ -0,0 +1,59 @@
+# Публикация на npmjs.com из GitHub Actions
+
+## Ошибки в CI
+
+| Код | Причина |
+|-----|---------|
+| `403` + bypass 2fa | `NPM_TOKEN` — не Automation / без bypass 2FA |
+| `EOTP` | В workflow передан `NPM_TOKEN` типа **Publish** — npm требует OTP, в CI его нет |
+
+**Рекомендуемый способ:** [npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers) (OIDC). Секрет `NPM_TOKEN` для publish **не нужен**.
+
+## Trusted Publisher (рекомендуется)
+
+Один раз на npmjs.com (под аккаунтом с правом publish `@sdamarketing/*`):
+
+1. Открой настройки пакета `@sdamarketing/qwen-tts-client` → **Publishing access** → **Trusted publishing**  
+   (или org: https://www.npmjs.com/settings/sdamarketing/packages)
+2. **Add GitHub Actions trusted publisher**
+   - Repository: `sdamarketing/qwen-tts-client`
+   - Workflow filename: `publish.yml`
+   - Environment: пусто (если не используете GitHub Environment)
+3. В GitHub **удали секрет `NPM_TOKEN`** (если есть) — иначе старый токен может мешать.
+4. Re-run workflow **Publish package**.
+
+Workflow уже настроен: `id-token: write`, `npm publish --provenance`, **без** `NODE_AUTH_TOKEN`.
+
+Первый publish scoped-пакета иногда делают локально один раз:
+
+```bash
+npm run publish:npm -- --otp=123456
+```
+
+После появления пакета на npmjs — дальнейшие версии через CI + Trusted Publisher.
+
+## Запасной вариант: NPM_TOKEN
+
+Если Trusted Publisher не используете:
+
+1. [Access Tokens](https://www.npmjs.com/settings/~/tokens) → Classic **Automation** (не Publish)  
+   или Granular с **Bypass two-factor authentication for automation**
+2. Секрет `NPM_TOKEN` в GitHub Actions
+3. В workflow **временно** вернуть:
+
+```yaml
+env:
+  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Не смешивайте Trusted Publisher и Publish-токен в одном job — будет `EOTP` или `403`.
+
+## После смены версии
+
+Если версия уже на registry — подними `version` в `package.json` перед повторным publish.
+
+## Локально с 2FA
+
+```bash
+npm run publish:npm -- --otp=123456
+```

package/docs/README.md

@@ -0,0 +1,11 @@
+# Qwen TTS Client Docs
+
+Документация по отдельному production-проекту `Qwen TTS Client`.
+
+- [01. Production Setup](01-production-setup.md)
+
+Клиент ориентирован на OpenClaw `2026.4.25+` и учитывает:
+
+- `messages.tts.providers` как основную схему;
+- новые команды `/tts latest`, `/tts chat`, `/tts persona`;
+- compatibility с per-agent/per-channel overrides без агрессивной зачистки `openclaw.json`.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sdamarketing/qwen-tts-client",
+  "version": "1.0.0",
+  "description": "OpenClaw tts-local-cli client for remote Qwen TTS Server (OGG/Opus proxy)",
+  "keywords": [
+    "openclaw",
+    "tts",
+    "qwen",
+    "opus",
+    "voice"
+  ],
+  "homepage": "https://github.com/sdamarketing/qwen-tts-client#readme",
+  "bugs": {
+    "url": "https://github.com/sdamarketing/qwen-tts-client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sdamarketing/qwen-tts-client.git"
+  },
+  "license": "MIT",
+  "author": "sdamarketing",
+  "type": "commonjs",
+  "files": [
+    "scripts/",
+    "deploy/",
+    "docs/",
+    ".env.example",
+    "README.md"
+  ],
+  "bin": {
+    "qwen-tts-proxy": "scripts/qwen_tts_proxy_opus.sh",
+    "qwen-tts-install": "scripts/install_qwen_tts_client.sh"
+  },
+  "scripts": {
+    "prepack": "chmod +x scripts/qwen_tts_proxy_opus.sh scripts/install_qwen_tts_client.sh",
+    "prepublishOnly": "npm run pack:check",
+    "pack:check": "npm pack --dry-run",
+    "publish:npm": "npm publish --access public --registry https://registry.npmjs.org",
+    "publish:github": "npm publish --registry https://npm.pkg.github.com",
+    "publish:all": "npm run publish:npm && npm run publish:github"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install_qwen_tts_client.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OPENCLAW_HOME="${OPENCLAW_HOME:-$HOME/.openclaw}"
+CLIENT_ENV_PATH="${OPENCLAW_HOME}/qwen_tts_client.env"
+PROXY_SCRIPT_SOURCE="${ROOT_DIR}/scripts/qwen_tts_proxy_opus.sh"
+PROXY_SCRIPT_TARGET="${OPENCLAW_HOME}/bin/qwen_tts_proxy_opus.sh"
+RUNTIME_SCRIPT_SOURCE="${ROOT_DIR}/scripts/qwen_tts_runtime.py"
+RUNTIME_SCRIPT_TARGET="${OPENCLAW_HOME}/bin/qwen_tts_runtime.py"
+DEFAULT_BASE_URL="https://qwen-tts-118.tailf26c2b.ts.net"
+
+print_step() {
+  echo
+  echo "==> $1"
+}
+
+env_quote() {
+  python3 -c 'import shlex,sys; print(shlex.quote(sys.argv[1]))' "$1"
+}
+
+prompt_value() {
+  local label="$1"
+  local default_value="$2"
+  local result
+  read -r -p "${label} [${default_value}]: " result
+  if [[ -z "${result}" ]]; then
+    result="${default_value}"
+  fi
+  echo "${result}"
+}
+
+print_step "Qwen TTS Client setup"
+echo "Root: ${ROOT_DIR}"
+echo "OpenClaw home: ${OPENCLAW_HOME}"
+
+BASE_URL="$(prompt_value "CENTRAL_TTS_BASE_URL" "${DEFAULT_BASE_URL}")"
+if [[ "${BASE_URL}" != http://* && "${BASE_URL}" != https://* ]]; then
+  echo "ERROR: CENTRAL_TTS_BASE_URL must start with http:// or https://" >&2
+  exit 1
+fi
+
+read -r -s -p "CENTRAL_TTS_API_KEY: " API_KEY
+echo
+if [[ -z "${API_KEY}" ]]; then
+  echo "ERROR: CENTRAL_TTS_API_KEY cannot be empty" >&2
+  exit 1
+fi
+
+SMOKE_TEXT="$(prompt_value "Smoke test text" "Проверка удаленного TTS клиента.")"
+DEFAULT_TARGET="$(prompt_value "CENTRAL_TTS_TARGET (voice-note|audio-file|telephony)" "voice-note")"
+DEFAULT_TIMEOUT_SEC="$(prompt_value "CENTRAL_TTS_TIMEOUT_SEC" "120")"
+DEFAULT_RETRIES="$(prompt_value "CENTRAL_TTS_RETRIES" "2")"
+DEFAULT_BACKOFF_MS="$(prompt_value "CENTRAL_TTS_RETRY_BACKOFF_MS" "350")"
+
+print_step "Writing ${CLIENT_ENV_PATH}"
+cat > "${CLIENT_ENV_PATH}" <<EOF
+CENTRAL_TTS_BASE_URL=$(env_quote "${BASE_URL}")
+CENTRAL_TTS_API_KEY=$(env_quote "${API_KEY}")
+SMOKE_TEXT=$(env_quote "${SMOKE_TEXT}")
+CENTRAL_TTS_TARGET=$(env_quote "${DEFAULT_TARGET}")
+CENTRAL_TTS_TIMEOUT_SEC=$(env_quote "${DEFAULT_TIMEOUT_SEC}")
+CENTRAL_TTS_RETRIES=$(env_quote "${DEFAULT_RETRIES}")
+CENTRAL_TTS_RETRY_BACKOFF_MS=$(env_quote "${DEFAULT_BACKOFF_MS}")
+CENTRAL_TTS_FFMPEG_TIMEOUT_SEC=$(env_quote "${DEFAULT_TIMEOUT_SEC}")
+CENTRAL_TTS_USE_SYSTEM_PROXY=
+# Optional hints for OpenClaw 2026.4.25+ flow
+CENTRAL_TTS_VOICE=
+CENTRAL_TTS_MODEL=
+CENTRAL_TTS_PERSONA=
+CENTRAL_TTS_SESSION_HINTS_JSON=
+EOF
+chmod 600 "${CLIENT_ENV_PATH}"
+
+print_step "Installing runtime scripts"
+mkdir -p "${OPENCLAW_HOME}/bin"
+cp "${PROXY_SCRIPT_SOURCE}" "${PROXY_SCRIPT_TARGET}"
+cp "${RUNTIME_SCRIPT_SOURCE}" "${RUNTIME_SCRIPT_TARGET}"
+chmod +x "${PROXY_SCRIPT_TARGET}"
+chmod +x "${RUNTIME_SCRIPT_TARGET}"
+
+print_step "Configuring OpenClaw TTS provider"
+python3 - "${OPENCLAW_HOME}" "${PROXY_SCRIPT_TARGET}" "${RUNTIME_SCRIPT_TARGET}" <<'PY'
+import json
+import pathlib
+import sys
+
+openclaw_home = pathlib.Path(sys.argv[1])
+proxy_script = sys.argv[2]
+runtime_script = sys.argv[3]
+config_path = openclaw_home / "openclaw.json"
+
+if not config_path.exists():
+    print(f"ERROR: {config_path} not found. Run OpenClaw at least once first.", file=sys.stderr)
+    sys.exit(1)
+
+data = json.loads(config_path.read_text())
+messages = data.setdefault("messages", {})
+tts = messages.setdefault("tts", {})
+providers = tts.setdefault("providers", {})
+
+providers["tts-local-cli"] = {
+    "enabled": True,
+    "command": proxy_script,
+    "args": ["{{Text}}", "{{OutputPath}}"],
+    "outputFormat": "opus",
+    "timeoutMs": 120000,
+    "env": {
+        "QWEN_TTS_RUNTIME_SCRIPT": runtime_script,
+        "QWEN_TTS_CLIENT_ENV": str(openclaw_home / "qwen_tts_client.env"),
+    },
+}
+
+tts["enabled"] = True
+tts["provider"] = "tts-local-cli"
+tts.setdefault("auto", "off")
+tts.setdefault("persona", "")
+tts.setdefault("personas", {})
+try:
+    _cur_max = int(tts.get("maxTextLength", 0))
+except (TypeError, ValueError):
+    _cur_max = 0
+# OpenClaw UI defaults to 1500; old installers left 600 and caused "max 600" with longer /tts text.
+tts["maxTextLength"] = max(_cur_max, 1500)
+tts.pop("audioAsVoice", None)
+tts.pop("textLimit", None)
+
+config_path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+print(f"updated {config_path}")
+PY
+
+print_step "Normalizing local TTS preferences"
+python3 - "${OPENCLAW_HOME}" <<'PY'
+import json
+import pathlib
+import time
+
+openclaw_home = pathlib.Path(__import__("sys").argv[1])
+prefs_path = openclaw_home / "settings" / "tts.json"
+if not prefs_path.exists():
+    print("no local tts prefs found")
+    raise SystemExit(0)
+
+try:
+    prefs = json.loads(prefs_path.read_text())
+except Exception:
+    backup = prefs_path.with_name(f"tts.json.bak.invalid.{int(time.time())}")
+    prefs_path.rename(backup)
+    print(f"moved invalid prefs to {backup}")
+    raise SystemExit(0)
+
+tts = prefs.get("tts", {})
+partial_override = isinstance(tts, dict) and "providers" not in tts
+if partial_override:
+    backup = prefs_path.with_name(f"tts.json.bak.partial-override.{int(time.time())}")
+    prefs_path.rename(backup)
+    print(f"moved partial tts override prefs to {backup}")
+else:
+    print("local tts prefs left unchanged")
+PY
+
+print_step "Restarting gateway service (if available)"
+if command -v systemctl >/dev/null 2>&1 && systemctl --user list-unit-files | awk '{print $1}' | grep -qx "openclaw-gateway.service"; then
+  systemctl --user restart openclaw-gateway.service || true
+  systemctl --user is-active openclaw-gateway.service || true
+elif command -v launchctl >/dev/null 2>&1; then
+  launchctl kickstart -k "gui/$(id -u)/ai.openclaw.gateway" || true
+fi
+
+if ! command -v ffmpeg >/dev/null 2>&1; then
+  echo "WARN: ffmpeg not in PATH. If the TTS server returns WAV/MP3 instead of Opus-in-Ogg, install ffmpeg (e.g. apt install ffmpeg)." >&2
+fi
+
+print_step "Running smoke test"
+TMP_OUT="/tmp/qwen-tts-client-smoke.ogg"
+QWEN_TTS_CLIENT_ENV="${CLIENT_ENV_PATH}" "${PROXY_SCRIPT_TARGET}" "${SMOKE_TEXT}" "${TMP_OUT}"
+ls -lh "${TMP_OUT}"
+file "${TMP_OUT}" || true
+
+echo
+echo "Done."
+echo "Client env: ${CLIENT_ENV_PATH}"
+echo "Proxy script: ${PROXY_SCRIPT_TARGET}"
+echo "Next: /tts status"

package/scripts/qwen_tts_proxy_opus.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TEXT="${1:-}"
+OUT="${2:-}"
+
+if [[ -z "${TEXT}" || -z "${OUT}" ]]; then
+  echo "usage: qwen_tts_proxy_opus.sh <text> <output_path>" >&2
+  exit 2
+fi
+
+_script_source="${BASH_SOURCE[0]}"
+while [[ -L "${_script_source}" ]]; do
+  _link_dir="$(cd "$(dirname "${_script_source}")" && pwd)"
+  _script_source="$(readlink "${_script_source}")"
+  [[ "${_script_source}" != /* ]] && _script_source="${_link_dir}/${_script_source}"
+done
+SCRIPT_DIR="$(cd "$(dirname "${_script_source}")" && pwd)"
+RUNTIME_SCRIPT="${QWEN_TTS_RUNTIME_SCRIPT:-${SCRIPT_DIR}/qwen_tts_runtime.py}"
+
+if [[ ! -f "${RUNTIME_SCRIPT}" ]]; then
+  echo "runtime script not found: ${RUNTIME_SCRIPT}" >&2
+  exit 1
+fi
+
+exec python3 "${RUNTIME_SCRIPT}" "${TEXT}" "${OUT}"

package/scripts/qwen_tts_runtime.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+import uuid
+from pathlib import Path
+
+
+def _normalize_text(value: str) -> str:
+    return value.encode("utf-8", errors="replace").decode("utf-8", errors="replace")
+
+
+def _load_env_file(path: Path) -> dict[str, str]:
+    data: dict[str, str] = {}
+    if not path.exists():
+        return data
+    raw = path.read_bytes()
+    try:
+        content = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        # Keep runtime resilient on hosts where env was edited with mixed encodings.
+        content = raw.decode("utf-8", errors="replace")
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        cleaned = value.strip().strip("'").strip('"')
+        data[key.strip()] = _normalize_text(cleaned)
+    return data
+
+
+def _env(name: str, default: str = "") -> str:
+    return _normalize_text(os.environ.get(name, default).strip())
+
+
+def _positive_int(value: str, default: int) -> int:
+    try:
+        num = int(value)
+        return num if num > 0 else default
+    except ValueError:
+        return default
+
+
+def _truthy_env(name: str) -> bool:
+    return _env(name, "").lower() in ("1", "true", "yes", "on")
+
+
+def _build_url_opener() -> urllib.request.OpenerDirector:
+    """
+    Gateway processes often inherit HTTP_PROXY/HTTPS_PROXY. urllib honors them by default,
+    which breaks private / Tailscale TTS URLs. Disable system proxies unless explicitly opted in.
+    """
+    if _truthy_env("CENTRAL_TTS_USE_SYSTEM_PROXY"):
+        return urllib.request.build_opener()
+    return urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+def _write_atomic(path: Path, payload: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(dir=str(path.parent), prefix=".qwen-tts-", delete=False) as temp_file:
+        temp_file.write(payload)
+        temp_name = temp_file.name
+    os.replace(temp_name, str(path))
+
+
+def _content_type_base(headers) -> str:
+    raw = (headers.get("Content-Type") or "").strip()
+    return raw.split(";", 1)[0].strip().lower()
+
+
+def _is_opus_in_ogg(content: bytes) -> bool:
+    if len(content) < 4 or content[:4] != b"OggS":
+        return False
+    scan = min(len(content), 131072)
+    return b"OpusHead" in content[:scan]
+
+
+def _is_riff_wave(content: bytes) -> bool:
+    return len(content) >= 12 and content[:4] == b"RIFF" and content[8:12] == b"WAVE"
+
+
+def _looks_json_error(content: bytes) -> bool:
+    stripped = content.lstrip()
+    return bool(stripped) and stripped[:1] == b"{"
+
+
+def _http_audio_acceptable(content_type: str, content: bytes) -> bool:
+    if content_type.startswith("application/json") or content_type.startswith("text/html"):
+        return False
+    if content_type.startswith("audio/"):
+        return bool(content) and not _looks_json_error(content)
+    if content_type in ("application/ogg", "application/octet-stream", "binary/octet-stream", ""):
+        return bool(content) and not _looks_json_error(content)
+    return False
+
+
+def _ffmpeg_to_opus_file(payload: bytes, out_path: Path, timeout_sec: int) -> None:
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        raise RuntimeError(
+            "TTS response is not Opus-in-Ogg; install `ffmpeg` to transcode (e.g. apt install ffmpeg)."
+        )
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = out_path.with_name(f".qwen-tts-ffmpeg-{uuid.uuid4().hex[:10]}.opus")
+    try:
+        proc = subprocess.run(
+            [
+                ffmpeg,
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-y",
+                "-i",
+                "pipe:0",
+                "-c:a",
+                "libopus",
+                "-b:a",
+                "64k",
+                str(tmp),
+            ],
+            input=payload,
+            capture_output=True,
+            timeout=max(timeout_sec, 5),
+        )
+        if proc.returncode != 0:
+            err = (proc.stderr or b"").decode("utf-8", errors="replace").strip()
+            raise RuntimeError(f"ffmpeg transcode failed (exit {proc.returncode}): {err[:800]}")
+        if not tmp.exists() or tmp.stat().st_size == 0:
+            raise RuntimeError("ffmpeg produced empty output")
+        os.replace(str(tmp), str(out_path))
+    finally:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+
+
+def _ensure_output_audio(content: bytes, content_type: str, out_path: Path, transcode_timeout: int) -> None:
+    """
+    OpenClaw tts-local-cli picks format from the OUTPUT FILE EXTENSION only.
+    For voice-note it expects real Opus-in-Ogg at *.opus; writing WAV bytes there causes provider_error.
+    """
+    suffix = out_path.suffix.lower()
+    want_opus_file = suffix in (".opus", ".ogg")
+
+    if not want_opus_file:
+        _write_atomic(out_path, content)
+        return
+
+    if _is_opus_in_ogg(content):
+        _write_atomic(out_path, content)
+        return
+
+    if _looks_json_error(content) and not _is_riff_wave(content):
+        preview = content[:800].decode("utf-8", errors="replace")
+        raise RuntimeError(f"server returned JSON instead of audio: {preview}")
+
+    if _is_riff_wave(content) or content_type in ("audio/wav", "audio/x-wav", "audio/wave"):
+        _ffmpeg_to_opus_file(content, out_path, transcode_timeout)
+        return
+
+    if content_type in ("audio/mpeg", "audio/mp3") or (
+        len(content) >= 2 and content[0:1] == b"\xff" and (content[1] & 0xE0) == 0xE0
+    ):
+        _ffmpeg_to_opus_file(content, out_path, transcode_timeout)
+        return
+
+    if content[:4] == b"OggS":
+        _ffmpeg_to_opus_file(content, out_path, transcode_timeout)
+        return
+
+    if content_type.startswith("audio/") or content_type in (
+        "application/ogg",
+        "application/octet-stream",
+        "binary/octet-stream",
+    ):
+        _ffmpeg_to_opus_file(content, out_path, transcode_timeout)
+        return
+
+    raise RuntimeError(f"cannot map TTS payload to Opus file (content-type={content_type!r}, {len(content)} bytes)")
+
+
+def _build_payload(text: str, request_id: str) -> dict[str, object]:
+    session_hints: dict[str, str] = {
+        "source": "qwen-tts-client",
+        "runtime": "local-cli",
+        "host": socket.gethostname(),
+    }
+    extra_hints = _env("CENTRAL_TTS_SESSION_HINTS_JSON")
+    if extra_hints:
+        try:
+            parsed = json.loads(extra_hints)
+            if isinstance(parsed, dict):
+                for key, value in parsed.items():
+                    session_hints[_normalize_text(str(key))] = _normalize_text(str(value))
+        except json.JSONDecodeError:
+            pass
+
+    payload: dict[str, object] = {
+        "text": _normalize_text(text),
+        "requestId": _normalize_text(request_id),
+        "target": _env("CENTRAL_TTS_TARGET", "voice-note"),
+        "sessionHints": session_hints,
+    }
+    if _env("CENTRAL_TTS_VOICE"):
+        payload["voice"] = _env("CENTRAL_TTS_VOICE")
+    if _env("CENTRAL_TTS_MODEL"):
+        payload["model"] = _env("CENTRAL_TTS_MODEL")
+    if _env("CENTRAL_TTS_PERSONA"):
+        payload["persona"] = _env("CENTRAL_TTS_PERSONA")
+    return payload
+
+
+def main() -> int:
+    text = sys.argv[1] if len(sys.argv) > 1 else ""
+    out_path = Path(sys.argv[2]) if len(sys.argv) > 2 else None
+    default_env = Path.home() / ".openclaw" / "qwen_tts_client.env"
+    env_path = Path(_env("QWEN_TTS_CLIENT_ENV", str(default_env)))
+    if not text or out_path is None:
+        print("usage: qwen_tts_runtime.py <text> <output_path>", file=sys.stderr)
+        return 2
+
+    for key, value in _load_env_file(env_path).items():
+        os.environ.setdefault(key, value)
+
+    base_url = _env("CENTRAL_TTS_BASE_URL")
+    api_key = _env("CENTRAL_TTS_API_KEY")
+    if not base_url or not api_key:
+        print(f"CENTRAL_TTS_BASE_URL or CENTRAL_TTS_API_KEY missing in {env_path}", file=sys.stderr)
+        return 1
+
+    timeout_sec = max(_positive_int(_env("CENTRAL_TTS_TIMEOUT_SEC", "120"), 120), 5)
+    max_retries = _positive_int(_env("CENTRAL_TTS_RETRIES", "2"), 2)
+    retry_backoff_ms = _positive_int(_env("CENTRAL_TTS_RETRY_BACKOFF_MS", "350"), 350)
+    request_id = f"qtts-{uuid.uuid4().hex[:12]}"
+    payload = _build_payload(text=text, request_id=request_id)
+    request_url = f"{base_url.rstrip('/')}/tts"
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    url_opener = _build_url_opener()
+
+    last_error = "unknown error"
+    for attempt in range(0, max_retries + 1):
+        started_at = time.perf_counter()
+        request = urllib.request.Request(
+            request_url,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "X-API-Key": api_key,
+                "X-Request-Id": request_id,
+            },
+            data=body,
+        )
+        try:
+            with url_opener.open(request, timeout=timeout_sec) as response:
+                content = response.read()
+                content_type = _content_type_base(response.headers)
+                if not content:
+                    raise RuntimeError("server returned empty audio payload")
+                if not _http_audio_acceptable(content_type, content):
+                    raise RuntimeError(f"unexpected content-type: {content_type or '(missing)'}")
+                transcode_timeout = max(
+                    _positive_int(_env("CENTRAL_TTS_FFMPEG_TIMEOUT_SEC", str(timeout_sec)), timeout_sec),
+                    5,
+                )
+                _ensure_output_audio(content, content_type, out_path, transcode_timeout)
+                elapsed_ms = (time.perf_counter() - started_at) * 1000
+                out_size = out_path.stat().st_size if out_path.exists() else 0
+                print(
+                    f"[qwen-tts-runtime] request_id={request_id} attempt={attempt + 1} status=ok "
+                    f"latency_ms={elapsed_ms:.2f} bytes_in={len(content)} bytes_out={out_size} "
+                    f"content_type={content_type or '(missing)'}",
+                    file=sys.stderr,
+                )
+                return 0
+        except urllib.error.HTTPError as exc:
+            error_body = exc.read().decode("utf-8", errors="ignore")
+            last_error = f"http {exc.code}: {error_body}"
+        except Exception as exc:  # pragma: no cover
+            last_error = str(exc)
+
+        elapsed_ms = (time.perf_counter() - started_at) * 1000
+        print(
+            f"[qwen-tts-runtime] request_id={request_id} attempt={attempt + 1} status=retry "
+            f"latency_ms={elapsed_ms:.2f} error={last_error}",
+            file=sys.stderr,
+        )
+        if attempt < max_retries:
+            time.sleep((retry_backoff_ms / 1000.0) * (attempt + 1))
+
+    hint = ""
+    if not _truthy_env("CENTRAL_TTS_USE_SYSTEM_PROXY"):
+        le = last_error.lower()
+        if any(s in le for s in ("timed out", "connection refused", "unreachable", "name or service not known", "nodename", "tunnel", "proxy")):
+            hint = " | hint: TTS uses direct TCP (no HTTP_PROXY); set CENTRAL_TTS_USE_SYSTEM_PROXY=1 if you need a proxy."
+    print(f"[qwen-tts-runtime] request_id={request_id} status=failed error={last_error}{hint}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())