最近在折腾 OpenClaw 时遇到了一个棘手的报错，折腾了两天才彻底解决。把整个排查和解决过程记录下来，希望能帮到遇到类似问题的同学。

一、问题现象

在 OpenClaw 运行过程中，日志里反复出现以下错误：

Error: Unable to resolve bundled plugin public surface speech-core/runtime-api.js

同时，网关虽然能启动，但 Agent 会话会失败，提示：

Agent failed before reply: Unable to resolve bundled plugin public surface speech-core/runtime-api.js

关键特征：我根本没有使用语音（speech）相关的功能，但这个错误却持续出现，导致网关无法正常提供服务。

二、初步排查

2.1 确认网关运行状态

首先用端口检查确认网关是否在运行：

netstat -ano | findstr :18789

结果发现网关进程确实存在，但日志中不断刷出上述错误。

2.2 尝试运行 doctor 工具

执行 OpenClaw 自带的诊断工具：

openclaw doctor --fix

结果却报了一个更严重的错误：

Error: Cannot find module 'C:\Users\Administrator\AppData\Roaming\npm\node_modules\openclaw\openclaw.mjs'

这说明核心文件已经丢失或损坏，speech-core/runtime-api.js 的报错只是表象，深层原因是安装损坏/版本错配。

三、根本原因分析

3.1 这个错误到底是什么？

根据 OpenClaw 的插件机制，speech-core 是一个内置插件（bundled plugin）。这类插件随 OpenClaw 主包一起分发，不需要单独安装。

runtime-api.js 是这个插件的运行时入口文件。当 OpenClaw 启动时，会尝试加载所有内置插件的运行时文件。如果文件缺失或路径不对，就会报 Unable to resolve 的错误。

3.2 为什么会发生？

结合搜索到的信息，主要有以下几种可能：

原因	说明
版本 bug	某些 Beta 版本（如 2026.5.12-beta.8）存在已知问题，内置插件加载路径出错
安装损坏	npm 全局安装过程中断或文件被误删，导致 dist/extensions/ 目录下部分文件缺失
版本错配	升级后新旧版本文件混用，导致路径解析失败

我的情况属于 核心文件丢失（openclaw.mjs 都找不到了），这比单纯的插件加载问题更严重。

四、解决方案

4.1 重装 OpenClaw（核心步骤）

既然核心文件丢失，最直接的办法就是完全卸载后重新安装：

# 1. 卸载全局包
npm uninstall -g openclaw

# 2. 清理 npm 缓存（可选）
npm cache clean --force

# 3. 重新安装
npm install -g openclaw

⚠️ 注意：卸载时如果遇到 EPERM 权限警告，通常是文件被占用（如杀毒软件或进程锁住），可以忽略，不影响卸载结果。

4.2 验证安装

openclaw --version

正常显示版本号即表示安装成功。

4.3 验证插件加载

重新安装后，检查插件是否正确加载：

openclaw plugins list --enabled --verbose

或者查看运行时注册状态：

openclaw plugins inspect speech-core --runtime --json

4.4 启动网关测试

openclaw gateway

观察日志中是否还有 speech-core/runtime-api.js 的错误。如果重装后问题依然存在，可以尝试：

1.降级到稳定版本（如果当前是 Beta 版）：

npm install -g openclaw@2026.4.29

2.运行 doctor 清理：

openclaw doctor --fix

doctor 可以隔离无效的插件配置，修复过时的插件状态。

五、经验总结

排查步骤	命令	目的
查看日志	openclaw logs --follow	获取详细错误信息
运行诊断	openclaw doctor --fix	自动修复常见配置问题
检查安装	openclaw --version	确认 CLI 可用
检查插件	openclaw plugins inspect <id> --runtime --json	验证插件是否加载
彻底重装	npm uninstall -g openclaw && npm install -g openclaw	解决文件损坏问题

核心教训：

1. speech-core/runtime-api.js 报错虽然看起来是语音插件的问题，但它只是一个症状，根本原因往往是整体安装损坏或版本错配。

2. 不要只盯着报错信息本身，先确认 CLI 本身是否正常工作。如果连 openclaw --version 都报错，那问题就不在插件层面了。

3. OpenClaw 的插件加载路径非常严格，任何文件缺失都可能导致级联失败。定期运行 openclaw doctor 可以防患于未然。

六、参考资料

• OpenClaw 官方文档 - 插件管理

• GitHub Issue #81819 - speech-core/runtime-api.js 报错

• GitHub Issue #76405 - Discord 插件文件缺失问题