OpenCodex Windows 服务控制台窗口问题全解析：从根因调查到“无窗口后台服务“的完整修复路径

【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载导读本文基于 opencodex 仓库中devlog/_fin/260720_windows_service/系列调查文档完整还原一次 Windows 平台服务运行机制问题从用户报障、根因定位、双议题拆分到最终落地修复隐藏式 VBS 启动器 可选的 WinSW 原生服务 backend的全过程。读者将理解为什么ocx service install在 Windows 上会弹出可关闭的 cmd 控制台窗口、窗口被关闭后为何所有模型包括 GPT 系会集体断连以及当前仓库源码中已经实现的两种修复路径各自的取舍与验证前提。一、问题背景用户报障与社区观察2026-07-15DC 画廊DC gallery出现一则用户报障英文原意是on Windows … closing the proxys console window can make every model (even gpt models) disconnect——在 Windows 上关闭代理的控制台窗口会导致**每一个模型包括 GPT 模型**全部断连。社区跟帖中用户已经给出了相当接近真相的观察在 Windows 上即使以服务方式安装cmd 窗口还是会弹出来只有在任务计划程序设置里改成『不需要登录即可运行』并填入密码窗口才会消失。因为这本来就不是真正安装成服务。用 nssm 注册可能能解决。这些评论恰好点中了问题的三个侧面窗口暴露Task Scheduler 计划任务在交互会话中运行、非真服务计划任务不是 SCM 服务、候选替代NSSM 这类服务包装器。本项目随即启动了260720_windows_service调查单元目标是把问题文档化、以代码为依据定位根因、并拆成 Bug/Feature 两个 GitHub 议题分别登记。二、症状与复现路径控制台窗口的连锁死亡调查文档 001_research.md 给出了完整的复现链路可以概括为以下六步在 Windows 上执行ocx service install。任务计划程序Task Scheduler创建任务opencodex-proxy以登录触发器LogonTrigger启动~/.opencodex/opencodex-service.cmd批处理包装器 →cmd 控制台窗口直接显示在用户屏幕上。用户点击窗口右上角的 X 关闭它这是代表性复现路径会话注销 logoff、任务管理器强制结束属于同一类强制终止。Windows 向该控制台关联的所有进程发送CTRL_CLOSE_EVENT默认处理例程HandlerRoutine直接结束进程。包装器批处理是同步执行Bun 的%OCX_BUN% %OCX_CLI% start因此包装器与代理子进程被绑定在同一控制台生命周期里一起死亡批处理内部的 5 秒重启循环ping -n 6延时因为批处理本身已死而失效。Codex 所依赖的 localhost 代理消失 → 所有经路由的模型GPT 系也在其中因为注入状态下 GPT 请求同样走代理全部 disconnect。这里有一个需要特别标注的未验证项needs-verification这种强制终止是否会被 Task Scheduler 记录为任务失败从而触发 XML 里配置的RestartOnFailurePT1M × 3 次见 src/service/windows-taskxml.ts 的Settings段自动重启官方文档只定义了 RestartOnFailure 在task failure时生效而窗口关闭导致的进程终止是否算 task failure需要 Windows 实机观测。文档明确列出了观测清单schtasks /query /v的LastTaskResult、TaskScheduler Operational 事件日志Microsoft-Windows-TaskScheduler/Operational、包装器/子进程 PID、代理 health 端点以及窗口关闭后 PT1M 内是否发生重启。三、根因三个因素的组合而非单一配置错误调查结论明确这是三个因素叠加的结果断言其中任何一个单独成立都是片面的。对应代码位置如下#因素代码位置aLogonTypeInteractiveToken/LogonType任务在用户的交互会话中执行等价于计划任务 UI 的仅在用户登录时运行src/service/windows-taskxml.ts 的Principal段b任务动作直接执行控制台程序.cmd批处理——交互式会话 控制台子系统 可见的控制台窗口同一 XML 的Actions/Exec段原本的Command指向包装器 .cmdc缺少隐藏启动机制没有 VBS/PowerShell-WindowStyle Hidden启动器也没有 conhost 分离等方案—文档还专门澄清了三个容易误解的点Hidden与窗口无关Task Scheduler XML 里的Hidden设置当前为false只是控制任务是否显示在计划任务 UI 列表中与运行时的控制台窗口没有任何关系。windowsHide: true只管注册那一刻在 CLI 调用schtasks.exe管理命令时才生效已注册任务日后真正执行时启动的窗口不受影响。包装器注释与实际行为矛盾包装器脚本源码里写着 The wrapper runs in its own hidden console自己的隐藏控制台但InteractiveToken下这并非事实。文档明确把这个注释与实际行为之间的矛盾写进了交付物。此外会话中断Remote Desktop 注销、会话解锁、控制台连接/断开同样会带走交互会话里的代理进程。仓库的 windows-taskxml.ts 已经通过WINDOWS_SESSION_RECOVERY_STATE_CHANGESRemoteConnect/SessionUnlock/ConsoleConnect三个SessionStateChangeTrigger把这类中断变成下次连接时自动恢复源码注释里记录过一次真实案例单台机器日志中 19 次此类终止造成了最长约 60 小时的代理空窗。四、为什么ocx stop没有问题正常终止路径的对照调查单元特意对照了正常终止路径证明问题只存在于关窗式强制终止ocx stopsrc/cli/index.ts 的handleStop的执行顺序是stopServiceIfInstalled()—— 先停掉服务管理器阻断 respawnstopProxy(pid)—— 走 management-API drain 优先的优雅停机在 Windows 上这是关机处理器真正跑起来的唯一路径taskkill /F只是内部回退restoreNativeCodex()/revertSystemEnv()—— 把 Codex 环境还原为原生状态。因此正常终止路径是完整的、有始有终的所有问题都集中在控制台窗口关闭这一类非优雅终止路径上。五、候选方案评估从最小改动到结构性改造调查文档 001_research.md 以表格形式对比了四类方案外加一个缓解性参考并逐项标注了约束与成本选项是否消除窗口性质约束/成本A. LogonType 改为S4U是非交互执行最小 diff 候选需要 batch-logon 权限无法访问网络凭据/EFS当前 XML 无显式UserId简单字符串替换的稳定性未验证Microsoft 账号 passwordless 注册兼容性未确认B. WinSW 包装器是真正 SCM 服务结构性解法需要随包分发二进制、部署成本服务注册需要管理员权限最新 stable 为 v2.12.020233.x 属于 prerelease 系列C. NSSM 包装器是社区方案可用但官方正式版停在 2.242014-08-31推荐 prerelease 也停留在 2017 年——作为新采纳候选劣于 WinSWD. 仅用sc.exe—不适用Node/Bun 进程未实现 SCM 服务控制协议握手参考VBS/PowerShell 隐藏启动器是仅隐藏窗口症状缓解进程生命周期问题随窗口消失而消失但拿不到真正的服务语义SCM 管理、开机启动对候选 AS4U文档强制要求先过一组验证矩阵才能采纳本地账号 / Microsoft 账号passwordless各自执行schtasks /create /xml是否都能注册成功执行账户是否默认具备Log on as a batch job权限普通用户 / 企业 GPO 环境分别验证包装器依赖的%USERPROFILE%/%APPDATA%环境间接化在 S4U 会话中是否正确解析ACL 加固的 token 文件读取、服务日志写入是否正常EFS 加密主目录、UNC / 自定义OPENCODEX_HOME、企业认证代理等边界环境。六、代码盘点当前实现已具备的能力与缺口调查单元对 src/service/windows-taskxml.ts 及周边代码做了能力盘点区分已有与缺失已有重复实例防护MultipleInstancesPolicyIgnoreNew/MultipleInstancesPolicy失败重启RestartOnFailureIntervalPT1M/IntervalCount3/Count/RestartOnFailure是否覆盖关窗场景见前述 needs-verification崩溃恢复循环包装器批处理的 5 秒重启循环用ping延时替代timeout资产重写韧性writeServiceAssetWithRetry对 EBUSY/EPERM/EACCES 重试陈旧路径诊断bakedServicePathsDiagnostic检测 npm prefix / nvm 迁移导致的路径失效服务重启时避免还原 Codex 配置的OCX_SERVICE1再注入契约。缺失窗口不可见、且无法通过关窗杀死的执行模式强制终止后的自动恢复保证需实机验证。七、落地的两步修复隐藏启动器默认路径 可选的 WinSW 原生服务调查单元本身只覆盖文档化 议题登记030 记录两个议题以gh issue create登记到仓库Bug #165 与 Feature #166但后续实现单元040→050→060→070把方案落成了代码。当前仓库源码中两套修复均已实现可以作为技术文章的收尾实证。7.1 默认路径wscript.exe VBS 隐藏启动器修复 #165这是对默认 Task Scheduler backend的修复核心决策在 050_hidden_launcher.md保留InteractiveToken不需要凭据、兼容 passwordless 账号任务动作从直接执行 .cmd改为执行C:\Windows\System32\wscript.exe /b /nologo launcher.vbsVBS 内用WshShell.Run cmd, 0, True以窗口样式 0隐藏启动批处理其中bWaitOnReturnTrue常驻启动器是关键wscript 必须存活到批处理结束任务实例才算运行中MultipleInstancesPolicyIgnoreNew的防重与schtasks /end的停止目标才得以维持若设为Falsewscript 立即退出任务被当作已结束防重机制随之失效这是评审中的 blocker 1编码契约VBS 必须与任务 XML 一样以UTF-16LE BOM写入writeServiceAssetWithRetry(path, \uFEFF vbs, utf16le)因为无 BOM 的 UTF-8 会在 WSH 版本/代码页差异下误读非 ASCII如韩文/中文用户路径blocker 2路径独立做 XML 转义含的路径 →amp;并拒绝 PowerShell 替代方案powershell.exe本身是控制台程序会闪窗且-File可能被默认 Restricted 执行策略拦截。当前源码 windows-taskxml.ts 的buildWindowsLauncherVbs()正是这个形态生成shell.Run escaped path, 0, True且buildWindowsTaskXml()的Exec已改为 wscript.exe /b /nologo launcher参数/b为批处理模式抑制脚本错误弹窗。测试套件 tests/service/service.test.ts 覆盖了引用转义恶意带引号路径、非 ASCII韩文用户路径、UTF-16 BOM 写入、以及 XML 中的转义。7.2 可选路径ocx service install --native的 WinSW 原生服务回应 #166对希望拿到真正 SCM 服务语义的用户仓库提供了选项式 backend。核心实现在 src/lib/winsw.ts设计与实现要点二进制供应不把二进制提交进 npm 包首次install --native时从 GitHub Release 下载WinSW.NET461.exev2.12.0用固定的 SHA-256 指纹校验当前源码WINSW_SHA256已固化 64 位十六进制值哈希不符即 fail-closed删除文件并抛错离线/代理环境给出手工放置路径的提示。服务身份SCM 服务 ID 为opencodex-proxy-native与计划任务名opencodex-proxy区分以用户账号运行且禁止 LocalSystem——因为 ACL 加固的 token 文件只授予用户 SIDSYSTEM 服务反而读不到 token且 SYSTEM 属主的写入会破坏用户访问契约。凭据处理XML 中不保存密码winsw install /p在控制台用 stdin 继承提示输入因此该命令走新增的runFileInteractive()同步执行 helper。安装后用sc.exe qc校验SERVICE_START_NAME若意外变成 LocalSystem 立即回滚卸载并报错。XML 要点v2 架构的serviceaccountdomain/user/allowservicelogon而非 v3 的usernameenv nameOCX_SERVICE value1/保持服务语义契约bake 当前 PATHSCM 服务环境没有用户交互 PATH不 bake 会导致 provider 可执行文件解析失败——这与 Scheduler/launchd/systemd 全线 bake PATH 的既有契约一致log moderoll-by-size日志轮转onfailure actionrestart delay5 sec/stoptimeout20 sec/stoptimeouttoken 通过OCX_API_TOKEN_FILE环境变量由应用启动时读取绝不放进 XML。backend 状态化安装状态service install state写入version: 2的 schema 并记录backend: scheduler | native导出readServiceBackend()与serviceReinstallArgs()供更新流程使用保证ocx update重装服务时保持原 backend且stop/uninstall/status会同时探测两个 backend 以捕获双安装冲突。对应测试见 tests/service/winsw.test.ts覆盖 serviceaccount 存在且 LocalSystem 缺位、PATH 转义、SHA-256 格式与 fail-closed、状态解析三分支Started/Stopped/NonExistent、以及本地化sc.exe输出中的 1060 错误识别。八、边界与后续事项本次调查单元明确不触碰代码src/service.ts等保持原样工作树中既有的 dirty 文件gui/src/pages/Models.tsx也不在本次范围内议题登记后代码修复由后续单元接力。待同步的 SoT本次未改、留给代码单元README.md 支持平台表中 Windows 行的 known-limitation 注释、README.md 第 237 行附近 starts on boot 与实际是 logon 触发器启动的语义修正、以及 docs/codex-path-investigation.md 的 Windows 服务一节。必须保留的实机验证项跨平台开发机无法替代 Windows 实测隐藏启动器的窗口不可见与schtasks /end后的进程树终止范围、RestartOnFailure是否在关窗场景触发、passwordless Microsoft 账号下的 WinSW 失败模式、以及 SCM stop 是否能把 CtrlC 信号送达 Bun 进程完成 graceful drain。结语这次调查的价值在于它把一个服务装了却弹窗、关窗就全断的 Windows 平台怪象归约到交互式登录令牌 直接执行控制台批处理 缺少隐藏启动的三因素组合并用两条互补的修复路线默认隐藏启动器 可选 WinSW 原生服务分别回应了最小改动与结构正确两个诉求。文中引用的计划、研究、双议题文告与实现文档全部可以在 devlog/_fin/260720_windows_service/ 目录按编号顺序查阅源码证据则以 windows-taskxml.ts 与 winsw.ts 为核心。赞分享【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载相关推荐opencodex Windows 服务控制台窗口问题Bug 提报、根因定位与窗口无关后台运行方案全解析opencodex Windows 服务控制台窗口问题Bug 提报、根因定位与窗口无关后台运行方案全解析 本指南完整收录 opencodex 在 Windowopencodex Windows 无窗口后台服务Task Scheduler S4U 与 WinSW 原生服务方案全解析opencodex Windows 无窗口后台服务Task Scheduler S4U 与 WinSW 原生服务方案全解析 导读 本文以 opencodexOpenCodex Windows 服务隐藏启动器改造wscript VBS 实现无控制台窗口的 Task Scheduler 后台服务OpenCodex Windows 服务隐藏启动器改造wscript VBS 实现无控制台窗口的 Task Scheduler 后台服务 本指南围绕 Op上一篇源雀SCRM AI开源版破解企业私域营销三大困境的终极解决方案下一篇GitButler TypeScript配置严格类型检查和编译优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考