⚠️ 已弃用 — 该技能已拆分为两个独立技能,以提升模块化程度:**webchat-https-proxy**(HTTPS/WSS 反向代理)和 **webchat-voi...**
WebChat Voice 代理服务器
功能概述
WebChat Voice 代理服务器是一项面向实际任务的技能,主要用于为 OpenClaw WebChat 设置一个可重开安全语音堆栈( 包括当前抛光的 mic/ stop/hour glass UI 状态):. .;HTTPS Control UI on port 8443./ translacy 代理服务器到本地。
核心要点
- 它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
- 使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。
- 从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
使用与执行
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;
结果检查与注意事项
涉及批量任务时,还应保存进度,避免中断后重复操作。该技能适合用于一次性任务,也可以接入自动化工作流,与其他技能或上层代理配合完成更完整的业务链路;在组合使用时,应明确每一步的输入输出关系,并避免不同步骤之间出现参数冲突。
WebChat 语音代理
为 OpenClaw WebChat 部署一套重启安全的语音栈(包含当前优化的麦克风/停止/沙漏 UI 状态):
- HTTPS 控制界面,运行于端口 8443
/transcribe代理至本地 faster-whisper 服务- WebSocket 直通网关(
ws://127.0.0.1:18789) - 将语音按钮脚本注入控制界面
- 实时音量表(VU meter):按钮阴影与缩放随语音强度动态变化
- 按键讲话(Push-to-Talk):按住麦克风按钮录音,松开即发送(默认模式)
- 切换模式(Toggle mode):单击开始录音,再次单击停止并转录(双击麦克风按钮可切换模式)
- 键盘快捷键:
Ctrl+Space触发 Push-to-Talk;Ctrl+Shift+M启动/停止连续录音 - 本地化 UI:自动检测浏览器语言(内置英文、德文、中文),支持自定义
前提条件(必需)
本功能依赖一个本地 faster-whisper HTTP 服务。默认预期如下:
- URL:
http://127.0.0.1:18790/transcribe - systemd 用户服务:
openclaw-transcribe.service
部署前请验证:
systemctl --user is-active openclaw-transcribe.service
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18790/transcribe -X POST -H 'Content-Type: application/octet-stream' --data-binary 'x'
若该依赖缺失,请先完成 faster-whisper 的部署(含模型加载 + HTTP 接口),再运行本功能。
相关功能模块:
faster-whisper-local-service(后端前置依赖)webchat-voice-full-stack(元安装器,同时部署后端与代理)
工作流程
- 确认转录服务已存在且正在运行(
openclaw-transcribe.service)。 - 将
voice-input.js部署至控制界面静态资源目录,并在index.html中注入标签。 - 配置网关允许的外部 HTTPS UI 来源(allowed origin)。
- 以持久化用户级 systemd 服务方式运行 HTTPS+WSS 代理(
openclaw-voice-https.service)。 - 依次排查并解决配对(pairing)、令牌(token)、来源(origin)等错误。
安全说明
- 默认仅限本地回环(localhost):HTTPS 代理默认仅绑定到
127.0.0.1。除非显式设置VOICE_HOST为局域网 IP,否则网络中其他设备无法访问。 - 局域网暴露风险:设置
VOICE_HOST=将使代理(连同网关 WebSocket 和转录端点)对整个局域网可见。仅应在可信网络中启用此配置。 - 持久化机制:本功能安装一个用户级 systemd 服务(
openclaw-voice-https.service),开机自动启动;并安装一个网关钩子(gateway hook),在控制界面更新后自动重新注入 UI 脚本。如需彻底回退,请使用uninstall.sh。 - 自签名 TLS:自动生成的证书不被浏览器信任,首次访问时将出现证书警告。
部署
运行(仅限本机访问 —— 默认配置,最安全):
bash scripts/deploy.sh
或开放至局域网(需从其他设备访问时启用):
VOICE_HOST=10.0.0.42 VOICE_HTTPS_PORT=8443 VOICE_LANG=de bash scripts/deploy.sh
若交互式运行且未指定 VOICE_LANG,脚本将提示选择 UI 语言(auto、en、de、zh)。设置 VOICE_LANG=auto 可跳过该提示。
本脚本具备幂等性(idempotent)。
快速验证
执行:
bash scripts/status.sh
预期结果:
- 两项服务均处于 active 状态
- 脚本注入已生效
- HTTPS 访问返回
https:200
常见问题修复
404 /chat?...→ HTTPS 代理缺少 SPA fallback 配置。origin not allowed→ 确保部署时使用了正确的VOICE_HOST,并在gateway.controlUi.allowedOrigins中添加了匹配的 HTTPS 来源。token missing→ 使用带?token=...参数的 URL 打开一次页面。pairing required→ 通过命令openclaw devices approve批准待处理设备。--token - 重启后麦克风失效 → 证书路径必须持久化(不可使用
/tmp等临时路径)。 - 无转录结果 → 首先检查本地 faster-whisper 端点是否正常响应。
具体命令详见 references/troubleshooting.md。
本功能所修改的内容
安装前,请知悉 deploy.sh 将对系统进行的所有变更:
| 内容 | 路径 | 操作 |
|---|---|---|
| 控制界面 HTML | |
添加 标签以加载 voice-input.js |
| 控制界面静态资源 | |
复制麦克风按钮 JS 脚本 |
| 网关配置 | ~/.openclaw/openclaw.json |
向 gateway.controlUi.allowedOrigins 添加 HTTPS 来源 |
| systemd 服务 | ~/.config/systemd/user/openclaw-voice-https.service |
创建并启用持久化的 HTTPS 代理服务 |
| 网关钩子(hook) | ~/.openclaw/hooks/voice-input-inject/ |
安装启动钩子,在控制界面更新后自动重注入 JS |
| 工作区文件 | ~/.openclaw/workspace/voice-input/ |
复制 voice-input.js 与 https-server.py |
| TLS 证书 | ~/.openclaw/workspace/voice-input/certs/ |
首次运行时自动生成自签名证书 |
注入的 JS(voice-input.js)在控制界面内运行,并与聊天输入框交互。部署前请务必审阅其源码。
麦克风按钮控制方式
| 操作 | 效果 |
|---|---|
| 长按(PTT 模式) | 按住期间录音,松开后触发转录 |
| 单击(Toggle 模式) | 开始录音 / 停止并转录 |
| 双击 | 在 PTT 与 Toggle 模式间切换 |
| 右键 | 开启/关闭提示音(beep) |
| Ctrl+Space(长按) | 键盘版 Push-to-Talk(即使文本框处于焦点状态亦可工作) |
| Ctrl+Shift+M | 启动/停止录音(停止时触发转录) |
| Ctrl+Shift+B | 启动/停止实时转录 [beta] — 文本实时显示,2 秒审查后自动发送,5 秒静音或识别到关键词 “Stop Hugo” 时自动停止 |
当前模式及可用操作将在鼠标悬停时以按钮 tooltip 形式显示。
语言 / 国际化(i18n)
UI 自动检测浏览器语言,并以对应语言显示 tooltip、toast 提示及 placeholder 文本。
内置语言:英语(en)、德语(de)、中文(zh)
覆盖语言设置
可在浏览器控制台中设置语言覆盖:
localStorage.setItem('oc-voice-lang', 'de'); // 强制德语
localStorage.setItem('oc-voice-lang', 'zh'); // 强制中文
localStorage.removeItem('oc-voice-lang'); // 恢复自动检测
随后刷新页面即可生效。
添加自定义语言
编辑 voice-input.js,向 I18N 对象新增条目。可参考 assets/i18n.json 模板 —— 其中包含全部翻译键(translation keys)及内置语言的对应译文。
以添加法语为例:
const I18N = {
// ... 已有条目 ...
fr: {
tooltip_ptt: "Maintenir pour parler",
tooltip_toggle: "Cliquer pour démarrer/arrêter",
tooltip_next_toggle: "Mode clic",
tooltip_next_ptt: "Push-to-Talk",
tooltip_beep_off: "Désactiver le bip",
tooltip_beep_on: "Activer le bip",
tooltip_dblclick: "Double-clic",
tooltip_rightclick: "Clic droit",
toast_ptt: "Push-to-Talk",
toast_toggle: "Mode clic",
toast_beep_on: "Bip activé",
toast_beep_off: "Bip désactivé",
placeholder_suffix: " — Voix : (Ctrl+Espace Push-To-Talk, Ctrl+Shift+M enregistrement continu)"
}
};
编辑完成后,运行 bash scripts/deploy.sh 以将更新后的 JS 复制至控制界面。
CORS 策略
/transcribe 代理端点使用可配置的 Access-Control-Allow-Origin 响应头。
可通过设置环境变量 VOICE_ALLOWED_ORIGIN 进行限制。默认值为:https://。
卸载
如需彻底回退所有变更:
bash scripts/uninstall.sh
该脚本将执行以下操作:
- 停止并移除
openclaw-voice-https.service - 移除网关启动钩子
- 从控制界面删除
voice-input.js并撤销index.html中的注入 - 从网关配置中移除 HTTPS 来源
- 重启网关
- 删除 TLS 证书
- 删除工作区运行时文件(
voice-input.js、https-server.py、i18n.json)
注意:卸载过程不会影响 faster-whisper 后端 —— 如需一并移除,请单独通过 faster-whisper-local-service 卸载。
热门AI工具
相关专题
本专题介绍Gradle插件开发的基本流程,涵盖插件类编写、自定义任务注册、扩展参数设计和插件应用方法,帮助你理解插件如何组织构建逻辑,减少多个项目之间的重复配置。
0
2026.10.22
本专题介绍Gradle Wrapper的基本作用,涵盖文件组成、生成方法、版本配置和任务调用,帮助你理解项目如何使用指定的Gradle版本,减少不同开发环境带来的构建差异。
0
2026.10.22
本专题整理Golangci-lint常用Linters的用途与配置方法,覆盖错误处理、无效代码、安全、复杂度、命名和依赖检查,帮助项目合理选规则。
0
2026.10.22
本专题介绍Gradle Java项目构建方法,涵盖Java插件配置、依赖声明、源码编译、测试执行和打包检查,帮助你理解各阶段的任务关系,逐步完成项目构建。
0
2026.10.22
本专题汇总PHP常见时间戳漏洞,包括2038年溢出、时区漂移、时间戳伪造、重放攻击、时间盲注与日志审计失效等,并给出升级64位环境、使用 DateTimeImmutable、统一UTC、严格超时校验、预处理绑定、hash_equals 比对等修复方案,帮助开发者快速排查和加固时间相关代码。
0
2026.10.22
本专题聚焦Golangci-lint YAML配置文件,讲清运行参数、规则启停、目录排除、问题过滤及严重级别设置,便于团队统一检查标准。
0
2026.10.22
本专题讲解Golangci-lint的安装、初始化、基础命令和首次代码检查,覆盖本地环境、Docker及多平台用法,帮助Go开发者快速上手。
0
2026.10.22
PHP2Shell漏洞是什么,哪些PHP版本和运行环境会受到影响,服务器应该如何检测与修复?本专题提供版本自查脚本、Linux与Docker升级命令、PHP-FPM和Apache排查步骤,以及修复验证、临时缓解和应急响应方案。
0
2026.10.22
热门下载
相关下载
精品课程
共6课时 | 12.1万人学习
共79课时 | 161.5万人学习
共6课时 | 54.7万人学习
