hex 控制 CLI¶
控制命令驱动正在运行的 Hex：开始或停止听写或会议、更改任何设置、切换模型、打开窗口、退出，或读取其状态。它们既为人类也为代理和脚本而设计，因此每个命令都支持 --json 参数、具备幂等性，并以稳定的退出码退出。
一个命令树（control::cli）在 macOS、Linux 和 Windows 上编译，一个版本化协议通过运行中的 Hex 的本地 API 在每种操作系统上承载它：仅所有者可读的发现文件（local-api.json）和使用 bearer 认证的 POST /control（local_api）。
在 Linux 和 Windows 上，一个共享宿主（control::host）通过各操作系统的薄适配层（linux/app、windows/rune）执行命令；macOS 的宿主是 macos_rune::control。运行中的 Hex 在其操作系统上无法执行的命令会在运行时返回 unsupported（退出码 1），而不是从 CLI 中缺失；hex status --json 会列出操作系统的 capabilities。目前，这包括 macOS 之外的 playground 故事（window story）命令，以及 macOS 上的本地 model 工具。
在 Windows 上，终端将 hex 作为 hex.com 运行，这是一个控制台程序，它运行应用的 hex.exe 并等待其结束，因此命令会打印输出、返回退出码，并可以像其他任何命令一样被捕获（docs/windows.md）。
只读命令 hex history、hex meetings list|show|chapters|search 以及 hex mcp 读取文件而非运行中的 Hex；参见 docs/transcript-cli.md。
命令¶
hex
├── status what Hex is doing (see Status below)
├── start open Hex if it isn't running (macOS Hex.app, else `hex app --hidden`); wait until it answers
├── quit [--force] refused while a meeting or dictation is active, or unconfirmed
├── restart [--force] quit and reopen (opens Hex when it isn't running)
├── dictation start|stop|toggle
│ ├── stop --print print the transcript instead of pasting it (below)
│ └── start|toggle --raw paste the transcript as heard, skipping the Output steps
├── paste-last paste the last dictation (Option-Shift-V); refused while recording
├── meetings
│ ├── record [--title T] as the menu bar's Record Meeting; needs meetings.enabled
│ ├── stop Stop & Transcribe
│ ├── copy-last copy the last meeting transcript to the clipboard
│ └── list | show | search read-only (docs/transcript-cli.md)
├── settings
│ ├── list every setting: key, value, kind, choices, writable, about
│ ├── get <key|prefix> one setting, or every key under a prefix (`meetings`)
│ └── set <key> <value>
├── model
│ ├── list every model, its languages and size, installed or not
│ ├── use <id> [--language L] installed models only; never downloads or repairs
│ ├── install [id] [--language L] download, then switch to it (default: the selected model)
│ ├── cancel stop a download or load in progress
│ ├── import <path> [--name N] Labs: check and copy in a GGUF; prints its custom-… id
│ ├── rename <id> <name> Labs: an import's picker name
│ ├── repair <id> Labs: rehash Hex's copy; ready again if it still matches
│ ├── remove <id> Labs: Hex's copy of an import (not the selected model)
│ └── status|devices|check|transcribe <wav> Linux and Windows, run in this process
├── commands
│ ├── init create ~/.config/hex (local, no running Hex needed)
│ └── check validate ~/.config/hex/hex.config.ts transformations
├── window
│ ├── show [settings|models|modes|history|meetings]
│ ├── hide close the window; Hex stays in the menu bar
│ └── story <story> [--variant V] [--play] the playground (Labs): open a story
├── onboarding reset (alias restart) replay the first run now; every OS (below)
├── history clear --yes delete every retained dictation
├── vocabulary the shared vocabulary (features/vocabulary.md)
│ ├── list [--json] every term and its "sounds like" spellings
│ ├── add <term> [--sounds-like a,b] add a term, or new spellings to an existing one
│ └── remove <term> any case
├── annotate (alias capture) Annotate (features/capture.md)
│ ├── start|stop|cancel|replay|status record a capture, end or discard it, save the last 15 s, or report
│ ├── list [--limit N] the newest captures in the captures folder
│ ├── show <capture> one capture's words, files, and where it went
│ ├── send <capture> [--to <session>] [--always] send it to an OpenCode session
│ └── route <capture> [--ask-jev] what routing sees and decides; sends nothing
├── screenshot [--pick] Labs (macOS): shoot the display under the pointer and print the PNG's path; --pick opens the ⌘⇧4 picker
├── labs [on|off <feature>] list Labs features or turn one on/off; edits settings.json (features/labs.md)
│ └── link <feature> macOS: print hex://labs/<feature>, the link that opens Hex's Labs page on that lab's group
├── check-for-updates check for an update now
├── launch-at-login [on|off] report or change Launch at Login (macOS: installed Hex.app only; Windows Run key; Linux XDG autostart)
└── logs [--process] [-n N] [-f] tail live.ndjson (or process.log); no running Hex needed
dictation start 会锁定录音，就像双击操作一样：dictation stop 或下一次快捷键按下会结束录音，而 dictation cancel 会丢弃它。CLI 启动没有可供判断的按键操作，因此其录音立即被视为有意为之：麦克风一打开就会播放开始提示音，录音行为（静音或暂停媒体、防止空闲休眠）和实时流也会像长按快捷键之后一样启动。只有当片段进入转写时，stop 才会回复 done；尚无音频的片段（麦克风仍在打开中）或静音片段会被丢弃并返回 discarded，并且不会显示任何正在转写的内容。
dictation stop --print 会立即停止录音，与 stop 完全一样，因此不会阻塞后续的 start；只有此命令随后会等待最多 60 秒以获取转录文本，并将其写入 stdout 而不是粘贴。文本会经过与粘贴相同的处理（全局替换、模式修正、OpenCode 重写以及转换）。历史记录将其记为 printed，而“粘贴上一条”（Paste Last）会跳过它。没有语音（尚未录制任何内容、静音片段或空转录）时，会以退出码 4（no-speech）退出且不打印任何内容；如果没有正在录音，则会以 not-recording 拒绝。失败或 60 秒超时会不打印任何内容、退出 1，并且永远不会回退到粘贴。--print 与任何其他操作组合都是用法错误（退出 2）。该命令在 Linux 和 Windows 上相同，其中 hex dictation 和 hex paste-last 会像其快捷键一样到达监听器自身的队列。
dictation start --raw 和 toggle --raw 启动的听写会按原样粘贴转录文本，跳过“输出”面板的步骤，就像“不经处理听写”快捷键（raw_dictation_hotkey）所做的那样。历史记录将其记为 raw，而“粘贴上一条”会粘贴它。--raw 与 stop 组合是用法错误（退出 2）；对原始听写执行 stop --print 会按原样打印转录文本。
dictation cancel 会在任何快捷键模式下丢弃录音：不会转录、粘贴或保存到历史记录，并且已在转录中的听写会正常完成。如果没有正在录音，它会回答 unchanged。在“切换”（Toggle）模式下，取消快捷键（cancel_hotkey，默认 Escape）的作用相同；在 Wayland 上，请改为将 hex dictation cancel 绑定到桌面环境中的某个按键（#786、#1022）。meetings cancel 不存在，因为 Hex 无法丢弃会议录音。
onboarding reset（或 onboarding restart）会立即打开首次运行的引导窗口，就像新安装时一样，以便在 macOS、Linux 和 Windows 上重新体验引导流程。它仅从数据文件夹中移除引导标记（onboarding-complete、onboarding-step、onboarding-relaunch）。设置、历史记录、模型和权限均不受影响，因此运行时会发现它们已就绪：下载立即通过，权限步骤被跳过。实验室（Labs）中的“再次运行设置”（Run setup again）行也会执行相同的操作。
paste-last 需要一个正在监听的 Hex（设置期间为 not-ready），并且在有任何录音或快捷键手势正在进行时会被以 busy 拒绝。在这种情况下，菜单栏中的“粘贴上一条听写”（Paste Last Dictation）不执行任何操作。
model import、rename、repair 和 remove 在每个 OS 上都在当前进程中运行；hex models 是 hex model 的别名。导入的 id 为 custom- 加上其 SHA-256 的前 16 位十六进制数字，所有模型命令都接受该 id。缺失或已更改的模型会以 model-unavailable 及原因作为回答。model list 还会查看 Hugging Face 缓存，并说明每个模型的来源（download、hex、imported 或 found: owner/name@abcdef1）；其中不属于目录模型的兼容文件会列为 custom-<其 blob 的前 16 位十六进制数字> (not tested by Hex)，而 model use 使用该 id 时会对其全面检查并在原位置使用它。对已找到的文件执行 remove 只会将其遗忘（自有模型）。
model use 只会切换到已下载的模型并检查其磁盘状态；它从不下载或修复模型（model install 会这样做）。与菜单栏一样，它会保留该模型自身记住的语言；--language 仅覆盖语言，且必须是该模型支持的语言。
vocabulary 通过正在运行的 Hex 编辑共享词汇表，Hex 会像窗口编辑一样保存设置并重新加载它们。术语匹配不区分大小写；add 对于已列出的术语只会合并新的拼写，如果没有新的拼写，则回答 changed: false。
没有 --force 的 quit 和 restart 在监听器未回答是否正在录音时会被以 busy 拒绝；没有监听器，或监听器正在等待设置，均视为空闲。在 Linux 上，由 systemd 单元运行的 Hex 会通过该单元重启（在写入此桌面的 session.env 之后）；在其他平台上，restart 会等待旧的 Hex 排空并退出，然后运行 hex start。
在 Linux 上，更新后仍在运行的旧版 Hex（在 hex 命令迁移到本地 API 之前）只会在其 service.sock 上应答。此时每个控制命令和 hex start 都会回答 outdated（退出 1）而不是 not-running，而 hex restart 会将其 systemd 单元重启到已安装的构建版本并等待其应答（#915）；非由该单元运行的 Hex 只能从其窗口或托盘退出。
model install 在 Hex 运行时会在后台下载，就像设置（Settings）所做的那样；在 Linux 和 Windows 上如果没有 Hex 在运行，它会在当前进程中下载并打印进度（源码安装步骤 hex model install）。model status、devices、check 和 transcribe 在 Linux 和 Windows 上是本地工具，除非指定了某个模型，否则使用所选模型；macOS 回答 unsupported。
start 和 restart 会保留 HEX_* 环境变量（HEX_RETAIN_DICTATION_AUDIO、HEX_ENABLE_LLM 等）：macOS 打开应用时不会携带调用方的环境，因此 Hex 会将每个 HEX_* 变量传递给 open --env。start 从运行它的 shell 获取这些变量，restart 从正在运行的 Hex 获取。这些值永远不会被记录到日志中。
annotate（或其旧名称 capture）驱动 Annotate，适用于每个 macOS、Linux 和 Windows 构建版本；当 capture.enabled 关闭时，它会以 feature-off 拒绝。在 Linux 上，list、show、route 和 send 在 hex 进程本身中运行，而 start、stop 和 cancel 与 status 一样由正在运行的 Hex 的监听器处理。在 Windows 上，每个 annotate 命令都会发送到正在运行的 Hex。capture stop 会立即以捆绑包路径作为回答，同时在后台写入文字和文件；capture replay（macOS 27+，Dev Lab 的 annotate-replay 开启）会将滚动记录最近 15 秒画面的 SCClipBufferingOutput 显示缓冲区导出到 <bundle>/recording.mp4，并以捆绑包路径作为回答，同时在同一队列上完成关键帧、剪贴板复制和路由（在 macOS 27+ 之外回答 unsupported，在 labs.annotate_replay 关闭时回答 feature-off）；capture status 会列出仍在写入的捆绑包以及最后一次结果（last：bundle、stage 为 done、failed 或 cancelled，对于已写入的捆绑包，还包括 words、gaps 和 missing_transcript，说明它为何没有文字）。当两个捕获仍在写入时，启动或重放会被以 busy 拒绝。每个操作都是幂等的。
<capture> 是一个 bundle 名称（1792933491953.scrawl，扩展名可选）、一个路径，或 latest。list、show 和 route 读取 captures 文件夹，只需实验；send 需要开启 captures 并有一个监听的 Hex。带 --to 的 send 接受一个会话 ID；对于最新的 capture，它还可以接受其路由列出的名称，并且它充当 capsule 的选择，因此 capsule 的撤销会跟随它。没有 --to 时，它会前往 capture 的路由（其规则或首个猜测）或其上次发送所指示的位置。--always（仅适用于最新 capture）还会保存一条规则，将该 capture 的站点或应用发送到那里，就像 capsule 的 ⇧⏎ 那样。它的回复会说明结果（Sent to …；当 OpenCode 未应答时显示 Queued for …，Hex 会重试）。route 就是 Scrawl 的 route --explain（接受 --explain）；--ask-jev 会再次询问 Jev，只需一次网络调用。未知的 capture 会被拒绝并返回 not-found。
CLI 启动的会议与菜单栏启动的录制相同：菜单栏状态、录制 capsule 以及 Stop & Transcribe 都适用于它。
meetings record 会在录制开始后（或 8 秒后）回复；meetings stop 会在转录开始后回复。
退出码¶
0 the command ran, or there was nothing to change (`changed: false`)
1 Hex refused or failed it (an error reply), or the transport failed
2 usage error (clap)
3 Hex isn't running (code `not-running`); control commands never launch it
4 `dictation stop --print` heard no speech (code `no-speech`); nothing printed
传输¶
CLI 读取仅所有者可见的发现文件
~/Library/Application Support/hex/local-api.json（HEX_APPLICATION_SUPPORT_DIR
可覆盖该文件夹），检查其 pid 是否存活，并向
127.0.0.1:<port> 发送一个 POST /control，同时带有 Authorization: Bearer <token>。
该路由在 macOS 桌面应用中始终开启；无头的 hex service
不提供它。Linux 和 Windows 上的 Hex 发布相同的本地 API（发现文件位于
~/.local/share/hex 和 %APPDATA%\hex），用于转录和 /streams，但在其宿主支持这些命令之前，它们会对 /control 返回
404 control-unavailable。
- 请求体为 JSON，最大 64 KiB；回复最多 1 MiB。
- 应用在 10 秒内应答（否则返回
504 control-timeout）；CLI 等待 15 秒。dictation stop --print的应答时限为 65 秒，CLI 等待 70 秒。 - 应用给出的每个应答都是
200并带ControlResponse，包括拒绝。 传输层失败使用 HTTP 状态码：400 invalid-control-command（格式错误或未知命令）、404 control-unavailable（没有 control 宿主）、413 control-too-large、503 control-busy（并发过多）或control-unavailable，以及504 control-timeout。与所有其他路由一样，错误或缺失的 token 会得到401。
线上格式（第 4 版）¶
请求是由 command 标记的扁平对象（kebab-case）：
{"version": 4, "command": "meeting-record", "title": "Design sync"}
{"version": 4, "command": "settings-set", "key": "sound_effects", "value": "off"}
{"version": 4, "command": "dictation", "action": "start"}
{"version": 4, "command": "dictation", "action": "stop", "print": true}
status | quit {force} | restart {force}
dictation {action, print?} action: start | stop | toggle | cancel;
print (stop only) answers `transcript`
paste-last
meeting-record {title?} | meeting-stop | meeting-copy-last
settings-get {key?} | settings-set {key, value}
model-list | model-use {model, language?} | model-install {model, language?} | model-cancel
window-show {pane?} | window-hide | window-story {story, variant?, play}
onboarding-reset
history-clear | check-for-updates | launch-at-login {enabled?}
vocabulary-list | vocabulary-add {term, sounds_like} | vocabulary-remove {term}
scrawl-capture {action} action: start | stop | cancel | status; `capture` experiment
scrawl-capture-list {limit?} | scrawl-capture-show {capture}
scrawl-capture-send {capture, to?, always?} | scrawl-capture-route {capture, ask_jev}
可选字段可以省略。hex start 和 hex logs 是本地命令，没有线上形式。history-clear 没有确认字段：CLI 在发送前会要求 --yes。
回复由 status 标记：
{"version": 4, "status": "done", "message": "Recording “Design sync”; …", "changed": true}
{"version": 4, "status": "error", "code": "feature-off", "message": "Meetings are off; …"}
{"version": 4, "status": "settings", "settings": [{"key": "sound_effects", "value": true,
"kind": "bool", "writable": true, "about": "Play recording and error tones"}]}
{"version": 4, "status": "models", "models": [{"id": "parakeet_v3", "name": "…",
"languages": ["en", "…"], "size": "…", "installed": true, "selected": true,
"streams": true, "vocabulary": "bias", "supports_recognition_hints": false}]}
{"version": 4, "status": "vocabulary", "entries": [{"term": "OpenCode",
"sounds_like": ["open code"]}, {"term": "Rune"}]}
{"version": 4, "status": "scrawl-capture", "changed": true, "state": "idle",
"bundle": "…/captures/1792933491953.scrawl", "elapsed_ms": null,
"finishing": ["…/captures/1792933491953.scrawl"], "last": null}
{"version": 4, "status": "scrawl-captures", "captures": [{"id": "1792933491953.scrawl",
"bundle": "…", "created_at_ms": 1792933491953, "duration_ms": 4000, "mode": "window",
"app": "Brave", "words": 12, "sent_to": {"session": "ses_…", "title": "Hex"},
"queued": false}]}
{"version": 4, "status": "scrawl-capture-detail", "id": "…", "…": "the list's fields",
"window_title": "…", "transcript": "…", "note": null, "missing_transcript": null,
"marks": 2, "keyframes": 3, "video": "…/video.mp4", "audio": null,
"contact_sheet": "…/contact-sheet.jpg"}
{"version": 4, "status": "scrawl-capture-route", "explanation": "Capture …"}
{"version": 4, "status": "transcript", "text": "Ship it."}
当命令发现状态已是如此时（“Already recording”“The window isn't open”），done.changed 为 false。kind 可以是 bool、number、integer、choice（带 choices）、text、shortcut、path 或 json 之一；未设置的可选设置的 value 为 null。
状态¶
{
"version": 4, "status": "status",
"app_version": "2.3.1", "pid": 31708, "memory_footprint_bytes": 412000000,
"listener": {"running": true, "status": "Listening"},
"capture": {"state": "idle", "recording": null, "pending_jobs": 0},
"meeting": {"state": "recording", "title": "Design sync", "elapsed_seconds": 723},
"model": {"id": "parakeet_v3", "name": "…", "language": "en", "installed": true,
"preparing": null, "downloaded_bytes": 0, "error": null},
"features": {"meetings": true, "release_microphone_while_idle": false,
"history_retention": "week"},
"permissions": {"ready": true, "microphone": "ready", "accessibility": "ready",
"transcription_model": true},
"window": {"open": false, "pane": null},
"update": "current",
"labs": ["live-text"]
}
listener.status Enabled | Waiting for setup | No microphone | Stopped (running false)
listener.shortcuts Wayland portal only: [{"name": "Dictation", "trigger": "Super+D"}], the keys the desktop
granted (changed in its settings or not); trigger null when it refused one
capture.state idle | recording | transcribing | unknown (the listener didn't answer or stopped)
capture.recording dictation | service | null
meeting.state idle | starting | recording | transcribing
permissions.* ready | needs-request | needs-settings | needs-restart
window.pane settings | modes | history | meetings | …
update current | checking | available | unavailable
memory_footprint_bytes 是 Activity Monitor 中显示的物理占用空间。
labs 列出已开启的 Labs 功能；旧版 Hex 会省略该字段。
错误代码¶
not-running Hex isn't running (CLI only; exit 3)
outdated Linux: an older Hex an update left running; run `hex restart` (CLI only)
transport the request couldn't reach Hex or its reply was unreadable (CLI only)
version-mismatch this hex speaks another control version; use the running app's hex
unknown-setting no such key (the message suggests a near match)
read-only the key can't be set here (the message says where)
invalid-value the value doesn't parse or is out of range
confirmation-required clears history; pass --yes
shortcut-in-use another Hex shortcut already uses that binding
not-found no such capture, or it has no scrawl.json yet
unknown-model no such model id (`hex model list`)
model-unavailable an imported model that is missing, changed, or behind its Labs toggle
not-installed `model use` on a model that isn't downloaded (`hex model install`)
feature-off the command needs an opt-in that is off (Meetings)
not-ready Hex is waiting for setup (permissions or the dictation model)
meeting-active quit/restart while a meeting records (pass --force)
busy something is in progress (recording, transcribing, a full queue),
or the listener couldn't confirm it's idle
discarded `stop` dropped the clip: no audio yet, or silent; nothing transcribes
no-speech `dictation stop --print` heard no speech; nothing printed (exit 4)
not-recording `dictation stop --print` with nothing recording
unavailable a part of Hex the command needs isn't available
unsupported this build or OS can't do it (e.g. restart from a development binary)
failed Hex tried and failed (the message has the cause)
internal reading or saving settings failed
设置¶
键是 settings.json 中的点分隔路径。hex settings list 会打印每个键及其类型和描述；hex settings list --json 会额外输出 choices。更改会经过与窗口中相同的规则校验，并会由应用保存，然后实时重新加载；打开的窗口会采纳更改，除非窗口中有未保存的编辑。
在 macOS、Windows 和 X11 上的 Linux 中，keyboard_model_switching.enabled 用于选择在键盘输入源变化时切换共享语音模型选择器。JSON 设置 keyboard_model_switching.mappings 将启用的输入源 ID 映射到其支持的模型和语言，例如 {"com.apple.keylayout.Spanish":{"model":"parakeet_v3","language":"es"}}。源 ID 可以是 macOS 输入源 ID、Windows 键盘布局句柄（俄语为 04190419）或 X11 XKB 布局（ru、de(neo)）。省略某个源表示“不切换”；Apple Speech 无法映射。自动切换只会加载已安装的模型，绝不会下载它们。启用或编辑当前映射会立即生效；启动 Hex 不会重新应用。Wayland 没有用于当前布局的通用协议，因此 Hex 在那里会保留这些设置，但不会观察输入源更改，也不会显示这些控件。
- 布尔值可接受
on/off、true/false、yes/no或1/0。 - 可选设置传入
none可清除。 microphone接受“设置”中列出的确切设备名称，或传入system-default（或none）以跟随操作系统的默认输入。avoid_bluetooth_microphone（默认开启）会让“系统默认”在操作系统默认输入为蓝牙耳机时，改用内置麦克风录音，否则使用其他有线或 USB 输入，从而避免耳机音频影响通话质量（在 Linux 上，Hex 会在打开 PipeWire 流之后将其从蓝牙默认源移开，因此耳机仍可能切换到免提模式；参见 蓝牙耳机）。保存的麦克风和--device始终按指定名称使用。- 快捷键接受诸如
option、right-command、option+shift+v、control+space、fn、f5或left-option+right-option（同时按住两个 Option）之类的文本。left-和right-适用于没有按键的快捷键。在 macOS、Windows 和 X11 上，mouse4和option+mouse4也可用（鼠标 1/2/3 分别对应左/右/中键）。按键名称会在当前键盘布局中解析，操作系统对“设置”中录音机适用的规则同样生效；与其他 Hex 快捷键共享的绑定会被以shortcut-in-use拒绝。double_tap_only需要一个组合键，如同“设置”中一样。 - 在 Linux 上，当
labs.standalone_special_keys开启时（hex labs on special-keys，默认关闭），快捷键可以使用menu、pause或scrolllock，单独使用或与修饰键组合，例如在将 Caps Lock 重新映射为 Menu 后运行hex settings set dictation_hotkey menu。关闭时，这些键会以invalid-value被拒绝；关闭该开关后，设置在这些键上的快捷键会恢复为默认值。在其他情况下，单独使用这些键仍需要修饰键。 second_dictation_hotkey（macOS，默认未绑定；none清除）是一个与dictation_hotkey完全一样的第二快捷键，例如外接键盘上的某个键。它仅在labs.second_dictation_shortcut开启时生效（hex labs on second-dictation-shortcut），并且不与其他快捷键共享按键。json设置（模式、会议提供方、排除的日历）接受文件存储的 JSON 值。ui_language接受en、pl、zh（简体中文）、zh-Hant（繁体中文）、ja、de、es、uk、pt、fr、ru或none（跟随系统语言），与“设置”提供的语言相同。跟随系统时，使用 Hant 文字或位于 TW、HK 或 MO 地区的中国区域设置会显示繁体中文；其他中国区域设置显示简体中文。updates.channel接受stable、dev或none（跟随构建版本：即其发布所用的渠道），并会立即检查更新。选择与构建版本不同的渠道时，会提供该渠道的当前版本（窗口中的“Switch to Stable 2.3.1”）；只有你在那里确认后，Hex 才会安装。版本之间从不进行比较。- 启用
capture实验后，会出现capture.*键：capture.enabled、capture.hotkey（默认option+shift+s）、capture.list_hotkey（胶囊的发送列表，默认option+shift+v）、capture.transcriber、capture.folder、capture.media_days、capture.bundle_days、capture.routing、capture.show_overlays_in_recordings（默认关闭；开启后，屏幕录制（包括 Hex 的录制）会显示其覆盖层），以及capture.capsule_flow（list（默认）、toast、menu_bar、cursor或notch：捕获后胶囊的显示流程，用于比较原型）。两个捕获快捷键都需要按键，且capture.enabled on要求两个快捷键都空闲；在“Paste Last”仍为 ⌥⇧V 的 Mac 上，请先重新绑定其中一个。 meetings.retention为day、week、month、forever或none（默认：自默认开始以来录制的会议保留 24 小时；更早的会议会一直保留，直到你自行选择）。Hex 会在启动时和每小时将结束时间早于该期限的会议移到废纸篓，无论 Meetings 是否开启，并且hex meetings和hex mcp不再列出它们。transcription.model和transcription.language此处为只读：请使用hex model use。transcription_recents和meetings.calendar.connected也是只读（连接日历会请求 macOS 从“设置”授予访问权限）。
recording_audio_behavior 也接受 duck（降低音频）：macOS 和 Linux 会降低默认输出音量，Windows 会降低其他应用的音频会话音量。recording_duck_volume 设置原始输出音量的比例（0–1，默认 0.2），当选择闪避（ducking）时，在下一次有意捕获时应用。
可写键：release_microphone_while_idle、sound_effects、sound_effect_volume、sound_theme、microphone、avoid_bluetooth_microphone、recording_audio_behavior、recording_duck_volume、double_tap_lock、double_tap_only、shortcut_mode、dictation_hotkey、paste_last_hotkey、raw_dictation_hotkey、second_dictation_hotkey、labs.second_dictation_shortcut、labs.standalone_special_keys、show_dock_icon、vocabulary_boost、dictation_processing.default_mode、dictation_processing.modes、history_retention、meetings.enabled、meetings.output_folder、meetings.summaries、meetings.opencode_model、meetings.show_recording_indicator、meetings.recording_indicator_corner、meetings.retention、meetings.providers、meetings.calendar.excluded_calendars、meetings.calendar.remind、meetings.calendar.lead_minutes、experimental.hex_microphone、experimental.hex_microphone_mode、experimental.hex_microphone_comfort_noise、experimental.hex_microphone_strength、enable_on_launch、paste_with_shift、ui_language、indicator_position、updates.channel。
transcription.recognition_hints 已弃用：识别提示已合并到 vocabulary 中。get 返回该 vocabulary 的术语，以逗号分隔；set（或 apply）会将逗号分隔的名称添加到其中；list 则省略该键。模型列表会在较新的 vocabulary 旁保留 supports_recognition_hints（当模型将 vocabulary 作为其提示词读取时为 true）：prompt、bias 或 none。
meetings.summaries 选择谁来为会议拟定标题和生成摘要：off、mac（Apple Intelligence；此 Mac 不会向外发送任何内容，也不会回退到 OpenCode）或 opencode（将转录文本发送到 meetings.opencode_model；如果该项为 none，则发送到 Hex 选择的快速模型）。在 Mac 之外，只能是 off 或 opencode。已停用的 meetings.summarize_with_apple_intelligence 和 meetings.summarize_with_opencode 会被拒绝，并提示改用 meetings.summaries 命令。
如果新的持久化设置在此处没有对应的键，测试（control::settings::tests::every_persisted_setting_has_a_cli_key）将失败。
兼容性¶
CONTROL_VERSION 为 4。任何破坏请求或回复形状的更改都会使其递增；添加命令、可选请求字段或回复字段则不会。来自不同版本的 hex 会收到 version-mismatch；请使用正在运行的 Hex.app 中的 hex，或在更新后重启 Hex。版本 2 从状态回复中移除了 permissions.input_monitoring；版本 3 移除了 voice-action 和 features.voice_action；版本 4 移除了 commands-retry、settings-set.confirm、window-show commands、capture.recording voice、features.commands 和 features.command_model。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 hex19/hex