5.22 调试与诊断工具

像开发者一样剖析 OpenCode

📝 课程笔记

本课核心知识点整理：

🎒 开始前的准备

了解命令行基本操作

遇到过难以排查的 Bug 或配置问题

核心思路

OpenCode 内置了一套强大的调试工具箱 opencode debug。这些工具不仅用于开发调试，也能帮助高级用户诊断配置错误、文件系统问题和 AI 行为异常。

跟我做

1. 调试配置 (Config)

想知道你的配置到底怎么生效的？

重要场景：OpenCode 的配置不仅来自 opencode.json，插件也可以在启动时动态注入配置。

如果你想确认：

某个插件注入的配置是否生效？

默认值、用户配置和插件配置合并后的最终结果是什么？

必须使用此命令：

输出示例（截取）：

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": { ... },
  // 这里列出了所有已加载的 Agent（包括默认和自定义）
  "agent": {
    "coder": { ... },
    "writer": { ... },
    "my-custom-agent": { ... } // 确认自定义 Agent 是否存在
  },
  // 这里可能包含插件动态注入的配置
  "plugin_injected_config": { ... }
}

::: tip 💡 怎么看加载了哪些 Agent？
直接看 opencode debug config 输出中的 agent 字段。这里列出了所有已注册且可用的 Agent。
如果这里没有，说明 Agent 定义文件有问题，或者没被 OpenCode 扫描到。
:::

2. 调试文件系统 (File & Ripgrep)

OpenCode 依赖 ripgrep 进行极速搜索。如果搜索结果不符合预期，可以用这些命令排查。

检查搜索底层行为：

检查文件读取：

3. 调试 Agent 和 Skill

当你安装了大量插件或手动添加了很多 Skill 时，可能会遇到**"我装了但不知道生效没"**的情况。

用了下面这个命令，就能快速知道 OpenCode 现在实际加载了哪些 Skill。它会列出 Skill 的名称和物理路径，是排查冲突的终极手段。

列出实际加载的 Skill：

输出示例：

[
  {
    "name": "fanyi",
    "description": "...",
    // 确认加载的是哪个路径下的文件
    "location": "/Users/user/.claude/skills/fanyi/SKILL.md"
  },
  {
    "name": "sync-changelog",
    // 确认是否覆盖了同名 Skill
    "location": "/Users/user/.config/opencode/skill/sync-changelog/SKILL.md"
  }
]

查看 Agent 配置详情：

[高阶] 手动执行 Agent 工具：
想测试 Agent 能否成功调用某个工具？可以直接测试：

列出所有 Skill：

4. 调试 LSP (语言服务器)

如果代码补全、跳转定义不工作，可能是 LSP 出了问题。

5. 查看系统状态 (Paths & Scrap)

查看关键路径：
不知道数据存在哪？

输出示例：

data       /Users/username/.local/share/opencode
config     /Users/username/.config/opencode
log        /Users/username/.local/share/opencode/log
cache      /Users/username/.cache/opencode

查看项目历史 (Scrap)：
OpenCode 会记录你打开过的所有项目（Worktree）。

6. 调试快照 (Snapshot)

OpenCode 的上下文压缩依赖快照机制。

命令速查表

命令	用途	典型场景
`debug config`	查看最终配置	检查配置是否生效、查看默认快捷键
`debug agent <name>`	查看 Agent 详情	检查 Prompt、权限、工具列表
`debug agent --tool`	手动执行工具	验证工具参数格式、测试工具权限
`debug skill`	列出 Skill	确认 Skill 是否加载、查看加载路径
`debug rg search`	测试搜索	排查搜索不到文件的问题
`debug file read`	读取文件	检查文件内容读取是否包含元数据
`debug file status`	文件状态	查看 Git 状态集成
`debug paths`	查看路径	找日志文件、清空缓存时确认路径
`debug lsp`	调试 LSP	排查代码补全/跳转失效问题
`debug scrap`	查看项目列表	找回历史项目 ID

踩坑提醒

现象	原因	解决
`command not found`	旧版本 OpenCode	升级到最新版
输出内容过多	JSON 数据量大	配合 `> debug.txt` 重定向到文件查看
`debug agent` 报错	未指定 Agent 名称	必须加名字，如 `opencode debug agent coder`

本课小结

opencode debug 命令的核心价值在于**"运行时可见性"**：

Config: 看到的是插件注入并合并后的最终配置，而非静态文件。

Skill: 看到的是实际加载的清单和路径，确认没有被忽略或覆盖。

Agent: 看到的是完整的上下文和权限，甚至可以模拟执行。

当你怀疑 OpenCode "坏了"的时候，先用这些命令照一照，通常能发现是配置问题还是真的 Bug。

📝 课程笔记#

🎒 开始前的准备#

核心思路#

跟我做#

1. 调试配置 (Config)#

2. 调试文件系统 (File & Ripgrep)#

3. 调试 Agent 和 Skill#

4. 调试 LSP (语言服务器)#

5. 查看系统状态 (Paths & Scrap)#

6. 调试快照 (Snapshot)#

命令速查表#

踩坑提醒#

本课小结#