1. OpenCode 报错先别急着重装按这条线索走OpenCode 是一个跑在终端里的开源 AI 编码工具能读项目、改文件、执行命令适合习惯命令行、想把模型能力接进本地工作流的开发者。它本身不绑定某一家模型服务你可以通过配置把请求指向任意兼容 OpenAI 协议的服务端。也正因为这层“可插拔”日志报错、插件加载失败、缓存异常这三类故障出现频率最高而且症状经常互相伪装——插件崩了看起来像模型报错缓存脏了看起来像网络不通。我处理这类问题的顺序固定为四步先看日志定位报错来源再隔离插件确认是不是第三方代码引起然后清缓存让 OpenCode 重建运行时依赖最后校验模型通道配置是否正确。这个顺序的好处是每一步都能缩小范围不会一上来就删配置把现场破坏掉。下面按这个顺序展开涉及的命令和路径都区分了 macOS、Linux、Windows配置骨架可以直接复制。文中模型通道部分用 TaoToken 做示例它的 API 地址是https://taotoken.net/api兼容 OpenAI 协议配置方式和接其他服务端一致你可以照着替换成自己的服务地址。2. 日志、插件、缓存三类故障的定位思路2.1 日志文件在哪怎么抓 DEBUG 级别输出OpenCode 会把运行日志写到本地磁盘出问题时第一站就是这里。日志目录macOS / Linux~/.local/share/opencode/log/WindowsWinR输入%USERPROFILE%\.local\share\opencode\log回车日志文件按时间戳命名比如2025-01-09T123456.log默认保留最近 10 个。想看最新一条的尾部# macOS / Linux tail -n 100 ~/.local/share/opencode/log/$(ls -t ~/.local/share/opencode/log/ | head -1)# Windows PowerShell Get-ChildItem $env:USERPROFILE\.local\share\opencode\log | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 100默认日志级别不够细时启动加参数opencode --log-level DEBUG如果 TUI 已经起不来用--print-logs把日志直接打到终端省得再去翻文件opencode --print-logs2.2 插件加载失败的隔离方法插件是 OpenCode 最容易出问题的一环因为它是第三方代码版本不匹配或初始化异常会直接让应用卡在启动阶段。排查原则是“先全禁再逐个放回”。先看全局配置里的plugin字段。配置文件位置macOS / Linux~/.config/opencode/opencode.jsonc或.json WindowsWinR输入%USERPROFILE%\.config\opencode\opencode.jsonc把 plugin 临时置空{ $schema: https://opencode.ai/config.json, plugin: [] }除了配置声明OpenCode 还会从磁盘目录加载插件这些目录也要临时移走# 全局插件目录 mv ~/.config/opencode/plugins ~/.config/opencode/plugins.bak # 项目级插件目录如果项目里配了 mv ./.opencode/plugins ./.opencode/plugins.bak重启后如果恢复正常就一个个移回来每移一个重启一次定位到具体是哪个插件。这个笨办法比看报错猜要快得多。2.3 缓存异常的判断与清理缓存问题有个典型特征报错信息和实际原因对不上比如模型参数明明没改却提示不兼容或者插件安装卡在半途。OpenCode 会把各服务商的提供程序包缓存到本地缓存损坏时就会出这种“鬼打墙”。缓存目录macOS / Linux~/.cache/opencodeWindowsWinR输入%USERPROFILE%\.cache\opencode清理前先完全退出 OpenCode然后# macOS / Linux rm -rf ~/.cache/opencode# Windows PowerShell Remove-Item -Recurse -Force $env:USERPROFILE\.cache\opencode重启后 OpenCode 会重新拉取最新版本的提供程序包很多因 API 变更导致的兼容问题会顺带解决。3. 可复制的配置骨架与 TaoToken 通道接入3.1 settings.json 与 config.toml 骨架不同版本和不同接入方式下OpenCode 可能读settings.json或config.toml。下面给两份骨架按你实际使用的文件填。settings.json骨架{ model: gpt-4.1, provider: { baseURL: https://taotoken.net/api, apiKey: sk-你的Key }, logLevel: INFO, plugin: [] }config.toml骨架model gpt-4.1 log_level INFO [provider] base_url https://taotoken.net/api api_key sk-你的Key [server] # 端口冲突时改这里或直接删掉让 OpenCode 自选 port 0port 0表示让系统分配空闲端口能避开“端口被占用导致启动失败”这类问题。如果你之前手写过server.port或server.hostname且应用起不来先把整个[server]段删掉重启试试。3.2 模型引用格式与可用列表模型引用必须是providerId/modelId格式写错会直接抛ProviderModelNotFoundError。正确示例openai/gpt-4.1 openrouter/google/gemini-2.5-flash opencode/kimi-k2查看当前可访问的模型列表opencode models如果列表为空或报认证错误说明 Key 或 baseURL 没生效回到上一节的配置检查。3.3 环境变量方式接入不想把 Key 写进配置文件时用环境变量# macOS / Linux export OPENAI_API_KEYsk-你的Key export OPENAI_BASE_URLhttps://taotoken.net/api# Windows PowerShell $env:OPENAI_API_KEYsk-你的Key $env:OPENAI_BASE_URLhttps://taotoken.net/api注意OPENCODE_PORT这个变量如果系统里设了它桌面版会强制用这个端口起本地服务器端口被占就会卡在启动画面。排查连接问题时先确认它没被设成奇怪的值。4. 验证请求是否打通配置改完别急着开新项目先用最小请求验证通道。启动 OpenCode 后执行opencode run 用一句话说明当前使用的模型名称正常返回说明模型通道、Key、baseURL 三者都对。如果报AI_APICallError先清缓存再试rm -rf ~/.cache/opencode opencode run ping还是失败的话用 curl 直接打 API把 OpenCode 这一层排除掉curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4.1, messages: [{role: user, content: ping}] }curl 通而 OpenCode 不通问题在配置或缓存curl 也不通问题在 Key 或网络出口。这样一刀切下去方向立刻清楚。认证类问题还可以在 TUI 里用/connect重新走一遍认证流程比手动改文件稳。5. 本篇常见错排查5.1 ProviderInitError这个报错基本等于“配置无效或已损坏”。先按第 3 节的骨架核对 provider 段确认 baseURL 和 Key 没写错。还不行就清存储配置重来rm -rf ~/.local/share/opencodeWindows 上WinR输入%USERPROFILE%\.local\share\opencode删除。删完用/connect重新认证。5.2 启动崩溃或界面空白先按 2.2 节禁插件。macOS 上如果是界面空白或卡死点菜单栏 OpenCode → Reload Webview 能救回来。Windows 上空白窗口多半是缺 WebView2 运行时装或更新一下再试。Linux 上 Wayland 环境导致空白时可以试OC_ALLOW_WAYLAND1启动如果更糟就换 X11 会话。5.3 连接失败对话框看到 “Connection Failed” 或一直停在启动画面检查是不是配了自定义服务器 URL。在主屏点带状态圆点的服务器名打开选择器在 Default server 区域点 Clear。再检查配置文件里有没有server.port/server.hostname有就删掉重启。5.4 复制粘贴失效LinuxLinux 下复制粘贴需要剪贴板工具X11 装xclip或xselWayland 装wl-clipboard# X11 apt install -y xclip # Wayland apt install -y wl-clipboard无图形界面环境需要xvfb并导出 DISPLAYapt install -y xvfb Xvfb :99 -screen 0 1024x768x24 /dev/null 21 export DISPLAY:99.05.5 最后手段重置桌面应用存储应用完全起不来、界面里也清不了设置时删这几个文件恢复初始状态opencode.settings.dat桌面默认服务器 URL、opencode.global.dat和opencode.workspace.*.dat最近服务器、项目等 UI 状态。它们的位置macOS 在~/Library/Application Support下搜Linux 在~/.local/share下搜Windows 在%APPDATA%下搜。删完重启即可。6. 把通道配置固定下来少踩重复的坑排查完一轮你会发现真正反复出问题的往往不是 OpenCode 本身而是模型通道配置漂移——今天改了 baseURL明天换了 Key后天缓存里还留着旧的服务商包。我的做法是把通道配置集中到一处用 TaoToken 统一 Key 和 API 入口baseURL 固定写https://taotoken.net/api这样切换模型时只改model字段不动 provider 段减少配置面。需要长期跑编码任务或 Agent 工作流的话可以了解下 Coding Plan把额度集中管理避免每个项目单独配 Key 导致混乱。配置过程中卡在认证或接入环节直接翻接入文档对照参数想先验证某个模型能不能用去模型对话页面发一条消息最快。Key 的创建和管理在 API Keys 页面控制台在 console。把这几处固定下来之后再遇到报错基本就是日志、插件、缓存三选一按本文顺序走一遍就能定位。