本地 STT 工作流

使用此技能调试完整的语音转文本路径，而不仅限于模型本身。

默认假设：本地 STT 服务运行在 http://127.0.0.1:8000/v1。

当前值得记住的本地 model-path 回退逻辑：若服务器未按名称拉取模型，它可能直接从本地路径加载，例如 ./models/Qwen3-ASR-0.6B-bf16。

当精确的路由结构至关重要时，本地 OpenAPI 文档可通过以下地址获取：

• http://localhost:8000/openapi.json

请将该 OpenAPI 文档作为模式/参考依据，用于比对本地 mlx-audio 服务器与 OpenAI API 的行为差异。请勿将其用作健康检查（health check）手段。

工作流

1. 在归责 OpenClaw 前，先验证服务器状态

首先检查基础项：

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/v1/models

确认目标 STT 模型存在，通常为 qwen3-asr。

若模型未以注册名形式出现在列表中，请勿立即断定 STT 故障——该服务器可能正加载本地路径下的模型（如 ./models/Qwen3-ASR-0.6B-bf16）。

若服务器启用了任务门控（task-gated），请确保已启用 STT：

MLX_AUDIO_SERVER_TASKS=stt uv run python server.py

若模型缺失，请在测试客户端前完成注册；但在此之前，请先确认服务器是否本意即从本地路径加载，并通过 /v1/models 或 http://localhost:8000/openapi.json 核实其实际接受的模型 ID 列表。

2. 验证原始 STT 接口是否正常工作

务必先将服务器与客户端栈完全隔离。

最小化直连转录测试：

curl -X POST http://127.0.0.1:8000/v1/audio/transcriptions 
  -F file=@sample.wav 
  -F model=qwen3-asr 
  -F response_format=json

更丰富的实用测试：

curl -X POST http://127.0.0.1:8000/v1/audio/transcriptions 
  -F file=@sample.wav 
  -F model=qwen3-asr 
  -F response_format=verbose_json 
  -F 'timestamp_granularities[]=segment' 
  -F 'timestamp_granularities[]=word'

若直连 curl 成功但 OpenClaw 无响应，则问题极可能出在消息摄入或路由层，而非 STT 后端。

3. 区分服务器故障与路由故障

请严格遵守如下判断规则：

• 直连 curl 失败 → 首先修复本地 STT 服务器
• 直连 curl 成功，但 OpenClaw 未返回任何转录结果 → 检查 OpenClaw 的音频流水线 / 附件路由逻辑
• OpenClaw 发出了请求，但字段内容错误 → 检查请求结构的兼容性

这一区分可节省大量排查时间。

4. 检查请求结构

本服务器设计基于OpenAI 风格的 multipart 表单上传协议。

根据当前本地 OpenAPI Schema，/v1/audio/transcriptions 接口所需的主体字段如下：

• 必填字段：file、model
• 可选字段：language、verbose、max_tokens、chunk_duration、frame_threshold、stream、context、prefill_step_size、text

这意味着本地服务器暴露的表单结构与 OpenAI Whisper 风格文档并不一致。切勿仅因 OpenAI 支持某字段（如 response_format、prompt 或 timestamp_granularities[]），就盲目假设本地服务器也支持相同字段。

若怀疑客户端发送了错误结构的请求，可通过临时部署 dump 代理或查阅服务器日志来分析网络流量。

5. 当字段细节至关重要时，请参考规范文档

当需确认以下功能的确切行为时，请查阅 references/stt-api.md：

• response_format=json|text|verbose_json|srt|vtt
• stream=true 下的 SSE 事件格式
• timestamp_granularities[]
• include[]
• 翻译接口（translation endpoint）语义
• 错误响应包（error envelope）结构
• 当前兼容性限制

当本地服务器可能有意偏离标准时，请切勿依据通用 OpenAI 文档猜测字段支持情况。

当前显著差异示例：本地 Schema 暴露了 context 和 text 字段，并提供了分块与预填充控制参数（如 chunk_duration、frame_threshold 和 prefill_step_size），这些均不属于常规 OpenAI STT 字段集。

6. OpenClaw 特定调试模式

当 OpenClaw 的 STT 功能疑似异常时，请执行以下步骤：

1. 确认配置的是 tools.media.audio，而非 messages.stt
2. 确认基础 URL 指向 http://127.0.0.1:8000/v1
3. 确认所选模型存在于 /v1/models 中
4. 将相同的入站音频文件直接提交至 /v1/audio/transcriptions
5. 检查网关日志，确认是否存在转录调度（transcription dispatch）记录
6. 若完全未出现** /audio/transcriptions 请求，则问题位于 STT 上游环节