快速答案
- 装完就报 "opencode: command not found"？安装器的 bin 目录没进 PATH——在 shell 配置里 export 一下（视频里给 Git Bash 加的就是 .opencode/bin 这条路径），再开个新终端。
- 安装脚本一直报错？它是 Bash 脚本——放到 PowerShell 里跑，-fsSL 这个参数就会出错。先把 VS Code 的默认终端配置切成 Git Bash，再重新跑 curl -fsSL https://opencode.ai/install | bash。
- 终端或桌面窗口打开一片黑？把 .local/share/opencode 下面损坏的数据目录清掉（Windows 是 AppData\Local\share\opencode），结束卡住的进程再重启——录屏里 TUI 一分钟内就恢复渲染了。
- 报 "Free usage exceeded" 或 provider 错误？用 /models 打开模型选择器换一个模型，或者用 /connect 重新认证。跑一下 opencode auth list 确认凭据已就位。
- 模型列表不全？只有已连接的 provider 才会显示。用 /connect 添加 provider，或者在 opencode.json 里用 model、disabled_providers 和每个 provider 的白名单/黑名单键来管理列表。
Fix OpenCode Error in Antigravity Terminal (Git Bash + PATH Solution)
频道：teacher account5:52
OpenCode docs — install, config & troubleshooting
文档：opencode.ai/docs
截图帧来自三段屏幕录制：上面的 PATH 修复、一次 Windows 黑屏修复（Vũ Văn Hà 的 xiXPoY2d4iw），以及一次免费额度触顶后的模型切换（Free Code 的 DX8MZFuu1BM）。每一步都能直达对应视频的位置。
视频画面版权归各自创作者所有，此处以分步文档形式嵌入，均注明出处并附深度链接。
一步一步修好 OpenCode
安装与 PATH——"命令找不到"阶段
- 1
拿到官方安装命令
打开 opencode.ai，从安装框里复制命令——curl -fsSL https://opencode.ai/install | bash——或者把标签页切到 npm、bun 或 brew。如果 OpenCode "用不了"其实是因为压根没装完整，从这个官方命令重来，比调试一条复制了一半的命令划算得多。
opencode.ai 的安装框，带 curl、npm、bun 和 brew 标签在 0:08 观看 - 2
在 Bash shell 里跑安装脚本，别用 PowerShell
安装脚本是为 Bash 写的。粘进 PowerShell 就会报 Invoke-WebRequest: A parameter cannot be found that matches parameter name 'fsSL'，和录屏里拍到的一模一样。画面上演示的修法：在 IDE 的 settings.json 里把 terminal.integrated.defaultProfile.windows 设成 Git Bash，让命令落进 Bash shell。
PowerShell 抛出的 -fsSL 错误，旁边就是默认终端配置项在 1:32 观看 - 3
扩展 PATH，修掉 "opencode: command not found"
安装完成了，终端却还是报 bash: opencode: command not found——说明二进制所在目录没进 PATH。录屏里在 Git Bash 用 export PATH=/c/Users/<you>/.opencode/bin:$PATH 加上 .opencode/bin 目录，然后重新启动 opencode——同一行 export 写进 ~/.bashrc 才能长期生效。
command not found、PATH export，以及重试成功的那一刻在 4:32 观看 - 4
在 Git Bash 里重跑安装器并确认
把 Git Bash 设为默认配置后，再跑一次 curl -fsSL https://opencode.ai/install | bash 并等它跑完。也可以走 npm：npm install -g opencode-ai，Windows 上还有 choco 和 scoop。装完重开终端，让更新后的 PATH 生效。
Git Bash 已是默认配置，安装命令正在重跑在 2:30 观看
黑屏与启动崩溃
- 5
认出黑屏启动长什么样
第二种故障形态：输入 opencode，窗口标题变了，主体却一直黑着——没有横幅，没有提示符。录屏在 Windows 11 上拍到的正是这种"死窗口"。你的输入没有问题；是磁盘上的状态或卡住的进程挡住了 TUI 渲染。
刚启动 opencode 时空白的命令提示符窗口在 0:09 观看 - 6
清掉损坏的数据目录
录屏里的修法：关掉 OpenCode，在任务管理器结束卡住的实例，然后删除 AppData\Local\share\opencode 数据目录（macOS 和 Linux 是 ~/.local/share/opencode）。里面存着 auth.json、日志和项目状态，所以之后要重新认证——换来一个能用的 TUI，这点代价不算什么。
删除前 AppData\Local\share 下的 opencode 数据目录在 0:28 观看 - 7
重新启动，确认 TUI 正常渲染
再跑一次 opencode。录屏的下一幕就是健康的终端界面——横幅、Ask anything 提示，还有 "Run /connect to add an AI provider and start coding" 这句提示。如果窗口还是黑的，用 opencode --print-logs 启动，看 log/ 目录下最新文件里报错的那一行。
状态清理完成后恢复的 OpenCode TUI在 1:09 观看
Provider、模型与 IDE 问题
- 8
切换前先读懂免费额度提示
内置模型的额度用完时，会话里会出现红色的 "Free usage exceeded, subscribe to Go [retrying…]" 横幅并停止响应。这不是崩溃——录屏显示一换模型会话立刻恢复，所以把这条提示当作"去第 9 步"的信号就好。
Free usage exceeded 横幅和当前模型行在 0:36 观看 - 9
打开模型选择器换一个模型
在会话里跑 /models（或在 shell 里跑 opencode models），列出已连接 provider 提供的所有模型。录屏从 OpenCode Zen 目录里挑了另一个带 Free 标记的模型；凡是你有凭据的模型都可以用，用 /connect 连上后 Claude、GPT、Gemini 都行。
Select model 选择器，带 Free 标记的模型和 provider在 0:12 观看 - 10
有推理档位就选一档
有些模型会再弹一个 Select variant 对话框，有 Default、minimal、medium、high、xhigh 几档，录屏里就是这么拍的。低档回答更快、花费更少；高难度重构留给 high。这个选择只对当前会话生效，随便试，很安全。
Select variant 里从 minimal 到 xhigh 的推理档位在 0:20 观看 - 11
在状态栏确认切换成功
提示符下方的状态栏会写明当前模型——录屏里切换后显示 Build · Muse Spark 1.2 Free · OpenCode Zen · xhigh，上下文面板显示已用 token 和 $0.00 花费。如果换到新模型错误仍然不消，用 /connect 重新认证，再用 opencode auth list 验证。
状态栏确认已切换的模型和推理档位在 0:30 观看 - 12
把 OpenCode 接进 VS Code
针对"在 VS Code 里用不了"这种情形：打开集成终端，跑 opencode，OpenCode 插件会自动安装——录屏的 Installed 列表里出现了 opencode for VS Code by SST。之后 Ctrl+Esc 会在分屏终端里打开 OpenCode；如果不行，在扩展市场搜 "OpenCode" 手动安装。
已安装的 opencode 插件和安装器的运行说明在 3:02 观看
还是没修好？把清单过一遍
如果上面三个阶段没覆盖你的症状，剩下的故障模式都在这里——每一条都对应官方文档，治的是病根，不是表象。
- 1装完还是"找不到命令"——每个已开的终端都留着旧 PATH。关掉重开 shell，并把 export 那行写进 ~/.bashrc（或在 Windows 的系统属性里设 PATH），这样重启后依然生效。npm 用户：npm 的全局 bin 目录也得在 PATH 里。
- 2完全起不来——跑 opencode --print-logs 实时看报错，再读 ~/.local/share/opencode/log/（Windows 是 %USERPROFILE%\.local\share\opencode\log）里最新的日志。应用只保留最近 10 份日志；最新的那份才是关键。怀疑二进制过旧就跑 opencode upgrade。
- 3ProviderInitError 或 "invalid or corrupted configuration"——官方文档给的方子是删掉数据目录（rm -rf ~/.local/share/opencode）再用 /connect 重新认证。和第 6 步修黑屏是同一个方子，只是这次从报错信息推过去。
- 4会话中途 AI_APICallError——用 rm -rf ~/.cache/opencode 清掉 provider 包缓存再重启，让 provider SDK 重装。之后查一下 opencode auth list；凭据过期或缺失是第二大常见原因。
- 5Windows 桌面版起不来——更新 WebView2 运行时，彻底退出再重启，并清掉自定义的 server.port / OPENCODE_PORT 覆盖项。官方文档推荐在 Windows 上用 WSL 获得最顺滑的体验，顺带绕开大多数终端配置问题。
- 6模型显示不全——/models 只列出你连接过的 provider。用 /connect 添加，再在 opencode.json 里管理目录：设 "model": "provider/model-id" 为默认，用 disabled_providers 隐藏整个 provider，或用每个 provider 的白名单/黑名单收窄列表。
按顺序过完这份清单，绝大多数 "opencode 用不了" 的反馈都能解决：先 PATH，再状态，最后 provider 和模型。全都无效时，把最新的日志文件收好，去 OpenCode 仓库开一个 issue——维护者要的是日志，不是截图。