说个这两周在 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 必装与可选工具清单

我把整套方案涉及的组件按“必须”和“可选”分了个类，实际搭建时按顺序装就行。

为什么强烈建议用 tmux？因为它是“分离会话”的终极解法。你在 tmux 里启动 Codex，按下Ctrl+B再按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 CLI：

npm 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 后先装 tmux：

sudo apt install -y tmux

然后创建一个专门跑 Codex 的会话：

tmux new -s codex

进入会话后正常启动 Codex：

codex

现在 Codex 就在这个 tmux 会话里运行了。关键操作来了：在 tmux 内按下Ctrl+B，然后按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 2>&1'

-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 /f

ForegroundLockTimeout的单位是毫秒，我之前提到默认值是 200000（200 秒），意思是“在你最后一次输入后，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 都支持虚拟桌面快捷键Win+Ctrl+D新建桌面。我给一个固定工作流：主桌面跑浏览器、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 里，屏幕上根本看不到它的窗口。

想确认任务状态时，我只需要Win+Ctrl+D切到虚拟桌面，或者直接敲：

tmux attach -t codex

界面里能看到 Codex 执行了哪些步骤，如果某一步出错了，我能看到堆栈和输出，回主桌面继续查资料修问题，再切回来让 Codex 重跑那一步。这种“互不干扰”的感觉才是正解：它不是不能干活，而是终于学会安静干活了。

另外这套方案对排查问题也有帮助。Codex 的任务日志会写到~/.codex/sessions/目录，每次会话对应一个 log 文件。如果你用 tmux 重定向输出，也可以把它统一收集到/tmp/codex.log。遇到某些奇怪的报错，直接看日志比看终端屏幕靠谱得多。举个我踩过的：Codex 晚上跑批处理，第二天早上我发现某个文件没生成，但终端早就滚没了。用 tmux attach 进去，历史还在；再看~/.codex/sessions日志，能定位到是中途有个网络请求失败，任务没继续。这一套下来，我再也不用守着窗口盯进度了。

6. 常见报错速查表

下面这些报错和问题，基本都是我在 Windows 上实测或者从群里看到的高频问题，整理成一张速查表，方便直接对照处理。

端口占用这个问题值得多说一句。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-task='tmux new -s codex -d "codex exec \"\$@\" >> /tmp/codex.log 2>&1"' alias codex-attach='tmux attach -t codex' alias codex-log='tail -f /tmp/codex.log'

这样以后跑任务只需要codex-task "帮我重构某个模块"，看进度就codex-log，想接管交互界面就codex-attach。三条命令覆盖全部日常操作，比每次都敲一长串舒服多了。

第二，建议给 Codex 单独建一个工作目录，不要让它直接操作你整个用户目录。这样即使它跑出什么幺蛾子，影响面也有限。我在 WSL 里建了~/codex-workspace，项目同步、临时脚本都丢在那里，配合 tmux 的会话隔离，整台电脑上就再也找不到一个会跳出来跟你抢鼠标的窗口了。用了一周之后，我最大的感受不是“Codex 变强了”，而是“我终于能把它当后台服务用了”。它干活，我干我的活，互不打扰，这才是 Windows 上跑 Codex 的正确姿势。