TTS Media Route Fix
Overview
Apply a production-safe patch workflow for OpenClaw installs where tts.convert and /media/tts/<id>.mp3 routing are broken or incomplete.
Always back up hashed dist files before edits, patch minimally, restart gateway, and verify with authenticated range curl.
Workflow
- 1. Locate active hashed
gateway-cli-*.js files. - Back up each file to
*.bak before modifying. - Patch HTTP handler for
GET/HEAD /media/tts/<id>.mp3 with auth, validation, binary output, and Range. - Ensure
tts.convert payload returns audioUrl under /media/tts/<id>.mp3 and mp3 metadata. - Restart gateway.
- Verify with Bearer-authenticated curl (including
--range). - Confirm temporary file TTL cleanup (2–5 minutes).
Commands
1) Find hashed dist targets
Use scripts/find_gateway_cli.sh to locate candidate files:
CODEBLOCK0
If multiple candidates exist, patch only the currently used runtime build(s).
2) Back up before edits
For each target:
CODEBLOCK1
Never skip backups.
3) Patch requirements
Implement or fix handler for GET and HEAD at /media/tts/<id>.mp3:
- - Validate filename strictly (no traversal, fixed suffix
.mp3). - Require Bearer token with same gateway auth policy.
- Serve binary MP3 with
Content-Type: audio/mpeg. - Support Range and send
Accept-Ranges: bytes. - Correct status behavior:
404, 405, 416, 200/206.
For tts.convert, ensure response structure:
CODEBLOCK2
TTL behavior: keep files temporary and auto-clean in 2–5 minutes.
4) Restart gateway
CODEBLOCK3
5) Verify media route
Use scripts/verify_tts_media_route.sh or run manually:
CODEBLOCK4
Expected:
- - HTTP
200 or INLINECODE23 - INLINECODE24
- Binary content (not HTML / control-ui page)
Guardrails
- - Patch minimally; avoid unrelated refactors.
- Keep auth checks identical to existing gateway Bearer model.
- Preserve existing routing behavior outside
/media/tts/*. - If patching fails, restore
.bak and retry.
Resources
scripts/
- -
find_gateway_cli.sh — locate hashed runtime files for patching. - INLINECODE28 — quick authenticated range-check for MP3 route.
references/
- -
patch-checklist.md — concise checklist of required behaviors and acceptance criteria.
TTS媒体路由修复
概述
针对OpenClaw安装中tts.convert和/media/tts/.mp3路由损坏或不完整的情况，应用生产安全补丁工作流程。编辑前始终备份哈希分发文件，最小化修补，重启网关，并通过带认证的Range curl进行验证。
工作流程
- 1. 定位活跃的哈希gateway-cli-.js文件。
- 修改前将每个文件备份为.bak。
- 为GET/HEAD /media/tts/.mp3修补HTTP处理器，包含认证、验证、二进制输出和Range支持。
- 确保tts.convert负载在/media/tts/.mp3路径下返回audioUrl及mp3元数据。
- 重启网关。
- 使用Bearer认证的curl（包含--range参数）进行验证。
- 确认临时文件TTL清理（2-5分钟）。
命令
1) 查找哈希分发目标
使用scripts/findgatewaycli.sh定位候选文件：
bash
bash scripts/findgatewaycli.sh
如果存在多个候选文件，仅修补当前使用的运行时构建版本。
2) 编辑前备份
针对每个目标文件：
bash
cp /path/to/gateway-cli-.js /path/to/gateway-cli-.js.bak
切勿跳过备份步骤。
3) 修补要求
为/media/tts/.mp3实现或修复GET和HEAD的处理器：
- - 严格验证文件名（禁止路径遍历，固定后缀.mp3）。
- 要求使用与网关相同认证策略的Bearer令牌。
- 以Content-Type: audio/mpeg提供二进制MP3内容。
- 支持Range并发送Accept-Ranges: bytes。
- 正确的状态行为：404、405、416、200/206。
对于tts.convert，确保响应结构如下：
json
{
ok: true,
payload: {
audioUrl: /media/tts/.mp3,
mimeType: audio/mpeg,
format: mp3
}
}
TTL行为：临时保存文件并在2-5分钟内自动清理。
4) 重启网关
bash
openclaw gateway restart
5) 验证媒体路由
使用scripts/verifyttsmedia_route.sh或手动执行：
bash
curl -i -H Authorization: Bearer \
http://:/media/tts/.mp3 \
--range 0-127
预期结果：
- - HTTP 200或206
- Content-Type: audio/mpeg
- 二进制内容（非HTML/控制界面页面）
安全准则
- - 最小化修补；避免无关重构。
- 保持认证检查与现有网关Bearer模型一致。
- 保留/media/tts/*之外现有路由行为。
- 如果修补失败，恢复.bak文件并重试。
资源
scripts/
- - findgatewaycli.sh — 定位用于修补的哈希运行时文件。
- verifyttsmedia_route.sh — 对MP3路由进行快速认证范围检查。
references/
- - patch-checklist.md — 所需行为和验收标准的简明清单。
