人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载导读本文是 ClawX 桌面客户端内置语音听写Voice Dictation / Speech-to-Text Input功能的深度技术指南。该功能在开启开发者模式后为聊天输入框composer提供一键录音、停止后自动转写并插入光标处的完整链路涉及 macOS/Windows 麦克风权限获取与恢复、渲染进程内的录音与 WAV 编码、Main 进程内的 ASR 请求与密钥隔离以及 Models 页面的 Speech-to-text 配置面板。读完本文你将掌握 ClawX 中语音输入的完整工作流程、两种 ASR 线上协议的差异与选型、麦克风权限问题的排查与修复包括 macOS 本地打包的签名身份陷阱并能基于仓库源码理解每个环节的实现细节。功能概览与入口语音听写在 ClawX 中是一个实验性表面只有当Developer Mode开发者模式开启后聊天 composer 才会渲染麦克风按钮Models 页面才会出现 Speech-to-text语音转文本标签页。开发者模式关闭时这两处入口均不渲染直接访问?tabvoice的 URL 也会回退到 Chat models。交互模型非常直观按一次开始录音再按一次或等待180 秒上限停止转写结果插入到 textarea 光标位置Escape取消并丢弃录音从录音开始到转写结束composer 的 textarea 处于锁定状态确保插入点不会漂移。录音状态由三态机管理idle空闲/recording录音中/transcribing转写中见 useVoiceDictation.ts 中的VoiceDictationStatus类型。该三态机受同步重入锁与 generation 计数器保护——generation 计数用于在组件卸载、草稿切换、取消等场景下使过期的异步续体失效避免产生双重会话等竞态问题录音器的stop()被记忆化memoized并发 stop 调用共享同一个终态结果。麦克风权限获取与恢复权限读取的完整流程点击麦克风按钮后权限检查遵循“先配置校验、后权限校验”的顺序详见 useVoiceDictation.ts 的toggle实现配置守卫先调用hostApi.asr.getConfig()读取 ASR 就绪状态configured。若未配置直接进入引导路径toast 提示并路由到/models?tabvoice权限读取再调用hostApi.asr.getMicrophoneAccess()录音启动权限通过后调用startVoiceRecording()走getUserMedia路径。Main 进程侧的权限读取在 microphone-access.ts 中实现在 macOS / Windows 上调用免弹窗的systemPreferences.getMediaAccessStatus(microphone)其他平台一律返回unknown该调用被 try/catch 包裹读取失败时静默降级录音仍可尝试。权限状态机行为denied / restricted显示本地化的权限引导弹窗不启动采集unknown / not-determined / 读取失败走正常的getUserMedia路径录音中遇到MIC_UNAVAILABLE采集失败会触发再一次权限读取用于捕获“首次使用时拒绝授权”的情况只有当再次读取结果为 denied / restricted 时才用权限引导替换通用错误generation 取消覆盖两次读取——包括组件禁用与卸载时未完成的权限读取会被同步作废。系统设置引导弹窗权限弹窗中显式的hostApi.asr.openMicrophoneSettings()动作只打开Main 进程拥有的固定 URLmacOSx-apple.systempreferences:com.apple.preference.security?Privacy_MicrophoneWindowsms-settings:privacy-microphone不支持的平台Linux 等该动作直接无操作返回{ opened: false }。启动系统设置失败时用户可见提示关闭设置或启动设置都不会触发录音——必须重新点击麦克风按钮此时才会读取到最新的权限状态。restricted 状态通常需要管理员或设备策略变更才能解除。弹窗本体是紧凑、居中、带内边距的卡片包含标题、简短权限说明与关闭/打开设置两个操作。平台细节、重启提示、开发启动方式等详细说明保留在文档中而不塞进弹窗。权限状态的边界不校验签名与硬件权限状态读取不验证应用签名或硬件可用性。macOS 上 Hardened Runtime 下的麦克风采集需要两件事应用及继承的 Helper 的 entitlements 中包含com.apple.security.device.audio-input以及NSMicrophoneUsageDescription用途描述。Mock 的单元/E2E 测试既不会改动 TCC也不会验证签名后的已安装构建——这类测试无法证明真实安装包在 TCC 层面可用。本地 macOS 打包签名身份分裂陷阱这是本功能最值得注意的坑。未进行应用签名的本地打包会保留 Electron 链接器生成的签名IdentifierElectron、flagsadhoc,linker-signed、Info.plistnot bound这与对完整应用包显式 ad-hoc 签名是完全不同的。在观察到的 0.5.7 本地构建中macOS TCC 将 Main 进程的权限读取/请求归属到app.clawx.desktopbundle 身份但 Helper 的 Core Audio 请求被归属到/Applications/ClawX.app/Contents/MacOS/ClawX可执行文件路径身份。结果是在“系统设置”中出现两个 ClawX 麦克风条目其中一个带应用图标、另一个带终端图标。由此产生了一个被确认的误报权限状态Main 返回granted而路径条目实为 deniedgetUserMedia成功、得到一条活跃且未静音的音轨、AudioContext 也在运行但 10 秒探针的 475,136 个采样全部为 0。仅启用路径条目不改采集代码、不重启同样大小的探针得到 473,915 个非零采样。实验中只检查了计数与峰值幅度没有保存或转写任何录音。显式的 MainaskForMediaAccess请求会为 bundle 身份打开真实同意弹窗但不能解决被单独拒绝的路径身份。因此不要把一次成功的权限请求或看似健康的音轨元数据当作打包问题已修复的证据也不要把普通的静音误判为权限拒绝。针对本仓库 electron-builder26.16.0的无证书本地打包正确做法是显式签名完整应用包而非跳过签名pnpm run package:mac:local --arm64 --config.mac.identity- --config.mac.notarizefalseIntel 构建改用--x64。保留现有的 audio-input 与 disable-library-validation entitlements见 entitlements.mac.plist。正式发布构建应保留 Developer ID 签名与公证。用以下命令检查产物与 Helper 的签名codesign -dvv --entitlements - bundle主应用应识别为app.clawx.desktop且 Info.plist 已绑定而不是保留原始 Electron 链接器签名。重建后的签名包验收仍然需要手动验证两点权限拒绝能阻断采集、授权后能拿到真实麦克风输入。重建不会自动清除既有的重复 TCC 条目——永远不要自动重置 TCC 或修改授权。录音与转写链路为什么选择“本地录制 批量转写”ClawX 刻意采用批量转写而非流式转写。原因很实在流式 ASR 没有通用的线上协议——讯飞、Deepgram、AssemblyAI、腾讯每家都有自己的 WebSocket 方言而 OpenAI 的POST {baseUrl}/audio/transcriptions是事实标准被 OpenAI、Groq、SiliconFlow、DeepInfra、Fireworks 以及 whisper.cpp、LocalAI 等本地服务共同采纳。因此 ClawX 的做法是本地录音 → 用户停止时上传一个 WAV 文件 → 插入返回的文本。全程只有一个 30 秒超时、Bearer 鉴权、统一的 HTTP 状态码到错误码映射并且把空结果视为业务错误而非成功。录音管线全部在渲染进程音频采集完全位于渲染进程见 recorder.tsgetUserMedia打开单声道流开启回声消除echoCancellation、噪声抑制noiseSuppression与自动增益autoGainControl一个ScriptProcessorNode4096 采样缓冲驱动管线线性重采样到16 kHz编码为小端 PCM16停止时在前面拼接44 字节 RIFF 头有效音频不足300 ms对应 wav.ts 中的VOICE_MIN_SAMPLE_COUNT即 16000 × 0.3 4800 采样则拒绝该次录音TOO_SHORT。WAV 数学细节见 wav.tsresampleLinear按采样位置线性插值encodePcm16Bytes将 Float32 采样钳制到 [-1, 1] 后按 PCM16 量化负值乘0x8000、正值乘0x7fffbuildWavFile写入标准 RIFF/WAVE 头PCM、单声道、16 位、16 kHz、字节率 32000。录音过程中同一份 PCM 块被折算为RMS 响度钳制到 0–1增益 4×压入useVoiceDictation钩子内的24 采样环形缓冲composer 按钮以120 ms间隔轮询该缓冲绘制5 根波形条见 VoiceDictationButton.tsx高度 4 14 × clamp(level)波形高度实时反映真实响度——静音贴地、说话随音量升高。转写请求两种协议转写请求由 Main 进程的asr模块发起getConfig/saveConfig/transcribe三个动作见 asr-api.ts。协议由AsrConfig.protocol字段选择旧配置无该字段时按normalizeAsrProtocol回退为transcriptions见 presets.ts。transcriptionsmultipart 表单POST {baseUrl}/audio/transcriptions字段为filerecording.wav16 kHz 单声道 PCM16、model以及可选的languageISO-639-1如zh/en未设置时字段整体省略由服务端自动检测。响应取{ text }。实现见 asr-client.ts 的transcribeWav。chatJSON chat completionsPOST {baseUrl}/chat/completions请求体为{ model, stream: false, messages: [{ role: user, content: [{ type: input_audio, input_audio: ... }] }] }。input_audio的编码随预设而变源码中transcribeViaChatCompletions的注释明确说明bailian预设阿里云百炼Model Studio方言——Data URIdata:audio/wav;base64,base64 wav不带独立的format字段其他所有预设自定义端点OpenAI 模式——data里放裸 Base64加format: wav。不发送任何厂商的asr_options。转写结果从choices[0].message.content读取——字符串直接取数组则把其中的文本片段拼接见extractChatContent。两种协议共享 30 秒超时ASR_REQUEST_TIMEOUT_MS 30_000、Bearer 鉴权、同一套状态码→错误码映射以及“空结果 业务错误”的判定。ASR 配置体系配置结构单端点画像配置是单一端点画像不是多账号结构。AsrConfig字段见 contract.ts字段类型说明protocoltranscriptions \| chat线上协议可选缺省按transcriptions处理presetopenai \| groq \| siliconflow \| bailian \| custom提供商预设baseUrlstring服务基地址必填须为 http/https 且非空modelstring模型名必填非空languagestring可选仅transcriptions协议使用预设列表按协议划分ASR_PRESETS_BY_PROTOCOL见 presets.tstranscriptionsopenai/groq/siliconflow/custom默认 baseUrl / modelopenai→https://api.openai.com/v1whisper-1groq→https://api.groq.com/openai/v1whisper-large-v3siliconflow→https://api.siliconflow.cn/v1Qwen/Qwen3-ASR-1.7Bcustom→ 两者均留空chatbailian/custombailian预填https://WorkspaceId.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 模型qwen3-asr-flash用户需替换WorkspaceId占位符。选择预设或切换协议会用默认值覆盖 baseUrl 与 model。URL 后缀规则源码transcribeWav中实现transcriptions协议下标准预设openai/groq/siliconflow自动追加/audio/transcriptions设置界面中 Base URL 字段会渲染不可编辑的该后缀transcriptions协议下custom预设把用户输入的 URL 当作完整请求端点直接使用不追加任何路径因为自定义提供商可能暴露非标准路径chat协议下用户输入的永远是 base URL固定追加/chat/completions。存储与密钥隔离配置存放在独立的 electron-store 文件store 名clawx-asr键asrConfig见 config-store.tsAPI 密钥复用 provider 密钥库账号 id 固定为asr——空字符串清除密钥undefined则保持不动。getConfig只向渲染进程返回hasApiKey布尔值渲染进程从不接触外部端点也永远看不到 API 密钥。所有特权工作请求发送、密钥读取都在 Main 进程通过 host-invoke 注册表以独立asr模块完成且不会向 OpenClaw gateway 推送任何内容。保存时的配置校验saveConfig在落盘前执行validateAsrConfig见 asr-client.ts配置必须是对象、preset必须是已知预设、protocol必须合法未定义则跳过、baseUrl必须是非空字符串且能解析为http:/https:URL、model必须非空任一不满足都抛INVALID_INPUT。设置界面与引导设置入口在Models 页面。Speech-to-text 与图像生成一样都是开发者模式门控的实验表面Chat models 则无条件可用。点击麦克风但配置不完整时toast 提示并路由到/models?tabvoice标准预设openai/groq/siliconflow的 Base URL 字段仅渲染不可编辑的/audio/transcriptions后缀custom预设或chat协议下后缀隐藏选择bailian会渲染两条本地化提示Data URIinput_audio要求带内联文档链接打开阿里云 OpenAI 兼容 ASR 指南与WorkspaceId占位符/地域说明此外 siliconflow 与 bailian 还会渲染获取 API 密钥的提供商控制台链接。错误码体系与国际化Electron 会把抛出的 host 错误拍平成 message 字符串因此 ASR 错误码被序列化进消息格式为ASR:CODE:message再由 errors.ts 的parseAsrErrorCode解析回来正则^ASR:([A-Z_]):匹配后还要在白名单ASR_ERROR_CODES中确认。可识别错误码AsrErrorCodeAUTH401/403、RATE_LIMITED429、SERVER≥500、REQUEST其余 HTTP 错误兼作回退兜底——由assertResponseOk按状态码映射NETWORK超时/网络失败由fetchWithTimeout抛出EMPTY_RESULT空响应/无文本INVALID_INPUT配置或 WAV 载荷非法NOT_CONFIGURED未配置就发起转写。每个错误码映射到 composer toast 与设置表单中逐码的 i18n 文案。录音侧另有MIC_UNAVAILABLE与TOO_SHORT两个本地错误码VoiceRecorderErrorCode见 recorder.ts。macOS 打包声明electron-builder.yml 的 mac 段声明了NSMicrophoneUsageDescription: ClawX requires microphone access for voice featuresentitlements.mac.plist 在应用与继承的 Helper entitlements 中启用了com.apple.security.device.audio-inputHardened Runtime 采集必需以及com.apple.security.cs.disable-library-validation。用途描述只负责解释 TCC 弹窗不能替代签名 entitlements。关键设计Chromium 的用户触发型getUserMedia路径会自行请求同意所以 Main 进程不需要显式askForMediaAccess调用默认窗口会话也不需要权限处理器——web-browser-session.ts 中的 deny-all 处理器只管辖嵌入式浏览器的 guest 会话。测试覆盖分层验证测试严格对应分层架构WAV 纯数学重采样、PCM16 编码、RIFF 头字节与录音器基于 fakeAudioContext图含 double-stop 竞态有单元测试hook 层使用 fake timers 验证 180 秒上限与 250 ms 计时 tick常量见 useVoiceDictation.tsVOICE_MAX_RECORDING_MS 180_000、VOICE_TIMER_INTERVAL_MS 250、VOICE_LEVEL_HISTORY 24Main 客户端stubfetch覆盖状态码映射与 multipart 形态设置表单与 Models 标签页有组件测试voice-dictation.spec.ts 覆盖两条端到端路径插入光标处的 happy path、未配置时的引导路径——通过installIpcMocksmockasrhost 动作并用 oscillator 支撑的流 stubgetUserMedia转写结果常量TRANSCRIBED_TEXT voice dictation result。权限被拒/恢复路径同样有覆盖首次使用拒绝与再次授权恢复。这些 E2E 用例是普通并行测试麦克风始终被 mock不触碰任何 OS 全局状态因此不需要exclusive标签。开发者模式覆盖还验证了模式关闭时 composer 麦克风与 Speech-to-text 标签页均隐藏开启后可见。总结与排查清单录音无声先检查“系统设置 → 隐私与安全 → 麦克风”中是否有两个 ClawX 条目本地未签名构建尤其要确认 Helper 的路径身份是否被拒打包修复无证书本地打包用pnpm run package:mac:local --arm64 --config.mac.identity- --config.mac.notarizefalseIntel 用--x64显式签名完整包再用codesign -dvv --entitlements - bundle确认主应用为app.clawx.desktop且 Info.plist 已绑定权限误报getUserMedia成功不代表权限真实可用以“探针采样是否非零”验证真实采集而不是依赖音轨元数据配置检查baseUrl必须可解析为 http(s)model非空transcriptions协议下custom预设的 URL 是全端点chat协议下永远追加/chat/completions错误排查转写失败信息以ASR:CODE:message形式出现对照AUTH/RATE_LIMITED/SERVER/NETWORK/EMPTY_RESULT/INVALID_INPUT/NOT_CONFIGURED/REQUEST逐码定位。赞分享人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载相关推荐AIRI 接入 Xiaomi MiMo 语音转写ASR/STT完整指南API Key、模型配置与麦克风转写实战AIRI 接入 Xiaomi MiMo 语音转写ASR/STT完整指南API Key、模型配置与麦克风转写实战 本指南以 AIRI 项目文档中关于 XiaAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染AIRI 语音转写接入 CometAPI从 API Key 配置到麦克风实时听写全指南AIRI 语音转写接入 CometAPI从 API Key 配置到麦克风实时听写全指南 CometAPI 是一个提供统一模型网关与凭据管理的云端服务AIRIAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染gpt_academic 实时语音交互实战阿里云 ASR 配置、麦克风授权与电脑音频截获完整指南gpt_academic 实时语音交互实战阿里云 ASR 配置、麦克风授权与电脑音频截获完整指南 gpt_academic 的音频交互功能让您可以完全脱离键盘人工智能大模型AI 应用交互助手上一篇如何通过HsMod插件实现炉石传说游戏效率革命下一篇NCPs项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载导读本文是 ClawX 桌面客户端内置语音听写Voice Dictation / Speech-to-Text Input功能的深度技术指南。该功能在开启开发者模式后为聊天输入框composer提供一键录音、停止后自动转写并插入光标处的完整链路涉及 macOS/Windows 麦克风权限获取与恢复、渲染进程内的录音与 WAV 编码、Main 进程内的 ASR 请求与密钥隔离以及 Models 页面的 Speech-to-text 配置面板。读完本文你将掌握 ClawX 中语音输入的完整工作流程、两种 ASR 线上协议的差异与选型、麦克风权限问题的排查与修复包括 macOS 本地打包的签名身份陷阱并能基于仓库源码理解每个环节的实现细节。功能概览与入口语音听写在 ClawX 中是一个实验性表面只有当Developer Mode开发者模式开启后聊天 composer 才会渲染麦克风按钮Models 页面才会出现 Speech-to-text语音转文本标签页。开发者模式关闭时这两处入口均不渲染直接访问?tabvoice的 URL 也会回退到 Chat models。交互模型非常直观按一次开始录音再按一次或等待180 秒上限停止转写结果插入到 textarea 光标位置Escape取消并丢弃录音从录音开始到转写结束composer 的 textarea 处于锁定状态确保插入点不会漂移。录音状态由三态机管理idle空闲/recording录音中/transcribing转写中见 useVoiceDictation.ts 中的VoiceDictationStatus类型。该三态机受同步重入锁与 generation 计数器保护——generation 计数用于在组件卸载、草稿切换、取消等场景下使过期的异步续体失效避免产生双重会话等竞态问题录音器的stop()被记忆化memoized并发 stop 调用共享同一个终态结果。麦克风权限获取与恢复权限读取的完整流程点击麦克风按钮后权限检查遵循“先配置校验、后权限校验”的顺序详见 useVoiceDictation.ts 的toggle实现配置守卫先调用hostApi.asr.getConfig()读取 ASR 就绪状态configured。若未配置直接进入引导路径toast 提示并路由到/models?tabvoice权限读取再调用hostApi.asr.getMicrophoneAccess()录音启动权限通过后调用startVoiceRecording()走getUserMedia路径。Main 进程侧的权限读取在 microphone-access.ts 中实现在 macOS / Windows 上调用免弹窗的systemPreferences.getMediaAccessStatus(microphone)其他平台一律返回unknown该调用被 try/catch 包裹读取失败时静默降级录音仍可尝试。权限状态机行为denied / restricted显示本地化的权限引导弹窗不启动采集unknown / not-determined / 读取失败走正常的getUserMedia路径录音中遇到MIC_UNAVAILABLE采集失败会触发再一次权限读取用于捕获“首次使用时拒绝授权”的情况只有当再次读取结果为 denied / restricted 时才用权限引导替换通用错误generation 取消覆盖两次读取——包括组件禁用与卸载时未完成的权限读取会被同步作废。系统设置引导弹窗权限弹窗中显式的hostApi.asr.openMicrophoneSettings()动作只打开Main 进程拥有的固定 URLmacOSx-apple.systempreferences:com.apple.preference.security?Privacy_MicrophoneWindowsms-settings:privacy-microphone不支持的平台Linux 等该动作直接无操作返回{ opened: false }。启动系统设置失败时用户可见提示关闭设置或启动设置都不会触发录音——必须重新点击麦克风按钮此时才会读取到最新的权限状态。restricted 状态通常需要管理员或设备策略变更才能解除。弹窗本体是紧凑、居中、带内边距的卡片包含标题、简短权限说明与关闭/打开设置两个操作。平台细节、重启提示、开发启动方式等详细说明保留在文档中而不塞进弹窗。权限状态的边界不校验签名与硬件权限状态读取不验证应用签名或硬件可用性。macOS 上 Hardened Runtime 下的麦克风采集需要两件事应用及继承的 Helper 的 entitlements 中包含com.apple.security.device.audio-input以及NSMicrophoneUsageDescription用途描述。Mock 的单元/E2E 测试既不会改动 TCC也不会验证签名后的已安装构建——这类测试无法证明真实安装包在 TCC 层面可用。本地 macOS 打包签名身份分裂陷阱这是本功能最值得注意的坑。未进行应用签名的本地打包会保留 Electron 链接器生成的签名IdentifierElectron、flagsadhoc,linker-signed、Info.plistnot bound这与对完整应用包显式 ad-hoc 签名是完全不同的。在观察到的 0.5.7 本地构建中macOS TCC 将 Main 进程的权限读取/请求归属到app.clawx.desktopbundle 身份但 Helper 的 Core Audio 请求被归属到/Applications/ClawX.app/Contents/MacOS/ClawX可执行文件路径身份。结果是在“系统设置”中出现两个 ClawX 麦克风条目其中一个带应用图标、另一个带终端图标。由此产生了一个被确认的误报权限状态Main 返回granted而路径条目实为 deniedgetUserMedia成功、得到一条活跃且未静音的音轨、AudioContext 也在运行但 10 秒探针的 475,136 个采样全部为 0。仅启用路径条目不改采集代码、不重启同样大小的探针得到 473,915 个非零采样。实验中只检查了计数与峰值幅度没有保存或转写任何录音。显式的 MainaskForMediaAccess请求会为 bundle 身份打开真实同意弹窗但不能解决被单独拒绝的路径身份。因此不要把一次成功的权限请求或看似健康的音轨元数据当作打包问题已修复的证据也不要把普通的静音误判为权限拒绝。针对本仓库 electron-builder26.16.0的无证书本地打包正确做法是显式签名完整应用包而非跳过签名pnpm run package:mac:local --arm64 --config.mac.identity- --config.mac.notarizefalseIntel 构建改用--x64。保留现有的 audio-input 与 disable-library-validation entitlements见 entitlements.mac.plist。正式发布构建应保留 Developer ID 签名与公证。用以下命令检查产物与 Helper 的签名codesign -dvv --entitlements - bundle主应用应识别为app.clawx.desktop且 Info.plist 已绑定而不是保留原始 Electron 链接器签名。重建后的签名包验收仍然需要手动验证两点权限拒绝能阻断采集、授权后能拿到真实麦克风输入。重建不会自动清除既有的重复 TCC 条目——永远不要自动重置 TCC 或修改授权。录音与转写链路为什么选择“本地录制 批量转写”ClawX 刻意采用批量转写而非流式转写。原因很实在流式 ASR 没有通用的线上协议——讯飞、Deepgram、AssemblyAI、腾讯每家都有自己的 WebSocket 方言而 OpenAI 的POST {baseUrl}/audio/transcriptions是事实标准被 OpenAI、Groq、SiliconFlow、DeepInfra、Fireworks 以及 whisper.cpp、LocalAI 等本地服务共同采纳。因此 ClawX 的做法是本地录音 → 用户停止时上传一个 WAV 文件 → 插入返回的文本。全程只有一个 30 秒超时、Bearer 鉴权、统一的 HTTP 状态码到错误码映射并且把空结果视为业务错误而非成功。录音管线全部在渲染进程音频采集完全位于渲染进程见 recorder.tsgetUserMedia打开单声道流开启回声消除echoCancellation、噪声抑制noiseSuppression与自动增益autoGainControl一个ScriptProcessorNode4096 采样缓冲驱动管线线性重采样到16 kHz编码为小端 PCM16停止时在前面拼接44 字节 RIFF 头有效音频不足300 ms对应 wav.ts 中的VOICE_MIN_SAMPLE_COUNT即 16000 × 0.3 4800 采样则拒绝该次录音TOO_SHORT。WAV 数学细节见 wav.tsresampleLinear按采样位置线性插值encodePcm16Bytes将 Float32 采样钳制到 [-1, 1] 后按 PCM16 量化负值乘0x8000、正值乘0x7fffbuildWavFile写入标准 RIFF/WAVE 头PCM、单声道、16 位、16 kHz、字节率 32000。录音过程中同一份 PCM 块被折算为RMS 响度钳制到 0–1增益 4×压入useVoiceDictation钩子内的24 采样环形缓冲composer 按钮以120 ms间隔轮询该缓冲绘制5 根波形条见 VoiceDictationButton.tsx高度 4 14 × clamp(level)波形高度实时反映真实响度——静音贴地、说话随音量升高。转写请求两种协议转写请求由 Main 进程的asr模块发起getConfig/saveConfig/transcribe三个动作见 asr-api.ts。协议由AsrConfig.protocol字段选择旧配置无该字段时按normalizeAsrProtocol回退为transcriptions见 presets.ts。transcriptionsmultipart 表单POST {baseUrl}/audio/transcriptions字段为filerecording.wav16 kHz 单声道 PCM16、model以及可选的languageISO-639-1如zh/en未设置时字段整体省略由服务端自动检测。响应取{ text }。实现见 asr-client.ts 的transcribeWav。chatJSON chat completionsPOST {baseUrl}/chat/completions请求体为{ model, stream: false, messages: [{ role: user, content: [{ type: input_audio, input_audio: ... }] }] }。input_audio的编码随预设而变源码中transcribeViaChatCompletions的注释明确说明bailian预设阿里云百炼Model Studio方言——Data URIdata:audio/wav;base64,base64 wav不带独立的format字段其他所有预设自定义端点OpenAI 模式——data里放裸 Base64加format: wav。不发送任何厂商的asr_options。转写结果从choices[0].message.content读取——字符串直接取数组则把其中的文本片段拼接见extractChatContent。两种协议共享 30 秒超时ASR_REQUEST_TIMEOUT_MS 30_000、Bearer 鉴权、同一套状态码→错误码映射以及“空结果 业务错误”的判定。ASR 配置体系配置结构单端点画像配置是单一端点画像不是多账号结构。AsrConfig字段见 contract.ts字段类型说明protocoltranscriptions \| chat线上协议可选缺省按transcriptions处理presetopenai \| groq \| siliconflow \| bailian \| custom提供商预设baseUrlstring服务基地址必填须为 http/https 且非空modelstring模型名必填非空languagestring可选仅transcriptions协议使用预设列表按协议划分ASR_PRESETS_BY_PROTOCOL见 presets.tstranscriptionsopenai/groq/siliconflow/custom默认 baseUrl / modelopenai→https://api.openai.com/v1whisper-1groq→https://api.groq.com/openai/v1whisper-large-v3siliconflow→https://api.siliconflow.cn/v1Qwen/Qwen3-ASR-1.7Bcustom→ 两者均留空chatbailian/custombailian预填https://WorkspaceId.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 模型qwen3-asr-flash用户需替换WorkspaceId占位符。选择预设或切换协议会用默认值覆盖 baseUrl 与 model。URL 后缀规则源码transcribeWav中实现transcriptions协议下标准预设openai/groq/siliconflow自动追加/audio/transcriptions设置界面中 Base URL 字段会渲染不可编辑的该后缀transcriptions协议下custom预设把用户输入的 URL 当作完整请求端点直接使用不追加任何路径因为自定义提供商可能暴露非标准路径chat协议下用户输入的永远是 base URL固定追加/chat/completions。存储与密钥隔离配置存放在独立的 electron-store 文件store 名clawx-asr键asrConfig见 config-store.tsAPI 密钥复用 provider 密钥库账号 id 固定为asr——空字符串清除密钥undefined则保持不动。getConfig只向渲染进程返回hasApiKey布尔值渲染进程从不接触外部端点也永远看不到 API 密钥。所有特权工作请求发送、密钥读取都在 Main 进程通过 host-invoke 注册表以独立asr模块完成且不会向 OpenClaw gateway 推送任何内容。保存时的配置校验saveConfig在落盘前执行validateAsrConfig见 asr-client.ts配置必须是对象、preset必须是已知预设、protocol必须合法未定义则跳过、baseUrl必须是非空字符串且能解析为http:/https:URL、model必须非空任一不满足都抛INVALID_INPUT。设置界面与引导设置入口在Models 页面。Speech-to-text 与图像生成一样都是开发者模式门控的实验表面Chat models 则无条件可用。点击麦克风但配置不完整时toast 提示并路由到/models?tabvoice标准预设openai/groq/siliconflow的 Base URL 字段仅渲染不可编辑的/audio/transcriptions后缀custom预设或chat协议下后缀隐藏选择bailian会渲染两条本地化提示Data URIinput_audio要求带内联文档链接打开阿里云 OpenAI 兼容 ASR 指南与WorkspaceId占位符/地域说明此外 siliconflow 与 bailian 还会渲染获取 API 密钥的提供商控制台链接。错误码体系与国际化Electron 会把抛出的 host 错误拍平成 message 字符串因此 ASR 错误码被序列化进消息格式为ASR:CODE:message再由 errors.ts 的parseAsrErrorCode解析回来正则^ASR:([A-Z_]):匹配后还要在白名单ASR_ERROR_CODES中确认。可识别错误码AsrErrorCodeAUTH401/403、RATE_LIMITED429、SERVER≥500、REQUEST其余 HTTP 错误兼作回退兜底——由assertResponseOk按状态码映射NETWORK超时/网络失败由fetchWithTimeout抛出EMPTY_RESULT空响应/无文本INVALID_INPUT配置或 WAV 载荷非法NOT_CONFIGURED未配置就发起转写。每个错误码映射到 composer toast 与设置表单中逐码的 i18n 文案。录音侧另有MIC_UNAVAILABLE与TOO_SHORT两个本地错误码VoiceRecorderErrorCode见 recorder.ts。macOS 打包声明electron-builder.yml 的 mac 段声明了NSMicrophoneUsageDescription: ClawX requires microphone access for voice featuresentitlements.mac.plist 在应用与继承的 Helper entitlements 中启用了com.apple.security.device.audio-inputHardened Runtime 采集必需以及com.apple.security.cs.disable-library-validation。用途描述只负责解释 TCC 弹窗不能替代签名 entitlements。关键设计Chromium 的用户触发型getUserMedia路径会自行请求同意所以 Main 进程不需要显式askForMediaAccess调用默认窗口会话也不需要权限处理器——web-browser-session.ts 中的 deny-all 处理器只管辖嵌入式浏览器的 guest 会话。测试覆盖分层验证测试严格对应分层架构WAV 纯数学重采样、PCM16 编码、RIFF 头字节与录音器基于 fakeAudioContext图含 double-stop 竞态有单元测试hook 层使用 fake timers 验证 180 秒上限与 250 ms 计时 tick常量见 useVoiceDictation.tsVOICE_MAX_RECORDING_MS 180_000、VOICE_TIMER_INTERVAL_MS 250、VOICE_LEVEL_HISTORY 24Main 客户端stubfetch覆盖状态码映射与 multipart 形态设置表单与 Models 标签页有组件测试voice-dictation.spec.ts 覆盖两条端到端路径插入光标处的 happy path、未配置时的引导路径——通过installIpcMocksmockasrhost 动作并用 oscillator 支撑的流 stubgetUserMedia转写结果常量TRANSCRIBED_TEXT voice dictation result。权限被拒/恢复路径同样有覆盖首次使用拒绝与再次授权恢复。这些 E2E 用例是普通并行测试麦克风始终被 mock不触碰任何 OS 全局状态因此不需要exclusive标签。开发者模式覆盖还验证了模式关闭时 composer 麦克风与 Speech-to-text 标签页均隐藏开启后可见。总结与排查清单录音无声先检查“系统设置 → 隐私与安全 → 麦克风”中是否有两个 ClawX 条目本地未签名构建尤其要确认 Helper 的路径身份是否被拒打包修复无证书本地打包用pnpm run package:mac:local --arm64 --config.mac.identity- --config.mac.notarizefalseIntel 用--x64显式签名完整包再用codesign -dvv --entitlements - bundle确认主应用为app.clawx.desktop且 Info.plist 已绑定权限误报getUserMedia成功不代表权限真实可用以“探针采样是否非零”验证真实采集而不是依赖音轨元数据配置检查baseUrl必须可解析为 http(s)model非空transcriptions协议下custom预设的 URL 是全端点chat协议下永远追加/chat/completions错误排查转写失败信息以ASR:CODE:message形式出现对照AUTH/RATE_LIMITED/SERVER/NETWORK/EMPTY_RESULT/INVALID_INPUT/NOT_CONFIGURED/REQUEST逐码定位。赞分享人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载相关推荐AIRI 接入 Xiaomi MiMo 语音转写ASR/STT完整指南API Key、模型配置与麦克风转写实战AIRI 接入 Xiaomi MiMo 语音转写ASR/STT完整指南API Key、模型配置与麦克风转写实战 本指南以 AIRI 项目文档中关于 XiaAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染AIRI 语音转写接入 CometAPI从 API Key 配置到麦克风实时听写全指南AIRI 语音转写接入 CometAPI从 API Key 配置到麦克风实时听写全指南 CometAPI 是一个提供统一模型网关与凭据管理的云端服务AIRIAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染gpt_academic 实时语音交互实战阿里云 ASR 配置、麦克风授权与电脑音频截获完整指南gpt_academic 实时语音交互实战阿里云 ASR 配置、麦克风授权与电脑音频截获完整指南 gpt_academic 的音频交互功能让您可以完全脱离键盘人工智能大模型AI 应用交互助手上一篇如何通过HsMod插件实现炉石传说游戏效率革命下一篇NCPs项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
