箐のblog

CC Switch 修复 Codex 桌面端：问题排查与解决手册

Sat, 22 Aug 2026 00:00:00 GMT

〇、先建立两个基本认知#

0.1 Codex 的两个核心配置文件#

文件	作用	典型位置
`config.toml`	用什么模型、走哪个 provider、接口协议	`C:\Users\<用户名>\.codex\config.toml`（Windows）
`auth.json`	认证方式（ChatGPT 官方登录 or API Key）	同上目录

CC Switch 切换时需要同时改这两个文件，它有时只改了其中一个——这是至少一半”切换不生效”问题的根源。

如果你安装时改过 Codex 的数据目录（例如 D:\codex-home），电脑上可能存在两份 config.toml。CC Switch 可能改了 C 盘那份，而 Codex 实际读取的是 D 盘那份。排查时先确认 Codex 真正在读哪个文件。

0.2 路由 vs 显示：两类问题必须分开#

路由断了：请求根本送不出去（401/404/400/model-not-found）。这是配置或模型本身的问题。
路由通了但桌面版不显示：CLI 里 /model 能看到模型、请求也正常，只是桌面版选择器看不见。这是显示问题（客户端过滤缺陷），有专门的绕行方案。

一条命令区分两者：在同一个文件夹打开终端运行 codex（CLI），输入 /model。

CLI 也失败 → 路由问题，看第三章。
CLI 成功、只有桌面版看不见 → 显示问题，看第二章。

一、30 秒快速诊断表#

你看到的现象	实际的问题	跳转
切完模型重启 Codex，还是显示 GPT-5.5	`config.toml` 与 `auth.json` 没同步，或改错了路径的那份	问题 1
选择器只显示 “Custom”，没有模型名	模型内联设置、缺少目录元数据（正常现象，能用）	问题 5
模型名称位置显示空白	`[model_providers.xxx]` 下缺 `name` 字段	问题 6
CLI 的 `/model` 能列出，桌面版没有	桌面版客户端过滤缺陷（issue #19694）	问题 7
选择器下拉列表整个是空的	目录缺失或格式错误（旧版 CC Switch）	问题 8
发图片直接报错，之后纯文字也报错	DeepSeek API 不支持图片输入，污染了会话历史	问题 2
Key 明明正确却报 401	Key 夹带空格/不可见字符/乱码	问题 3
每个请求都 404	`wire_api = "chat"` 已废弃，或网关无 `/responses` 端点	问题 9
切回 GPT-5.5 后依然显示国产模型	`auth.json` 残留 api-key 模式 / `config.toml` 残留 provider	问题 4
切换后会话记录消失、插件变灰	认证体系切换导致（非数据丢失，新版已改善）	问题 10
启动时打印 provider 被忽略的警告	provider 写在了项目级 `.codex/config.toml`	问题 11
配置全对但列表还是旧的/空的	`models_cache.json` 缓存过期	问题 12

二、切换类问题（改了不生效 / 改不回来）#

问题 1：切完模型重启 Codex，还是显示 GPT-5.5#

典型报错（CLI 中）：

1
{"type":"error","status":400,"error":{"type":"invalid_request_error",
2
"message":"The 'deepseek-v4-flash' model is not supported when using Codex with a ChatGPT account."}}

根因：CC Switch 只改了 config.toml 和 auth.json 中的一个；或者改的是另一路径下的副本。于是 Codex 检测到”ChatGPT 账号登录态 + 第三方模型名”对不上，直接拒绝。

排查步骤：

确认 Codex 实际读取的配置目录（默认 ~/.codex/，改过安装路径的去找对应目录）。
打开该目录的 config.toml，检查是否包含 model = "deepseek-v4-flash" 之类的模型行和 [model_providers.custom] 配置块。
打开同目录的 auth.json，检查 auth_mode 是否已从 chatgpt 变为 api-key 模式。
两处只改了一处 → 把没改的那份补齐，或从备份恢复后重新操作。

修复（推荐用备份恢复）：

CC Switch 每次改配置前会自动备份，文件名带时间戳，如 config.toml.bak.20260602121223。
找到切换前的正确备份，两个文件一起覆盖回去，再在 CC Switch 里重新操作一遍。
有 Claude Code / opencode 等本地 agent 的话，直接把两个文件路径丢给它，让它对比差异并修复，效率远高于手动翻。

问题 4：切回 GPT-5.5 后依然显示国产模型#

根因：与问题 1 同源。禁用了 DeepSeek，但 auth.json 仍停留在 api-key 模式，或 config.toml 里残留 [model_providers.custom] 配置。

修复：

用 CC Switch 的备份（或你自己手动备份的）把 config.toml 和 auth.json 同时恢复到切换之前的状态。
重启 Codex，重新登录 ChatGPT 账号。
恢复后插件、历史会话会一起回来。

问题 10：切换模型后会话记录全没了、插件变灰#

这不是 bug，也不是数据丢失。 切换模型等于换了一套认证体系，Codex 把你当成了新用户，所以旧会话和插件暂时不可见。

CC Switch 升级到 v3.16.1+ 后，切回原模型的流程已修复：切回 GPT-5.5 且配置恢复正确，会话记录、插件全部原样回来。
实操建议：切到国产模型前，重要会话内容先复制出来存一份；用完切回即可，不用慌。

三、请求类问题（路由断了）#

问题 2：能用了，但一发图片就报错#

典型报错：

1
CC Switch local proxy failed while handling Codex endpoint /responses.
2
Provider: DeepSeek; model: deepseek-v4-flash; upstream_status: HTTP 400;
3
cause: Failed to deserialize the JSON body into the target type:
4
messages[6]: unknown variant `image_url`, expected `text`

根因：部分模型不支持图片输入，与 CC Switch 和你的配置都无关。

最坑的一点：一旦某会话里发过图片报错，该会话后续纯文字也会持续报错——因为 Codex 每次都会把含图片的历史消息一起发给 API。

问题 3：API Key 明明正确，却报 401#

典型报错：unexpected status 401 Unauthorized: Incorrect API key provided: sk-bb527*****0175

根因：CC Switch 输入框的玄学问题——复制粘贴进去的 Key 可能夹带首尾空格、不可见字符，甚至保存时出现乱码。肉眼看不出来。

修复（注意顺序）：

先关掉 Codex。
在 CC Switch 里删除该供应商的 API Key。
重新去服务商后台重新复制一次 Key，粘贴保存。
再打开 Codex。
还不行就手动输入 Key（反人类但能彻底排除剪贴板问题）。

问题 9：启动报错，或每个请求都 404#

根因：wire_api = "chat"。Codex 在 2026 年 2 月移除了旧的 chat/completions 路径，responses 现在是唯一合法取值（也是默认值）。或者你的网关根本没有 /responses 端点。

修复：

1
[model_providers.custom]
2
wire_api = "responses"
3
base_url = "https://你的网关地址/v1"   # 以 /v1 结尾，末尾不带斜杠

网关必须在 {base_url}/responses 暴露 OpenAI 兼容的 Responses 端点。只支持 /chat/completions 的网关会让每个请求 404——看起来像模型问题，实际是协议不匹配。
顺带检查：base_url 末尾多一个斜杠或路径写错，会导致连接时不时被重置。

附：其他伪装成显示问题的路由错误#

症状	真正原因	修复
每个请求 401（手写配置场景）	配了 `env_key` 但环境变量从未导出	在 shell 配置里 `export XXX_API_KEY=sk-...`
模型能跑但返回错误的输出	目录里的 `slug` 与 provider 实际模型 ID 不一致	`slug` 改成与发送给 provider 的字符串逐字符一致
curl 网关返回 model-not-found	模型字符串写错	核对服务商后台的模型 ID，别猜

四、显示类问题（路由通了，桌面版看不见）#

问题 5：选择器只显示 “Custom”，没有模型名#

根因：你只在 config.toml 里内联写了 model = "xxx"，没有模型目录，选择器没有可展示的元数据。

结论：这是正常现象，不用修。 请求会正常发往你的模型。如果不在乎下拉列表好不好看，到这里就可以停了。

问题 6：模型名称位置显示空白#

根因：[model_providers.custom] 配置块下缺少 name 字段（Windows 上 CC Switch 偶尔写入不完整）。

修复：手动补上，重启 Codex：

1
[model_providers.custom]
2
name = "deepseek"        # ← 就是这个字段控制界面显示名称
3
base_url = "https://api.deepseek.com"
4
wire_api = "responses"

name 的值随意，写你能认出来的名字即可（“deepseek”、“qwen” 都行）。

问题 7：CLI 的 /model 能列出模型，桌面版选择器没有#

根因：Codex 桌面版的客户端过滤缺陷（openai/codex issue #19694，2026-04-26 提交，截至目前未关闭）。app-server 的 model/list 端点正常返回了你的模型，但桌面版渲染层在到达下拉列表前把本地配置的条目丢掉了。后端知道你的模型，前端拒绝显示。改配置修不好。

修复（按顺序）：

修复 A——内联模型绕行（永远管用，最先做）：

1
# ~/.codex/config.toml（用户级，不是项目文件夹里）
2
model = "moonshotai/kimi-k2.7-code"
3
model_provider = "custom"
4

5

6
[model_providers.custom]
7
name = "myprovider"
8
base_url = "https://你的网关/v1"
9
env_key = "MY_API_KEY"
10
wire_api = "responses"

彻底退出 Codex 桌面版再重开。选择器显示 “Custom” 无妨，请求都会发往正确模型。换模型只需改 model 那一行字符串。

修复 B——加模型目录，让选择器显示真名：在 config.toml 顶部加 model_catalog_json 指向一个 JSON 文件：

1
model_catalog_json = "C:/Users/你/.codex/my-models.json"

最小目录条目：

1
{
2
  "models": [
3
    {
4
      "slug": "moonshotai/kimi-k2.7-code",
5
      "display_name": "Kimi K2.7 Code",
6
      "description": "Coding model via gateway",
7
      "context_window": 262000,
8
      "max_context_window": 262000,
9
      "supported_in_api": true,
10
      "visibility": "list",
11
      "priority": 1
12
    }
13
  ]
14
}

slug 必须等于发给 provider 的模型字符串。目录只在启动时读取一次，改动后必须重启桌面版。

问题 8：选择器下拉列表整个是空的#

根因：早于 v3.16.5 的 CC Switch 生成的目录格式与 Codex 选择器期望的对不上（cc-switch issue #3668），路由正常但 /model 返回空。

修复：

升级 CC Switch 到 v3.16.5 或更高版本——该版本会为使用原生 Responses 端点（apiFormat: "openai_responses"）的供应商生成 ~/.codex/cc-switch-model-catalog.json。
升级后必须把每个原生 provider 重新保存一次——目录只在保存时重新生成，旧 provider 不会自动迁移。
验证目录已生成：

1
# Windows PowerShell 里用 findstr 代替 grep
2
cat ~/.codex/cc-switch-model-catalog.json | grep -o '"slug":[^,]*'
3
# 如果为空，回 CC Switch 重新保存该 provider 后再查

v3.16.5 的两个注意点：

目录生成与”本地路由”开关已解耦：无论本地路由是否开启，原生 Responses 供应商都会生成目录；Chat 格式供应商仍走代理转换。
少数国产模型（MiMo、LongCat、MiniMax、Qwen3-Coder）的网关不支持 OpenAI 内置 web_search，v3.16.5 默认对它们关闭该工具以避免 400 报错——预期这些模型的网络搜索不可用，不是故障。

问题 11：启动时打印 provider 被忽略的警告#

根因：model_provider / model_providers 写在了项目级 .codex/config.toml（某个仓库目录里）。provider 定义只在用户级 ~/.codex/config.toml 生效，项目级的会被忽略并打印警告。

修复：

1
# 检查 provider 到底写在哪个文件
2
grep -rn "model_providers" ~/.codex/config.toml ./.codex/config.toml 2>/dev/null

把 [model_providers.*] 配置块和 model_provider = "..." 挪到 ~/.codex/config.toml，项目级配置只留仓库专属内容（如指令文件）。

问题 12：配置全对，但列表还是旧的/空的#

根因：~/.codex/models_cache.json 缓存过期。切换 provider 或编辑目录后它不总会重新同步。

修复：删掉 models_cache.json，下次启动会强制重建。在断定目录本身出错之前，先试这一招。

五、通用排查流程（一张图记住）#

1
桌面版看不到模型 / 切换不生效
2
        │
3
        ▼
4
终端运行 codex（CLI），输入 /model
5
        │
6
   ┌────┴────┐
7
 CLI 也失败   CLI 正常、只有桌面版不行
8
   │              │
9
   ▼              ▼
10
 路由问题        显示问题（#19694 过滤）
11
 检查：          处理：
12
 · config/auth   · 修复 A：内联 model 绕行
13
   两文件是否     · 修复 B：补 model_catalog_json
14
   同步且路径对   · CC Switch 升 v3.16.5+
15
 · wire_api=     并逐个重新保存 provider
16
   responses
17
 · Key 无空格    仍不行：
18
   乱码          · 删 models_cache.json
19
 · base_url      · 检查 name 字段
20
   以 /v1 结尾

展开收起

验证模型真正加载的可靠方法：不要相信选择器（坏的就是它），在更下层验证——

CLI 里 /model 能列出 → 目录和 provider 都正确；
用密钥对网关直接 curl {base_url}/responses → 确认路由本身能解析；
用网关的话，在网关的请求日志面板确认模型路由命中了预期后端。

六、操作规范与预防（比修复更重要）#

任何切换前先手动备份 config.toml 和 auth.json。CC Switch 虽会自动备份（.bak.时间戳），但自己再存一份双保险。
操作顺序铁律：先关 Codex → 改配置 → 再开 Codex。顺序反了，很多”不生效”就是这么来的。
CC Switch 保持最新版。v3.16.1 修复了切换后会话丢失，v3.16.5 修复了目录格式。很多坑在新版本已经不存在。
切换三种场景速查：
- 官方 → 国产：关 Codex → CC Switch 加供应商填 Key → 设置里开路由总开关+Codex 路由 → 启用供应商 → 开 Codex。
- 国产 → 官方：关 Codex → 禁用供应商 → 关路由 → 开 Codex 重新登录（配置乱了就用备份恢复）。
- 国产 A → 国产 B：关 Codex → 直接启用新供应商（旧的自动禁用）→ 开 Codex，路由不用动。
善用本地 agent 排查：把 config.toml、auth.json 和备份文件丢给 Claude Code / opencode，让它对比差异并修复，比手动翻文件高效得多。

Hello World

Sat, 22 Aug 2026 00:00:00 GMT

Hello World

每个人的博客，大概都是从这一篇开始的。我的也一样，就当是个开场白。为什么会想写博客？说白了，这么多年在网上找答案，没少蹭过前辈们认真写下的博客文章。很所以现在我也想自己留点东西——学到的、想到的、踩过的坑，都记一记。这个博客是用 Firefly 搭的，基于 Astro，算是 Fuwari 的一个分支主题。挑它没别的原因，好看。以后大概会写点什么：

技术学习笔记
做项目时的那些经验和教训
读过的书，顺手写两句
生活里零零碎碎的碎碎念

顺便交代一下我自己：平时喜欢看动漫《某科学的超电磁炮》，闲了就随便听听歌？（浅影阿），

第一篇就先写到这里，算是正式开张。

希望这儿能变成一个安安静静的小角落，把我成长路上的每一步都留个底。有空常来坐坐 ✨

— 莜之箐

npm 全局安装的 CLI 工具报"不支持的 16 位应用程序 / 不是有效应用程序"——通用修复笔记

Sat, 22 Aug 2026 00:00:00 GMT

适用范围：Windows 10 / 11 64 位，通过 npm install -g 安装、但运行时报”原生二进制不兼容”的一类 CLI 工具。典型受害者：Claude Code（claude）、OpenCode（opencode），以及其它”npm 包装器 + 原生 exe”结构的工具。本文使用 $env:APPDATA 等环境变量占位，命令在任意机器通用，无需关心用户名、盘符、版本号。

一、问题现象#

通过 npm install -g 安装后，在终端输入工具名（如 claude、opencode）或运行其 .exe 时失败。

典型报错（任选其一，本质相同）：

弹窗：不支持的 16 位应用程序
弹窗：由于与 64 位版本的 Windows 不兼容，此程序或功能无法启动或运行

PowerShell：

1
Program 'claude.exe' failed to run: ... The specified executable is not a valid application for this OS platform.

部分用户还会看到：claude.exe 与你运行的 Windows 版本不兼容

共同特征：报错路径永远指向 ...\node_modules\<包名>\bin\<工具名>.exe

二、根本原因#

这类工具在 npm 上的”主包”只是一个启动器（wrapper），本身不含真正可执行的原生二进制；真正的 .exe 来自独立的平台原生包（命名形如 *-win32-x64、*-windows-x64）。

安装时，主包的 postinstall 脚本应把原生二进制复制/链接到 bin/<工具名>.exe。当该步骤因以下原因失败时：

国内网络被墙，无法从 GitHub / 官网下载原生二进制；
安全软件 / 杀毒拦截了写入；
旧版本残留污染了 PATH 或目录；
~/.npmrc 里设了 ignore-scripts=true：这会全局禁止 npm 执行安装脚本（含 postinstall），原生二进制因此完全不会被放置，最终 bin/<工具名>.exe 必然是 stub。装完会直接报错 claude native binary not installed. Either postinstall did not run (--ignore-scripts...)。该情况必须靠「手动复制真实二进制覆盖 stub」修复，npm 自身不会帮你放好。
~/.npmrc 里设了 min-release-age=N：会忽略发布不到 N 天的新版本，等效于给 npm 加了 before = 今天-N天 的日期过滤器。升级到较新版本（如 npm install -g <包>@<新版>）时会直接报 ETARGET ... No matching version found ... with a date before <某日期>。注意：npm view <包>@<新版> 能查到（它不过滤日期），但 npm install 会装不了。修复：删掉该限制（npm config delete min-release-age，恢复后可 npm config set min-release-age=N 重新加回），再安装。

bin/<工具名>.exe 会残留为一个无效的占位 stub（几百字节到几 KB）。Windows 无法将其识别为合法的 64 位 PE 文件，于是报上述错误。

结论：文件并未真的损坏，本质是原生二进制没有落位到正确路径。修复方式 = 找到真实二进制，覆盖占位文件。

三、前置说明：该用哪个终端、怎么复制命令#

全程使用 PowerShell（建议”以管理员身份运行”），可避免全局目录写权限问题。
不要把 Markdown 代码块的行首 ``` 和语言标识（如 powershell、bash）一起复制——它们不是命令，复制进去会报”无法识别的术语”。
本笔记所有命令均为 PowerShell 语法；若只用 Git Bash，核心 npm 命令一致，但 Remove-Item / Copy-Item / $env:APPDATA 需改写为 Bash 等价写法，故统一给 PowerShell。
国内用户必须走 npmmirror 国内镜像（步骤 3），不要从官方源 registry.npmjs.org 装，否则会超时。

四、分步解决方案#

步骤 1：彻底清理旧的无效残留（必须）#

以管理员身份打开 PowerShell，逐行执行（只复制命令本身，不含 ``` 等格式符）：

1
npm uninstall -g @anthropic-ai/claude-code
2
npm uninstall -g @anthropic-ai/claude-code-win32-x64
3
npm uninstall -g opencode-ai
4
Remove-Item -Force -Recurse "$env:APPDATA\npm\claude.cmd" -ErrorAction SilentlyContinue
5
Remove-Item -Force -Recurse "$env:APPDATA\npm\claude.ps1" -ErrorAction SilentlyContinue
6
Remove-Item -Force -Recurse "$env:APPDATA\npm\claude" -ErrorAction SilentlyContinue
7
Remove-Item -Force -Recurse "$env:APPDATA\npm\opencode.cmd" -ErrorAction SilentlyContinue
8
Remove-Item -Force -Recurse "$env:APPDATA\npm\opencode.ps1" -ErrorAction SilentlyContinue
9
Remove-Item -Force -Recurse "$env:APPDATA\npm\opencode" -ErrorAction SilentlyContinue
10
Remove-Item -Force -Recurse "$env:APPDATA\npm\node_modules\@anthropic-ai" -ErrorAction SilentlyContinue
11
Remove-Item -Force -Recurse "$env:APPDATA\npm\node_modules\opencode-ai" -ErrorAction SilentlyContinue
12
npm cache clean --force

只装了其中一个工具？把对应的行删掉即可，其余照跑无妨。

步骤 2：确认清理干净#

1
where.exe claude
2
where.exe opencode

两条都没有任何输出（直接回到提示符）即为成功。若仍有路径输出，手动删除对应文件后重试本步骤。

步骤 3：设置国内镜像（国内用户必做，一次性）#

1
npm config set registry https://registry.npmmirror.com
2
npm config get registry

第二条应返回 https://registry.npmmirror.com。

步骤 4：重新安装主包 + 平台原生包#

把 <版本号> 替换为你需要的版本（Claude Code 社区验证可用的稳定版本如 2.1.112；OpenCode 用 latest 即可）。

Claude Code：

1
npm install -g @anthropic-ai/claude-code@<版本号> --registry=https://registry.npmmirror.com
2
npm install -g @anthropic-ai/claude-code-win32-x64@<版本号> --registry=https://registry.npmmirror.com

OpenCode：

1
npm install -g opencode-ai --registry=https://registry.npmmirror.com

OpenCode 的 Windows 原生包会在安装 opencode-ai 时作为依赖自动拉取（位于 opencode-ai\node_modules\opencode-windows-x64...），但 postinstall 可能因网络无法把它链接进 bin/。这正是下一步”手动定位并复制”要补齐的。

步骤 5（关键·通用）：定位真实的原生二进制#

这一步不依赖固定路径，直接在整个 npm 全局目录里搜索同名 exe，由你根据输出确认哪个是”真货”。

Claude Code：

1
Get-ChildItem "$env:APPDATA\npm\node_modules" -Recurse -Filter "claude.exe" -ErrorAction SilentlyContinue | ForEach-Object { "{0}   大小:{1}字节" -f $_.FullName, $_.Length }

OpenCode：

1
Get-ChildItem "$env:APPDATA\npm\node_modules" -Recurse -Filter "opencode.exe" -ErrorAction SilentlyContinue | ForEach-Object { "{0}   大小:{1}字节" -f $_.FullName, $_.Length }

解读输出（重点）：

路径形如 ...\node_modules\@anthropic-ai\claude-code\bin\claude.exe（或 ...\opencode-ai\bin\opencode.exe），且大小只有几百字节到几 KB 的 = 占位 stub（报错指向的那个，待覆盖）。
路径里包含 win32-x64 / windows-x64 等字样（如 ...\node_modules\opencode-ai\node_modules\opencode-windows-x64\bin\opencode.exe 或 ...\node_modules\@anthropic-ai\claude-code-win32-x64\bin\claude.exe），且大小为几 MB 到几十 MB 的 = 真实原生二进制（复制来源）。

把这两个路径记下：

占位 stub 路径（待覆盖）
真实二进制路径（来源）

步骤 6：复制真实二进制覆盖占位文件#

把上一步记下的两个路径，分别替换到下面命令的 <真实二进制完整路径> 和 <占位stub完整路径>：

1
Copy-Item -Force "<真实二进制完整路径>" "<占位stub完整路径>"

示例（以 OpenCode 为例，路径以你机器实际输出为准）：

1
Copy-Item -Force "C:\Users\21186\AppData\Roaming\npm\node_modules\opencode-ai\node_modules\opencode-windows-x64\bin\opencode.exe" "C:\Users\21186\AppData\Roaming\npm\node_modules\opencode-ai\bin\opencode.exe"

为稳妥，可顺手再覆盖一层全局 npm/<工具名>.exe，确保 where 解析到的也是真货：

1
Copy-Item -Force "<真实二进制完整路径>" "$env:APPDATA\npm\<工具名>.exe"

若真实二进制有多个候选（如同时出现 opencode-windows-x64 与 opencode-windows-x64-baseline），优先用不带 -baseline 的那个；若仍报错，再换 -baseline 版本重试。

OpenCode 升级后”检测到多处安装 / 默认无法运行”的必做项：

OpenCode 自身的安装自检会扫描多个标准位置，并把 C:\Users\<用户>\AppData\Roaming\npm\opencode.exe（顶层）标记为”默认”入口。它的 npm postinstall 在升级时会把顶层 npm\opencode.exe 也写成一个坏壳，而你运行 opencode 时命令行实际就走这个”默认”位置。因此 OpenCode 必须同时覆盖两处才算彻底修好：

1
$real = "<真实二进制完整路径，取自步骤 5 输出中较大的那个>"
2
Copy-Item -Force $real "$env:APPDATA\npm\node_modules\opencode-ai\bin\opencode.exe"
3
Copy-Item -Force $real "$env:APPDATA\npm\opencode.exe"
4
opencode --version

只覆盖 bin/ 下的 stub 而漏掉顶层 npm\opencode.exe，就是”升级一次就复发”的根因。

步骤 7：验证#

1
claude --version
2
opencode --version

预期：正常输出版本号，且不弹出”16 位应用程序 / 不兼容”窗口。到此两个工具均修复完成。

五、常见疑问#

Q：为什么不能只装主包就完事？ A：主包不含原生 exe，必须依赖平台包；而 npm 在国内的 postinstall 链接步骤常因下载被墙失败，原生二进制没进 bin/。

Q：WinGet / 官方安装脚本为什么不算正解？ A：两者最终都从 downloads.claude.ai / claude.ai 下载，国内直连不通，会卡在下载阶段。本方案走 npm 国内镜像，可落地。

Q：会不会每次更新都复发？ A：有可能。若 npm update -g 后再次出现相同报错，直接重做「步骤 5 ～步骤 6」（定位真实二进制并复制）即可，无需重新安装。

Q：运行 opencode 提示”检测到多处安装”，并标记 AppData\Roaming\npm\opencode.exe 为”默认”且无法运行，怎么办？ A：这是 OpenCode 自身的安装自检，说明顶层 npm\opencode.exe 这个”默认”入口是坏的。npm postinstall 在升级时会把它写成坏壳。必须按上面的 OpenCode 必做项，同时把真实二进制复制覆盖到 node_modules\opencode-ai\bin\opencode.exe 与顶层 npm\opencode.exe 两处，再验证。仅覆盖一处仍会复发。

Q：怎么避免以后再复发？ A：根因是 npm 每次 install / update 都会重跑 postinstall、把 stub 重置回坏壳。已修好后，尽量不要执行 npm update -g opencode-ai；若确实需要升级版本，升级完成后重做一次「步骤 5 ～步骤 6」的复制即可。对追求一劳永逸的用户，可改用 Scoop（scoop install opencode，二进制直接落 ~/scoop/apps/opencode/current/opencode.exe）或手动从 GitHub Releases（走国内可达镜像）下载原生二进制放入 PATH，彻底绕开 npm 包装器。

Q：其它同类工具（也是 npm 包装器 + 原生 exe）能用同样方法吗？ A：能。把全文的 claude / opencode 换成对应工具名，按步骤 5 搜索其 .exe，找到 *-win32-x64 / *-windows-x64 下的真实二进制，覆盖 bin/ 下的占位文件即可。

Q：运行 opencode 时它提示”当前 1.18.11，最新 1.18.15，可升级”，是不是我又装错了？ A：不是装错。这里出现两个版本号是两个不同来源：

当前版本 1.18.11：来自你通过 npm 安装的 opencode-ai 主包版本（npm 源上当前最新的就是 1.18.11）。
最新版本 1.18.15：来自 OpenCode 运行时联网去 GitHub Releases 检测到的版本（GitHub 上已发 1.18.15）。两者版本号不同步是常态。你手动复制的真实原生二进制配套的也是 1.18.11，所以当前能用。只要能正常运行，这行提示可以忽略，不必理会。

Q：想升级到 1.18.15（或其它新版）该怎么安全地升？ A：千万不要在 opencode 交互界面里点”升级”，那会去 GitHub 下载并重置 stub，大概率又回到坏壳状态（国内还常被墙）。正确做法二选一：

方案甲（仍走 npm，前提是 npm 源已发布该版本）：先 npm install -g opencode-ai@<目标版本> --registry=https://registry.npmmirror.com，装完重做「步骤 5～6」（定位新版本的真实原生二进制并复制到两处）。若 npm install 报 No matching version，说明 npm 源还没发该版，改用方案乙。

方案乙（手动落二进制，一劳永逸，推荐）：从 GitHub Releases 下载对应版本的 opencode-windows-x64.zip，解压出 opencode.exe，手动覆盖到顶层 npm\opencode.exe、node_modules\opencode-ai\bin\opencode.exe、以及平台包 node_modules\opencode-ai\node_modules\opencode-windows-x64\bin\opencode.exe 三处（覆盖平台包可避免自检报”多处安装”），再 opencode --version 验证。PowerShell 具体步骤（把 v<VERSION> 换成目标版本，如 v1.18.15；国内若 ghproxy.com 不通，换成 ghproxy.net 或删掉该前缀直连 github.com）：

Terminal window

1
$url = "https://ghproxy.com/https://github.com/anomalyco/opencode/releases/download/v<VERSION>/opencode-windows-x64.zip"
2
Invoke-WebRequest -Uri $url -OutFile "$env:TEMP\opencode-new.zip"
3
Expand-Archive -Path "$env:TEMP\opencode-new.zip" -DestinationPath "$env:TEMP\opencode-new" -Force
4
$real = (Get-ChildItem "$env:TEMP\opencode-new" -Recurse -Filter "opencode.exe" | Select-Object -First 1).FullName
5
Copy-Item -Force $real "$env:APPDATA\npm\node_modules\opencode-ai\bin\opencode.exe"
6
Copy-Item -Force $real "$env:APPDATA\npm\opencode.exe"
7
Copy-Item -Force $real "$env:APPDATA\npm\node_modules\opencode-ai\node_modules\opencode-windows-x64\bin\opencode.exe"
8
opencode --version

若不确定目标版本在 npm / GitHub 是否发布，先用 npm view opencode-ai versions 查 npm 已发版本，再决定走甲还是乙。

Q：Claude Code 怎么升级（比如 2.1.112 → 2.1.226）？它和 opencode 机制一样吗？ A：机制不同，不要套用 opencode 的 GitHub 下载法。 Claude Code 的正确升级渠道就是 npm 平台包，原生二进制在 npm 镜像上有同步，且主包 postinstall 会自动把平台包里的真二进制链接到 bin/，不必手动从 GitHub 拉。步骤：

Terminal window

1
# 1) 升级主包 + 平台包（两行顺序执行，均走国内镜像）
2
npm install -g @anthropic-ai/claude-code@<目标版本> --registry=https://registry.npmmirror.com
3
npm install -g @anthropic-ai/claude-code-win32-x64@<目标版本> --registry=https://registry.npmmirror.com
4
# 2) 验证
5
claude --version

两个包缺一不可：只装主包会得到坏 stub；平台包 @anthropic-ai/claude-code-win32-x64 必须与主包同版本。执行前可用 npm view @anthropic-ai/claude-code-win32-x64@<版本> version --registry=https://registry.npmmirror.com 先确认该版本平台包已发布。

安全网（仅当 claude --version 仍报”不兼容/无效应用程序”时跑）：手动定位平台包里的真二进制并覆盖到主包 bin/：

Terminal window

1
$real = (Get-ChildItem "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code-win32-x64" -Recurse -Filter "claude.exe" | Select-Object -First 1).FullName
2
Copy-Item -Force $real "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe"
3
claude --version

六、总结#

报错本质是 npm 包装器的 bin/<工具名>.exe 是未落位的占位 stub；通用解法 = 国内镜像重装主包与平台原生包 → 搜索定位真实原生二进制 → 复制覆盖占位文件 → 验证版本号。