[OpenClaw 4.5 notifyActiveTaskWaiters TypeError 导致 Discord 网关崩溃] - OpenClaw 4.5 notifyActiveTaskWaiters TypeError crashes Discord gateway

主要表现

Discord 网关在接收任何传入消息时崩溃，并抛出 TypeError。机器人完全无响应，未发送任何回复。

错误输出

TypeError: undefined is not iterable (cannot read property 'length' of undefined)
  at notifyActiveTaskWaiters (command-queue.ts)
  → Gateway handler crashes before any reply can be sent
  → All Discord messages silently dropped

行为症状

• 机器人成功接受 WebSocket 连接
• 日志中未显示已接收消息的确认信息
• Discord 中显示机器人未响应用户消息
• 网关连接保持活跃但处于空闲状态
• 其他插件功能可能受影响，取决于命令队列的使用情况

环境

• OpenClaw 版本： 2026.4.5
• Node.js： v22.22.1
• 操作系统： Linux (Ubuntu)
• 渠道： Discord

直接原因

command-queue.ts 中的 notifyActiveTaskWaiters 函数接收到一个 undefined 值，而它期望的是一个可迭代数组。该函数尝试访问此值的 .length 属性或对其进行迭代，但没有保护子句，从而触发了 TypeError。

故障序列

1. 用户向 Discord 机器人发送消息
2. 网关通过 WebSocket 接收消息负载
3. 网关处理器调用 notifyActiveTaskWaiters
4. notifyActiveTaskWaiters 接收到 undefined 而不是数组
5. 内部迭代或长度检查在 undefined 上失败
6. TypeError 沿调用栈向上传播
7. 网关处理器崩溃，未处理消息

配置问题的影响因素

在诊断过程中，发现了使问题恶化的次要配置问题：

• 配置嵌套错误： 配置在自身内部嵌套/重复，包含格式错误的 "cha" 键，表明 config.yml 已损坏
• 遗留键未移除： channels.discord.guilds.<id>.channels.<id>.allow 在 OpenClaw 4.5 中已移除，但仍存在于配置中
• 缺少插件声明： discord 和 anthropic 插件未在 plugins.allow 中声明
• 过时的插件引用： browser 在 plugins.allow 中存在，但该插件已在先前版本中移除

架构上下文

命令队列系统管理网关和插件执行之间的异步任务协调。在 4.5 版本中，代码变更引入了一个对数组的依赖，该数组在某些配置状态下可能并不总是被填充，特别是当插件声明不完整或遗留键与新架构冲突时。

临时解决方案：回滚（建议用于生产环境）

如果需要立即恢复 Discord 功能：

# Roll back to last known stable version
npm install [email protected]

# Restart the gateway
openclaw restart

永久修复：配置修复

执行内置的诊断和修复工具：

openclaw doctor --fix

此命令自动处理：

• 损坏或嵌套的配置结构
• 4.5 版本中移除的遗留键
• 缺少的插件声明
• 过时的插件引用

手动配置修复（如果 doctor 失败）

步骤 1：备份当前配置

cp config.yml config.yml.backup-$(date +%Y%m%d)

步骤 2：移除遗留的频道允许键

找到并移除所有以下实例：

channels:
  discord:
    guilds:
      <guild-id>:
        channels:
          <channel-id>:
            allow: [...]  # REMOVE THIS KEY COMPLETELY

步骤 3：修复 plugins.allow 部分

将您的 plugins.allow 块替换为正确的插件列表：

# Before (broken)
plugins:
  allow:
    - browser  # STALE - remove this
    # Missing: discord, anthropic

# After (correct)
plugins:
  allow:
    - discord
    - anthropic
    # Add other active plugins as needed

步骤 4：验证配置结构

openclaw config validate

步骤 5：重启网关

openclaw restart

**修复后：验证插件声明

openclaw plugins list --enabled

确认 discord 出现在已启用插件列表中。

**步骤 1：确认配置有效性

openclaw config validate

预期输出：

✓ Configuration schema validated
✓ No legacy keys detected
✓ Plugin declarations complete

**步骤 2：运行诊断工具

openclaw doctor

预期输出（无错误）：

Checking configuration... OK
Checking plugin declarations... OK
Checking Discord gateway connectivity... OK
No issues found.

**步骤 3：验证网关连接

openclaw status --channel discord

预期输出：

Discord Gateway: CONNECTED
Bot User: <your-bot-name>
Latency: <value>ms

**步骤 4：功能测试

向 Discord 中的机器人发送测试消息。验证：

• 消息被接收并记录在网关输出中
• 机器人在预期延迟内响应
• 网关日志中未出现 TypeError

**步骤 5：检查日志中的错误

openclaw logs --tail 100 --level error

预期结果：无 TypeError: undefined is not iterable 条目。

**步骤 6：验证命令队列稳定性

发送多条快速消息以确认命令队列处理并发请求：

# Send 5 messages in rapid succession
for i in {1..5}; do
  echo "Test message $i" | openclaw send --channel test-channel
done

所有消息应被处理而不会崩溃。

配置损坏

• 重复/嵌套配置： 手动编辑 config.yml 可能引入嵌套副本。始终使用 openclaw config set 进行程序化更新。
• YAML 缩进： 错误的缩进会破坏解析。使用空格（而非制表符）进行缩进。
• 特殊字符： 未加引号的字符串包含 :, #, {, } 可能导致解析错误。

插件管理

• 插件未在允许列表中： 即使已安装，插件也不会加载，除非在 plugins.allow 中明确列出。
• 已移除的插件： 在先前版本中移除的插件（如 browser）可能残留在配置中并导致验证失败。
• 顺序敏感性： 某些插件具有依赖关系。确保依赖插件在其依赖项之后声明。

版本特定陷阱

• 跳过版本： 从 4.3 直接升级到 4.5 可能遗漏迁移步骤。对于复杂的版本跳跃，使用顺序升级。
• 锁定文件漂移： package-lock.json 可能缓存损坏的版本。在重新安装前删除锁定文件。

环境特定问题

• Docker： 确保卷挂载在容器重启之间保持配置持久化。检查 openclaw doctor --fix 是否写入正确的挂载卷。
• pm2/systemd： 服务管理器可能缓存旧的进程状态。重启服务，而不仅仅是进程。
• Windows： 换行符差异（\r\n vs \n）可能损坏 YAML。确保 config.yml 中的换行符一致。

迁移注意事项

• 频道允许键： 4.5 版本移除了按频道的允许规则。在升级前将任何现有规则迁移到新的权限系统。
• 插件配置键： 某些插件特定键已重命名。查看 4.5 变更日志以了解已弃用的键映射。