配置参考

OpenASR 的所有配置都保存在本地目录中，不会同步到任何服务器，也不包含遥测。本页介绍配置文件结构、命令行配置工具、环境变量，以及 API 密钥管理。

`OPENASR_HOME` 目录

OpenASR 的数据和配置统一存放在一个本地主目录下，解析顺序如下：

环境变量 OPENASR_HOME（若已设置且非空）；
否则回退到 $HOME/.openasr（Windows 上依次尝试 HOME 和 USERPROFILE）。

如果两者均无法解析，程序会报错退出：

Could not determine the OpenASR home directory. Set OPENASR_HOME to a writable directory.

目录结构

~/.openasr/
├── config.json              # 配置/偏好设置
├── apikeys.json             # API 密钥存储（仅保存哈希值）
├── catalog.json             # 缓存的模型目录
├── pairing-registry.json    # 远程计算配对注册表
├── tls-identity.json        # --tls-self-signed 生成的自签名 TLS 身份
├── models/                  # 已安装的 .oasr 模型包
├── history/                 # 守护进程转写/直播历史
└── diarize/
    └── voiceprints.json     # 说话人声纹档案（仅嵌入向量）

`openasr config` 子命令

通过命令行读写 config.json 中的顶层配置键：

openasr config list            # 打印当前已保存的配置
openasr config get <key>       # 查看某个键的值
openasr config set <key> <value>  # 设置某个键
openasr config unset <key>     # 删除某个键（恢复为默认值）

可用配置键

仅以下四个键可通过 openasr config set 设置，使用未知键名会报错：

Unknown config key ‘<key>’. Use one of: default_model, default_backend, media.ffmpeg_bin, download_source.

键	说明	默认值	校验规则
`default_model`	默认模型	`qwen3-asr-0.6b`	必须是已知的模型标识，否则拒绝
`default_backend`	默认后端	`native`	仅接受 `mock` 或 `native`
`media.ffmpeg_bin`	ffmpeg 二进制路径	（无）	与 `--ffmpeg-bin` / `OPENASR_FFMPEG_BIN` 等效
`download_source`	模型下载源	`auto`	仅接受 `auto`、`hf`、`hf-mirror`、`weights`

`config.json` 完整结构

config.json 由上述四个顶层键和一个嵌套的 preferences 对象组成。注意：preferences.* 字段无法通过 openasr config set 修改，它们由桌面应用或服务端的 PUT /v1/config 接口管理。以下列出完整字段供参考：

{
  "default_model": "qwen3-asr-0.6b",
  "default_backend": "native",
  "media.ffmpeg_bin": null,
  "download_source": "auto",
  "preferences": {
    "version": 1,
    "language": null,
    "diarize": false,
    "word_timestamps": false,
    "auto_save": false,
    "launch_at_login": false,
    "tray_icon": true,
    "output_dir": null,
    "hotwords": [],
    "hotword_boost": null,
    "theme": "system",
    "accent_color": null,
    "density": "comfortable",
    "dictation_shortcut": "Alt",
    "push_to_talk": true,
    "inference_threads": null,
    "quant_preference": "auto",
    "execution_target": "auto",
    "history_retention": "last5",
    "idle_unload": "10m"
  }
}

其中两个字段值得展开说明：

history_retention：控制转写历史的保留策略。可选值为 off（不保留，切换时清除已有记录）、last5（保留最近 5 条，默认）、week、month、quarter、year、forever。
idle_unload：模型闲置多久后从内存中卸载（模型包保留在磁盘上，下次请求重新加载即可）。可选值为 never、now（约 5 秒）、2m、10m（默认）、1h。
inference_threads：推理线程数，取值 1–256。留空则自动决定。

环境变量

以下 OPENASR_* 环境变量面向用户和脚本，可在 shell 或容器环境中使用。环境变量的优先级高于 config.json 中的对应配置。

变量	说明
`OPENASR_HOME`	覆盖 OpenASR 主目录路径
`OPENASR_MODEL`	默认模型标识，等效于 `-m/--model`
`OPENASR_ADDR`	`openasr serve` 的监听地址，默认 `127.0.0.1:8080`
`OPENASR_ASSUME_YES`	等效于 `-y/--yes`，自动确认缺失模型的下载提示
`OPENASR_OFFLINE`	等效于 `--offline`/`--no-pull`，禁止下载，模型缺失时直接报错退出
`OPENASR_FFMPEG_BIN`	ffmpeg 路径，等效于 `--ffmpeg-bin` / `media.ffmpeg_bin`
`OPENASR_HF_TOKEN`	Hugging Face 认证令牌（也接受 `HF_TOKEN`、`HUGGING_FACE_HUB_TOKEN`）
`OPENASR_DOWNLOAD_SOURCE`	下载源，与 `download_source` 配置键取值相同
`OPENASR_CATALOG_URL`	覆盖模型目录 URL 或本地目录路径
`OPENASR_API_KEYS_PATH`	覆盖 API 密钥存储路径（默认 `OPENASR_HOME/apikeys.json`）
`OPENASR_SPEAKER_PROFILES`	覆盖声纹存储路径（默认 `OPENASR_HOME/diarize/voiceprints.json`）
`OPENASR_PULL_CONNECTIONS`	模型下载时的并行连接数
`OPENASR_GGML_CPU_THREADS`	覆盖 ggml CPU 线程数（等效于 `preferences.inference_threads`）

OPENASR_ASSUME_YES 和 OPENASR_OFFLINE 接受 1、true、yes、on 作为真值。

OPENASR_ALLOW_INSECURE_NON_LOOPBACK 可以跳过服务端对非回环绑定的 TLS 校验。这是一个危险选项，仅适用于完全受控的内网环境，正常使用不应依赖它。

API 密钥管理

openasr apikey 用于管理 openasr serve 的 Bearer 令牌认证。默认情况下，回环地址（127.0.0.1）的请求无需认证；一旦创建了任何密钥，所有请求（包括回环）都必须携带有效的 Authorization: Bearer <key> 头。

openasr apikey create [--name <LABEL>]   # 创建密钥，明文仅显示一次
openasr apikey list                       # 列出已有密钥（不显示完整密钥）
openasr apikey revoke <id>                # 按 ID 吊销（如 key_1a2b3c4d5e6f7a8b）

安全设计要点：

密钥创建时明文仅显示一次，之后无法恢复。
存储文件（默认 OPENASR_HOME/apikeys.json，可通过 OPENASR_API_KEYS_PATH 覆盖）中只保存 SHA-256 哈希，从不保存明文。
服务端校验时同样只比对哈希值，明文从不跨越存储或服务边界。

诊断：`openasr doctor`

openasr doctor 可以快速检查当前配置和运行环境的健康状态，输出内容包括：

OpenASR 主目录和配置文件路径
模型注册表状态（已知模型数量）
默认模型和默认后端是否有效
量化偏好设置
ggml 运行时信息：最佳后端、CPU 特性标志、设备详情（名称、显存等）
ffmpeg 状态：配置的路径或 PATH 查找结果

ffmpeg 是可选依赖——处理 WAV 格式不需要它；当输入为其他音频格式时，native 后端会使用 ffmpeg 进行格式转换。

openasr doctor

更多命令行用法见 CLI 参考，服务端配置见本地 API，说话人分离相关配置见说话人分离。

配置参考

OPENASR_HOME 目录