Qwen Live Host 深度解析macOS 原生语音交互组件、全局快捷键与安全发布链路【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本篇技术指南以packages/live-host/README.md为骨架结合 qwen-code 单仓库中的源码实现系统讲解 Qwen Live Host 的架构定位、首次启用流程、权限模型、快捷键机制、内置 Appshot、音视频输入输出、fail-closed 安全策略、开发构建与发布签名链路。读完本文你将掌握如何启用 Qwen Live 语音能力、理解 Host 与 daemon 之间的安全连接协议以及如何在 macOS 上独立构建、诊断和卸载这一原生组件。一、定位Host 是什么与 daemon、WebShell 是什么关系Qwen Live Host 是独立 Qwen Live daemon 与 WebShell Live Voice 在 macOS 上的原生组件参见 packages/live-host/README.md。它承载四类能力屏幕上的**小浮层orb**与设置面板Electron全局快捷键默认CommandE麦克风输入与扬声器输出可选摄像头输入与内置原生 Appshot屏幕/窗口截图。关键边界在于Host不打开 WebShell 或 Session 窗口。对话由连接的 daemon 管理编码任务由配置的后端执行因此没有浏览器麦克风或浏览器快捷键的降级方案——这些能力必须由原生 Host 提供。从packages/qwen-live/README.md的架构描述可以确认整个 Live 体系连接三方Live Host通过 Live Host WebSocket 协议 v9 连接 daemon并读取 daemon 发布的~/.qwen/live/daemon.jsondiscovery 文件实现自动连接DashScope Realtime 语音模型如qwen3.5-omni-plus-realtime拥有对话负责 VAD、直接回答与派发工作的工具面编码会话Backend通过BackendAdaptor驱动qwen serveREST/SSE或任意 ACP 兼容 agentqwen --acp、qodercli --acp、gemini --acp等作为子进程。Host 处于整个链路最靠近用户硬件的一端负责把麦克风、摄像头、屏幕与全局快捷键这些只有原生应用才能可靠拿到的能力暴露给 daemon 和模型。二、运行前提与用户要求启用 Live Host 需要满足以下条件macOS 12 或更高版本electron-builder.yml中mac.minimumSystemVersion: 12.0.0与之对应本机运行独立qwen-livedaemon或Qwen Code WebShell内置 Live Voice 默认关闭一个可调用qwen3.5-omni-plus-realtime的DashScope API key。需要注意原生音视频功能目前要求 macOS。独立qwen-live可直接从命令行启动并连接 Host在 Linux/Windows 上由于缺少原生麦克风、全局快捷键与屏幕捕获组件在对应平台出现 Host 之前无法使用语音功能。三、首次启用与自动安装的安全链路在 WebShell 中按以下步骤启用打开设置 → 实验性功能 → Qwen Live输入专用于 Realtime 模型的 DashScope API key快捷键默认是CommandE可在同一处修改打开开关并确认安装。WebShell 会优先从阿里云 OSS 镜像下载当前架构的签名 Host镜像不可用时回退到独立的 GitHublive-host-latestfeed下载后依次校验manifest、SHA-256、bundle identity、Developer ID 签名和 Gatekeeper然后原子安装到/Applications/Qwen Live Host.app并启动按 Host 引导完成麦克风以及当前视觉源需要的授权Screen需要辅助功能和屏幕录制Camera需要摄像头。授权只能由用户在 macOS 完成当前 Source 的 readiness 通过前 Live 不可使用。两条安全细节值得强调API key 只写入用户级设置。WebShell 只能看到已配置状态不会读取或回显 key关闭 Live 会停止当前通话、撤下快捷键和 Host discovery但不会卸载 Host 或删除 Live 对话。四、权限模型四类系统权限与用途权限授权主体用途麦克风Qwen Live Host采集 Live 对话音频摄像头Qwen Live HostCamera Source 的预览、实时帧或单帧截图辅助功能Qwen Live Host读取前台窗口的可访问性树屏幕录制Qwen Live HostScreen Source 的实时帧或单帧截图从 protocol.ts 的类型定义可以看到Host 向 daemon 上报的权限状态为granted | denied | not_determined自检项HostSelfChecks包括audioInput、audioOutput、globalShortcut、appshot四项——任一权限、自检、快捷键或 provider 配置失败时Live 都保持不可用fail-closed。初始化页只处理连接、Source 和对应权限不要求 Camera 用户先授权 Screen未选中的来源权限不会阻止 Live。通话中切换到尚未授权的来源时Host 会先保留当前可用来源授权成功后再一次性完成切换授权取消或失败不会让正在工作的来源提前失效。五、daemon discoveryHost 如何找到并信任 daemonLive 启用后daemon 会在~/.qwen/live/daemon.json发布权限为0600的稳定 locator。Host 侧的读取与校验逻辑实现在 discovery.ts从源码可以看到多层防御文件校验必须是常规文件且不是符号链接权限必须严格为0600属主必须是当前用户大小限制在 16 KiB 以内内容校验protocolVersion必须等于LIVE_PROTOCOL_VERSION即 9pid为正整数instanceNonce必须匹配^[A-Za-z0-9_-]{16,256}$模式token 与configPath均有长度与形态约束URL 校验buildHostWebSocketUrl强制 daemon URL 必须是 loopback 地址127.*、localhost、::1并转换为ws/wss后固定指向/live/host路径轮询监控DiscoveryMonitor默认每秒轮询一次只有记录身份pid nonce url token 哈希 configPath变化时才通知上层。daemon 侧还会校验 Host 的instanceNoncerecord 可能包含 bearer token因此文档明确要求不要打印、复制或共享其内容。Host 只连接 loopback 地址并校验协议版本和 daemon nonce。六、快捷键机制daemon 下发、Host 注册快捷键由 daemon 通过每个LiveStatus.shortcut下发默认是CommandE。Host 使用 ElectronglobalShortcut注册普通 accelerator不请求 Input Monitoring 权限也没有裸修饰键 helper。核心实现在 global-shortcut.ts 的LiveGlobalShortcut.replace()若当前 accelerator 健康且与目标相同直接返回空字符串表示解注册当前值注册失败时区分非法值host.error.shortcutInvalid与已被占用host.error.shortcutInUse先注册新 accelerator成功后才解注册旧值失败则保留旧快捷键并返回设置错误stop()在退出或断开 daemon 时解注册当前 accelerator。WebShell 设置通过 daemon 请求 Host 走这条替换路径冲突或非法值会保留旧快捷键并返回设置错误。菜单栏中的新对话会显式创建新的无项目对话开始、停止当前通话是独立动作。七、悬浮球、设置面板与体验细节位置与拖动初始化框和悬浮球首次分别按当前可见尺寸放在启动屏幕右下角保留 20px 边距拖动位置保存到 Host 用户数据目录的overlay-position.json下次启动恢复显示器移除后会调整到可见区域。小球按动画、工具栏和字幕的紧凑区域限位打开 Settings 或预览时会临时调整到完整可见位置关闭后恢复记忆位置——临时调整不会覆盖拖动记录状态刷新也不会重新定位窗口。交互细节鼠标移到小球上显示麦克风、播报、Start callEnd call、Settings和Quit Host按钮移出后等待 1 秒淡出移回或键盘聚焦会保持可用。CommandE启动结束通话。结束后小球变灰并留在原位不再自动隐藏。麦克风关闭或扬声器静音时状态条第二行显示Mic offSpeaker muted支持中文麦克风静音会释放输入设备取消静音后重新收音。自动启动语义Host 启动后会等待连接、当前来源权限和自检就绪再自动开始一次交互已有通话时不会重复启动。实现见 startup-interaction.tsshouldStart()要求connectionReady、rendererReady、hostReady、live.available且状态为idle并且该意图是一次性的——手动启停新对话退出、自动启动失败、重连或 renderer 重载均不会再次触发自动启动重新启动 Host 才产生下一次自动启动意图。Settings 面板日常设置集中在SettingsAudio Source麦克风、Video SourceScreenCamera、Capture ModeOn DemandLive Feed三个同级设置组以及独立 daemon 支持的Memory。设置支持 Esc、外部点击关闭编辑草稿保留。顶部的Open config.json ↗使用系统为 JSON 文件关联的默认 IDE文本编辑器打开当前独立 daemon 实际使用的配置默认~/.qwen-live/config.json也支持 daemon 的QWEN_LIVE_DATA_DIR保存后需重启 Qwen Live 才应用手动修改。文件缺失、不是常规文件包括符号链接或编辑器打开失败时会提示不自动创建或覆盖配置。语言与主题Settings 倒数第二组为Language语言其后是 Theme支持简体中文和English。独立 daemon 确认后立即切换并保存到~/.qwen-live/config.json顶层languagezh-CNen旧配置未设置时保持英文。语言不影响模型提示词回答或用户自定义名称qwen-live init的第一项也可通过左右方向键选择语言。全部固定 Live 展示文案统一维护在 packages/qwen-live/src/i18n/messages.ts每个键并列en和zh-CNHost 的构建别名直接编译同一份纯文本模块打包后不需要 qwen-live 运行时依赖。Theme主题支持跟随系统默认、浅色和深色保存在 Host 本地与 daemon 的模型Memory 配置无关切换不会重建媒体或中断通话。Memory连接独立 Qwen Live daemon 时Settings 的Memory区域提供记忆开关、独立的Visual memory开关、选择记忆库、NewRename以及Consolidation model设置默认qwen3.7-plus。通话中可以开关和改名选择新建记忆库和修改模型需要先结束通话。库默认存储在~/.qwen-live/memories。详细参数见 Qwen Live README 的 Memory 章节。Quit Host 的退出语义Quit Host请求当前独立 Live daemon 完成通话、后端、Memory 和 discovery 清理后退出 Host不会关闭另外运行的qwen serve。退出只有在匹配的退出回执或系统明确确认原 daemon PID 已不存在时才完成404、连接重置或拒绝连接都不单独视为退出成功。清理失败时 daemon 保留同实例的退出控制入口和 discovery但拒绝新通话及普通请求。八、子智能体状态面板悬停或用键盘聚焦小球时侧面显示明确标注Subagents子智能体的摘要紧凑图标计数显示进行中和已完成有运行任务时小点柔和闪烁遵循系统减少动态效果设置需要用户输入时才显示提醒标记。点击展开列表再点击任务在同一个无边框悬浮面板中显示详情原始委托、实际运行状态、最新活动、公开中间文本、可用的计划工具更新及最终结果。Back返回回到列表不再打开带 macOS 标题栏的独立详情窗口关闭面板不会取消任务。语义细节与 qwen-live/README.md 的 Subagents 章节一致进行中包含排队等待输入任务已完成包含成功任务及已取消的 Proactive monitor——monitor 详情仍显示已取消不伪装成成功需关注只表示正在等待用户输入授权不包括失败或中断持续 monitor 的每轮判断或通知不会增加子智能体数量追加到既有后台任务的指令不重复计数无通话时收到权限请求只登记等待不新增自动批准普通文件系统拒绝不会被虚构成授权请求列表和详情提供Stop停止只停止对应任务后端尚未确认时显示正在停止任务历史只保留本次 daemon 运行全部活动任务保留有限详情已结束任务仅保留最近 32 条每页最多 32 条单个快照上限 240 KiB。该功能通过可选能力协商subagentsV1仅在支持的独立 Live daemon 连接上显示不影响旧版 Host 或 WebShell。九、视觉输入Camera、Screen 与全显示器捕获Source 与 ModevisualInput有两组独立设置source为screen或cameramode为on-demand或live-feed默认Screen On Demand配置决定每次 daemon 启动的初值SourceMode 切换只影响当前运行实例。未识别键会被拒绝——拼错的 camera 设置不会静默选择默认 Screen source。从 protocol.ts 的解析逻辑可见约束FPS 必须在0.1~10之间liveResolution默认 720p所有送入 Omni 的 JPEG 和 Host 传输预览受1080p190 KiB上限约束MAX_INPUT_IMAGE_FRAME_BYTES 190 * 1024Camera 原图 asset 与 Screen 的 PNG asset 不受该小图上限影响。CameravisualInput.cameraResolution控制预览Live Feed 采集默认1280×720visualInput.cameraSnapshotResolution独立控制 Camera Appshot默认native也可设置{ width: 1920, height: 1080 }环境变量为QWEN_LIVE_CAMERA_SNAPSHOT_RESOLUTIONnative或WIDTHxHEIGHTHost 优先从同一 camera track 拍摄静态照片设备不支持时尝试临时调整视频采集约束截图后恢复预览无法满足原生采集时明确报错不会把预览的 720p 冒充原生照片Camera 高分辨率 JPEG 单独保存为 handoff asset上限8 MiB即MAX_CAPTURE_ASSET_BYTES不通过 Host WebSocket 传输。Screen 与 DisplayScreen Live Feed 与视觉 Proactive monitor 使用独立的完整显示器采集路径包含桌面、菜单栏、Dock 和其他应用但排除 Live Host 自身窗口。Settings 的 Video Source 下可选Display显示器选择保存到config.json的visualInput.screenDisplayId默认primary跟随系统主显示器也可保存某块显示器的 UUID明确选择的显示器断开后报错不自动换屏。切换显示器会丢弃过期截图并清空 monitor 旧视觉缓冲无需重新 init。完整范围不代表原生像素——两条持续画面路径都使用liveResolution默认等比放进 1280×720。权限差异Camera Source 需要摄像头权限Screen On Demand 的 Appshot 需要辅助功能和屏幕录制权限Screen Live Feed仅需屏幕录制权限。停止通话、切换 Source/Mode、daemon 断开或 Host 退出都会清理不再使用的通话采集。十、内置 Appshot无参数、只读的模型侧工具Appshot 是 Host 的内部核心能力。构建时会把仓库内的 Objective-C Appshot 源码src/native/appshot.mm编译成一个universal N-API 模块qwen-live-appshot.node随 Host 一起签名。从 native-appshot.ts 可以看到模块在主进程内加载提供getPermissionState、requestAccessibility、requestScreenRecording、captureAppshot、listDisplays、captureDisplay等原生能力通过 macOS 截屏与 AX API 工作。关键设计没有额外 Appshot App、Appshot Helper、MCP、CLI、插件、守护进程或运行时下载模型侧的appshot是无参数、只读工具捕获气泡球当前选中的 Source不能通过工具参数临时指定另一个来源、窗口、坐标或动作Live Feed 模式禁用该工具On Demand 模式才允许调用Host 激活后会在 Screen 为当前或待切换来源时定期刷新 Appshot 权限每次真实 Screen 捕获还会在 Host 进程内重新验证两项权限当前来源的授权丢失会令捕获失败并使 Livefail closed整个流程不启动或探测任何外置屏幕工具。十一、音频处理与 fail-closed 策略播放链路Omni 响应以单声道 16-bit、24 kHz PCM接收。播放 AudioContext不指定采样率使用当前系统输出设备的默认时钟如 44.14896 kHz不强制更改设备采样率。对于协商了输出结束标记的连接outputAudioEndMarkerV1对每条响应进行连续、带抗混叠滤波的流式重采样再放入设备采样率的 AudioBuffer按整数采样点连续排程避免逐块转换的衔接尖峰及无谓间隙结束标记到达时输出短暂的滤波尾部。未协商结束标记的旧连接保持原有 Web Audio 逐帧转换和播放排空逻辑。--live-debug日志中的output_context_ready显示源输出上下文采样率及是否重采样。输入链路与静音关闭麦克风时 Host立即停止输入 track 并释放捕获上下文而不只是丢弃录音数据静音期间设备变化不会重新打开麦克风取消静音后才重新收音。devicechange会在收音时检查替换输入在空闲时重新自检。蓝牙耳机麦克风被打开时macOS 可能将耳机切换到免提通话模式影响同时播放的音乐视频——这与模型 PCM 采样率是两回事可在 Audio Source 选择 Mac 内置麦克风输出仍使用蓝牙耳机。fail-closed输入 track ended、播放失败或音频帧无法交给 daemon 时Host 会先将 input/output 标记为 unavailable、停止当前通话并清理旧 context再重新执行自检麦克风重新授权后只有实际输入自检通过才会恢复 ready。overlay renderer、preload 加载、页面加载失败或 renderer 无响应也会执行 fail-closed。Host readiness不会连接 Realtime首次就绪自动开始或用户手动开始对话时才建立 provider WebSocket限流或配额错误不做自动重试或后台探测用户稍后可手工重试。十二、开发构建、诊断与测试构建命令开发者需要Node.js 22package.json中engines.node 22.0.0。在仓库根目录执行cd packages/live-host npm ci npm run build npm run typecheck npm test npm run dist:mac构建产物位于packages/live-host/dist/打包产物位于packages/live-host/release/npm run dist:mac走electron-builder --config electron-builder.yml --mac产物为 arm64x64 的 DMG 与 ZIP正式用户不需要手工下载 DMGWebShell 的实验性设置负责安装和启动。从 electron-builder.yml 可以看到打包配置要点appId: com.alibaba.qwen-code.live-host、LSUIElement: true纯菜单栏应用、QwenLiveProtocolVersion: 9、hardened runtime、entitlements以及把原生模块qwen-live-appshot.node作为 extraResources 打入native/目录。测试覆盖npm test运行src/main/__tests__/下的测试覆盖 discovery 校验、全局快捷键替换、overlay 位置恢复、Appshot 架构与捕获、音频引擎与重采样、Camera 引擎、daemon 连接、reconnect 策略、subagents 视图、theme 与 language 存储、release packaging 守卫等模块。诊断开关开发诊断可在终端启动开发版或应用可执行文件并传入--live-debugcd packages/live-host npm start -- --live-debug release/mac-arm64/Qwen Live Host.app/Contents/MacOS/Qwen Live Host --live-debug不要给 Electron Host 传--debug——该参数会被 Electron 当成已废弃的 Node 调试参数并在启动前退出。日志只包含状态、readiness blocker、尺寸、字节数和错误码不包含图片、音频、API key 或转写内容。Proactive 判断、通知排队播报、harness 任务和 Realtime 生命周期日志由daemon输出需在另一个终端运行qwen-live --debug。排查 monitor 输入时用frameHashJPEG 字节的 SHA256 前 16 位对应 Host 的visual_snapshot_capturedvisual_frame_sent与 daemon 的proactive.monitor_image_sent、proactive.monitor_commit、monitor_committed、monitor_action等日志。daemon debug 模式还会在系统临时目录的qwen-live-monitor-debug/下保存视觉 Monitor 的真实请求request.json、实际送出的 JPEG、含协议静音的 16 kHzinput.wav、response.json仅保留最近创建的 10 个 Monitor这些文件包含真实屏幕摄像头内容诊断完请关闭 debug。十三、发布、签名与更新链路Live Host 使用独立的Qwen Live Host Releaseworkflow、版本号和发布节奏不参与也不阻塞 Qwen Code Desktop ReleasePR 会自动执行一次未签名 dry run检查 arm64/x64 的 DMG、ZIP 和 manifest正式发布只能从main手工触发并执行 Developer ID 签名、notarization、Gatekeeper 和 stapler 验证版本发布使用live-host-vX.Y.Ztag包含两个 DMG、两个 ZIP、Qwen-Live-Host-manifest.json和SHA256SUMS.txt非 draft、非 prerelease 的正式版本还会更新固定的 GitHublive-host-latestfeed并调用一次独立的 OSS 镜像 workflow镜像保存版本化 ZIP 和 manifest再发布一个 latest manifestWebShell 自动安装优先读取 OSS失败时使用 GitHub feed与首次启用一节描述的下载顺序一致Host不会自行创建或强制启用 Login Item需要开机启动时由用户在系统设置 → 通用 → 登录项中显式添加。十四、卸载从菜单栏选择退出 Qwen Live Host如果曾手工添加 Login Item在系统设置中将其移除从/Applications删除Qwen Live Host.app在 WebShell 的设置 → 实验性功能 → Qwen Live中关闭功能如不再需要可在隐私与安全性中撤销 Host 的麦克风、摄像头、辅助功能和屏幕录制权限。结语Qwen Live Host 是 Qwen Live 语音体系中最贴近系统硬件的原生组件它用 Electron 提供轻量浮层与全局快捷键用 Objective-C N-API 模块提供 Appshot 与显示器捕获用严格的 discovery 文件校验与 loopback-only 连接保证 daemon 通信安全并用 fail-closed 策略确保任一权限或自检失败时 Live 保持不可用而非降级出错。理解其架构边界、权限模型与发布链路是正确部署、诊断和二次开发 Qwen Live 语音能力的前提相关实现细节可继续深入 live-host 源码目录 与 qwen-live daemon 文档 查阅。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考