Codex Switch

重磅新增：Claude Code CLI 也能「看图」了 🖼️

v2.1.0 让 Codex 用上了 DeepSeek 的视觉模型（deepseek-v4-flash-vision-exp），这一版把它带给 Claude Code CLI——模型映射里新增该选项，选它之后 Claude Code CLI 就能把图片 / 截图发给 DeepSeek 识别。

• Claude Code CLI 也能选「DeepSeek V4 Flash Vision」了。在「Claude Code CLI 接入」卡片点「管理模型映射…」，把某个 Claude 档位映射到 deepseek-v4-flash-vision-exp（默认已把 Haiku 映射到它）；保存后在新终端窗口生效
• 怎么用「看图」：打开新终端 claude，输入 /model 切到已映射到该视觉模型的档位（默认是 Haiku），然后把图片 / 截图拖进对话即可让 DeepSeek 识别画面内容、读取截图文字
• 默认映射已为你配好三档：Claude Opus → DeepSeek V4 Pro，Claude Sonnet → DeepSeek V4 Flash，Claude Haiku → DeepSeek V4 Flash Vision（「看图」档）；主对话跟随 Sonnet（DeepSeek V4 Flash）、子代理跟随 Haiku（DeepSeek V4 Flash Vision）
• 依旧官方直连、无需本地代理。Claude Code CLI 直接连 DeepSeek 官方 Anthropic 兼容接口（api.deepseek.com/anthropic），请求里的模型名会原样发送，因此视觉模型能真正收到图片
• 从哪里找：设置 →「Claude Code CLI 接入」→「管理模型映射…」

变更

• Claude Code CLI 的 DeepSeek 可选模型补齐为三个（Flash / Pro / Vision），与 Codex 接入一致；Claude Code CLI 主对话 / 子代理默认模型跟随档位自动更新
• 说明（Claude Desktop）：Claude Desktop 的第三方网关受 Anthropic 客户端限制，只能请求 claude-* 路由名，图片到不了 DeepSeek 视觉模型，因此 v2.2.0 Claude Desktop 不提供该模型，模型映射仍为 Pro / Flash 两个 DeepSeek 模型
• 提示：Vision 是 DeepSeek 的实验模型，能力可能随官方迭代调整；能否真正收发图片取决于 DeepSeek 官方对 Anthropic 兼容端点的支持

重磅新增：Codex 也能「看图」了 🖼️

DeepSeek 推出了实验多模态模型 DeepSeek V4 Flash Vision（deepseek-v4-flash-vision-exp），除了文字，它还能接收图片 / 截图。v2.1.0 把 Codex 接到了这个模型上——官方模型目录已同步补上该模型的图片能力，Codex 据此允许给这个模型发图。

• Codex 接入新增「DeepSeek V4 Flash Vision」模型。在「Codex 接入」的默认模型里选它（首次启动的模型向导里也能选），点保存即可生效。日常文字任务建议继续用 Flash / Pro，需要「看图」时再切换到 Vision
• 模型可以读懂图片 / 截图。选中后，在 Codex 里贴入图片或截图，即可让 DeepSeek 描述画面内容、识别截图里的文字、分析图表等
• 依旧官方直连、无需本地代理。选好模型点保存，Codex 直接连 DeepSeek 官方接口；同时会自动把官方最新三模型目录同步到本机的 ~/.codex/models.json，Codex 才能识别这个新模型
• 从哪里找：设置 →「Codex 接入」卡片 →「默认模型」下拉里多了一项「DeepSeek V4 Flash Vision · 实验（可读图）」

变更

• 设置页与首次启动向导的模型列表同步更新，Flash / Pro / Vision 三个模型放在一起、一目了然
• 提示：Vision 是 DeepSeek 的实验模型，能力可能随官方迭代调整。图片请放在你的提问里；关于支持格式、大小上限等细节，可参考 DeepSeek 官方「图像理解」文档

重磅变更：Codex 直连 DeepSeek 🚀

DeepSeek 官方已原生支持 Codex 使用的 Responses API。从 v2.0.0 开始，Codex 直接连接 DeepSeek 官方接口，不再经过本地代理——配置方式与 DeepSeek 官方一键脚本完全一致，延迟更低、少一层转发。

• Codex 直连 DeepSeek。在设置中选 DeepSeek，填 Key，点保存——Codex 直接连 api.deepseek.com，本地代理自动跳过启动。Dashboard 会显示「直连」状态
• 官方模型目录。自动写入 ~/.codex/models.json，Codex 能像使用内置模型一样使用 deepseek-v4-flash / deepseek-v4-pro，推理强度、上下文窗口等元数据与官方一致
• 存量用户自动迁移。从旧版本升级的用户，Codex 配置会自动从代理模式改写为直连模式，无需手动操作
• 代理仅保留给 Agnes / 智谱 GLM。这两个供应商仍走本地代理做协议翻译；全直连时代理不会启动

变更

• 侧边栏「和 X 位朋友一起使用」数字口径更新。从「30 天活跃用户」改为「累计注册客户端数」——更真实地反映有多少人用上了 Codex Switch
• 注意（已知取舍）：直连模式下，Codex 的请求日志、token 用量统计、对话缓存这些原本由本地代理提供的能力不再生效。这是直连的固有特性——请求数据直接到 DeepSeek，不再经过本机
• 版本要求：~/.codex/models.json 模型目录需要 Codex 0.144 或更高版本才能正确读取；旧版 Codex 仍可直连使用，但可能退化为默认模型行为

重磅变更：PackyCode 升级为「自定义供应商」🔓

v1.15.0 引入的 PackyCode 是一个特定第三方服务。v1.16.0 把它升级为通用自定义供应商——不再绑定任何特定服务商，你自己填 Base URL，想接哪个兼容 API 就接哪个。完全自主、完全灵活。

• 「自定义」取代「PackyCode」。设置中所有供应商选择已从「PackyCode」改为「自定义」——不再预置任何服务商名称。用什么服务、填什么地址，完全由你决定
• 两个 Base URL，各管各的。Codex 接入和 Claude 工具接入现在各有独立的 Base URL 输入框——Codex URL（OpenAI Responses 兼容端点，通常带 /v1 后缀）和 Claude URL（Anthropic Messages 兼容端点，通常不带后缀）。填写后点保存即生效，适配任意兼容的第三方 API
• 存量用户平滑迁移。之前选了 PackyCode 的用户，供应商类型会自动改为「自定义」，API Key 保留不动——只需补填两个 Base URL 即可继续使用（URL 字段留空，等你自行填写）
• 模型列表完全不动。自定义供应商的模型选项和之前 PackyCode 一样——无需重新配置模型映射

变更

• 全局去品牌化。FAQ 帮助文档、智能搜索、设置页、主面板——所有提到「PackyCode」的地方都已替换为「自定义供应商」的中性表述。强调「选择什么供应商完全由用户自主决定」
• 代码层重命名。底层 provider 标识从 packycode 改为 custom，配置存储新增 customProvider 字段（含 codexBaseUrl 和 claudeBaseUrl）。自定义供应商依然是直连模式，不经过本地代理

重磅新增：PackyCode 供应商接入 🎉

PackyCode（packyapi.com）是一个第三方 AI API 聚合服务，同时支持 Codex 和 Claude 的原生协议。用它接入 Codex 和 Claude，不需要本地代理翻译——数据直接加密发到 PackyCode，延迟更低、速度更快。

• Codex 直连 PackyCode。在设置中「Codex 接入」卡片选 PackyCode，填 Key，点保存——Codex 直接和 PackyCode 对话，不经过本地代理。代理会自动跳过启动，节省系统资源
• Claude Desktop / Code CLI 直连 PackyCode。Claude 工具同样支持 PackyCode——选完供应商填 Key，Claude Desktop 和 CLI 直接走 PackyCode 的 Anthropic 兼容端点。Opus / Sonnet / Haiku 三个模型各自透传原生模型名，计费精准不混淆
• 混合模式自由搭配。Codex 用 PackyCode（直连）、Claude Desktop 用 Agnes（经代理）、Claude CLI 用 DeepSeek（直连）——三张卡片各选各的，互不干扰。代理只在需要时启动，全直连时自动停
• 主面板智能适配。全直连模式下主面板不再显示「启动/停止代理」按钮，改为绿色「直连模式」标识——点开就知道当前不需要代理，清爽直观

修复

• 混合模式下 Claude 工具不再报错。Codex 选 PackyCode + Claude 选 Agnes 的组合现在正常工作——Agnes Key 正确加载，Claude 请求正常转发
• 全切直连后代理自动停。把三个工具都切到 PackyCode 后，代理自动停止不再空跑占端口
• Haiku 模型计费精准了。修复了 Claude Desktop 中选 Haiku 模型时实际发给 PackyCode 的是 Sonnet 模型名的问题——现在三个模型各自精准透传

修复：切换供应商后 Claude Desktop / CLI 配置文件不生效 🔧

在设置里把 Claude Desktop 从智谱 GLM 切换到 DeepSeek（或反过来），点「保存并应用」，配置文件可能没有被修改——Claude Desktop 里看到的还是旧供应商的模型。

• 切换供应商后配置文件强制写入。不再依赖「检测到 Claude Desktop 已安装」才写配置——只要你主动点了保存，不管检测结果如何，配置一定会写入。没装 Claude Desktop 就先写好了等你装，装了就直接生效
• 模型映射不再残留。切换供应商时，之前存的旧供应商模型映射自动清空，点保存后模型自动用新供应商的默认值（例如切到 DeepSeek 自动用 deepseek-v4-pro / deepseek-v4-flash）。想自定义映射也可以打开「管理模型映射」自行调整
• 少了 Key 会明确提示。之前只有 Agnes 和 GLM 缺 Key 才提示，DeepSeek 缺 Key 时点保存静默失败——现在三个供应商缺 Key 都会明确告诉你「请先在供应商设置中配置 Key」
• 写入失败会报错了。之前配置写入失败在后台悄悄吞掉，你看到的始终是「保存成功」——现在写入失败会直接在界面上显示具体错误原因

新增：长对话自动续命 🎉

聊到一半突然报「对话过长」中断？现在代理会自动帮你处理——把太早的历史精简掉，对话继续，你什么都感觉不到。

• 上下文超限自动截断重试。DeepSeek 报"聊太长了"时，代理不再直接丢错误给你看，而是自动裁剪最早的旧消息、保留最近 30 条关键对话，然后静默重试。绝大多数情况下对话无缝继续，你完全无感知
• 工具调用结果也不会丢。裁剪时自动保留相关的工具配对，不会出现工具结果孤零零没上下文的情况
• 日志里能看见。如果自动截断发生了，Codex Switch 日志页会显示一条「自动截断 N 条旧消息后重试」，方便排查

修复

• 供应商切换后模型选啥就是啥。切换供应商时选择的默认模型不再被覆盖——选 glm-4.7 就是 glm-4.7，不会偷偷变成 glm-5.2
• macOS 升级不再懵圈。升级新版本后如果提示「已损坏」，点安装按钮时会弹出修复指引，下载文件夹里还会自动生成一个双击即修复的脚本
• 修复了长对话中的三个隐蔽问题（同版本持续迭代）：
• 截断重试失败时 Codex 不再卡在「等待中」转圈——现在正确发送 response.failed 事件让 Codex 正常结束
• 截断后不再出现孤立工具调用导致 DeepSeek 协议错误——工具调用和结果的配对清理现在覆盖双向
• 修复了对话历史在被截断重试后仍可能因消息重复而超限的问题——消息累积逻辑不再重复拼接历史记录

重磅新增：智谱 GLM 完整接入 🎉

智谱 GLM 是国内大模型供应商，API 兼容性好、中文能力强。现在 Codex Switch 完整支持——设置里选 GLM，填 Key，点保存，Codex / Claude Desktop / Claude Code CLI 全部接上。

• 多供应商再加一员。设置页四张接入卡片现在都支持「智谱 GLM」选项，DeepSeek、Agnes、GLM 三选一，各工具独立选择
• GLM + Codex。供应商选 GLM 后，代理自动翻译 OpenAI Responses → Chat Completions 发到 open.bigmodel.cn，Codex 无感知直接对话
• GLM + Claude Desktop / Code CLI。Claude 全家桶选 GLM 后直连智谱 Anthropic 兼容端点（open.bigmodel.cn/api/anthropic），不经过本地代理，延迟更低
• 模型映射同步更新。模型映射弹窗新增 glm-5.2 / glm-5.1 / glm-4.7 三个 GLM 模型，开启「管理模型映射」即可选择

重磅新增：免费模型 Agnes AI 接入 🎉

Agnes AI 是一个免费 API 供应商，无需付费，支持 256K 上下文、工具调用。现在 Codex Switch 完整支持——设置里选 Agnes，填 Key，点保存，全家桶一起切。

• 多供应商支持。设置页新增四张独立接入卡片：「供应商设置」统一管理 Key、「Codex 接入」「Claude Desktop 接入」「Claude Code CLI 接入」——每张卡片独立选择 DeepSeek 或 Agnes，互不干扰
• Agnes + Codex。供应商选 Agnes 后，代理自动翻译 OpenAI Responses → Chat Completions，Codex 无感知，直接对话
• Agnes + Claude Desktop / Code CLI。Claude 全家桶选 Agnes 后自动走 Codex Switch 代理，Anthropic Messages → Chat Completions 翻译在代理层完成，Claude 端无需改模型名
• 模型映射弹窗。Claude 卡片新增「管理模型映射」，可单独配置每个 Claude 模型对应哪个实际模型
• 供应商秒切不重启。切供应商只改代理内存映射，Codex 和代理都不需要重启

新增

• 🔍 智能搜索。右上角新增搜索按钮，输入问题 AI 秒回答案，支持拖拽调整窗口大小
• FAQ 新增 Agnes。帮助文档新增「如何接入免费的 Agnes AI 模型」，从注册到配置三步走

变更

• 对话缓存大幅精简。删掉自研的上下文压缩和磁盘持久化，改为纯内存缓存。代码净减 2000 行
• 旧对话不怕丢。缓存超限后，代理自动从 Codex 原生会话文件读取历史，没有上限

修复

• 长对话不再报 compact 错误。代理直接返回"无需压缩"，不再 404/502
• 上下文超限给中文提示。超出上限时弹出人话建议
• 保存配置时自动写入窗口优化设置。告诉 Codex "你有 1M 窗口"

修复

• 自动更新检查终于正常工作了。修复了更新检查一直报错的问题，现在启动 5 秒后会自动检查新版本，每 6 小时再检查一次。有新版会自动下载，完成后点右上角一键升级

修复

• 装完插件，技能列表终于有东西了。Codex 插件安装后会自动注册所有技能到活跃列表，技能面板不再空空如也。只注册通用开发类技能，跳过需要外部账号的 SaaS 插件

新增

• Claude 扩展一键安装。插件页面 Claude 标签不再是占位——现在可以下载 170+ 个 Claude 扩展包（165 MB），一键复制指令粘贴到 Claude Desktop Cowork 中自动安装。精选 20 个核心扩展（含 Superpowers 全系列），也可以自定义选择安装哪些
• Claude Code 也支持。下载完成后点击「安装到 Claude Code」按钮，获得专属提示词，粘贴到 Claude Code 即可把扩展装进去
• 插件列表硬编码。170+ 个 Claude 扩展清单内置在应用中，分类浏览、按需勾选，不需要等网络加载

新增

• 推荐给朋友。侧边栏新增「💚 推荐给朋友」入口，一键复制推荐语发给朋友。朋友打开安装指南，按步骤就能装好 Codex 和 Claude
• 社区计数。侧边栏底部显示「和 X 位朋友一起使用」，知道自己不是一个人
• 🎖 早期成员。v1.11.0 发布前安装的用户将永久拥有「早期成员」身份标签，显示加入日期和通过你加入的朋友数量
• 自动更新增强。设置中新增「自动下载新版本」开关（默认开启）。开启后有新版本自动下载，完成后右上角通知，点一下就能升级。macOS 也会自动下载 DMG 到下载文件夹

修复

• 修复更新后窗口无法显示的崩溃问题（IPC handler 重复注册）

重磅新增：离线插件一键安装 🎉

这是 Codex 用户安装后的 Top 1 痛点：插件市场强依赖 GitHub/npm 等境外资源，国内用户根本刷不出来。现在只需点两下——下载 → 复制一条指令粘贴到 Codex——173 个精选插件全部就位。

• 173 个精选离线插件包。涵盖 Claude Code 集成、代码格式化、Git 辅助、中文优化等，由 codex-switch-server 维护更新
• 国内 COS 广州高速下载。36 MB 约 15-20 秒完成（2 MB/s），比直连 GitHub 快 50 倍以上
• 零门槛体验。侧边栏新增「🔌 插件」入口 → 点击下载 → 复制指令 → 粘贴到 Codex 对话框中 → Codex 自动完成安装
• 智能去重。已下载过的用户再次进入直接跳到安装引导，不浪费流量
• 下载保护。磁盘空间不足提前提示、30 秒静止超时自动中断、取消即清理临时文件
• Dashboard NEW 角标。首次使用引导，进入一次后自动消失

新增

• 插件页面（src/pages/Plugins.tsx）。5 阶段状态机：加载 → 浏览 → 下载中（进度条+速度+剩余时间）→ 完成引导 → 错误恢复
• PluginManager 核心模块（electron/plugins/）。Server API 调用 → 302 重定向到 COS → 流式 pipe 写入磁盘 → 500ms 进度推送
• 插件遥测。plugin_pack_info_fetch / plugin_pack_download / plugin_install_command_copy 三个事件，追踪下载漏斗转化率
• Dashboard 插件快捷卡片。「🔌 Codex 插件 · 173 个精选插件可一键安装 → 下载并安装」
• Help FAQ 新增。「如何安装 Codex 插件？」——标签「插件」

修复

• 修复 plugins:get-install-command IPC handler 被重复注册导致应用启动时窗口无法显示的崩溃 bug

修复

• 上下文超限自动恢复 Token 化。emergencyCompact 从按消息条数截断改为按 token 数截断（800K 上限），解决大代码块对话中单条消息 30 万+ token 导致压缩后仍超限的问题。
• 孤儿 tool 消息自动清理。新增 removeOrphanedTools 函数，token 截断后自动移除失去对应 tool_calls 的孤立 tool 消息，修复 DeepSeek 返回 "tool must be a response to a preceding tool_calls" 错误。
• 中文错误识别。isContextExceededError 新增"对话过长"、"上下文限制"、"超过模型"中文模式匹配。
• 压缩状态保存提前。恢复逻辑改为先保存 compacted 状态再重试，即使重试失败下轮请求也不会重复从原始超大对话开始。

新增

• 对话历史保护方案（多用户反馈，P0）。详见 docs/DESIGN-conversation-preservation.md。
• 代理停止前强制刷盘，消除 5 秒 debounce 窗口内的对话数据丢失
• 对话缓存默认不清除（MAX_AGE→永久，MAX_ENTRIES 50→1000），用户可在设置中调整上限或手动清空
• Settings → 新增「对话缓存」区块：显示已缓存条数、最早记录时间、缓存上限、清空按钮
• 对话记录来源切换。首次安装时自动备份原始配置（install-original），永久保留。
• Settings → 新增「对话记录来源」开关：一键在 OpenAI 官方 ↔ Codex Switch 代理之间切换
• 切换不会删除任何对话——用户随时可找回 OpenAI 上的历史对话
• Dashboard 恢复提示。首次使用后若存在原始配置备份，显示可关闭的 amber 提示条引导用户找回对话。

修复

• 上下文超限自动恢复增强（v1.8.1 补充）。isContextExceededError 新增中文模式识别（"对话过长"、"上下文限制"、"超过模型"），覆盖 DeepSeek 中文错误信息。
• conversation-store 自动清理逻辑移除（24h/50 条静默删除 → 用户手动控制）

质量提升（按 QUALITY-AUDIT-v1.7.0.md 执行）

P0 — Critical - C4 CSP: src/index.html 新增 Content-Security-Policy meta 标签 - C1 Server 拆分: server.ts 1587→641 行（-60%），提取 6 个子模块

P1 — High - H1 路径穿越: restoreCodexConfig/deleteBackup/restoreClaudeDesktopBackup 新增目录白名单校验 - H2 命令注入: env-writer.ts 的 setx/reg delete 改为 execFile（参数数组） - H5 IPC 校验: keySet/proxyLookupPort/proxyKillPort/prefsSet/codexWrite 新增类型/范围校验 - H6 并发竞态: store.ts 新增 writeMutex 串行化写入 + applyPreferencesTransaction 精确回滚

P2 — Medium - M1 静默 catch: 6 个文件 9 处 catch 块添加 log.warn/log.debug - C2 渲染层测试: 新增 store.test.ts（10 用例）+ Settings.test.tsx（6 用例） - C3 E2E 框架: Playwright 配置 + smoke.test.ts + test:e2e 脚本

P3 — Low - M2 死代码: 移除 2 个未使用的 IPC 通道 + void dialog - M3 IPC 一致性: 新增自动验证 preload 与 channels IPC 同步的测试 - M5 依赖更新: electron-updater 6.8.3→6.8.9，prettier 3.8.3→3.8.4；评估报告记录大版本风险

新增

• Server 集成 — 更新检查接入 codex-switch-server。 新增 'server' 镜像模式（默认首选），更新检查 feed URL 指向 https://www.codexswtich.cloud/api/v1/updates。pickAuto 探测顺序调整为 server → github → ghproxy。
• 体验优化计划（匿名遥测上报）。 新增 electron/server-client/ 模块：config.ts（Server URL 三级优先级解析 + clientId 管理）、client.ts（HTTP 客户端，原生 node:https）、telemetry.ts（遥测客户端，支持离线检测、退避重试）。默认开启，可在 Settings 底部关闭。
• 网络离线自适应。 断网时遥测静默停止上传，HEAD ping 主动探测 + 被动错误兜底，连续 3 次失败后指数退避（5min → 10min → 20min，上限 1h）。离线下 track() 不入 buffer，网络恢复后自动恢复上报。遥测故障绝不阻塞代理主流程。
• Settings → 底部新增「体验优化计划」勾选框（默认勾选）。

变更

• updateMirror 默认值从 'auto' 改为 'server'。v1.6.x 存量用户自动迁移。
• electron/updater/mirrors.ts：MirrorMode 类型新增 'server'，buildFeedUrl 和 pickAuto 支持 server 参数。
• electron/config/store.ts：新增 serverUrl、telemetryEnabled、clientId 三个字段及默认值。
• electron/ipc/channels.ts：新增 telemetry:set-enabled、telemetry:get-online、server:ping IPC 通道。
• electron/proxy/server.ts：新增 ProxyOptions.onModelCall 回调，每次请求完成时触发，供遥测使用。
• src/types/global.d.ts：新增 serverUrl、telemetryEnabled、clientId 类型，updateMirror 扩展为含 'server'。

开发连调

• 开发模式（!app.isPackaged）自动连接 http://localhost:8000/api/v1，零配置即可本地连调。
• 环境变量 CODEX_SWITCH_SERVER_URL 可覆盖 Server URL（优先级最高）。

变更

• Claude Desktop 直连 DeepSeek（不再走本地代理）。 Claude Desktop 3P 网关 profile 从指向本地代理 http://127.0.0.1:{port}/anthropic 改为直接指向 https://api.deepseek.com/anthropic，API Key 从占位符改为真实 DeepSeek Key。与 Claude Code CLI 一致——两者都直连 DeepSeek，不再经过 Codex Switch 代理转发。
• 删除 electron/proxy/anthropic-relay.ts（约 400 行）。模型名重写、tools/tool_choice strip、SSE 流式转发、max_tokens clamp 等代理层逻辑全部移除。
• server.ts 移除 /anthropic/v1/* 路由（3 条）。
• desktop-writer.ts 重写：profile JSON 增加 __codexSwitch: "managed" 标记用于卸载识别；inferenceModels 扩展为 3 条（opus→v4-pro, sonnet→v4-flash, haiku→v4-flash）；PROFILE_NAME 改为 "DeepSeek"。
• store.ts 简化：ClaudeDesktopPrefs.modelMap 字段移除（模型映射由 DeepSeek 端点按前缀处理）。
• detect.ts 更新：检测 Claude Desktop 配置的条件从 127.0.0.1 改为 deepseek.com。
• 前端 UI 简化：ClaudeSettingsSection 移除 Desktop 三行模型映射下拉框，改为只读模型表。
• 新增 v1.6.0 迁移：存量用户 profile 自动从本地代理 URL 改写为 api.deepseek.com + 真实 API Key。

修复

• max_tokens 穿透问题自然消除。 v1.5.5 修复的 Claude Desktop warmup probe max_tokens=1 导致回复截断问题，直连后不再需要代理层 clamp（DeepSeek 端点自行处理）。

新增

• 上下文压缩完整重构（LLM 摘要 + 持久化）。 修复了 Codex Desktop 在长对话后调用 /v1/responses/compact 时报 502 错误的问题。根因有三：① compact 端点缺少错误处理/超时/请求体大小限制，流异常时连接裸断导致 502；② 旧实现仅做"ID 克隆"没有真正的上下文压缩，长对话最终超出 DeepSeek 上下文窗口；③ conversationStore 纯内存存储，代理重启后历史全部丢失（"失忆"bug 复现）。重构为三个维度：健壮性（HTTP handler 全加固：30s 超时 / 1MB 大小限制 / 流错误捕获 / 400/408/413/500 分级错误响应；WebSocket 新增 response.compact 事件处理）、LLM 摘要（消息数 >20 时调用 DeepSeek 做对话摘要，保留最近 10 条不动，失败时回退截断保留 30 条）、持久化（conversationStore 使用 ndjson 文件存储，debounce 5s 刷盘 + compact 后强制刷盘，启动恢复 + 24h/50 条自动清理）。新增 electron/proxy/compact.ts 和 electron/proxy/conversation-store.ts 两个模块，新增 19 个测试用例，全量测试 123 个通过。

修复

• 对话失忆修复。 使用 Codex Switch 代理后，Codex 每轮回复都不记得上一轮说了什么。根因：OpenAI Responses API 是有状态的，Codex 客户端每轮只发当前新消息并附带 previous_response_id，历史上下文本应由服务器维护；代理完全忽略了该字段，导致每次请求都只含当轮消息、模型完全失忆。修复：代理新增 conversationStore，每轮请求结束后将完整对话保存为对应 responseId 的记录，下轮收到 previous_response_id 时自动查找并拼接历史，再发给 DeepSeek，最多缓存 200 轮（按连接生命周期自动 GC）。

修复

• 多工具调用（multi-tool use）400 报错修复。 当 Codex 在同一轮次里发出多个 function_call（如同时调 shell、read_file、write_file），之前每个调用被翻译为独立的 assistant 消息，导致 DeepSeek 返回 400 错误："An assistant message with tool_calls must be followed by tool messages"。现已修复：同一轮次所有 function_call 合并进一条 assistant 消息的 tool_calls 数组。

修复

• Windows 自动升级/退出可靠性修复。 解决 Windows 用户在下载完更新点「立即升级」时报错"原版本程序未关闭"的问题。优化：在调用升级安装前主动停止代理并刷新统计数据，避免 before-quit 事件锁死进程；退出逻辑由 app.quit() 改为 app.exit(0)，确保进程彻底销毁。
• 多工具调用（multi-tool use）400 报错修复。 当 Codex 在同一轮次里发出多个 function_call（如同时调 sh、read_file、write_file），之前每个调用被单独翻译成一条 assistant 消息，导致 DeepSeek 报 400："An assistant message with 'tool_calls' must be followed by tool messages"。现在将同一轮次的所有 function_call 合并进一条 assistant 消息的 tool_calls 数组，符合 Chat Completions 协议规范。

新增

• 拦截请求不计入统计，日志默认过滤。 被本地拦截的请求（空 warm-up / suggestion）不再累加到"处理请求数"或 lifetime 统计；日志面板默认隐藏拦截条目，可通过"显示拦截请求 (N)"按钮切换显示。统计条仅展示实调 DeepSeek 的请求数量。
• Token 计费（持久化）。 每次实调 DeepSeek 结束后记录 DeepSeek 返回的 usage（inputTokens / outputTokens），在日志面板成功行末尾显示 ↑X ↓Y tokens；主面板「累计」区块新增输入 / 输出 / 总 token 统计，跨重启持久化（每 30s 写入 electron-store）。未来付费「节省 token」功能预留了 tokenSavingEnabled 字段钩子。

修复

• v1.1.9 的空 warm-up 拦截条件写错了。 原条件要求 instructions 为空，但 Codex Desktop 的 warm-up 帧虽然 input=[]，却带了系统提示词，导致条件始终为 false、warm-up 仍被转发到 DeepSeek（1.5–2.5s/次）。本版只看 input.length === 0，不再看 instructions。
• 日志面板区分 "实调 / 已拦截 / 失败"。 被本地拦截的请求现在指示为灰色圆点 + ⌫ 本地拦截，未调用 DeepSeek（未消耗 token），顶部统计条同时展示 实调 DeepSeek / 已拦截 两个计数，让用户一眼看出哪些请求费了 token、哪些是免费本地返回。

v1.1.8 拦住了 "建议气泡" 提示词本身（~1ms），但 Codex Desktop 在打开后台 WS 时还会发一帧 空 warm-up handshake（items=0 instructions=''），上版仍会转发到 DeepSeek。结果是即使用户不操作，Codex Desktop 仍然每 ~30s 轮询一次，每次费一次真 DeepSeek 调用。

修复

• 同时拦截空 warm-up 请求：如果一条 response.create 的 input 是空数组且 instructions 为空，本地直接返回空 response.completed，不走上游。finishReason=blocked-empty-input，耗时 ~1ms。
• codex CLI 的真实提问首帧 items ≥ 1，不会误伤。

说明

• Codex Desktop 的轮询本身是其客户端行为，我们无法从代理侧禁止（关掍 WS 会被立即重连，反而更坏）。本修复使每次轮询的两条请求（warm-up + suggestion）都变为本地短路，累计费用接近零。

用户用 Codex Desktop 单句提问产生 17+ 请求、长时间使用累积 500+：复盘日志定位出 Codex Desktop 后台 "hyperpersonalized suggestions" 特性在每个闲置周期会拉起独立 WS，每个 WS 又带动 4-7 次 tool-use 调用。这些请求与当前会话无关、不影响使用、纯耗 token。

修复

• 拦截 Codex Desktop "建议气泡" 后台请求。 代理以指纹识别（# Overview / Generate 0 to 3 hyperpersonalized suggestions）本地返回空建议 + end_turn=true，不调用 DeepSeek。后台 finish 标记为 blocked-suggestion，日志可查。开启后同一提问的总请求数从可能数十次变为 1–2 次。
• 设置 → 代理与模型 里新增开关（默认开）：拦截 Codex Desktop 后台 "建议气泡" 请求。依赖该特性的用户可手动关闭。

基于 v1.1.6 的可观测日志，复盘了用户提供的 ndjson：所谓 "一句话被打 5 次" 实际上是 两个独立 WS 上的两件事——一个是用户真实提问（1 次请求即 end_turn），另一个是 Codex IDE 的 "hyperpersonalized suggestions" 后台特性触发的多轮 tool-use 链（warm-up + 提示 + 3 次 function_call_output → 最终 stop）。代理本身行为正确，每次 tool_calls 都正确发 end_turn=false、最终 stop 发 end_turn=true。

修复

• 模型映射补全：gpt-5.4、gpt-5.4-pro 加入默认映射表，避免 codex CLI 自报 gpt-5.4 时落到前缀兜底规则触发 WARN。CURRENT_MAPPING_VERSION 升至 3，老用户启动时自动合并新键（已有自定义映射不被覆盖）。

说明（不修复）

• 后台 "suggestions" 多轮 tool-use 链是 codex IDE/CLI 自身的能力，由模型决定是否调工具、调几次。代理只是忠实转发协议，不应也不会拦截。如希望减少这类调用，请在 codex 端关闭对应特性。

v1.1.5 的 end_turn 修复在 codex exec 单次问答里验证有效（1-2 次请求即结束），但用户报告交互式 codex 仍然有连发请求；本版本不再做 "靠猜的修复"，而是把诊断信息 写进默认日志，让下一次复现就能看出真因。

新增（诊断/可观测）

• proxy.ndjson 现在每条 WS 请求都带 connId（如 ws_mptyt2e9_7hrm），同一个 WS 上的请求一目了然——之前所有日志条目都没有连接 id，导致无法区分 "5 次同 WS 循环" 和 "5 次独立 WS 调用"。
• 请求开始日志现在包含 items=N kinds={message:3,function_call_output:1,...} tools=N lastUser="前 80 字"，可以直接看出 codex 是不是在重发同一个问题（lastUser 重复 = bug；items/kinds 增长 = 正常 tool-use 流转）。
• 请求成功日志现在包含 end_turn=true|false finish=stop|tool_calls|...，确认本进程实际发出去的 response.completed.end_turn 与上游 DeepSeek 的 finish_reason。
• WS 关闭日志多打印 conn=... 关联 connId。

加固

• end_turn 判定加 finish_reason !== 'tool_calls' 双保险：即使 DeepSeek 把空 tool_calls 数组带在 deltas 里，只要 finish_reason: 'stop' 也会被判为本轮结束。
• 文档代码审查：PROXY_DEBUG_WS=1 仍然保留为打印 WS 原文消息的强力开关，但日常诊断已不再依赖它。

仍待验证

• 本机 codex exec 验证为单次问答 2 次调用（1 次 warm-up + 1 次真实回答），无循环——此版本不再做盲目修复，等用户在交互式 codex 上跑一次后，根据新增日志锁定真因。

彻底修复"问一句话被打 5 次"的浪费请求 bug。这是真正的根因，1.1.4 的字段补全是必要但不充分的前置修复。

修复

• response.completed 现在包含 end_turn 字段：当本轮没有挂起的 function_call 时为 true，否则为 false。
• 根因：codex CLI v0.135 的 agent loop（见 codex-rs/codex-api/src/sse/responses.rs 的 ResponseCompleted / codex-rs/core/src/client.rs）以 Option<bool> 解析该字段。我们之前没发，codex 解析为 None，agent loop 误判"对话还没结束"，自动在同一 WS 上再发 response.create，把同一句话反复打到 DeepSeek，直到客户端 backoff 用尽以 1006 断连——用户看到的就是"一句话被打 5 次 + Reconnecting"。
• 修复后 codex 拿到 end_turn=true 立刻终止本轮，单次问题只产生一次上游请求。
• 验证：本机用真实 codex exec --skip-git-repo-check "..." 跑通，PROXY_DEBUG_WS=1 抓 WS 原文确认每个用户提问只对应一对 response.create/response.completed。

新增

• PROXY_DEBUG_WS=1 环境变量：开启后在 stdout 打印每条 WS 入/出消息原文（截断到 600 字符），便于本地排查协议层问题。生产模式默认关闭，无任何性能影响。
• 仓库内新增 scripts/dev-proxy.cjs 与单测 tests/unit/stream.endTurn.test.ts，把 end_turn 行为锁死。

修复 codex CLI 不交事、不停「Reconnecting…」但 proxy 依然连续返 200 的坊间 bug（同一条 WS 上 5 次重发同一个问题，WS 未闭）。

修复

• response.created / response.completed 现在包含 created_at、error: null、incomplete_details: null、usage（上游 DeepSeek 返回的 token 计数映射为 OpenAI 格式，缺省 0/0/0），与 OpenAI Responses API 契约一致。较新版 codex CLI 缺这些字段会判响应不完整并重试，用户看到的是“Reconnecting…”。
• handleWs 加 20s 服务端 ping 心跳（ws 库默认不发），WS 关闭日志补充 reason。

CI 修复：v1.1.2 发版流水线在下载 nsis-resources-3.4.1.7z 时遇 GitHub 镜像 502，导致 Windows 包未产出；format:check 检出 7 个文件未走 prettier。

修复

• 为 release.yml 的 Windows build 加 3 次重试（与 mac 一致），避免偶发 502 直接失败。
• pnpm format 走一遍，全库 prettier 清洁。

UX 补丁：为关键操作补上「点了之后有反应」的可见反馈。

优化

• 设置页「保存并应用」、「保存 API Key」：点击后按钮即时变 spinner + 「正在应用…」并 disabled；右上角 Toast 依次弹「正在保存并应用…」→「已保存并应用」（成功/错误/变更重启代理都会提示）。
• 主面板「启动/停止代理」同样使用 spinner + 文案切换（「正在启动…/正在停止…」）+ 全局 Toast，按钮最小宽防抖动。
• 统一反馈风格：info → success/error 三色 Toast 2 秒自动消失，可点击关闭。

紧急修复：用户点击"停止代理"后，已建立的 keep-alive / WebSocket 连接仍存活，导致 Codex CLI 还能继续问答。

修复

• stop() 现在会立即强制终止所有 WebSocket 客户端（ws.terminate()）与 HTTP 已连接 socket（server.closeAllConnections() + closeIdleConnections()），不再等到 3 秒超时兜底。
• 旧实现仅依靠 server.close() / wss.close()，但二者都只是"停止接受新连接"，对已 ESTABLISHED 的 socket 不主动断开；codex CLI 的长连接因此可以在 stop 之后继续穿透。
• 新增回归测试 stop() forcibly terminates established keep-alive connections，断言 stop 用时 < 1.5s 且端口已不可访问。
• 说明：~/.codex/config.toml 只是把 base_url 指向本地代理；codex CLI 不会自启动任何代理进程。Codex Switch 是端口 11435 的唯一持有者。

稳定性专项：修复"改端口后启动用旧端口"的 P0 bug，并配套上线代理生命周期状态机、端口冲突可视化处置、持久化日志、累计统计、单实例锁、自动恢复（仅运行期 crash）、设置事务化"保存并应用"。详见 docs/PROPOSAL-v1.1.0-stability.md。

修复

• 修改设置中的本地端口后，停用→启动代理时端口与设置不一致的问题（同时同步写 ~/.codex/config.toml，并重启代理）。
• start() 不再静默把端口 +1 占用其它端口；端口冲突会显式报错并交给用户处置。
• stop() 增加 3 秒硬超时与 closeAllConnections() 兜底，挂起的 SSE / WebSocket 不会再阻塞退出。

新增

• 端口冲突弹窗：识别占用方 PID/进程名，提供"关闭进程并重试 / 打开设置改端口 / 取消"三种操作。
• ndjson 持久化日志：单文件 10 MB 滚动、保留 4 个历史，启动时按 50 MB 上限 prune；日志页支持加载、清空、打开目录。
• 主面板新增累计统计：累计请求数、累计运行时长，自首次升级日起。
• 运行期崩溃自动恢复：3 次退避（1s / 3s / 9s），仍失败则停留在错误态并提示。
• 单实例锁：双击图标弹出"已经在运行"提示并聚焦已存在的窗口。

变更

• 设置页将"保存偏好 + 重新写入 ~/.codex"合并为单按钮"保存并应用"（事务化、失败回滚）。
• 状态以 server.listening 为准，对外暴露 stopped/starting/running/stopping/error。

验证 v1.0.5 引入的 macOS “检查更新 → 浏览器手动下载”回退路径，以及 Windows NSIS 原生 auto-update 在发布新版本后仍可正常检测/下载/安装。本版本仅用于升级流程验证，不包含功能变更。

根本性修复 macOS 自动升级 “代码不含资源”错误。

原因

electron-updater 在 macOS 上由 Squirrel.Mac 实施升级，它会调用系统 API SecRequirementForLaunchedApp() 取出当前运行 app 的 designated requirement， 再用该 requirement 验证 zip 里的新 .app。对于未使用 Apple Developer ID 证书 签名的 app，requirement 会退化为「新版本 CDHash 必须 == 旧版本 CDHash」—— 这在跨版本升级时不可能成立。这是 Apple/Squirrel 的硬性限制，不是可调项。 v1.0.0..v1.0.4 里所有的 「identity / hardenedRuntime / zip target」 调整都不能绕过这一点。

修复

• macOS 改为“提示 + 手动下载”模式：检查到新版本后， 点击「下载」会在默认浏览器打开 GitHub Releases 页面， 用户下载 dmg 后拖拽到 “应用程序” 文件夹覆盖即可。
• Windows 不受影响：NSIS 仍然是完整的一键 auto-update。

重要提示

已安装 v1.0.0..v1.0.4 的 macOS 用户点击「检查更新」还会看到上述错误（他们跑的是旧代码）。 请手动访问 下载页面 一次性升级到 v1.0.5； 之后从 v1.0.5 开始再点「检查更新」会直接跳转浏览器，不会再报错。

紧急修复 auto-update：v1.0.3 客户端拉到 zip 后 Squirrel.Mac 安装报错：

Code signature at URL ... did not pass validation:
代码不含资源，但签名指示这些资源必须存在

修复

• 明确未签名分发配置：electron-builder.yml 的 mac 下 增加 identity: null 并将 hardenedRuntime 从 true 改为 false。 根因：之前设了 hardenedRuntime: true 但未提供签名证书，electron-builder 仍在 .app 里写入了 _CodeSignature/CodeResources 清单，但 zip 化过程中 清单与实际资源不一致，Squirrel.Mac 严格校验时报 “代码不含资源”。 明确告诉 electron-builder “本构建不走签名”后，.app 不再写入这份 不一致的签名清单，Squirrel.Mac 才能顺利应用更新。

再次紧急修复 auto-update：v1.0.2 客户端报 ZIP file not provided。

修复

• macOS 增加 zip 产物：electron-updater 在 macOS 上由 Squirrel.Mac 实施 原子升级，必须通过 zip 应用补丁，dmg 只用于首次手动安装。electron-builder.yml 的 mac target 此前只有 dmg，导致 latest-mac.yml 缺 zip 条目；现补上 zip (x64+arm64)，auto-update 链路完整。

紧急修复 auto-update 的关键 404：v1.0.1 的 latest-mac.yml / latest.yml 引用了 Codex-Switch-1.0.1-* 文件名，但 electron-builder 实际生成并上传的 是 Codex.Switch-1.0.1-*（productName 含空格时 yml 与文件名转义不一致）， 导致已安装客户端调用 auto-update 拉取 dmg/exe 时 404。

修复

• 统一安装器命名为 Codex-Switch-*：在 electron-builder.yml 把 artifactName 中的 ${productName} 替换成字面量 Codex-Switch，使 yml 内引用与实际产物名 100% 一致。

端到端验证自动升级链路的小版本。无功能变化，仅用于让已安装 v1.0.0 的客户端 拉取并应用一次完整的自动更新流程。

修复

• CI 格式检查：pnpm format -- --check 在 CI 上被解析成 prettier --write . --check，导致 prettier 把 --check 当成文件 glob 报 No files matching the pattern were found。新增独立 format:check 脚本， CI 改用 pnpm format:check，并补 .prettierignore 排除 lockfile / 自动生成 文档 / 记忆文件。

内部

• 重新格式化 43 个被 prettier 标记的源文件，使 CI 全绿。

首个公开稳定版。本次升级聚焦"小白用户能用、有问题看得懂、有问题能反馈"。

新增

• 自动检查新版本：启动时静默检查 GitHub Release，发现新版可一键下载安装；支持 ghproxy 镜像加速国内下载，sha512 校验保留。
• 应用内帮助中心：每个页面右上角 ? 按钮，包含「常见问题」「使用入门」「报告问题」「交流群」四块；FAQ 面向"配置不生效 / 401 / 限流 / 备份还原 / 离线使用"等高频场景。
• 更新日志弹窗：升级到新版后首次启动自动弹出本次更新内容；「设置」中可随时查看历史版本。
• 错误就地修复：DeepSeek 返回的错误自动翻译为中文友好原因（API Key 失效 / 额度不足 / 限流 / 模型名不被接受 …），并附"打开设置"等一键跳转。
• 请求生命周期日志：每次请求都有唯一 req_xxxxx 编号，开始 / 成功 / 失败三阶段日志带耗时、状态码、模型，「日志」页可按编号折叠分组。
• 主面板 5 分钟统计：实时显示成功率、平均耗时、最近一次错误，一眼看出健康度。
• 备份治理 GUI：「设置 → 备份管理」可列出所有 .codex 备份，一键还原 / 删除单个 / 清理全部。
• 首次启动小贴士：完成向导后弹出 5 步 Codex 入门图文，告诉新用户如何打开 Codex CLI 并验证连通性。

改进

• 模型映射更稳健：未识别的模型（如 gpt-5.4-mini）不再透传到 DeepSeek 触发 400，先按前缀规则智能回退（如 gpt-* → deepseek-v4-flash），日志同步给出 WARN 提示。
• 默认映射表内置 v4：包含 deepseek-v4-flash、deepseek-v4-pro，并通过 modelMappingVersion 实现旧用户自动迁移（用户自定义键不丢失）。
• 备份不再无限增长：对 config.toml 与 auth.json 默认各保留最新 5 份；写入内容与上次完全一致时跳过备份和写入。
• auth.json 权限始终 0o600：写入和还原都强制设权，避免 macOS / Linux 上被其他用户读取。
• 日志全链路脱敏：Authorization: Bearer …、sk-…、OPENAI_API_KEY 在写入磁盘和发往渲染层之前一律替换为 ***。
• 极简风格扫荡：四种主色 / 三种字号 / 8px 栅格，主操作只一个，配合 Claude Desktop 的克制感。

修复

• 修复 restoreCodexConfig 还原备份时未给 auth.json 重新设权 0o600。
• 修复同名备份时间戳冲突可能丢失旧备份的边角问题。

新增依赖

• electron-updater：自动更新核心。

• 项目骨架，HTTP + WebSocket 代理可用，Codex 配置可写入与备份。