企业官网建设流程全解析

OpenCode 报 AI_APICallError 时如何清理 provider 包缓存并重装

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode

当 OpenCode 发起模型请求时报出AI_APICallError这类 API 调用错误时，一个常见的根因是 provider 包过期。OpenCode 会在需要时动态安装各提供商（OpenAI、Anthropic、Google 等）的 provider 包，并把它们缓存在本地；一旦缓存的包版本过旧，就可能与模型参数或 API 变更不兼容。本文基于 OpenCode 官方故障排除文档（troubleshooting.mdx），说明如何通过清理 provider 包缓存并让 OpenCode 重新安装最新版包来解决这个问题。

适用的现象与前提是：

• 错误类型为 API 调用错误（AI_APICallError），而不是ProviderModelNotFoundError（模型引用写错）或ProviderInitError（配置损坏），这两者有各自的处理路径，不在本文范围内；
• 你运行在 macOS、Linux 或 Windows 上，文档对三个平台都给出了缓存位置。

为什么会报 AI_APICallError：provider 包是如何被缓存的

按照故障排除文档的说明，opencode 不会把所有 provider 的 SDK 打进主程序，而是按需动态安装 OpenAI、Anthropic、Google 等提供商的包，并将它们缓存到本地目录。文档给出的解释是：强制重新下载最新版本的 provider 包后，"often resolves compatibility issues with model parameters and API changes"（通常能解决模型参数和 API 变更带来的兼容性问题）。因此处理思路是：删掉本地缓存的包，重启让 opencode 重新拉取最新版本。

需要区分两个目录，本文涉及的是后者：

• ~/.local/share/opencode/（Windows 为%USERPROFILE%\.local\share\opencode）：存放auth.json（API 密钥、OAuth Token）、log/日志和project/会话数据。这是文档中ProviderInitError一节要求清理的目录，不是本文要清理的对象。
• ~/.cache/opencode（Windows 为%USERPROFILE%\.cache\opencode）：缓存目录。OpenCode Desktop 的"清除缓存"一节（禁用插件无效或插件安装卡住时）同样指向这个目录。npm 插件在启动时由 Bun 安装，其包和依赖就缓存在~/.cache/opencode/node_modules/下（见 plugins.mdx）。

清理 provider 包缓存

该命令会删除整个~/.cache/opencode缓存目录，删除后 OpenCode 会在下次启动时重新构建缓存（包括重新下载 provider 包），属于文档明确给出的标准操作。注意它同时会清掉缓存在该目录下的 npm 插件依赖，同样会按需重新安装。

macOS / Linux在终端执行：

rm -rf ~/.cache/opencode

Windows按WIN+R打开运行框，粘贴并删除该目录：

%USERPROFILE%\.cache\opencode

macOS 图形界面方式（文档"桌面应用清除缓存"一节给出的路径）：Finder 中按Cmd+Shift+G，粘贴~/.cache/opencode后删除。

如果你使用的是 OpenCode Desktop，文档建议先完全退出应用再操作缓存目录，然后重新启动。

重启并验证结果

清缓存之后的步骤是文档原文：重启 opencode 以重新安装最新的 provider 包。

opencode

启动后，opencode 会重新下载最新版本的 provider 包。验证方式按文档给出的通用手段：

1. 重新发起之前触发AI_APICallError的那次模型请求，确认不再报 API 调用错误；

2. 若问题仍然存在，检查日志。日志文件写入位置（文档"Logs"一节）：

   • macOS/Linux：~/.local/share/opencode/log/
   • Windows：WIN+R粘贴%USERPROFILE%\.local\share\opencode\log

   日志文件以时间戳命名（例如2025-01-09T123456.log），最近 10 个日志文件会被保留。文档"OpenCode won't start"一节还提到可以用--print-logs参数让输出直接显示在终端。

边界与限制

• 文档对AI_APICallError给出的处理路径只有"清~/.cache/opencode缓存 + 重启重装"两步，未承诺所有 API 调用错误都会由此解决。若清缓存后依旧报错，属于文档未覆盖的范围。
• 不要把本文的缓存目录和ProviderInitError的处理混用：后者清的是~/.local/share/opencode，且之后需要用 TUI 中的/connect重新认证，那是一条独立的排障路径。
• 模型引用错误（ProviderModelNotFoundError）应检查模型名写法（格式为<providerId>/<modelId>，例如openai/gpt-4.1），可用opencode models查看可访问的模型，与 provider 包缓存无关。
• 中文版本的同一篇文档位于 zh-cn/troubleshooting.mdx，内容与英文版一致，可作为对照阅读。

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode