这些是搭建过程中真实踩过的坑。按主题整理,供后续维护参考。
最初运行时文件散落在两处: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),旧目录清除;下面的迁移步骤作为通用经验保留。
迁移步骤(可复用):
config.json 和用户态配置到目标目录的 _backup-from-c\python.exe -c "import ..."),venv 的 pyvenv.cfg 指向系统 Python,复制后仍有效现象:用 Start-Process -WindowStyle Hidden pythonw.exe tray.py 启动托盘,进程立即退出,无错误日志。
根因:pystray 的图标需要正常进程环境,强制 Hidden 会让它失效。注册表 Run 项本身不带这个参数,由系统处理隐藏,所以开机自启没问题。
处理:测试时不要加 -WindowStyle Hidden;直接执行注册表里的原始命令即可。
官方 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))。
要点:
(expected vs actual) 取 actual 回填”,
已证伪:patch_inplace.py 离线重算写回即可;sync_exe_hash.py 仅作应急回填官方 App 前端打包了完整的简体中文翻译(39772 条,chunk async/1561.*.js),但语言
开关 enable_i18n 默认关闭——翻译 chunk 不会被加载,界面回退英文。这类”翻译在包里
但开关挡住”的现象,先搜包内是否有现成翻译,再考虑自己做翻译。
接线方法(本项目实测结论,2026-11-17 复核):
webview/assets/async/907538.*.js 里
get("enable_i18n",!1) → !0。官方前端随后自动走
locales/zh-CN.json → i.e(1561) 加载全部翻译,界面全中文。defaultMessage。早期误以为必需,做了 5793 条/15 文件,
复核证明冗余——核心文案 “New chat” 等的 defaultMessage 仍是英文却显示中文,
说明翻译是按 id 从 chunk 匹配,与 defaultMessage 无关。codex-zh/patch.py 默认只改那 1 处 bool。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(驱动本机应用)显示 Disabled by your organization or
unavailable in your region。这是 OpenAI 云端功能的灰度控制,与本地桥接无关。
不要试图通过改桥接来解锁——那是服务端灰度。
三端都读写 ~/.codex 下的会话存储,所以在任一端发起的对话,其他端的
历史列表里都能看到。这也意味着:桥接挂掉时三端同时不可用。
官方桌面 App 读取同一份 config.toml 后,桥接(标准 Responses 端点)直接被它 使用——不需要 CC GUI 也能获得桌面体验。这是本项目最重要的发现。
现象:写好的中文 .ps1 脚本一运行就报莫名其妙的语法错误,比如 Try 语句缺少 Catch 或 表达式或语句中包含意外的标记 }。
根因:Windows PowerShell 5.1 把无 BOM 的 UTF-8 文件按 GBK 解码。中文字符串里的引号、括号被错误解析,报错位置看起来完全无关。
处理:
.ps1 脚本的输出字符串和注释统一用 ASCII,中文说明放到 .md 文档-Encoding UTF8(会加 BOM),用:
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($path, $text, $utf8NoBom)
现象: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 并确认不会挂起。
.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"
)
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() 验证,再部署。
开机自启(HKCU\...\Run)启动时工作目录是 C:\,而托盘依赖同目录的 config.json、.env。脚本开头必须:
BASE = Path(__file__).resolve().parent
os.chdir(BASE)
sys.path.insert(0, str(BASE))
Codex 0.169 删除 wire_api = "chat",只支持 Responses API。自建网关多数只有 Chat Completions,因此必须做协议转换。
CC Switch 的 Routing 能做转换,但前提是 provider 的「上游格式」设为 Chat Completions (translated);设成 Responses (原生) 会原样转发,必然 404。
有些网关用请求体特征判断「是不是官方客户端」。实测触发点是 Codex 系统提示词的开头:
You are a coding agent running in the Codex CLI...
11128 Illegal API invocation from an unapproved channel随后网关会把账号打入冷却,短时间返回 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 从本仓库源码构建。
-Forceconfig.toml 默认不覆盖,先备份.part,成功后再 Move,避免半截文件python.exe 运行,而不是 pythonw)test-no-flicker.ps1,截图确认界面)github.com:443 连接重置,但 api.github.com 正常。推送走 GitHub Data API:
# blob -> tree -> commit -> PATCH refs/heads/main
# 详见提交历史中的脚本
本地分支可能因此领先远端且 SHA 不同,但内容一致。