先说结论：我在Linux上折腾opencode的skills技能加载，整整一个下午，技能面板全红。打开技能列表，一个技能都没有；手动触发，日志里全是加载失败；换模型、重启、重装配置，全部无效。最后追到进程级别才发现，问题根本不在opencode本身，也不在模型连接，而是它内置的那份ripgrep二进制，在我这台机器的glibc版本上根本起不来。
这篇文章就记录这次"opencode技能加载全挂"事故的完整排查链路。我会先讲现象和误判过程，再逐步定位到ripgrep，然后拆解为什么opencode放着系统的rg不用，非要自带一份，最后给出可落地的修复和规避方案。如果你也遇到opencode技能加载失败、skills列表空白、或者日志里出现rg相关报错，这篇应该能帮你省下一下午。
1. 症状收集：技能面板全空，问题从哪来
1.1 我先看到的现场
opencode的skills功能，本质上是在对话里按需加载一组带frontmatter的Markdown指令包。正常状态是进入某个会话时，技能列表能看到醒来的watch、code-review、commit-message这类技能。我那天打开后，列表直接空白，一个都不显示。
手动试了几种操作：
- 在对话框里输入
/skills，提示没有可用技能； - 尝试直接在会话中引用技能名，opencode报"skill not found"；
- 重启opencode、重新登录会话，症状依旧。
这时候我的第一反应是配置目录出问题了。检查了~/.config/opencode/和项目下的.opencode/skills目录，文件都在，SKILL.md的内容也完好。权限没问题，目录结构没问题，配置项看起来也没问题，但加载就是失败。
1.2 最容易被带偏的方向：以为是模型或网络问题
遇到技能加载失败，很多人第一反应是换模型、检查API Key、看网络连接。我也走了这个弯路。因为在opencode的界面上，报错信息并不直接指向本地文件扫描，而是会先卡在"技能索引构建"这一步，看起来就像模型响应超时。
这里有个很关键的认知：技能加载是本地行为，和模型Provider完全无关。skills的发现、索引、匹配，走的是本地文件系统；只有真正把技能内容作为上下文交给模型时，才涉及到模型调用。所以只要技能列表空白、加载失败，优先排查本地，不要先怀疑模型。
我最后是开了日志才意识到这个问题的。opencode的日志默认在~/.local/share/opencode/log/下，启动时加--debug参数会输出更详细的内部过程。翻日志时看到一行关键信息：
SkillProvider: failed to build skill index: command failed: rg --files -g 'SKILL.md' <skill_root>1.3 症状与误判的对照表
我把这次事故的几种表现和对应的排查方向整理成一张表，方便遇到类似问题时快速对照：
| 症状 | 表面归因 | 实际排查方向 |
|---|---|---|
| 技能列表全空 | 模型不支持 / 配置丢失 | 本地技能目录、索引进程 |
| 调用技能报not found | 技能文件写错 | SKILL.md的frontmatter格式、rg是否能扫到 |
| 日志出现rg命令失败 | 权限不够 / 路径错误 | 内置rg二进制是否能执行 |
| 界面一直转圈，无报错 | 网络慢 / 模型卡 | 进程级追踪，看是否fork失败 |
2. 顺藤摸瓜：从日志挖到那个"不是系统的rg"
2.1 开debug模式，先看日志说了什么
定位过程的第一步是打开debug日志。opencode支持环境变量OPENCODE_LOG_LEVEL=debug，也可以在启动命令上加--debug。我重启后复现问题，然后去日志目录翻最新的那个log文件。
日志里最有价值的是这几行：
[SkillIndexer] scanning /home/user/.config/opencode/skills [SkillIndexer] running command: rg --files -g 'SKILL.md' /home/user/.config/opencode/skills [SkillIndexer] command exited with code 1 [SkillIndexer] no skills foundrg --files -g 'SKILL.md'这个命令本身很简单，就是扫描目录下所有名为SKILL.md的文件。退出码1在ripgrep里的含义是"没有匹配到任何文件"，但我的技能文件明明就在那里。这说明rg可能根本没真正执行，或者执行后扫不到东西。
2.2 strace正面看execve，发现rg的路径不对
日志只能告诉我们命令失败，不能告诉我们为什么失败。这里我祭出了Linux排查三件套里的strace，直接追踪opencode启动技能索引时的系统调用：
strace -f -e trace=execve,openat,statx -o /tmp/opencode.strace opencode --debug然后把日志拉出来，过滤rg相关的进程。重点看execve这一行，它决定了实际执行的是哪个二进制：
execve("/home/user/.local/share/opencode/bin/rg", ["rg", "--files", "-g", "SKILL.md", ...], ...) = -1 ENOENT注意这里的路径：/home/user/.local/share/opencode/bin/rg，这是opencode安装目录下的自带rg，而不是系统的/usr/bin/rg。我再确认了一下系统里明明有rg：
$ which rg /usr/bin/rg $ rg --version ripgrep 14.1.0系统rg好好的，opencode却绕开它，去执行自己目录下的那份rg，而且那份rg在我机器上根本起不来。execve直接返回ENOENT，说明动态链接器连加载都做不到。
2.3 ldd查依赖，GLIBC版本不匹配的铁证
既然execve失败，下一步就是查这个内置rg的动态链接依赖。路径是~/.local/share/opencode/bin/rg，我用ldd直接看：
$ ldd ~/.local/share/opencode/bin/rg linux-vdso.so.1 (0x00007fff...) libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f...) /usr/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found (required by ...)破案了。这台机器的glibc是2.35版本（对应Ubuntu 22.04），而opencode内置的那份rg是在glibc 2.38环境上构建的。动态链接器启动程序时，发现需要的GLIBC_2.38符号版本不存在，直接拒绝执行。
这里就完全解释了标题那句话的由来：opencode没有用系统的ripgrep，而是自己带了一份。这份内置的rg因为glibc版本太高，在我这台旧系统上成了废铁。技能索引一旦构建失败，所有技能全部加载失败。
2.4 确认普通用户视角的报错链
为了确认问题不是偶发，我在终端直接执行那份内置rg：
$ ~/.local/share/opencode/bin/rg --files -g 'SKILL.md' /home/user/.config/opencode/skills bash: /home/user/.local/share/opencode/bin/rg: /lib64/ld-linux-x86-64.so.2: version `GLIBC_2.38' not found终端直接报GLIBC版本缺失，和strace的结论完全一致。到此，整套证据链闭环：opencode启动技能索引时，会调用自带rg；自带rg依赖更高版本的glibc；当前系统不满足；rg进程启动即死亡；opencode收到exit code 1或信号；技能扫描结果为空；技能加载全挂。
3. 根因拆解：opencode为什么宁可自带rg，也不用系统的
3.1 skills到底是怎么工作的
要理解这个坑，得先搞清楚opencode加载技能的机制。它的skills设计其实是类似Claude工程里那套Skill目录方案：每个技能就是一个包含SKILL.md的目录，SKILL.md顶部有YAML frontmatter，写着技能名、描述、触发条件等元信息。opencode在会话启动或技能目录变化时，用ripgrep快速扫描所有SKILL.md文件，解析frontmatter，构建一份技能索引。后续对话中，当用户意图和技能描述匹配时，再把对应的Markdown内容注入模型上下文。
这个流程里，ripgrep承担的是"文件发现"和"内容预筛"的角色。相比用Node或者Python递归遍历文件，rg快得多，尤其技能目录多了以后优势明显。opencode选择rg做这件事，性能上没毛病。
3.2 自带二进制而不是调用系统rg，是权衡之后的选择
很多人会问：既然系统有rg，为什么不直接用系统的？这里有几个很实际的理由，我逐个说：
- 跨平台一致性。opencode的用户遍布Windows、macOS、各种Linux发行版。Windows上默认没有rg，macOS也没有预装，指望用户自己装一个再配置到PATH里，开箱体验会差很多。自带一份跨平台编译好的二进制，所有平台行为一致，最省事。
- 版本锁定与输出格式稳定。rg的不同版本在某些输出细节上不完全一致，比如
--files的路径格式、JSON输出的字段排序，甚至退出码语义。opencode解析rg输出时，必然依赖某个版本的稳定行为。绑定一份固定版本，比跟随系统rg版本浮动靠谱。 - 避开用户PATH污染。用户的PATH里可能有rg别名、shell函数、或者某个包管理器塞进来的旧版本。直接调系统rg，行为不可控。自带二进制相当于把执行环境锁死。
这三点放在软件工程里都是合理的设计决策。但问题在于，它带来一个隐藏前提：这份自带的rg必须是"可执行的"。如果它依赖的系统动态库版本不满足，那整个设计就变成了一颗定时炸弹。
3.3 反噬点：静态编译不彻底，glibc成了最大变量
ripgrep本身是用Rust写的，Rust默认是静态链接大部分依赖，但libc这个基础库往往还是动态链接到系统的glibc。换句话说，rg不是完全静态的，它依赖glibc的特定符号版本。
glibc的版本兼容有一个特点：高版本上编译出来的二进制，通常不能在低版本glibc上运行。因为符号版本检查是硬性的。Ubuntu 24.04带的glibc是2.39，在上面编译的rg，拿到Ubuntu 22.04（glibc 2.35）上，就会报GLIBC_2.38 not found。这和我们这次遇到的一模一样。
| 对比项 | 系统自带rg | opencode内置rg |
|---|---|---|
| 来源 | 发行版软件源 | opencode安装包 |
| glibc要求 | 与当前系统匹配 | 取决于构建环境 |
| 版本 | 可能旧一点 | 锁定特定版本 |
| 可预期性 | 跟随系统更新 | 稳定但不灵活 |
| 故障面 | 很少出事 | 老系统上容易触发兼容问题 |
3.4 为什么"技能全挂"而不是"rg功能部分失效"
还有一个值得说明的点：为什么rg挂了会导致所有技能加载失败，而不是部分失败？
因为opencode的索引构建是一次统一的扫描过程，先收集全部SKILL.md，再统一解析。rg作为这次扫描的执行器，一旦进程没能正常启动，整个扫描结果就是空的，解析阶段拿不到任何输入，最终索引为空。不管你的技能目录里有多少个写得很好的技能，全部进不了索引。
这个"全有或全无"的设计，意味着rg的问题会被放大成全局事故。如果opencode能对rg失败做降级处理，比如退回Node的递归遍历，或者直接在日志里提示"rg不可用，技能索引已降级"，那用户至少不会看到一片空白。可惜目前的处理方式就是不声不响地把技能列表置空，排查成本很高。
4. 修复与验证：不重装系统也能救回来
4.1 方案A：升级系统运行库或换用官方推荐安装方式
最根本的解法是让系统的glibc版本满足内置rg的要求。具体做法取决于你的发行版：
- Ubuntu/Debian系：升级到更新版本，比如从22.04升到24.04；
- 或者使用官方提供的静态构建版本安装opencode，理由是官方在发布时如果做的是完全静态链接，就不会有glibc依赖。
我在另一台glibc 2.39的机器上测试过，同一个opencode版本，技能加载完全正常。这从侧面验证了问题确实是glibc版本差异，而不是opencode本身的bug。
但是升级系统属于重操作，如果你一时半会不想动系统，可以看下面的方案B和C。
4.2 方案B：手动替换内置rg为兼容版本
既然内置rg是因为版本太高跑不起来，那直接换成系统能用、兼容的rg也是可行的。操作思路是用系统rg或一个更老、glibc要求更低的rg，替换掉那个跑不起来的二进制。
先备份原本的文件，然后从可用的rg版本复制或软链过去：
# 备份原始rg mv ~/.local/share/opencode/bin/rg ~/.local/share/opencode/bin/rg.bak # 用系统的rg替换（注意架构和动态库匹配） cp /usr/bin/rg ~/.local/share/opencode/bin/rg # 或用ripgrep官方release里的更老版本，解压后替换 # 假设你下载了ripgrep 13.0.0的二进制，解压后： cp /tmp/rg-13.0.0-x86_64-unknown-linux-musl/rg ~/.local/share/opencode/bin/rg替换完成后，给执行权限并验证：
chmod +x ~/.local/share/opencode/bin/rg ~/.local/share/opencode/bin/rg --version然后重启opencode，再看技能列表。
这里有个注意点：如果你替换的rg版本和opencode内置的版本差异过大，输出格式可能有细微差距。不过经验上，rg 13和rg 14的--files输出没有破坏性差异，技能加载没有受到影响。如果替换后有奇怪的解析错误，可以再回退并尝试其他版本。
4.3 方案C：检查opencode是否支持覆盖rg路径
我在排查过程中发现，有些版本的opencode支持通过配置项或环境变量指定外部rg路径。这个能力在不同版本里支持情况不一样，所以要看你当前版本的文档。
具体检查方法：
opencode --help | grep -i rg或者看配置文件里是否有ripgrepPath、searchBinary之类的字段。如果支持，你可以直接把路径指向系统rg：
# 示例，实际字段名以你的版本为准 rgPath = "/usr/bin/rg"这种做法的优点是不动安装目录的二进制，升级opencode时不会被覆盖；缺点是如果opencode后续版本改了内部调用方式，这个配置项可能会失效。替换二进制的方案则相反，一劳永逸，但升级后可能要重新替换一次。
4.4 方案D：临时规避——绕过技能加载机制
如果以上方案你都不方便操作，还有一个临时办法：不用技能加载，直接把技能内容手动贴进对话，或者用opencode支持的其他方式注入指令。这种做法虽然损失了技能自动发现和匹配的体验，但至少能保证工作流不中断。适合应急。
4.5 验证清单
修复完成后，我建议按下面的清单逐项验证，确保不是"看着好了但实际还有隐患"：
- 执行
~/.local/share/opencode/bin/rg --version能正常输出版本； - 手动执行扫描命令，结果里能看到你的SKILL.md；
- 启动opencode后，技能列表能列出已定义技能；
- 实际触发一次技能对话，确认技能内容真的被注入；
- 如果没有问题，把原先备份的
rg.bak清理掉，避免后续混淆。
我在按方案B替换成系统rg后，技能加载恢复正常，整个流程下来大约五分钟。没有重装opencode，没有升级系统，问题解决。
5. 这类"内置二进制"依赖，还有哪些暗雷值得防
5.1 不止opencode，很多工具都栽在glibc版本上
这次事故让我想到一个更普遍的规律：凡是自带二进制的跨平台工具，在老旧Linux系统上都有可能遇到glibc版本兼容问题。这不是opencode独有的坑。
类似的例子在Node生态里非常常见：
- esbuild，安装时下载的平台二进制，在glibc版本过低的系统上直接报
Cannot find module或段错误； - sharp，图像处理库，自带libvips二进制，同样有glibc版本要求；
- sqlite3、bcrypt这种原生模块，编译时绑定的libstdc++版本对不上，启动即崩溃。
它们的共同点都是：为了让用户免安装、跨平台，选择了"自带二进制"这条路，但二进制和系统的glibc版本之间的脆弱的兼容关系，成了最容易被忽略的一环。
5.2 沉淀下来的排查三板斧
这次排查如果用一句话总结，就是：不要信表面的报错，先确认实际执行的是哪个二进制，再查它的动态库依赖。我把这套方法沉淀成了三板斧，所有类似问题都可以套用：
第一步，确认实际问题范围。开debug，看日志，记录报错上下文，区分是"找不到文件"还是"程序起不来"。
第二步，确认真正被执行的二进制。用strace或which、type确认命令实际指向的路径，不要把系统里能跑的同名命令当成实际执行的那一个。
第三步，用ldd检查动态库依赖。ldd <二进制>和readelf -V <二进制>可以快速看出glibc符号版本要求，对比本机版本就能定位兼容性问题。
# 查看动态库依赖 ldd /path/to/binary # 查看要求的glibc版本符号 objdump -T /path/to/binary | grep GLIBC_2.38 # 查看本机glibc版本 ldd --version | head -1如果一个工具报错让你摸不着头脑，先跑这三步，八成能定位到根因。
5.3 一个值得养成的习惯：升级前先看glibc版本
自从这次事故后，我在部署任何自带二进制的工具时，都会先看一眼目标机器的glibc版本，再决定用哪个版本的工具。尤其是那些跟进最新版的朋友，工具新版本很可能在老系统上跑不起来。
ldd --version | head -1如果你的系统glibc版本低于工具要求的版本，优先选择工具的历史版本或者等官方提供静态构建版本，别硬着头皮升级，也别指望每个工具都会做兼容性检测。
说回opencode本身，这次事故暴露出来的其实是它在错误处理上的短板：技能索引失败时，如果能给出"rg不可用"的明确提示，而不是静默返回空列表，排查成本会低很多。希望后续版本能补上这个降级逻辑。但作为用户，在官方修复之前，掌握"手动替换rg"和"检查glibc版本"这两个手段，基本就能覆盖这类问题了。
