OpenCode 常见报错怎么解：日志、插件与桌面端排查

OpenCode 是运行在终端、IDE 和桌面端的开源 AI 编程代理，可用来编写、运行和排查代码。2026 年 10 月 28 日更新的官方故障排除文档补齐了日志、存储、插件与桌面应用的处理路径；现在值得按这套路径排查，是因为很多“启动失败”并非代码问题，而是插件、缓存、认证数据或本地服务器状态造成的。

先定位故障层：日志、数据还是插件

OpenCode 的故障排查顺序是：先找日志，再确认本地数据，最后检查桌面端插件。不要一看到空白页面就重装，因为重装通常不会清除 auth.json、数据库和插件目录，反而可能丢掉排查线索。

在 macOS 或 Linux 上运行：

opencode debug paths
opencode db path
opencode --log-level DEBUG

第一条用于确认当前版本的日志与数据目录；第二条用于找到实际使用的数据库；第三条会开启更详细的调试日志。Windows 可按 Win + R，粘贴：

%USERPROFILE%.localshareopencode

官方文档列出的 macOS/Linux 数据目录是 ~/.local/share/opencode/。其中可能包含：

路径或文件	用途	出问题时重点检查
~/.local/share/opencode/log/	CLI 与服务器日志	启动失败、请求异常、插件加载错误
~/.local/share/opencode/auth.json	API 密钥、OAuth Token 等认证数据	登录失效、供应商认证失败
~/.local/share/opencode/opencode.db	SQLite 数据库，保存项目、会话和消息	会话异常、项目状态不一致
~/.local/share/opencode/snapshot/	用于撤销的项目快照	快照相关异常

这里有一个值得注意的口径差异：2026 年 10 月 28 日的中文页面说明日志以时间戳文件命名，并保留最近 10 个日志文件；10 月 29 日的英文页面则将日志路径写成 ~/.local/share/opencode/log/opencode.log。这是文档或版本演进造成的差异，不应只按其中一个目录下结论。执行 opencode debug paths，以本机实际输出为准。

命令无法启动：先换安装方式，不要混装

如果终端无法识别 opencode，先检查是不是同时装过旧版和新版。官方仓库明确提示：安装新版前，应移除低于 0.1.x 的旧版本。

个人电脑可以选择一种安装方式，不要让 npm、Homebrew 和安装脚本留下的多个版本互相抢占命令：

# npm
npm i -g @opencode/cli@latest

# Homebrew 当前版
brew install anomalyco/tap/opencode-v2

# macOS 与 Linux 通用安装脚本
curl -fsSL https://opencode.ai/v2/install | bash

这些命令来自 OpenCode 官方仓库 README。仓库还列出了 brew install opencode、Arch Linux 的 sudo pacman -S opencode、AUR 的 paru -S opencode-beta、mise 的 mise use -g opencode 和 Nix 的 nix run github:anomalyco/opencode。

安装脚本把程序放到 $HOME/.opencode/bin。因此，旧 shell 找不到新命令时，应确认 $HOME/.opencode/bin 已加入 PATH，然后重新打开终端。成功标志不是单纯“下载完成”，而是运行 opencode debug paths 能返回本机路径；如果之前混装过多个版本，应先卸载旧版，再只保留一种安装方式。

桌面端崩溃或空白：先禁用插件

桌面应用会在后台运行一个本地 OpenCode 服务器。官方故障排除文档特别指出：桌面应用启动时崩溃、卡住或行为异常，应先禁用插件。这个判断很重要，因为插件加载失败可能发生在界面出现之前，只重启窗口无法消除问题。

macOS/Linux 的全局配置位于：

~/.config/opencode/opencode.jsonc

旧版安装也可能使用：

~/.local/share/opencode/opencode.jsonc

Windows 可按 Win + R，粘贴：

%USERPROFILE%.configopencodeopencode.jsonc

找到 plugin 键后，先移除该键，或者临时改成空数组：

{
  "plugin": []
}

保存配置，完全退出桌面应用再启动。若问题消失，就说明问题集中在插件加载链上，可以逐个恢复插件以找出冲突项。桌面端仍无法显示时，macOS 用户依次点击 OpenCode 菜单 → Reload Webview；这是官方针对 UI 空白或冻结给出的操作。若界面出现错误页面，点击“重新启动”，并复制页面提供的错误详情，再与同目录下的 DEBUG 日志按时间对应。

认证或会话异常：分清密钥与会话数据库

认证数据保存在 auth.json，会话数据则可能位于数据库中。不要直接编辑 auth.json：其中可能包含 API 密钥和 OAuth Token，手工修改 JSON 容易造成格式错误。

先运行 opencode db path 确认活动数据库。OpenCode 的部分构建、开发通道或自定义 OPENCODE_DB 设置可能使用不同文件名，因此不能假设数据库永远叫 opencode.db。如果日志显示认证信息已失效，回到 OpenCode 的认证入口重新完成供应商登录，再启动一次新会话；如果日志显示的是项目或消息读取异常，则先记录数据库路径，再处理数据库，而不要重新生成全部认证信息。

官方首页说明 OpenCode 可以使用 GitHub Copilot、ChatGPT Plus/Pro，也可以连接其他模型供应商或本地模型。排查时要先确认选中的模型供应商与实际登录方式匹配：使用 Copilot 订阅时，应通过 GitHub 登录；使用 API 供应商时，则检查对应 API 密钥。登录入口和模型列表可从 OpenCode 官方首页 的 Models、Subscription 与 Console 进入。

日志太长或信息太少：重新采集一次

普通日志无法判断问题时，不要反复重装。退出 OpenCode 后，用 DEBUG 级别重新启动：

opencode --log-level DEBUG

然后只复现一次问题，例如启动后立即关闭桌面端，或只运行一次失败的模型请求。日志过多会掩盖首次出现的异常，因此一次只做一个动作，更容易找到第一条错误记录。

排查时按这个顺序读：日志中第一次出现的错误、此前紧邻的配置加载信息、对应时间点的插件或服务器消息。不要只看最后一行；最后一行通常只是“进程退出”，不是根因。若使用自定义 XDG 路径，日志目录也可能被改变，此时 opencode debug paths 的结果比固定路径更可靠。

对照处理后怎么算成功

CLI 故障处理成功后，运行 opencode debug paths 应返回有效路径，且 opencode --log-level DEBUG 能启动并产生调试日志。桌面端处理成功后，窗口不再空白或卡死，后台本地服务器可以正常启动，错误页面不再出现。

插件排查的判断更明确：把 plugin 设为空数组后能稳定启动，说明问题与插件有关；恢复插件后若故障重现，就可以锁定具体插件。认证排查则应看到新的会话能够正常请求模型，而不是只看 auth.json 是否存在。

如果上述操作都无效，就保留三项材料交给官方仓库：完整复现步骤、DEBUG 日志相关片段，以及 opencode debug paths 与 opencode db path 的输出。不要在公开 issue 中粘贴 API 密钥、OAuth Token 或包含敏感信息的完整配置。

官方入口：继续排查和提交问题

完整的路径、数据库、插件与桌面端说明见 OpenCode 故障排除文档；需要核对英文版对 opencode.log、数据库文件名的描述时，可打开 英文故障排除页面。安装命令、桌面应用下载说明和仓库 issue 入口都在 OpenCode 官方仓库。

提交问题前，先按上述顺序保留日志、确认实际路径、隔离插件，再附上最小复现步骤。这样既减少来回询问，也更容易判断问题发生在 CLI、认证、数据库还是桌面本地服务器这一层。