【OpenClaw 故障排查完全指南】
OpenClaw 故障排查完全指南
版本: OpenClaw 2026.2.26
适用平台: Windows / Linux / macOS
整理时间: 2026-03-04
目录
常见问题速查
飞书插件连接失败
Ollama 认证错误
配置警告与敏感信息
端口占用与进程冲突
插件重复加载问题
快速修复脚本
1. 常见问题速查
遇到问题先别急，对照下表，通常能立刻找到症结所在。这张表汇总了近期最高频的几个故障，帮你快速定位。
| 错误现象 | 根本原因 | 快速解决 |
|---|---|---|
createFixedWindowRateLimiter is not a function |
飞书插件 SDK 版本不兼容 | 删除插件重装 |
disconnected (1006): no reason |
飞书插件加载失败 | 修复插件后重启 |
OLLAMA_API_KEY required |
Ollama 需要占位符认证 | 设置环境变量 |
duplicate plugin id detected |
插件重复安装 | 清理重复目录 |
Port 18789 is already in use |
僵尸进程占用端口 | 杀死进程重启 |
Config warnings: possibly sensitive key |
配置扫描警告 | 正常现象，可忽略 |
2. 飞书插件连接失败
2.1 症状表现
这个问题算是近期的“头号通缉犯”，表现相当典型：
- 频道状态直接“摆烂”：显示
Running: No,Configured: No,Connected: n/a。 - 右上角无情提示：
disconnected (1006): no reason。 - 日志里会抛出关键错误：
TypeError: (0 , _pluginSdk.createFixedWindowRateLimiter) is not a function。
如果你看到了这一连串的组合拳，那基本就没跑了。
2.2 根本原因
问题出在版本迭代的“衔接空档”。OpenClaw 在 2026.2.26 版本中更新了插件 SDK，移除了 createFixedWindowRateLimiter 这个函数。但当前版本的飞书插件还没来得及适配，依然在调用这个已经不存在的旧接口，结果就是插件一加载就崩掉，连接自然就失败了。说白了，就是个典型的API不兼容事故。
2.3 解决方案
应对方法很清晰，核心就是解决这个版本冲突。给你两个方案，推荐优先尝试A方案，更精准快捷。
方案 A：删除冲突插件（推荐）
这个方案直击要害，只清理有问题的飞书插件，不影响其他功能。跟着下面这四条PowerShell命令走一遍：
# 1. 停止服务
openclaw gateway stop
# 2. 删除所有飞书插件目录（确保清理干净）
Remove-Item -Recurse -Force "C:\Users\dell\AppData\Roaming\npm\node_modules\openclaw\extensions\feishu" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "C:\Users\dell\.openclaw\extensions\feishu" -ErrorAction SilentlyContinue
# 3. 清理可能残留的僵尸进程（这步很重要）
Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.Path -like "*openclaw*"} | Stop-Process -Force -ErrorAction SilentlyContinue
# 4. 重新启动服务，系统会自动拉取正确的插件版本
openclaw gateway start
方案 B：完全重装 OpenClaw
如果方案A不奏效，或者你倾向于来一次“彻底的大扫除”，那就用这个核弹级方案。它会将OpenClaw连带所有配置、缓存、插件全部清空重装。
# 1. 完全卸载全局包
npm uninstall -g openclaw
# 2. 手动清理用户目录下的残留配置和缓存（关键步骤）
Remove-Item -Recurse -Force "C:\Users\dell\.openclaw" -ErrorAction SilentlyContinue
# 3. 重新安装最新版本
npm install -g openclaw@latest
# 4. 像第一次使用一样，重新走一遍配置向导
openclaw onboard
话说回来，多数情况下，方案A足以解决问题。执行完毕后，记得去频道状态页刷新一下，应该就能看到“Connected: Yes”的快乐提示了。