OpenWhispr CLI 完全指南本地桌面桥接与云端 API 双后端命令行实战【免费下载链接】openwhisprVoice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.项目地址: https://gitcode.com/GitHub_Trending/op/openwhispr本指南以 OpenWhispr 仓库中的 CLI 技能文档agent-skills/openwhispr-cli/SKILL.md为核心系统讲解openwhispr命令行工具的全部能力单二进制同时对接桌面应用本地桥接与云端 REST API、notes/folders/transcriptions/audio 全套管理命令、认证与配置、脚本化与程序化调用规范。读完本文你将能够在终端中完整地管理 OpenWhispr 的笔记与转写数据并把 CLI 接入自己的自动化脚本或 Agent 工作流。一、CLI 是什么一条命令两个后端OpenWhispr 是一个语音转文字dictation应用支持本地模型Nvidia Parakeet、Whisper 等与云端模型BYOK。openwhispr命令行工具npm 包openwhispr/cli以单一二进制形式对终端用户暴露操作 OpenWhispr 笔记、文件夹、转写记录与音频的全部能力同时包含认证auth与配置config管理。关键设计在于同一套命令既可以跑在本地桌面应用上也可以跑在云端后端通信对象适用场景local桌面应用的 loopback HTTP 桥监听127.0.0.1桌面应用正在运行。录制期间/刚结束时数据以本地为准remotehttps://api.openwhispr.com/api/v1桌面已关闭或在另一台机器上运行或需要云端语义从用户视角看两个后端的行为完全一致差异只在数据源。后端选择顺序CLI 按以下优先级决定使用哪个后端先命中者优先命令行上的--local或--remote标志环境变量OPENWHISPR_BACKEND取值local、remote或auto~/.openwhispr/cli-config.json中的backend键自动探测本地桥可用则用本地否则若配置了 API Key 则用云端再否则报错并给出引导提示。二、安装与版本要求npm install -g openwhispr/cli要求Node.js 20 或更高版本。安装后用openwhispr --version验证。若用户反馈command not found通常是 npm 全局 bin 目录不在$PATH中检查并补充路径即可。桌面应用内也内置了 CLI 集成入口在应用的 Integrations 页面中CliIntegrationCard.tsx 会直接展示安装命令、本地用法示例openwhispr --local notes list与云端登录命令openwhispr auth login并附一键复制按钮方便用户在应用内快速上手。三、本地后端零配置的桌面桥接当桌面应用启动时它会自动在~/.openwhispr/cli-bridge.json写入{version, port, token}三个字段文件权限为0600。CLI 启动时自动读取该文件。如果文件缺失或内容过期本地后端将被视为不可用。源码级原理CliBridge 的实现细节本地桥接并非虚拟概念而是由仓库中的 src/helpers/cliBridge.js 真实实现的 HTTP 服务。从源码可以看到几个关键设计端口范围服务在8200–8219范围内扫描可用端口PORT_RANGE_START 8200、PORT_RANGE_END 8219绑定地址固定为127.0.0.1令牌认证每次启动生成 32 字节随机 tokencrypto.randomBytes(32).toString(hex)写入桥文件每个请求必须携带Authorization: Bearer token并用crypto.timingSafeEqual做常量时间比较防时序攻击回环校验请求来源地址必须是127.0.0.1、::1或::ffff:127.0.0.1LOOPBACK_ADDRESSES否则直接返回 403文件权限写入桥文件时显式指定mode: 0o600并在创建后再执行一次chmodSync(..., 0o600)以兼容忽略 mode 参数的文件系统请求体限制MAX_REQUEST_BODY_BYTES 1 * 1024 * 10241 MiB按UTF-8 字节数计数而非 JavaScript 字符数超限直接拒绝并销毁请求优雅启停start()启动服务并写桥文件stop()关闭服务并删除桥文件避免留下过期凭据。测试 test/helpers/cliBridgeRequestBody.test.js 验证了这些边界一个 30 万 emoji 的请求体在字符数上小于 1 MiB、但字节数超出限制时会被拒绝返回 400validation_error多字节字符如「日本語のノート」被拆分到多个网络 chunk 时内容不损坏恰好等于 1 MiB 的请求体被正常接受。本地桥的路由表从 cliBridge.js 的路由表可以看出本地桥暴露了完整的 v1 REST 接口包括笔记、文件夹、字典、片段snippets与转写相关路由。其中值得注意的实现细节创建/更新笔记后会通过broadcastToWindows广播note-added/note-updated事件、触发向量索引 upsert 与镜像写入保证桌面 UI 实时同步字典与片段更新采用增量delta语义传入add/remove数组导入操作不会误删未提及的词条或片段删除类操作返回 HTTP 204 空响应体。终端转写音频不跨桥本地桥最强大的能力之一是终端转写POST /v1/transcribe。由于 CLI 与桌面应用运行在同一台机器上CLI 只需发送音频文件路径由应用自己读取文件——音频数据从不经过桥接通道用户下载的本地模型whisper.cpp、Parakeet、Nemotron、Cohere、Orukeet直接完成识别。GET /v1/transcribe/models列出所有本地模型及其下载状态。根据测试 test/helpers/cliBridgeTranscribe.test.js 可确认的行为不传model时使用应用当前默认模型传model时精确匹配匹配前会先校验文件存在且为普通文件指定了未下载或未知模型时返回校验错误如Unknown model nope. Available: base, large, parakeet-tdt-0.6b-v3识别到静音时返回空文本加warning: No speech detected而不是报错应用未选择任何本地模型时会给出明确提示请到Settings → Transcription选择模型或显式传model。此能力正是openwhispr/cli0.3.0 中openwhispr transcribe file命令的底层支撑见 CHANGELOG.md。四、远程后端API Key 认证使用云端后端需要先在桌面应用的Integrations API Keys页面生成一个 API Key然后执行openwhispr auth login # 提示输入 key以 0600 权限存入 ~/.openwhispr/cli-config.json openwhispr auth status # 确认配置生效 openwhispr auth logout # 清除配置API Key 在服务端按作用域scope隔离授权。请按需匹配命令所需的最小作用域Scope允许的命令notes:readnotes list/get/search、folders listnotes:writenotes create/update/delete、folders createtranscriptions:readtranscriptions list/gettranscriptions:deletetranscriptions deleteusage:read供doctor与云端可达性探测内部使用作用域由服务端强制执行CLI 本地不做校验。缺少作用域时 API 返回 401/403CLI 以退出码 3 结束。仓库侧的 src/constants/apiKeys.ts 印证了作用域体系API_SCOPES定义了 8 个可见作用域而usage:read属于每个 key 隐式授予的作用域IMPLICIT_SCOPES不显示在 UI 中单用户最多持有 5 个 keyMAX_API_KEYS 5key 可配置过期时间永不/30/60/90 天/1 年。五、输出格式与退出码输出格式CLI 自动检测 stdout 是否为 TTYTTY→ 人类可读输出列表为表格单资源为 markdown 或纯文本管道/重定向→ JSON可用--format fmt覆盖各命令支持的值不同列表类notes list、notes search、folders list、transcriptions listjson|tablenotes getjson|markdowntranscriptions getjson|textnotes create、notes update、folders create无--format标志——总是把创建/更新后资源的完整 JSON 输出到 stdout删除类变更notes delete、transcriptions delete、audio delete与状态类命令auth status、config get、doctor、version--format json用于机器输出否则为人类可读文本程序化解析 CLI 输出时务必始终传--format json。退出码脚本或错误恢复逻辑必须遵守以下退出码约定码含义恢复建议0成功继续1用户错误参数错误、缺少必填标志修正命令后重跑2后端不可达启动桌面应用或为云端执行auth login或显式指定--remote/--local3认证失败key 缺失/无效、作用域不足不要重试——直接告知用户4未找到笔记/转写/文件夹不存在检查 ID 后重跑六、命令参考名词-动词语法CLI 采用openwhispr noun verb的名词-动词语法与gh、kubectl、aws、stripe等工具保持一致。Notes笔记openwhispr notes list [--folder id] [--limit N] [--format json|table] openwhispr notes get id [--format json|markdown] openwhispr notes create --content text | --content-file path [--title t] [--folder id] openwhispr notes update id [--content t] [--folder id] [--title t] openwhispr notes delete id [--dry-run] [--format json] openwhispr notes search query [--limit N] [--format json|table]Folders文件夹openwhispr folders list [--format json|table] openwhispr folders create --name name [--sort-order n]文件夹名在同一用户内必须唯一。重复创建返回 409 等价结果退出码 1 并附清晰错误消息。Transcriptions转写记录openwhispr transcriptions list [--limit N] [--format json|table] openwhispr transcriptions get id [--format json|text] openwhispr transcriptions delete id [--dry-run] [--format json]--format text返回纯转写文本正文。SRT/VTT 字幕导出目前未在 CLI 中开放需要带时间戳的字幕格式时请用--format json获取后自行后处理。Audio音频openwhispr audio delete transcription-id [--format json]仅限本地后端。云端 API 不存储音频。若以--remote运行此命令会返回明确的 not supported 错误退出码 1。从源码看本地桥的音频删除路由DELETE /v1/transcriptions/id/audio在删除音频文件后还会同步更新转写记录中的hasAudio、audioDurationMs、provider、model字段。Auth认证openwhispr auth login [--api-key key] # 省略 --api-key 时从 stdin 提示输入 openwhispr auth status [--format json] openwhispr auth logout注意auth status只读取已存配置、报告是否配置了 key不会发起网络调用。要真正验证 key 是否可用请使用openwhispr doctor。Config配置openwhispr config get [--format json] openwhispr config set backend auto|local|remote openwhispr config set api-base https://api.openwhispr.comconfig set只能设置backend与api-base两个键API Key 通过auth login/auth logout管理。api-base可覆盖以适配自托管或 staging 部署默认为生产云地址单次调用也可用环境变量OPENWHISPR_API_BASE覆盖。Doctor诊断openwhispr doctor [--format json]同时探测两个后端并分别报告状态。只要有一个可达即退出码 0两个都不可达退出码 2。当用户反馈CLI 不工作时优先运行此命令——它能快速定位问题出在桌面桥、API Key 还是其他环节。Version版本openwhispr --version # 或openwhispr version七、实用工作流批量笔记操作将notes list --format json通过jq过滤再迭代处理openwhispr notes list --limit 100 --format json | \ jq -r .[] | select(.title | contains(draft)) | .id | \ while read id; do openwhispr notes delete $id done写笔记前搜索上下文openwhispr notes search quarterly budget --format json | jq .[].id用返回的 ID 通过notes get读取相关笔记再撰写新笔记的内容。八、配置文件CLI 读写以下两个文件两者都应保持0600权限文件写入方内容~/.openwhispr/cli-bridge.json桌面应用启动时{version, port, token}供 loopback 桥使用~/.openwhispr/cli-config.jsonCLI 的auth login与config set{backend, apiBase, apiKey}CLI 写入这两个文件时都会设置0600权限。若发现权限过宽例如手动编辑过请用chmod 0600 file收紧。桌面侧同样在启动时对桥文件执行双重 0600 设置写入 mode 参数 事后 chmod详见 cliBridge.js。九、程序化调用规范在程序中调用 CLI 时始终传--format json并解析 stdout先检查退出码——非零码1–4的含义见上文退出码表出错时 CLI 向stderr写入纯文本消息不是 JSON并以对应码退出请单独捕获 stderr 以便向用户展示成功的列表/搜索响应打印的是裸 JSON 数组CLI 会剥离 API 的{data: [...]}外壳所以用jq .[]而不是jq .data[]单资源查询打印的是裸对象。这一点同样与本地桥的实现一致桥接路由如GET /v1/notes/list在内部返回{data: notes, has_more: false, next_cursor: null}信封结构由 CLI 层负责剥壳后输出。十、故障排查速查表症状可能原因修复每条命令都报Backend unreachable退出码 2桌面未启动且未配置 API Key启动桌面应用或执行openwhispr auth login仅远程命令报Auth failed退出码 3API Key 被吊销、过期或缺少作用域以正确作用域重新生成 key已知存在的笔记报Not found退出码 4后端选错——笔记在另一侧尚未同步尝试相反后端--local或--remote配置文件可被其他用户读取文件由 CLI 之外创建或编辑chmod 0600 ~/.openwhispr/cli-config.json十一、源码与测试路线图如果你想深入理解 CLI 背后的实现以下仓库路径是最佳入口src/helpers/cliBridge.js本地桥 HTTP 服务的完整实现认证、路由、校验、文件权限test/helpers/cliBridgeTranscribe.test.js终端转写路由的测试模型选择、静音处理、路径校验test/helpers/cliBridgeRequestBody.test.js请求体字节限制与多字节编码处理的测试src/constants/apiKeys.tsAPI Key 作用域定义与隐式作用域逻辑src/components/CliIntegrationCard.tsx桌面应用内的 CLI 集成引导 UICHANGELOG.mdCLI 桥相关演进历史如 UTF-8 修复 #1386/#1777、终端转写 #2121、字典管理 #1366、字典与片段路由 #2119。综上OpenWhispr CLI 以一套命令、双后端的设计把桌面应用的本地数据与云端 API 统一到了同一种终端体验之下配合--format json、约定退出码和 stderr 错误输出它可以稳定嵌入任何脚本与 Agent 自动化流水线。【免费下载链接】openwhisprVoice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.项目地址: https://gitcode.com/GitHub_Trending/op/openwhispr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考