# Voice Notify for Codex [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | [Русский](README.ru.md) 当 Codex 需要您关注或完成工作时，以私密的本地语音提醒您。它适合容易错过权限请求、 子代理变化、上下文压缩或任务完成提示的 macOS 和 Windows 用户。 ### 使用 - [在 ChatGPT 中打开 Voice Notify for Codex](https://chatgpt.com/plugins/plugins_6a6600dd92148191a6dfe0c16eb85c83)，或使用下方 GitHub 安装命令。 - 完成引导式设置，亲自检查 `/hooks`，然后选择声音、语言、生命周期事件或播放间隔。 您可以随时测试、静音或恢复本地提示。 ### 试一试 - `当 Codex 请求权限或完成时，用简体中文女声提醒我。` - `测试本地 Stop 提示，然后将 Voice Notify 静音。` - `Tell me aloud when Codex finishes, using the female Simplified Chinese voice.` ### 关键边界 - 运行时播放完全离线，不保留或发送任何对话内容。 - 仅处理 Codex 生命周期语音设置，不适用于通用 TTS 或旁白、语音转写、云通知、 任意操作系统音频自动化或从截图提取操作项。 - 不会静默安装或绕过 hook 信任。用户必须亲自检查并信任插件自带的 hook； 不会修改无关的通知设置。 Verified on 2026-08-29: OpenAI Platform shows **Published**; the latest remote catalog snapshot shows **GLOBAL/AVAILABLE** with discoverability **UNLISTED**. `UNLISTED` 并不表示已在公共目录中列出或可搜索。仓库包 0.1.7 是更新候选；此已验证状态仅描述现有远程条目，并不表示 0.1.7 已审核或发布。 这是一个独立插件，源代码采用 MIT 许可证，语音资源采用单独的许可证。它不隶属于 OpenAI，也未获 OpenAI 背书。 ## 功能 插件会为以下事件播放本地 WAV： - `SessionStart` - `UserPromptSubmit` - `PreToolUse` - `PostToolUse` - `PermissionRequest` - `PreCompact` - `PostCompact` - `SubagentStart` - `SubagentStop` - `Stop` 版本 0.1.7 内含 100 WAV 文件，覆盖两种声音配置、五种语言与十种生命周期事件的 全部组合。本次补丁明确了 discovery 元数据，并在五种语言的 README 中提供等效的首屏 使用说明；语音资源和运行时行为与 0.1.6 相同。 在 macOS 上，插件使用系统自带的 `/bin/sh`、`plutil`、`afplay` 和 `osascript`； 在 Windows 上，则使用 PowerShell 和 `System.Media.SoundPlayer`。它不需要 Python 或 Xcode Command Line Tools。插件不包含网络代码或遥测，也不会存储提示词、消息、 工具输入或工具输出。播放不会阻塞任务，本地锁和短暂冷却时间可避免音频重叠。 ### 交互式代码本体 本仓库的自包含交互式本体是使用 [Code Ontology Companion](https://github.com/battle-doll/code-ontology-companion) 从 Voice Notify `0.1.6` 生成的。Code Ontology Companion 可以将已获授权的 Java/Spring 或 Python 代码库逆向分析为注重隐私的本地知识图谱。 [在线打开 Voice Notify 代码本体](https://rawcdn.githack.com/battle-doll/codex-voice-notify/ce42d10e88fc490271bea2c123a611bfa3d12b13/codex-voice-notify-code-ontology.html)，或[在 GitHub 上查看和下载源 HTML](https://github.com/battle-doll/codex-voice-notify/blob/code-ontology-showcase/codex-voice-notify-code-ontology.html)。 该快照分析了 6 个 Python 文件，包含 417 个节点和 769 条关系，解析警告为零，且每条关系都附有提取证据和源码位置范围。您可以搜索符号，检查调用者和依赖项，在 2D 结构视图与 3D 星座视图之间切换，并查看每条关系的规则、定性依据、运行时状态、源码位置范围和局限性。 这仍是静态分析证据，而非运行时证明。Voice Notify 在 Windows 和 macOS 上的实际钩子入口点分别是 PowerShell (`.ps1`) 和 POSIX shell (`.sh`)，超出了此 Python 快照的适配器覆盖范围。此示例在获得明确的发布授权后公开。在线预览仅使用 raw.githack 作为 HTML 内容类型桥接；自包含工作台本身在运行时不依赖 CDN 或网络。 ## 从 GitHub 安装 将仓库 URL 交给 Codex 并要求安装此插件，或者运行以下命令。 macOS： ```bash codex plugin marketplace add battle-doll/codex-voice-notify --ref main codex plugin add codex-voice-notify@codex-voice-notify ``` Windows PowerShell： ```powershell codex.cmd plugin marketplace add battle-doll/codex-voice-notify --ref main codex.cmd plugin add codex-voice-notify@codex-voice-notify ``` ## 首次设置 安装后，选择插件的 **Finish first-time setup** 提示，或直接用自然语言向 Codex 提出请求。 > 使用韩语女声完成 Voice Notify 的首次设置。需要时检查并更新 Codex CLI。 此启动提示可以安全地重复执行。目前 Codex 插件界面不会在首次使用后有条件地隐藏 提示，因此它会保留下来，便于恢复或重新设置。 引导式设置会执行以下操作： 1. 检查 Codex CLI 版本是否支持 `/hooks`；仅当设置提示明确授权时，才会按需更新 npm 或 Homebrew 安装。 2. 保存所选声音和语言。 3. 试播本地 `Stop` 通知。 4. 打开一个新的终端窗口，并在其中启动已验证的 Codex CLI，而不只是显示 `/hooks` 输入说明。 插件自带的设置脚本只报告兼容性，不会自行修改主机安装。Codex 会先检查 CLI 来自 npm、Homebrew cask 还是其他位置，再执行用户已经授权的更新。 在新打开的 Codex CLI 终端中输入 `/hooks`，检查插件自带的命令并明确选择信任。 然后彻底退出并重新启动 Codex，再测试实际的生命周期事件。钩子信任设置会被保留， 但已经运行的 Codex 进程可能要到下次启动时才会启用新信任的插件钩子。Codex 不会在 安装时自动信任第三方钩子，本插件也绝不会绕过该审核步骤。 如果正在运行的 CLI 可执行文件无法被替换而导致更新失败，请退出该 CLI，在另一终端中 运行显示的更新命令，然后重新开始设置。 ## 配置 您可以随时使用自然语言提出请求，例如： - “使用英语女声。” - “把 Voice Notify 改为日语男声。” - “使用俄语女声。” - “把 Voice Notify 改为简体中文男声。” - “改为韩语女声。” - “将 Voice Notify 静音。” - “测试 Stop 通知。” Codex 会将 `female` 或 `male` 以及韩语/韩文 (`ko`)、日语 (`ja`)、英语 (`en`)、 俄语 (`ru`) 或简体中文 (`zh-CN`) 映射到插件自带的设置命令。插件仅内含 `zh-CN` 这一种中文变体，因此未指定变体的“中文”请求会默认映射到 `zh-CN` （简体中文、中国大陆普通话）。您也可以从克隆的仓库中手动运行以下命令。 macOS： ```bash /bin/sh scripts/voice_notify_config.sh setup --voice female --language ko --open-hooks /bin/sh scripts/voice_notify_config.sh show /bin/sh scripts/voice_notify_config.sh set --voice female --language ko /bin/sh scripts/voice_notify_config.sh set --voice male --language en /bin/sh scripts/voice_notify_config.sh set --voice female --language ru /bin/sh scripts/voice_notify_config.sh set --voice male --language zh-CN /bin/sh scripts/voice_notify_config.sh test --event Stop /bin/sh scripts/voice_notify_config.sh mute ``` Windows： ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\voice_notify_config.ps1 setup -Voice female -Language ko -OpenHooks powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\voice_notify_config.ps1 show powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\voice_notify_config.ps1 set -Voice female -Language ko powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\voice_notify_config.ps1 set -Voice male -Language ru powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\voice_notify_config.ps1 set -Voice female -Language zh-CN powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\voice_notify_config.ps1 test -Event Stop powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\voice_notify_config.ps1 mute ``` 默认值为 `female`、`ko`、450 毫秒最短播放间隔，并启用八种事件。为避免每次工具 调用都产生过多通知，`PreToolUse` 和 `PostToolUse` 保持可用但默认关闭。 `PermissionRequest` 只会在 Codex 实际请求权限时播放。 ## 故障排除 - 如果无法识别 `/hooks`，请将 Codex CLI 更新至 `0.145.0` 或更高版本，然后重新 开始设置。 - 如果 PowerShell 阻止 `codex.ps1` 或 `npm.ps1`，请使用 `codex.cmd` 或 `npm.cmd`。插件自带 Windows 设置命令中的 `-ExecutionPolicy Bypass` 仅适用于 当前进程，不会更改系统执行策略。 - 如果测试声音可以播放，但生命周期通知没有出现，请在 `/hooks` 中检查并信任该钩子， 然后彻底重新启动 Codex。 ## 兼容性 版本 0.1.7 支持 macOS 和 Windows，并使用系统自带的音频与脚本组件。macOS 不需要 Python 或 Xcode Command Line Tools。引导式钩子设置需要 Codex CLI `0.145.0` 或更高版本。暂不支持 Linux。 ## 许可证 源代码采用 MIT 许可证。`assets/audio/` 下的所有 WAV 文件均不属于 MIT 许可证 范围。根据 [ASSET_LICENSE.md](ASSET_LICENSE.md) 中的有限授权，这些文件只能 保持原样，只能作为未经修改的免费 Voice Notify for Codex 副本的一部分，并且只能 用于个人、非商业通知播放；仅可在这些条件下使用、复制和重新分发。 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 仅记录生成来源。大多数男声通知 由 Fish Audio 生成，两个韩语子代理文件则使用 Qwen Base 重新生成，以匹配当前 文案。这些来源信息不会改变语音资源的使用条款。