正文

最近我在把 OpenClaw 更新到新版本后，遇到了一个非常典型但也很容易让人困惑的问题：更新前一切正常，更新后 Gateway 突然起不来了。

表面上看，系统像是“启动了又没启动”，openclaw doctor --fix 也会跑一遍流程，但最后还是提示 Gateway 不可用。折腾一圈之后，发现真正的根因并不在模型、权限或者网络，而是一个旧版本残留下来的 Feishu 插件路径配置。

这篇文章记录一下这个问题的现象、原因，以及最终是怎么修好的。希望能帮到同样在 Ubuntu/WSL 环境中使用 OpenClaw + 飞书的同学。

---

一、问题现象

升级 OpenClaw 之后，执行下面的命令：

openclaw doctor --fix

输出中会出现类似这样的信息：

Config invalid; doctor will run with best-effort config.
...
ERROR: plugin path not found:
/home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu
...
Gateway not running.
...
Invalid config:
- plugins.load.paths: plugin: plugin path not found: /home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu

这时候最容易误判成以下几类问题：

• 是不是飞书机器人配置坏了？
• 是不是 Gateway 服务挂了？
• 是不是模型配置失效了？
• 是不是新版本和旧环境不兼容？

但其实，上面这些都不是主因。

---

二、根因是什么

问题的根因很简单：

升级后的 OpenClaw 已经不再使用你之前手动指定的本地 Feishu 插件目录，但旧配置里还保留着这个路径。

例如，我当时配置文件里有这样一段：

"plugins": {
  "allow": ["feishu"],
  "load": {
    "paths": [
      "/home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu"
    ]
  },
  "entries": {
    "feishu": {
      "enabled": true
    }
  }
}

这里的关键问题在于：

"load": {
  "paths": [
    "/home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu"
  ]
}

新版本升级之后，这个目录已经不存在了，但 OpenClaw 仍然会尝试从这里加载插件。结果就是：

• 插件路径检查失败
• 配置被判定为 invalid
• Gateway 无法正常启动

所以本质上，这是一个旧插件路径残留导致的新版本启动失败问题。

---

三、为什么更新前没问题，更新后才出问题

因为旧版本里你可能是通过本地路径加载 Feishu 插件的，例如：

/home/xxx/.npm-global/lib/node_modules/openclaw/extensions/feishu

但新版本升级后，插件加载机制或者插件安装位置已经变化了。
结果就是：

• 旧路径还留在配置里
• 新版本启动时检查这个路径
• 路径找不到
• 整个配置失效

这类问题很常见，属于一种典型的：

“软件升级后，旧版本的本地路径配置失效，但配置文件没有自动清理。”

---

四、如何确认就是这个问题

最直接的方法就是执行：

openclaw doctor --fix

如果你看到类似下面这句，那基本就可以确定了：

Invalid config:
- plugins.load.paths: plugin path not found: /home/你的用户名/.npm-global/lib/node_modules/openclaw/extensions/feishu

这个报错比“Gateway not running”更关键。
因为 Gateway not running 只是结果，真正的原因是：

配置文件中的 plugins.load.paths 指向了一个不存在的 Feishu 插件目录。

---

五、修复方法

修复其实不复杂，核心思路就是：

删除旧的插件路径配置，只保留插件启用和允许列表。

第一步：备份配置文件

先备份一下当前配置，防止改错后不好回滚：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%F-%H%M%S)

---

第二步：打开配置文件

nano ~/.openclaw/openclaw.json

---

第三步：找到 plugins 配置块

如果你看到类似下面这样的内容：

"plugins": {
  "allow": ["feishu"],
  "load": {
    "paths": [
      "/home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu"
    ]
  },
  "entries": {
    "feishu": {
      "enabled": true
    }
  }
}

把中间这段 load.paths 删除掉：

"load": {
  "paths": [
    "/home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu"
  ]
},

修改后应变成：

"plugins": {
  "allow": ["feishu"],
  "entries": {
    "feishu": {
      "enabled": true
    }
  }
}

---

第四步：保存并退出

如果你用的是 nano，保存方式是：

Ctrl + O
Enter
Ctrl + X

---

第五步：重启 Gateway

openclaw gateway restart

然后检查状态：

openclaw gateway status

---

六、如果重启后还是不行怎么办

可以继续执行下面几个命令检查：

openclaw plugins list
openclaw logs --follow

如果 plugins list 里没有看到 feishu，可以再手动启用一次：

openclaw plugins enable feishu
openclaw gateway restart

---

七、哪些信息其实不是主因

在排查过程中，还会看到类似这样的提示：

Memory search is enabled, but no embedding provider is ready.

这条信息会让人以为是 embedding 或模型配置出了问题，但实际上：

它不是导致 Gateway 起不来的主因。

它只是说明：

• 你的 memory search 开着
• 但没有配置 embedding provider

这和本次“更新后无法启动”的问题无关。

真正的主因还是：

plugins.load.paths: plugin path not found

---

八、这次问题给我的经验

这次问题虽然不复杂，但很有代表性。它让我意识到一个现实：

1. 软件升级后，最容易出问题的不是主功能，而是“旧配置残留”

尤其是路径、插件、外部依赖这些东西，一旦升级策略变化，就很容易出问题。

2. 不要只盯着 “Gateway not running”

这个提示太表面了。真正有用的信息，通常藏在更早的报错里。

3. doctor 很重要，但要学会读它的输出

openclaw doctor --fix 确实会帮你发现问题，但它不会自动替你理解问题。
真正有价值的是那一句：

Invalid config:
- plugins.load.paths: plugin path not found

---

九、最终结论

如果你在 OpenClaw 更新后遇到：

• Feishu 之前能用，现在不能用
• doctor 说 Config invalid
• Gateway not running
• 日志里出现 plugin path not found

那么大概率不是飞书权限、不是模型、不是网络，而是：

旧版本遗留的 Feishu 本地插件路径失效了。

最直接的修复方法就是：

1. 打开 ~/.openclaw/openclaw.json
2. 删除 plugins.load.paths 中旧的 Feishu 路径
3. 保留 allow 和 entries.feishu.enabled
4. 重启 Gateway

修完之后，系统通常就能恢复正常。

---

十、附：修复后的推荐配置示例

"plugins": {
  "allow": ["feishu"],
  "entries": {
    "feishu": {
      "enabled": true
    }
  }
}

---