April 22, 2026 • 版本: 2026.4.14

Telegram群组斜杠命令升级后失效 - Telegram Group Slash Commands Stop Working After OpenClaw 2026.4.12 → 2026.4.14 Upgrade

回归问题导致OpenClaw版本升级后，特定机器人账户在群聊中的Telegram斜杠命令选择器和手动命令失效，而健康检查仍报告正常。

🔍 症状

主要表现

在从 2026.4.12 升级到 2026.4.14 后观察到以下症状：

斜杠命令选择器故障： 在 Telegram 群组中输入 / 不再在原生命令自动补全 UI 中显示 Morty (@RickS_C137_bot)。
手动命令失败： 发送 /status@RickS_C137_bot 作为独立消息不会产生任何响应。
单个勾选标记： 发送的命令消息只显示一个 Telegram 勾选标记（消息已传送到服务器），而不是两个勾选标记（消息已传送到用户），表明命令未被处理。

诊断命令输出示例

# 健康检查仍报告正常，尽管斜杠命令已损坏
$ openclawctl status telegram --account morty
Channel: telegram
Account: morty (@RickS_C137_bot)
Status: HEALTHY
Last ping: 2026-04-15T10:23:45Z
Commands registered: true

# 但群组中不显示斜杠命令
# (预期：命令选择器显示 /status、/help 等)
# (实际：自动补全为空或选择器中无 Morty)

# 群聊中的手动命令测试
$ /status@RickS_C137_bot
# (预期：机器人响应状态信息)
# (实际：单个勾选标记，无响应)

# 2026.4.14 的调试日志摘录
[2026-04-15T10:24:01.123] DEBUG [telegram] Received update 123456789: {message: {...}, entities: [{type: "bot_command", ...}]}
[2026-04-15T10:24:01.124] WARN  [commands] Command "/status" not routed - no matching target for group context

环境上下文

主机平台： Raspberry Pi 5
频道： Telegram
受影响的账户： morty (@RickS_C137_bot)
聊天类型： Telegram 群组 (Dev Team)
正常工作的版本： 2026.4.12
出现问题的版本： 2026.4.14
对照机器人： 另一个运行 2026.4.5 的机器人继续正常工作

🧠 根因分析

技术分析

此回归问题源于 OpenClaw 在版本 2026.4.12 到 2026.4.14 之间如何解析 Telegram 群组上下文中命令目标的变化。

故障序列

命令注册阶段 (setMyCommands)： 机器人成功使用 setMyCommands 向 Telegram Bot API 注册了命令。这就是为什么健康检查报告"Commands registered: true"以及为什么运行 2026.4.5 的另一个机器人继续工作——命令注册未受影响。

命令路由阶段 (传入更新)： 当在群聊中收到斜杠命令时，Telegram Update 负载包含：

{
  "message": {
    "chat": {"id": -123456789, "type": "group"},
    "text": "/status@RickS_C137_bot",
    "entities": [{"type": "bot_command", "offset": 0, "length": 21}]
  }
}

目标解析失败： 回归问题在 src/channels/telegram/command-routing.ts 中引入了一个逻辑变更，该变更改变了当消息源自群聊时如何验证机器人提及 (@RickS_C137_bot) 与配置账户的匹配方式。
静默丢弃： 目标解析失败的命令被静默丢弃，而不是返回错误响应，导致单勾选标记症状（消息已传送但未处理）。

架构不一致

2026.4.14 中的变更修改了群组上下文的命令目标解析，使用了更严格的匹配算法：

// 2026.4.12 (正常工作)
function resolveCommandTarget(update, accounts) {
  if (update.message.chat.type === 'group') {
    // 接受带有有效机器人提及的命令
    return accounts.find(a => a.username === extractMention(update.message.text));
  }
  // ... 单聊后备方案
}

// 2026.4.14 (已损坏)
function resolveCommandTarget(update, accounts) {
  if (update.message.chat.type === 'group') {
    // 已损坏：除提及外还要求绑定匹配
    const binding = resolveGroupBinding(update.message.chat.id);
    const mentionedAccount = accounts.find(a => a.username === extractMention(update.message.text));
    if (binding && binding.account !== mentionedAccount?.name) {
      return null; // 静默丢弃 - 根本原因
    }
    return mentionedAccount;
  }
}

这个额外的绑定检查在以下情况下错误地过滤掉了有效命令：

群组有主绑定（例如，绑定到不同的账户）
用户发送明确提及 @RickS_C137_bot 的命令
被提及的账户 (morty) 不是绑定的默认账户

命令应该被路由到 morty，因为提及明确指定了该机器人，无论群组绑定如何。

🛠️ 逐步修复

选项 A：回滚（立即缓解）

如果需要立即恢复服务：

# 回滚到 2026.4.12
$ openclawctl downgrade --version 2026.4.12
Downgrading from 2026.4.14 to 2026.4.12...
Stopping OpenClaw service...
Rolling back binary...
Restoring configuration from backup...
Starting OpenClaw service...
Rollback complete.

$ openclawctl status
OpenClaw v2026.4.12
Status: RUNNING
All channels: HEALTHY

选项 B：应用补丁（修复可用时）

一旦后续版本中修复了回归问题（例如 2026.4.15+）：

# 升级到已修复版本
$ openclawctl upgrade --version latest
Upgrading to OpenClaw v2026.4.15 (contains fix for #XXXX)...
Downloading package...
Verifying checksum...
Stopping service...
Installing new binary...
Starting service...
Upgrade complete.

# 验证修复
$ openclawctl status | grep version
OpenClaw v2026.4.15

选项 C：通过配置解决（临时方案）

在等待补丁时，修改群组绑定配置以包含受影响的账户：

注意： 这是一个临时解决方案，如果多个机器人应该在同一个群组中响应，可能会产生意想不到的副作用。

# 之前 (2026.4.14 配置) - 导致回归问题
channels:
  telegram:
    accounts:
      morty:
        apiToken: "${MORTY_TOKEN}"
        username: "RickS_C137_bot"
    bindings:
      - groupId: -123456789
        account: morty  # 只有 morty 被绑定，其他提及被丢弃

# 之后 (临时方案) - 允许群组中的所有账户
channels:
  telegram:
    accounts:
      morty:
        apiToken: "${MORTY_TOKEN}"
        username: "RickS_C137_bot"
    bindings:
      - groupId: -123456789
        account: "*"  # 通配符允许任何被提及的账户

选项 D：显式命令白名单（替代临时方案）

如果通配符绑定不可取，确保显式白名单包含群组上下文：

# 2026.4.14 的增强配置
channels:
  telegram:
    accounts:
      morty:
        apiToken: "${MORTY_TOKEN}"
        username: "RickS_C137_bot"

commands:
  native: "auto"
  nativeSkills: "auto"
  allowFrom:
    telegram:
      - group: -123456789  # 显式群组 ID
        accounts:
          - morty
          - "*"  # 或其他应该响应的账户

🧪 验证

验证步骤

应用修复（回滚、升级或配置更改）后，使用以下序列验证修复：

步骤 1：服务健康检查

$ openclawctl status
OpenClaw v2026.4.15
Status: RUNNING
Channels:
  telegram:morty: HEALTHY

步骤 2：命令注册验证

$ openclawctl telegram commands list --account morty
Bot: @RickS_C137_bot
Registered commands:
  - /status
  - /help
  - /settings
  - /skills
Registration status: ACTIVE

步骤 3：群聊中的斜杠命令选择器测试

在 Telegram 群组 (Dev Team) 中：

# 1. 清除与机器人的任何现有对话
# 2. 导航到群聊
# 3. 输入 "/" - 您应该在自动补全中看到 @RickS_C137_bot
# 4. 选择 "/status" - 它应该出现在输入字段中

预期结果： 命令选择器显示 /status@RickS_C137_bot、/help@RickS_C137_bot 等。

步骤 4：手动命令测试

# 在群聊中发送：
/status@RickS_C137_bot

# 预期响应：机器人回复状态信息
# 预期标记：两个勾选标记（消息已读）

步骤 5：调试日志验证

$ openclawctl logs --follow --filter telegram | grep -i command
[2026-04-15T10:30:01.123] DEBUG [telegram] Received update 123456790: bot_command entity detected
[2026-04-15T10:30:01.124] DEBUG [telegram] Resolved target account: morty
[2026-04-15T10:30:01.125] DEBUG [commands] Routing "/status" to skill: status
[2026-04-15T10:30:01.200] INFO  [commands] Command executed successfully: /status (took 75ms)

步骤 6：回归确认测试

# 使用机器人提及进行测试（这在 2026.4.14 中已损坏）
/hello@RickS_C137_bot
# 预期：机器人响应（不是单勾选标记丢弃）

# 不使用提及进行测试（应该仍然有效）
/hello
# 预期：路由到群组绑定的账户

成功标准

以下所有条件必须通过，修复才能被视为已验证：

openclawctl status 显示 Status: RUNNING 且所有频道 HEALTHY
在群组中输入 / 时，Telegram 斜杠命令选择器显示机器人的命令
/status@RickS_C137_bot 返回响应并显示两个勾选标记
调试日志显示显式提及的命令 Resolved target account: morty

⚠️ 常见陷阱

环境特定的陷阱

Raspberry Pi 5 特定问题： ARM64 二进制文件可能有缓存问题。在回滚或升级后，重启前清除二进制缓存：sudo rm -rf /var/cache/openclaw/binaries/*。
Docker 部署： 如果在 Docker 中运行，确保在版本更改后重新创建容器（不仅仅是重启）：
```
$ docker-compose down
$ docker-compose pull openclaw:2026.4.15
$ docker-compose up -d
```
多账户 Telegram 设置： 在绑定中使用 account: "*" 的临时方案可能导致多个机器人响应同一命令（如果群组中有多个机器人）。

配置错误

群组 ID 格式不正确： Telegram 群组 ID 必须使用负数格式（例如 -123456789），而不是聊天用户名或正数。
白名单与黑名单混淆： commands.allowFrom.telegram 部分使用白名单模型。如果账户未列出，来自该来源的命令将被静默丢弃。

环境变量未重新加载： 配置更改后，确保正确加载环境变量：

$ openclawctl config reload Configuration reloaded from /etc/openclaw/config.yaml 验证受影响的账户可见

$ openclawctl telegram accounts list

边缘情况

超级群组与普通群组： 超级群组在迁移后可能有不同的群组 ID 格式。使用群组中的 @userinfobot 或 @JSONDumpBot 验证正确的 ID。
群组创建后添加的机器人： 如果机器人在初始设置后被添加到群组，Telegram 可能需要将机器人重新添加到群组的管理员列表中，以便命令可见性正常工作。
机器人隐私模式： 尽管问题报告者确认隐私模式已禁用，但请在 BotFather 中使用 /mybots → 选择机器人 → → 机器人设置 → 群组隐私 → 关闭进行验证。

命令范围： Telegram 命令有范围设置。确保命令使用 ScopeType.DEFAULT 注册（而不是 ScopeType.PRIVATE）：

# 通过 BotFather 验证
/mybots > @RickS_C137_bot > Edit Bot > Edit Commands
# 所有命令应全局显示，不限于私聊

诊断错误

误解单勾选标记： 单个勾选标记可能表示：
1. 命令被静默丢弃（回归症状）
2. 消息传递的网络问题
3. 用户屏蔽了机器人
使用调试日志区分这些情况。
混淆健康检查与命令功能： 健康检查验证机器人可以发送传出消息和接收更新。它们不验证命令路由。请务必使用实际斜杠命令进行测试。

🔗 相关错误

直接相关的问题

"机器人在群组中不显示命令自动补全"(Telegram Bot API) - 与 setMyCommands 范围设置和隐私模式相关。表现为命令在私聊中可见但不在群组选择器中。
"多账户设置中命令被静默丢弃" - 配置多个 Telegram 账户时命令目标解析的历史问题。之前的 2026.4.8 修复可能已被部分回退。

症状相似但原因不同

E_TELEGRAM_COMMAND_NO_TARGET - 当没有账户匹配机器人提及时引发。表示配置问题而非回归问题。
E_TELEGRAM_BOT_NOT_IN_GROUP - 机器人必须是群组成员命令才能工作。通过 BotFather 中的 /mybots 检查。
E_TELEGRAM_PRIVACY_MODE_ENABLED（非阻塞警告） - 隐私模式限制机器人接收哪些消息。禁用可恢复群组消息访问。
E_COMMAND_ROUTING_GROUP_CONTEXT - 群组绑定解析失败时的内部错误。检查绑定配置。
E_TELEGRAM_API_ERROR 400: Bad Request: chat not found - 通常表示配置中的群组 ID 格式不正确。

版本历史上下文

2026.4.5 - 对照机器人的已知良好版本。比较基线。
2026.4.8 - 多账户命令路由的先前修复。回归问题可能部分撤销了此修复。
2026.4.12 - 最后已知正常工作版本。回归问题在 2026.4.14 中引入。
2026.4.14 - 受影响的版本。包含群组上下文命令目标解析中的回归问题。