OpenCode 启动与鉴权排障

结论

三类故障症状不同、修法不同，先对号入座，不要一上来就改配置：

症状	根因	处理
opencode 命令找不到 / 报「不是有效的 Win32 应用程序」	npm 全局安装损坏（三层，见下）	重装 opencode-ai
opencode run 报 Unauthorized: Invalid API key / 401	配置引用的 API key 失效（公司 key 轮换后未同步），模型 ID 可能也已过期	换用有效凭据 + 更新模型 ID
加了 --workdir 后只打印帮助就退出	1.18.29 没有 --workdir 参数	改用 --dir

环境

• Windows 11 + Windows PowerShell 5.1
• opencode-ai 1.18.29，npm 全局安装（<NODE_GLOBAL>）
• Provider：内网 OpenAI 兼容端点 http://<INTERNAL_HOST>:<PORT>/v1

一、命令找不到：npm 全局安装三层损坏

现象：

Invoke-Expression : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

但 <NODE_GLOBAL> 目录存在、里面也有 node_modules。三层故障相互独立，可能同时存在：

层	检查点	症状	处理
1. npm shim	<NODE_GLOBAL> 下只有 .opencode-<随机串>、.opencode.cmd-<随机串>、.opencode.ps1-<随机串>	上次 npm 更新时文件被占用，重命名失败，正式文件没了	把三个临时文件改回 opencode / opencode.cmd / opencode.ps1
2. 占位符 exe	node_modules\opencode-ai\bin\opencode.exe 只有几百字节，输出 postinstall script was not run	postinstall 没跑成功	在 node_modules\opencode-ai\ 内执行 node postinstall.mjs
3. 平台包 exe 被截断	Windows 报 %1 is not a valid Win32 application	下载的 opencode-windows-x64* 里的 exe 不完整	重装

重装（需要网络，先确认代理可用）：

npm uninstall -g opencode-ai
npm i -g opencode-ai@latest --prefer-online --no-audit --no-fund
opencode --version

判定 exe 是否被截断：不要看文件大小，也不要看 MD5。opencode 的 exe 是 Bun 编译产物，最后一个节特别大——本次故障中文件只有 20,123,534 字节，而 PE 节表声明的末尾在 179,636,736 字节，少了约 160 MB。只有「节表末尾 vs 真实 EOF」的比对能确认截断。

本次实测结果：

opencode --version  ->  1.18.29
bin\opencode.exe    ->  179,632,680 字节，节表与 EOF 一致

二、401 / Invalid API key：key 轮换后配置未同步

现象（日志里能直接看到实际使用的 provider 与模型）：

llm.provider=<PROVIDER>  llm.model=<MODEL_ID>
AI_APICallError: Unauthorized

排查顺序：先排除网络，再查凭据，最后核对模型名。

1. 确认端点可达，排除代理干扰：

   curl.exe -sS -o NUL -w "%{http_code} %{time_total}s`n" http://<INTERNAL_HOST>:<PORT>/v1/models

   本次结果：200，73 ms —— 网络和代理都不是问题。
2. 逐个验证配置引用的 key：本次配置里三把 key 全部 401。
3. 用 opencode 自己保存的凭据试：auth.json 里那条凭据有效。
4. 由此得出结论：公司做过 API key 轮换，配置文件里引用的 key 全部失效，只有凭据库里那把还是新的。
5. 顺带核对模型 ID：配置里的模型名也已过期，需要一起更新。

处理方向：把配置引用的 key 换成有效凭据（或统一改为只从凭据库 / secrets 文件读取），并同步更新 model / small_model。

状态：截至 2026-09-09 未完成修复。 会话在「定位 provider 定义来源」处中断，尚未把有效 key 落到配置并端到端验证。若仍报 401，按上面第 2–3 步重新对齐 key。

三、--workdir 不存在

opencode run --help（1.18.29）里没有 --workdir，只有：

--dir    directory to run in, path on remote server if attaching

写自动化脚本时用 --dir。用 --workdir 会打印帮助后退出，不产生会话，也不会给出明确的参数错误。

风险与边界

• 本文命令均在 Windows PowerShell 5.1 下执行；curl.exe 是 Windows 自带版本，不是 PowerShell 的 curl 别名。
• 内网地址一律用占位符，实际地址以本机配置为准。
• 不要把 API key、密码写进文档、脚本或 Git 提交；优先用 secrets 文件 + 引用。
• 重装只解决「命令跑不起来」；401 属于凭据问题，重装无效。

验证方法与实际结果

检查	命令	实际结果
命令可用	opencode --version	1.18.29 ✅
exe 完整	PE 节表末尾 vs 文件大小	一致 ✅
端点可达	curl.exe .../v1/models	200 ✅
鉴权	opencode run ...	Unauthorized ❌ 未解决

相关

• 本机配置审计
• 进阶使用手册