说个这两周在 Windows 上折腾 Codex CLI 的真实感受这个终端里的编程代理跑起来是真能打但它那个“抢鼠标”的毛病差点让我把它卸载了。你这边正开着浏览器查资料、鼠标滚轮翻到一半Codex 那边的终端窗口突然“啪”地弹到最前面焦点被它抢走你切回 IDE 继续写代码过两秒它又弹出来一次。那种感觉就像旁边坐了个不停拍你肩膀的同事活儿是真没少干但你就是没法专心干自己的事。这篇文章把“Windows 下 Codex 安静运行”这件事一次说透。我会先解释它到底为什么抢鼠标再给出一套我已经实测过一段时间的组合方案WSL2 里跑 Codex tmux 会话分离 Windows 前台锁定策略调整顺带覆盖 Codex 安装、第三方模型接入、常见的/responses网关报错和端口占用问题。适合正在用 Codex 写代码、又不想被它打断节奏的人也适合刚在 Windows 上装好 Codex 准备入坑的朋友。1. 先搞清楚Codex 到底是怎么“抢鼠标”的1.1 罪魁祸首不是 Codex是终端焦点机制先说结论Codex CLI 自己并没有写“抢占鼠标”的逻辑它是一个跑在终端里的 Node.js 程序主要通过交互式 TUI 界面类似那种半屏面板和codex exec非交互模式工作。你在 Windows 上通常会用 Windows Terminal、PowerShell 或 VSCode 集成终端来跑它。真正惹祸的是终端窗口和 Windows 前台窗口机制之间的配合。Windows 有一套“前台锁定”机制正常情况下后台进程想把自己变成前台窗口系统会限制它最多在任务栏闪一闪。但很多终端程序为了让用户看到最新输出会主动调用激活窗口的 API当你正在操作鼠标时这种“激活请求”和你的输入打架结果就是终端窗口强行跳到最前面鼠标焦点、滚动条、键盘输入全被它带走。Codex CLI 跑任务时输出非常密集每完成一步就重绘一次界面终端窗口的激活频率比普通命令行高很多于是你就感觉它一直在抢鼠标。生活化类比就是一个热心同事总想插话但每次插话都要站起来凑到你面前。Codex 本来只是“想让你看到进度”Windows 的窗口机制却让它变成了“必须挡住你视线才能说话”。明白了这层关系解决方案就不是去改 Codex 的行为而是从运行环境和窗口策略下手。1.2 我实际遇到的三类“抢鼠标”现场第一类也是最常见的我在浏览器里查 API 文档Codex 正在另一个终端窗口里跑codex exec批量修改文件。每当它输出新的结果终端窗口就弹到最前面鼠标滚轮立刻失效因为焦点不在浏览器上了。一开始我以为是 Windows Terminal 的设置问题试了各种选项没用。第二类是 UAC 和授权弹窗。Codex 自动执行命令时如果碰到需要管理员权限的操作比如修改系统目录、操作 Windows 服务系统会弹 UAC 确认框。这个 UAC 弹窗是系统级的前台窗口一定会抢走鼠标焦点。更麻烦的是有些操作还会触发浏览器登录页或外部工具窗口同样会打断你。第三类是在 VSCode 集成终端里跑 Codex 时终端的输出会自动触发面板切换或滚动导致我正在编辑的代码区域突然被终端面板覆盖。鼠标虽然没被“抢走”但编辑视口被挤没了体验同样很差。明白这些场景之后我给自己定的目标很明确让 Codex 在后台安静跑允许它输出日志但绝不能主动跳到前台打断我。接下来这套方案就是围绕这个目标搭的。2. 整体设计让 Codex 当一个“安静的后台同事”2.1 方案选型思路为什么不是简单忍一忍最省事的想法是“窗口弹出来就再切回去呗”但实测下来这招根本不行。Codex 跑一个稍长的任务输出频率高的时候能弹出十几次甚至几十次你每次切回去都会丢失正在输入的上下文注意力被切得稀碎。也有人说“把终端窗口缩小放角落”但这治标不治本它照样会在你操作其他软件时抢焦点。我最后确定的方案是四个层次叠加第一把 Codex 放进 WSL2 里跑避免 Windows 原生命令行和终端工具各种剪不断理还乱的兼容性问题第二用 tmux 把 Codex 会话和终端窗口“解耦”Codex 即使跑到天荒地老也不需要一个前台终端窗口陪着它第三在 Windows 层面前台锁定策略让任何后台进程都难以强行激活第四把 Windows Terminal 的启动行为改成最小化、不抢焦点并配合虚拟桌面做隔离。这四层缺一不可tmux 负责“不需要窗口”焦点锁定负责“就算有窗口也抢不动”虚拟桌面负责“就算抢了也看不见”。这套组合的成本很低全部用系统自带能力和开源工具基本不引入额外的常驻软件。唯一的代价是需要你稍微适应一下 tmux 的快捷键但换来的收益是Codex 可以像后台服务一样运行你再也不用跟它抢鼠标。2.2 必装与可选工具清单我把整套方案涉及的组件按“必须”和“可选”分了个类实际搭建时按顺序装就行。组件角色是否必须说明WSL2运行 Codex 的环境必须隔离终端行为避免 Windows 原生终端干扰Windows Terminal终端入口必须管理 WSL 会话和 tmux attachNode.js LTSWSL 内Codex 运行依赖必须Codex CLI 是 npm 包必须有 NodeCodex CLIopenai/codex核心工具必须通过 npm 安装tmuxWSL 内后台会话管理器强烈建议核心中的核心没有它很难根治抢焦点问题RBTray / TrayIt!托盘化终端窗口可选喜欢把窗口收起来的人再用微软 PowerToysFancyZones窗口布局可选如果你希望 attach 窗口固定在某些位置为什么强烈建议用 tmux因为它是“分离会话”的终极解法。你在 tmux 里启动 Codex按下CtrlB再按D就能把会话丢到后台关闭终端窗口也不影响它运行。想看进度时随便开一个终端执行tmux attach -t codex就能重新连上。这个模式下Codex 根本不需要一个常驻前台窗口自然谈不上抢鼠标。3. Windows 上安装 Codex 并接入可用模型3.1 标准安装流程统一走 WSL 路径网上很多教程会让你直接在 Windows 的 CMD 或 PowerShell 里安装 Codex但我吃了亏之后强烈建议你走 WSL2 路径。原因很简单Codex 的交互界面、文件读写、命令执行在 WSL2 环境下更稳定Windows 本地的 PATH 环境变量、权限模型和终端工具组合在一起容易出现各种“Windows 专属”问题比如文件路径转义、符号链接权限、自动审批命令失败等。安装流程分三步。第一步启用 WSL2管理员身份的 PowerShell 里执行wsl --install安装完成后重启默认会装好 Ubuntu。第二步进入 WSL安装 Node.js LTS。这里推荐用 nvm 管理版本避免日后升级麻烦curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --lts node -v npm -v第三步安装 Codex CLInpm install -g openai/codex codex --version装完之后先别急着跑任务先登录或配置认证。codex login会打开浏览器完成 OAuth 登录如果你已经有 API Key也可以直接设置环境变量OPENAI_API_KEY。我第一次在 Windows 上登录时卡了很久浏览器弹不出来后来发现是终端里没有正确传递回调地址换成 WSL2 环境后基本一次成功。3.2 配置第三方模型或网关注意 /responses 端点差异很多人跑 Codex 用的是第三方网关或本地代理把请求转发到其他模型。这里有个特别容易踩的坑Codex 新版默认走 OpenAI 的/responses端点Responses API而不是传统/chat/completions。如果你用的本地网关只实现了旧协议就会出现文章标题后面那串报错类似的提示cc switch local proxy failed while handling codex endpoint /responses. provider ...这个报错是把你 Codex 配置切到自定义提供方时本地代理服务无法处理/responses请求。解决办法有两类。第一类把 Codex 的wire_api配置改成网关支持的协议比如 Media 网关只支持 Chat Completions就在~/.codex/config.toml里这样写model_provider custom-gateway [model_providers.custom-gateway] name Custom Gateway base_url http://127.0.0.1:8787/v1 wire_api chat第二类直接换一个支持/responses的网关实现。社区里很多网关都已经适配了新端点如果你的本地代理迟迟不更新建议换一个维护更活跃的项目。还有一类相关报错是模型名不匹配比如网关返回detail: the gpt-5.6-sol model is not supported when using codex with a...这个原因很好判断Codex 默认请求模型名和你网关实际支持的模型名对不上。处理方式是在config.toml里显式覆盖模型名改成你买的或网关支持的别名比如model deepseek-chat。注意改完之后重启 Codex不要在一个已经跑起来的会话里切换。3.3 登录与组织设置加载失败热词榜里有一批人卡在“codex登录不上”和“codex无法加载组织设置”。我遇到过的原因主要有三种。第一种是浏览器登录流程被拦截回调地址没传给终端表现为浏览器一直转圈但终端没有任何反应。这种直接退出登录流程换用 API Key 环境变量方式最省事。第二种是账号对应组织权限问题登录后发现无法加载组织设置经常是账号切换后旧的本地凭证坏了可以删掉~/.codex/auth.json再重新登录。第三种是网络层不稳导致登录请求中断这个跟你的网络环境有关我一般建议错峰重试几次。如果你是首次安装后直接跑codex还会遇到初始化配置向导它会问你要不要用 ChatGPT 登录、要不要设置自动审批等。这里先无脑选默认即可跑通以后再按自己习惯调。4. 核心实操五步让 Codex 不再抢鼠标4.1 第一步把 Codex 会话放进 tmux 后台这是整套方案里最核心的一步也是我反复强调“必装”的原因。进去 WSL 后先装 tmuxsudo apt install -y tmux然后创建一个专门跑 Codex 的会话tmux new -s codex进入会话后正常启动 Codexcodex现在 Codex 就在这个 tmux 会话里运行了。关键操作来了在 tmux 内按下CtrlB然后按D会话会脱离当前终端窗口回到普通的 shell。此时就算你把这个终端窗口关掉Codex 也照样在后台运行。想看进度的时候再开一个 WSL 终端tmux attach -t codex这个模式为什么能根治抢鼠标因为 Codex 运行的“载体”不再是屏幕上的某个窗口而是 tmux 这个虚拟会话。它没有窗口可以抢焦点。你关掉终端窗口后Windows 前台自然跟你正在用的浏览器、IDE 保持原样。如果你用的是codex exec非交互模式也建议放进 tmux。命令可以这样用tmux new -s codex-exec -d codex exec 修复 src/utils.ts 里的类型错误 /tmp/codex.log 21-d参数让 tmux 会话直接后台运行输出写到日志文件。然后你可以随时用tail -f /tmp/codex.log查看进度整个过程中 Codex 一个窗口都没出现过。4.2 第二步调整 Windows Terminal 的“安静模式”虽然有 tmux 打底但有时你还是会想让 Codex 跑在一个可见窗口里比如你正在盯着它执行长任务。这种场景下Windows Terminal 的窗口行为也得调一下否则它还是会抢焦点。第一种做法不要用鼠标双击 Windows Terminal 图标打开新窗口而是统一用命令行控制。Windows Terminal 支持在已有窗口中创建新标签页wt -w 0 nt这样新标签页会在现有窗口里打开不会单独弹一个窗口到你面前。如果你经常要开新终端可以给这个命令配一个别名。第二种做法调整 Windows Terminal 的启动模式。打开设置页面进入“启动”分页把“启动行为”里的默认终端行为设置成“在已有窗口打开”或者直接在settings.json里写windowingBehavior: useExisting这样你启动 wt 时它不会创建一个新窗口而是复用当前已存在的终端窗口。配合虚拟桌面使用更顺滑。第三种做法Windows Terminal 标签页确实抢了焦点时用“专注助手Focus Assist”兜底。Windows 设置里搜索“专注助手”把它设为“仅闹钟”或自定义优先级列表可以屏蔽一部分通知层面的干扰但对窗口激活的帮助有限。别把它当成主要手段tmux 才是正道。4.3 第三步调整 Windows 前台锁定策略Windows 系统自带的前台锁定参数默认能挡住部分抢焦点行为但很多终端程序会用特殊方式绕过。为了更彻底我建议调整两个注册表值。打开注册表编辑器或者直接用管理员权限的终端执行reg add HKCU\Control Panel\Desktop /v ForegroundLockTimeout /t REG_DWORD /d 600000 /f reg add HKCU\Control Panel\Desktop /v ForegroundFlashCount /t REG_DWORD /d 1 /fForegroundLockTimeout的单位是毫秒我之前提到默认值是 200000200 秒意思是“在你最后一次输入后200 秒内后台程序不允许抢占前台”。调成 600000 就是把这个保护窗口拉长到 10 分钟。平时你手动切换窗口是主动操作不受这个限制只有后台程序想偷偷激活时才会被挡。ForegroundFlashCount控制任务栏按钮闪烁次数设成 1 能减少视觉骚扰。改完之后注销或重启一下让它生效。注意这个参数不是越大越好设成几百万毫秒会让某些正常的“呼出窗口”操作变迟钝比如你点击某个托盘图标它要多等几秒才弹出。我的个人经验是 600000 到 3600000 之间比较稳妥无感且有效。4.4 第四步绕开 UAC 弹窗而不是关闭它很多教程看到 Codex 执行管理员命令时老弹 UAC就让你把 UAC 拉到最低。这个做法我坚决反对不要为了省事关掉系统安全机制。更好的做法是让 Codex 尽量不碰需要管理员权限的操作或者把这类命令提取出来单独处理。Codex 有一个自动审批机制可以在配置里设置批准模式。你要小心使用别全局设为“永远不问我”否则 Codex 可以执行任意命令风险很高。我自己的做法是只对受信任的目录启用部分自动批准codex exec --ask-for-approval never --sandbox //wsl$/Ubuntu/home/me/projects/safe-project万一某个任务真的需要管理员权限UAC 弹窗虽然会打断你但至少它会让整个屏幕暗下来明确告诉你系统正在请求授权。这种打断是可以接受的毕竟安全更重要。不要跟它硬刚去关 UAC 不是“不抢鼠标”的正确姿势。4.5 第五步可选最小化启动与虚拟桌面隔离如果你还是习惯让 Codex 跑在可见的终端窗口里可以把它最小化扔到另一个虚拟桌面。Windows 10/11 都支持虚拟桌面快捷键WinCtrlD新建桌面。我给一个固定工作流主桌面跑浏览器、IDE、文档虚拟桌面跑 Codex 终端。你甚至可以把虚拟桌面里的终端设置成开机自动启动每天早上打开电脑它就自己开始跑任务了。自动启动可以简单做一个启动脚本。Windows 里创建一个.bat或.ps1文件内容大致是wt -w 0 nt -- wsl -e tmux attach -t codex把它放进 shell:startup 目录。这段命令的意思是在现有终端窗口里创建一个新标签直接连到 tmux 的 codex 会话。由于 tmux 会话已经脱离窗口这个标签只是“查看器”关掉也不影响 Codex 运行。RBTray 之类的托盘工具算加分项。它可以让你把任意窗口最小化到系统托盘不再占用任务栏区域。终端窗口收到更新时不会在任务栏闪烁因为托盘图标根本没有闪烁逻辑。用了托盘工具后就算 Codex 偶尔弹个窗口也不会把你的注意力拽走。5. 实测工作流左边干活右边 Codex 自己卷方案搭好之后我实际跑了一个多星期的日常开发感觉终于正常了。举一个典型例子我上午在浏览器里查一个第三方 SDK 的文档同时把 Codex 丢在 tmux 会话里让它重构一个小模块。浏览器文档翻到第三页Codex 已经改完文件并且跑完测试了。整个过程中鼠标焦点一次都没被抢走——因为它的会话在 tmux 里屏幕上根本看不到它的窗口。想确认任务状态时我只需要WinCtrlD切到虚拟桌面或者直接敲tmux attach -t codex界面里能看到 Codex 执行了哪些步骤如果某一步出错了我能看到堆栈和输出回主桌面继续查资料修问题再切回来让 Codex 重跑那一步。这种“互不干扰”的感觉才是正解它不是不能干活而是终于学会安静干活了。另外这套方案对排查问题也有帮助。Codex 的任务日志会写到~/.codex/sessions/目录每次会话对应一个 log 文件。如果你用 tmux 重定向输出也可以把它统一收集到/tmp/codex.log。遇到某些奇怪的报错直接看日志比看终端屏幕靠谱得多。举个我踩过的Codex 晚上跑批处理第二天早上我发现某个文件没生成但终端早就滚没了。用 tmux attach 进去历史还在再看~/.codex/sessions日志能定位到是中途有个网络请求失败任务没继续。这一套下来我再也不用守着窗口盯进度了。6. 常见报错速查表下面这些报错和问题基本都是我在 Windows 上实测或者从群里看到的高频问题整理成一张速查表方便直接对照处理。报错现象常见原因处理方式cc switch local proxy failed while handling codex endpoint /responses本地代理网关只支持/chat/completions不支持/responses在config.toml里把wire_api改为chat或升级兼容网关the gpt-5.6-sol model is not supported when using codex with a...Codex 请求的模型名与网关支持的不一致在配置里覆盖model改成网关支持的模型别名codex: command not foundnpm 全局安装路径不在 PATH 里或没在 WSL 中安装检查npm prefix -g添加 PATH确认当前 shell 是 WSL 环境无法加载组织设置本地登录凭证损坏或账号权限变更删除~/.codex/auth.json重新codex login登录不上浏览器回调无响应登录回调被拦截或端口冲突改用OPENAI_API_KEY环境变量方式或检查回调端口是否被占执行命令时卡在审批环节批准模式设置不匹配使用codex exec --ask-for-approval指定模式注意授信范围本地代理端口被占用另一个程序如 Elasticsearch占用了同一个端口用netstat -ano | findstr :端口查 PIDtaskkill /PID 进程号 /F释放端口codex login后终端没反应Windows 命令行环境下的回调处理异常换到 WSL2 再执行登录或直接使用 API KeyWSL 内 npm 安装报权限错误全局安装目录权限不足用 nvm 管理 Node而不是手动改目录权限端口占用这个问题值得多说一句。Codex 接入本地代理时我习惯固定端口比如8787或3000但这类端口经常被其他开发服务占用。排查命令是netstat -ano | findstr :8787 tasklist | findstr 进程号 taskkill /PID 进程号 /F确认端口空闲后再启动你的本地代理。要是端口被系统保留比如 Hyper-V 保留端口可以换一个高位端口比如18087避开常见冲突。说到排查我在实际操作里还有一个心得很多问题其实不用猜Codex 自带调试日志。运行codex exec时加上--debug参数或者直接看~/.codex/log/下的日志文件报错原因写得比终端里的提示清楚得多。遇到“代理失败”“请求被拒”这类问题先看日志再改配置能少走很多弯路。7. 最后再分享两个小技巧第一把常用的 Codex 命令别名化。我自己在~/.bashrc里加了几行比如alias codex-tasktmux new -s codex -d codex exec \\$\ /tmp/codex.log 21 alias codex-attachtmux attach -t codex alias codex-logtail -f /tmp/codex.log这样以后跑任务只需要codex-task 帮我重构某个模块看进度就codex-log想接管交互界面就codex-attach。三条命令覆盖全部日常操作比每次都敲一长串舒服多了。第二建议给 Codex 单独建一个工作目录不要让它直接操作你整个用户目录。这样即使它跑出什么幺蛾子影响面也有限。我在 WSL 里建了~/codex-workspace项目同步、临时脚本都丢在那里配合 tmux 的会话隔离整台电脑上就再也找不到一个会跳出来跟你抢鼠标的窗口了。用了一周之后我最大的感受不是“Codex 变强了”而是“我终于能把它当后台服务用了”。它干活我干我的活互不打扰这才是 Windows 上跑 Codex 的正确姿势。