进阶 opencode.ai 2026-11-11 16:13:22 · 19 阅读

第6章 OpenCode 故障排查与日志诊断指南

故障排查 OpenCode 采用客户端/服务端架构。后台服务进程负责管理会话、插件、权限及其他应用状态。排查问题时,首先确定故障点位于客户端、共享服务端还是某个特定项目。

查看当前服务端信息: Terminalopencode service status 确认其 API 健康状态: Terminalopencode api get /api/info 如果服务卡住或不健康,请重启: Terminalopencode service restart 也可以显式停止并启动服务: Terminalopencode service stop opencode service start

如果其他来源的浏览器客户端因 CORS 问题无法连接,请将客户端来源添加到服务配置中: Terminalopencode service set cors http://192.168.1.10:3001 opencode service get cors 请使用精确的 HTTP 或 HTTPS 来源,必要时包含端口,不要包含路径或尾部斜杠。若要允许多个来源,请将逗号分隔的来源列表作为单个参数传入;每个来源周围的空白字符会被自动去除: Terminalopencode service set cors "http://192.168.1.10:3001, https://app.example.com" service get cors 会打印一个 JSON 数组。使用以下命令移除已配置的列表: Terminalopencode service unset cors 设置或取消服务配置会停止后台服务。下次启动时会加载新配置;使用 opencode service start 可显式启动服务。 对于前台服务端,每添加一个允许的额外来源,就重复使用 --cors 参数: Terminalopencode serve --cors http://192.168.1.10:3001 --cors https://app.example.com 使用 serve --service 时,提供的 --cors 参数会覆盖该进程持久化的列表。若未提供这些参数,服务模式下会使用持久化的列表。CORS 不会更改监听地址或绕过服务端认证。

api 命令使用本地服务发现和认证流程。它接受 HTTP 方法与路径,或 OpenAPI 操作 ID。 请参阅 API 参考以了解所有端点和操作 ID。 使用 --data 或 -d 传递 JSON 请求体,使用 --header 或 -H 添加请求头。

已安装版本将日志写入: ~/.local/share/opencode/log/opencode.log 在复现问题时跟随日志: Terminaltail -f ~/.local/share/opencode/log/opencode.log 每行日志包含进程运行 ID 和角色字段。使用 role=server 筛选会话、提供商、插件、权限和工具活动。 Terminalgrep 'role=server' ~/.local/share/opencode/log/opencode.log grep 'run=8fc3b1d5' ~/.local/share/opencode/log/opencode.log

在任何平台上生成运行中后台服务进程的内存(堆)快照: Terminalopencode debug heap-dump 该命令会等待快照完成,然后打印其路径: /home/me/.local/share/opencode/log/heap-48213-2026-10-23T013012345Z.heapsnapshot 使用 --directory 将快照写入其他位置。如果目录不存在,服务端会自动创建: Terminalopencode debug heap-dump --directory ./snapshots

此命令仅适用于已运行的服务端,绝不起、替换或重启任何服务端。 使用 --server 捕获通过 opencode serve 启动的服务端。如果该服务端设置了密码,请配置 OPENCODE_PASSWORD。 此时 --directory 指向服务端所在机器上的路径。 在 Chrome DevTools 的内存面板中打开该文件。

通过命令面板运行“捕获堆快照”。它会在下载文件夹中生成一个文件夹,其中包含应用各部分的快照,以及快照无法显示的内存明细: opencode-heap-2026-10-23T013012345Z/ memory.json 各进程的内存分布(单位:MiB),从这里开始查看 memory-infra.json Chromium 内存转储跟踪;在 https://ui.perfetto.dev 中打开 heap-48213-….heapsnapshot 桌面自身的服务端 window-1-48390.heapsnapshot 每个应用窗口一个 main-48102.heapsnapshot 桌面主进程 gpu.json GPU 和驱动程序 manifest.json 进程、PID 及前后内存状态;最后写入

堆快照仅包含 JavaScript 对象和页面。图像、布局、合成层及 GPU 内存则记录在 memory.json 和 memory-infra.json 中。 远程服务端不会被捕获。请在那台机器上使用 opencode debug heap-dump。 服务端会直接将快照写入该文件夹,因此不会移动或复制大型文件。 不包含浏览器选项卡,因为它们的快照包含已访问页面的内容。

在 macOS 和 Linux 上,可以向正在运行的 OpenCode 进程发送信号以捕获诊断数据。从健康检查端点获取后台服务进程 PID: Terminalopencode api get /api/info 使用响应中的 pid 并发送以下任一信号:

SIGPROF 捕获十秒 CPU 分析: Terminalkill -SIGPROF 结果写入日志目录,命名为 cpu--.cpuprofile。

SIGUSR1 捕获内存(堆)快照: Terminalkill -SIGUSR1 结果写入日志目录,命名为 heap--.heapsnapshot。

在打开文件之前,请等待 opencode.log 中出现“CPU profile written”或“heap snapshot written”提示。对应的日志条目包含完整路径。可在 Chrome DevTools 中检查这两种文件类型。

共享服务端注册文件位于: ~/.local/state/opencode/service.json 其私有服务配置单独存储于: ~/.config/opencode/service.json 数据库通常位于: ~/.local/share/opencode/opencode.db 可通过 OPENCODE_DB 覆盖数据库位置。

报告可复现问题时,请包含以下内容:

opencode --version 的输出 opencode service status 的输出 复现该问题的最小步骤序列 该问题是影响共享服务、特定客户端还是单个项目 相关日志行,包括其运行和角色字段

共享日志前,请移除 API 密钥、认证头、提示词、文件内容及其他敏感数据。 请在 GitHub Issues 中提交可复现的问题。

评论 (0)