🔔 Codex Remote Notify
English
将在无 GUI Linux 服务器上运行的 Codex 任务进展，直接通知到本地 VS Code 窗口。
最后更新时间：2026-08-05
[!NOTE]
本扩展专注于一个使用场景：本地 VS Code 通过 Remote SSH 连接 Linux 服务器，Codex 任务在远端运行，任务完成、请求授权或等待输入时在本地 VS Code 中提醒。
✨ 功能
- Codex 完成任务、请求授权或请求用户输入时，默认在 VS Code 状态栏显示可点击的定时提醒。
- 可间接缓解
plan mode 下 60 秒自动回复问题；扩展本身不会关闭 Codex 的倒计时或自动回复机制。
- 点击状态栏提醒或原生通知中的“查看对话”，在右侧 Codex 辅助边栏打开对应会话。
- 支持定时状态栏与原生通知两种模式，以及自定义通知模板、消息长度、显示时机和 Hook 管理方式。
- 远端 Linux 无需 GUI、DBus、X11、
notify-send 或桌面通知服务。
🎬 功能示例（点击展开）
以下动画展示可选的原生通知模式；默认模式为定时状态栏提醒。
任务完成通知
请求输入通知
🔎 关键词
Codex extension notification、Codex Remote SSH notification、task status notification、grill-me notification、countdown timer in plan mode、disable timed auto-resolution for questions
✅ 使用要求
- VS Code 1.90 或更高版本；
- OpenAI Codex VS Code 扩展（
openai.chatgpt，已声明为扩展依赖）；
- Codex 已启用生命周期 Hooks；
- 远端主机可以启动 Codex CLI，用于通过
/hooks 审查并信任扩展安装的 Hook。
[!IMPORTANT]
本扩展不支持本地工作区通知、Windows 远端或非 SSH 远端，也不提供声音提醒或操作系统桌面通知。所有提醒都显示在本地 VS Code 窗口中。
🚀 快速开始
- 使用 Remote - SSH 连接 Linux 主机并打开一个远端目录。
- 在扩展中搜索
codex-remote-notify，选择 Codex Remote Notify，安装后重新加载远端窗口。
- 接受首次安装提示，或运行 Codex Remote Notify：安装或更新 Codex Hooks。
- 在远程终端中运行
codex，进入 Codex CLI 交互界面后输入 /hooks，审查并信任 Stop、PermissionRequest 和 PreToolUse 下由本扩展安装的三个处理器。
- 重新加载窗口，即可实现任务通知。
- （可选）按下
Ctrl+Shift+P 打开命令面板，输入并运行 Codex Remote Notify：打开设置，根据需要调整，详见设置小节。
[!TIP]
/hooks 是 Codex CLI 的斜杠命令，不是 Codex IDE 扩展聊天输入框中的命令。详见 Codex Hooks 文档。- Hook 变更后，建议新建 Codex 会话再进行验证，已有会话可能仍使用旧的 Hook 配置。
⚙️ 设置
按下 Ctrl+Shift+P 打开命令面板，输入并运行 Codex Remote Notify：打开设置，即可根据需要调整以下参数：
| 设置后缀 |
默认值 |
用途 |
enabled |
true |
在本地 VS Code 中显示远端 Codex 的任务通知。 |
displayMode |
statusBar |
可选定时 statusBar 或原生 notification。 |
onlyWhenWindowUnfocused |
false |
仅当切换到其他应用或其他 VS Code 窗口时显示通知。 |
showCompletion |
true |
Codex 完成任务后显示通知。 |
showInputRequired |
true |
Codex 请求授权或用户输入时显示通知。 |
completionMessageTemplate |
{title}: {message} |
任务完成通知模板。 |
inputRequiredMessageTemplate |
{title}: {message} |
等待输入或授权通知模板。 |
completionDisplaySeconds |
4 |
状态栏完成提醒显示 1–60 秒。 |
inputRequiredDisplaySeconds |
6 |
状态栏输入或授权提醒显示 1–60 秒。 |
messageMaxCharacters |
240 |
将{message} 限制为 1–2000 个 Unicode 字符。 |
hookInstallationMode |
prompt |
可选prompt、automatic 或 manual。 |
migrateLegacyHooks |
false |
安装或更新时，可选删除依赖仓库路径的旧 Hook。 |
pollIntervalMs |
750 |
轮询 Codex 事件的间隔，范围为 250–10000 毫秒。 |
retentionHours |
24 |
过期事件的保留时间，范围为 1–168 小时。 |
openCodexCommand |
chatgpt.openSidebar |
无法打开对应会话时执行的回退命令。 |
codexHome |
空 |
覆盖远端CODEX_HOME；否则使用 ~/.codex。 |
eventDirectory |
空 |
覆盖远端事件队列目录；否则使用默认目录。 |
完整设置名以 codexRemoteNotify. 开头。两个通知模板均支持 {title}、{message}、{sessionId}、{turnId} 和 {cwd} 占位符。
🪝 Hook 管理
| Codex Hook |
触发的通知 |
Stop |
Codex 当前 turn 结束 |
PermissionRequest |
Codex 请求授权 |
匹配request_user_input 的 PreToolUse |
Codex 请求用户输入 |
安全默认值 prompt 会在修改 Hook 前询问；automatic 会在扩展启动和相关设置变化时自动安装或修复；manual 不自动修改 Hook，但仍可手动运行安装、更新和卸载命令。
[!WARNING]
扩展默认不会修改依赖仓库路径的旧 Hook。只有明确开启 migrateLegacyHooks 后，下一次安装或更新才会删除可识别的旧通知 Hook。新旧 Hook 同时存在可能产生重复通知。
卸载扩展前，请先运行 Codex Remote Notify：卸载 Codex Hooks。卸载命令只删除带有新版扩展管理标记的处理器，不会影响其他 Codex Hook。
🔄 实现原理
通知链路由远端 Hook、私有事件队列和 VS Code Remote Extension Host 共同完成：
远端 Codex 生命周期事件
↓
Codex Remote Notify Hook
↓ 原子写入 JSON 事件
~/.codex-remote-notify/events
↓ 定时轮询并领取匹配当前工作区的事件
远端 VS Code Extension Host
↓ 按配置创建定时状态栏项目或调用原生通知 API
本地 VS Code 窗口
↓ 点击状态栏项目或“查看对话”
右侧 Codex 辅助边栏中的对应会话
每个事件包含类型、消息、会话 ID、turn ID 和远端工作目录等信息。扩展根据事件中的 cwd 将通知路由到对应的 Remote SSH 工作区；领取事件后立即从队列删除，避免同一事件被多个 VS Code 窗口重复提醒。
默认 statusBar 模式最多同时显示两条提醒；新提醒会依次替换最早的一条。任务完成默认显示 4 秒，等待输入或授权默认显示 6 秒，超时后直接删除且不进入通知中心。切换到 notification 模式可恢复原生信息/警告弹窗，其时长和通知中心记录由 VS Code 管理。
点击状态栏提醒或“查看对话”时，扩展使用事件中的 sessionId 请求 OpenAI Codex 扩展打开对应会话。如果无法直接定位会话，则执行 openCodexCommand 配置的回退命令，至少打开 Codex 侧栏。
🔐 数据与隐私
事件只在远端主机的私有 JSON 队列中传递，不会发送给第三方通知服务。扩展不收集遥测。在支持 POSIX 权限的文件系统上，事件目录权限为 0700，事件文件权限为 0600。
点击通知打开会话时，跳转操作交给已安装的 OpenAI Codex 扩展；Codex Remote Notify 自身不会上传会话内容。
🛠️ 排查问题
运行 Codex Remote Notify：显示诊断信息，然后查看 Codex Remote Notify 输出通道。重点确认以下内容：
remote=ssh-remote；platform=linux；hookStatus=installed；- Hook 运行脚本和事件目录均为有效路径；
- 在远端 Codex CLI 的
/hooks 界面中，三个处理器均已信任。
更多帮助见 SUPPORT.md，安全问题报告方式见 SECURITY.md。
🙏 致谢
本项目基于 ZekerTop/ai-cli-complete-notify 构建。原项目实现了多平台、多渠道的通知功能，但似乎没有覆盖本项目专注的“本地 VS Code Remote SSH 无 GUI Linux”使用场景。感谢原作者和贡献者的开源工作。
📄 许可证
ISC
