OpenWhispr CLI 完全指南：本地桌面桥接与云端 API 双后端命令行实战

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）管理。

关键设计在于同一套命令既可以跑在本地桌面应用上，也可以跑在云端：

从用户视角看两个后端的行为完全一致，差异只在数据源。

后端选择顺序

CLI 按以下优先级决定使用哪个后端（先命中者优先）：

1. 命令行上的--local或--remote标志；
2. 环境变量OPENWHISPR_BACKEND（取值local、remote或auto）；
3. ~/.openwhispr/cli-config.json中的backend键；
4. 自动探测：本地桥可用则用本地；否则若配置了 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 字节随机 token（crypto.randomBytes(32).toString("hex")），写入桥文件；每个请求必须携带Authorization: Bearer <token>，并用crypto.timingSafeEqual做常量时间比较，防时序攻击；
• 回环校验：请求来源地址必须是127.0.0.1、::1或::ffff:127.0.0.1（LOOPBACK_ADDRESSES），否则直接返回 403；
• 文件权限：写入桥文件时显式指定mode: 0o600，并在创建后再执行一次chmodSync(..., 0o600)以兼容忽略 mode 参数的文件系统；
• 请求体限制：MAX_REQUEST_BODY_BYTES = 1 * 1024 * 1024（1 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）隔离授权。请按需匹配命令所需的最小作用域：

作用域由服务端强制执行，CLI 本地不做校验。缺少作用域时 API 返回 401/403，CLI 以退出码 3 结束。

仓库侧的 src/constants/apiKeys.ts 印证了作用域体系：API_SCOPES定义了 8 个可见作用域，而usage:read属于每个 key 隐式授予的作用域（IMPLICIT_SCOPES），不显示在 UI 中；单用户最多持有 5 个 key（MAX_API_KEYS = 5）；key 可配置过期时间（永不/30/60/90 天/1 年）。

五、输出格式与退出码

输出格式

CLI 自动检测 stdout 是否为 TTY：

• TTY→ 人类可读输出（列表为表格，单资源为 markdown 或纯文本）；
• 管道/重定向→ JSON；
• 可用--format <fmt>覆盖，各命令支持的值不同：
  • 列表类（notes list、notes search、folders list、transcriptions list）：json|table
  • notes get：json|markdown
  • transcriptions get：json|text
  • notes 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。

退出码

脚本或错误恢复逻辑必须遵守以下退出码约定：

六、命令参考：名词-动词语法

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.com

config 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权限：

CLI 写入这两个文件时都会设置0600权限。若发现权限过宽（例如手动编辑过），请用chmod 0600 <file>收紧。桌面侧同样在启动时对桥文件执行双重 0600 设置（写入 mode 参数 + 事后 chmod），详见 cliBridge.js。

九、程序化调用规范

在程序中调用 CLI 时：

1. 始终传--format json并解析 stdout；
2. 先检查退出码——非零码（1–4）的含义见上文退出码表；
3. 出错时 CLI 向stderr写入纯文本消息（不是 JSON）并以对应码退出，请单独捕获 stderr 以便向用户展示；
4. 成功的列表/搜索响应打印的是裸 JSON 数组（CLI 会剥离 API 的{data: [...]}外壳），所以用jq '.[]'而不是jq '.data[]'；单资源查询打印的是裸对象。

这一点同样与本地桥的实现一致：桥接路由如GET /v1/notes/list在内部返回{data: notes, has_more: false, next_cursor: null}信封结构，由 CLI 层负责剥壳后输出。

十、故障排查速查表

十一、源码与测试路线图

如果你想深入理解 CLI 背后的实现，以下仓库路径是最佳入口：

• src/helpers/cliBridge.js：本地桥 HTTP 服务的完整实现（认证、路由、校验、文件权限）；
• test/helpers/cliBridgeTranscribe.test.js：终端转写路由的测试（模型选择、静音处理、路径校验）；
• test/helpers/cliBridgeRequestBody.test.js：请求体字节限制与多字节编码处理的测试；
• src/constants/apiKeys.ts：API Key 作用域定义与隐式作用域逻辑；
• src/components/CliIntegrationCard.tsx：桌面应用内的 CLI 集成引导 UI；
• CHANGELOG.md：CLI 桥相关演进历史（如 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