zc-codex-ccswitch

经验总结

这些是搭建过程中真实踩过的坑。按主题整理,供后续维护参考。

安装位置与迁移

运行时文件要放在稳定目录

最初运行时文件散落在两处:workspace 的随机目录(带会话 ID)和 AppData\Local。前者的问题在于 ZCode 会话工作区可能被清理,放在里面的桥接和自启引用会随之失效;后者不受控且造成重复安装。

处理(历史方案,旧三件套时代):统一到 D:\zc-codex-ccswitch\,三个子目录 cc-gui、cc-switch、bridge。用户态配置(~/.codex、~/.cc-switch)仍留在用户目录,这是程序默认行为。2026-11-17 起已收敛为 D:\CodexBridge\(exe + bridge-data),旧目录清除;下面的迁移步骤作为通用经验保留。

迁移步骤(可复用):

  1. 停掉所有相关进程,避免复制时写坏文件
  2. 备份 config.json 和用户态配置到目标目录的 _backup-from-c\
  3. 复制三个组件目录和 venv 到新位置
  4. 验证 venv 可用(python.exe -c "import ..."),venv 的 pyvenv.cfg 指向系统 Python,复制后仍有效
  5. 更新注册表自启路径和所有快捷方式
  6. 从新位置启动并验证 PID、端口、对话
  7. 删除旧副本前,确认没有任何引用还指向旧路径
  8. 删除后再测一次,确保运行中的服务不依赖旧目录

pystray 不能用 -WindowStyle Hidden 启动

现象:用 Start-Process -WindowStyle Hidden pythonw.exe tray.py 启动托盘,进程立即退出,无错误日志。

根因:pystray 的图标需要正常进程环境,强制 Hidden 会让它失效。注册表 Run 项本身不带这个参数,由系统处理隐藏,所以开机自启没问题。

处理:测试时不要加 -WindowStyle Hidden;直接执行注册表里的原始命令即可。

官方 App 的 exe integrity 校验(Electron 内嵌清单)

官方 ChatGPT/Codex 桌面 App 的 exe 在 PE 资源段内嵌 integrity 清单:

[{"file":"resourcespp.asar","alg":"SHA256","value":"<64位hex>"}]

启动时 Electron(fork)校验 asar 与清单是否一致,不匹配 FATAL 退出 (asar_util.cc:144 Integrity check failed for asar archive (X vs Y))。

要点:

前端 i18n 的”孤儿 chunk”现象

官方 App 前端打包了完整的简体中文翻译(39772 条,chunk async/1561.*.js),但语言 开关 enable_i18n 默认关闭——翻译 chunk 不会被加载,界面回退英文。这类”翻译在包里 但开关挡住”的现象,先搜包内是否有现成翻译,再考虑自己做翻译。

接线方法(本项目实测结论,2026-11-17 复核):

官方桌面 App

codex app 的 Store 分发是全自动的

codex app 在桌面 App 缺失时打开 Microsoft Store 安装器,自动开始下载约 1008MB,全程无需点击确认。Store 显示名是 ChatGPT,实际包名是 OpenAI.Codex(x64),安装在 C:\Program Files\WindowsApps\ 下。

用 Get-AppxPackage -Name '*ChatGPT*' 查不到?注意按名字过滤会漏——包名是 OpenAI.Codex,要用 Get-AppxPackage | Where-Object Name -like 'OpenAI.Codex*'。

官方 App 的 Computer use 是区域/账号限制

App 内 Computer use(驱动本机应用)显示 Disabled by your organization or unavailable in your region。这是 OpenAI 云端功能的灰度控制,与本地桥接无关。 不要试图通过改桥接来解锁——那是服务端灰度。

官方 App 与 CLI/CC GUI 共享会话

三端都读写 ~/.codex 下的会话存储,所以在任一端发起的对话,其他端的 历史列表里都能看到。这也意味着:桥接挂掉时三端同时不可用。

桥接是「官方客户端适配器」

官方桌面 App 读取同一份 config.toml 后,桥接(标准 Responses 端点)直接被它 使用——不需要 CC GUI 也能获得桌面体验。这是本项目最重要的发现。

Windows 与 PowerShell

PowerShell 5.1 的编码陷阱

现象:写好的中文 .ps1 脚本一运行就报莫名其妙的语法错误,比如 Try 语句缺少 Catch 或 表达式或语句中包含意外的标记 }。

根因:Windows PowerShell 5.1 把无 BOM 的 UTF-8 文件按 GBK 解码。中文字符串里的引号、括号被错误解析,报错位置看起来完全无关。

处理:

中文 Windows 的控制台输出是 GBK

现象:subprocess.run(["tasklist", ...], capture_output=True, text=True) 抛 UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd0。

根因:tasklist / wmic 在中文 Windows 输出 GBK。

处理:所有 subprocess.run 传 errors="replace":

subprocess.run(args, capture_output=True, text=True, errors="replace")

黑窗周期性闪烁

现象:屏幕上每隔几秒闪过一个黑色 cmd 窗口。

根因:托盘每 5 秒调用 tasklist 检查进程。控制台程序默认会弹出窗口。

处理:统一封装 _run_hidden(),对 Windows 传 CREATE_NO_WINDOW:

kwargs = {"capture_output": True, "text": True, "errors": "replace"}
if os.name == "nt":
    kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
return subprocess.run(args, **kwargs)

验证用 test/test-no-flicker.ps1。

codex 是 .cmd 包装脚本

Start-Process 直接执行 codex.cmd 会报「不是有效的 Win32 应用程序」。要经 cmd /c:

Start-Process -FilePath $env:ComSpec -ArgumentList '/c', 'codex', 'exec', ...

同时 prompt 里的空格要加引号,否则被 cmd 拆成多个参数。

codex exec 等待 stdin EOF

检测到 stdin 是管道时会阻塞。脚本里要么重定向 stdin,要么经 cmd /c 并确认不会挂起。


Python 与打包

.env 不会被 api2codex 读取

api2codex 只用 os.environ.get(...),从不解析 .env 文件。写 .env 只是存配置,必须由启动器把它加载进环境变量:

for /f "usebackq eol=# tokens=1,* delims==" %%A in (".env") do (
  if not "%%~A"=="" set "%%~A=%%~B"
)

pythonw 没有 stdout

uvicorn 默认日志 formatter 会调用 sys.stdout.isatty(),在 pythonw.exe 下 sys.stdout 是 None,导致 ValueError: Unable to configure formatter 'default'。

处理:uvicorn.Config(..., log_config=None),并把异常写到崩溃日志 tray-error.log。

字符串转义写坏文件

用 Python 脚本批量替换源码时,"\n" 容易被写成真实换行,造成 SyntaxError: unterminated string literal。字节级替换最稳妥:

bad  = bytes([0x22, 0x0A, 0x22])         # " LF "
good = bytes([0x22, 0x5C, 0x6E, 0x22])   # " \ n "
data = data.replace(bad, good)

改完务必 ast.parse() 验证,再部署。

托盘必须从任意 cwd 启动

开机自启(HKCU\...\Run)启动时工作目录是 C:\,而托盘依赖同目录的 config.json、.env。脚本开头必须:

BASE = Path(__file__).resolve().parent
os.chdir(BASE)
sys.path.insert(0, str(BASE))

协议与网关

Codex 的 wire_api 断层

Codex 0.169 删除 wire_api = "chat",只支持 Responses API。自建网关多数只有 Chat Completions,因此必须做协议转换。

CC Switch 的 Routing 能做转换,但前提是 provider 的「上游格式」设为 Chat Completions (translated);设成 Responses (原生) 会原样转发,必然 404。

渠道指纹校验(11128)

有些网关用请求体特征判断「是不是官方客户端」。实测触发点是 Codex 系统提示词的开头: You are a coding agent running in the Codex CLI...

随后网关会把账号打入冷却,短时间返回 503。CC Switch 不改写请求体,所以过不了;api2codex 补丁可以改写。

重要:这是对网关策略的绕过。只在你被授权使用该网关时启用提示词中性化。

模型其实是透传的

api2codex 里 body.get("model") or DEFAULT_MODEL,会把请求里的 model 原样转发。所以同一网关上的多个模型(只要地址和 Key 相同)可以同时使用,用 codex -m <model> 或 /model 切换即可。

之前”同一时间只能有一个 provider 生效”的说法只对不同上游成立。文档已更正。


工程实践

下载文件要校验

下载文件要固定 SHA256 并在安装时核对(旧三件套时代的 scripts/checksums.psd1 已随安装器删除,见 git 历史)。GitHub Release 的 .sig 文件也可以作为交叉验证。现在 exe 路线不下载第三方二进制,由 bridge/build-exe.cmd 从本仓库源码构建。

安装脚本要幂等

诊断顺序

  1. 先抓真实报错(用有控制台的 python.exe 运行,而不是 pythonw)
  2. 再采样视觉副作用(黑窗用 test-no-flicker.ps1,截图确认界面)
  3. 最后测功能(API 返回 200 不代表链路完整,要跑端到端)

本机 git push 被阻断

github.com:443 连接重置,但 api.github.com 正常。推送走 GitHub Data API:

# blob -> tree -> commit -> PATCH refs/heads/main
# 详见提交历史中的脚本

本地分支可能因此领先远端且 SHA 不同,但内容一致。