——
OpenClaw 新增 Telegram 媒体消息编辑功能：3 种 API 调用策略详解
一句话总结：OpenClaw 最新版本智能区分 Telegram 媒体消息的编辑类型，通过 editMessageCaption 和 editMessageReplyMarkup 替代单一的 editMessageText，彻底解决图文消息编辑失败的问题。
在开发 Telegram Bot 时，开发者经常遇到一个棘手问题：当用户尝试编辑一条包含图片、视频或文件的消息时，传统的 editMessageText API 会直接报错。OpenClaw 本次更新针对这一场景进行了深度优化，实现了媒体消息编辑的智能路由。
—
为什么需要专门的媒体消息编辑方案？
Telegram Bot API 对文本消息和媒体消息采用了不同的编辑接口：
| 消息类型 | 推荐 API | 常见错误 |
|———|———|———|
| 纯文本消息 | editMessageText | — |
| 带媒体的图文消息 | editMessageCaption | message is not modified |
| 仅修改按钮 | editMessageReplyMarkup | 媒体内容被意外覆盖 |
OpenClaw 作为开源的 AI Agent 框架，此前在遇到媒体消息编辑时统一调用 editMessageText，导致 Telegram 返回错误提示消息无可编辑文本。本次更新彻底重构了这一逻辑。
—
核心实现：三层智能路由策略
1. 纯按钮编辑 → editMessageReplyMarkup
当用户仅修改消息下方的 Inline Keyboard（内联按钮）时，系统直接调用 editMessageReplyMarkup，避免触碰媒体内容：
// 仅更新回复标记，保留原有媒体和标题
await telegramBot.editMessageReplyMarkup({
chat_id: chatId,
message_id: messageId,
reply_markup: newInlineKeyboard
});
2. 标题/说明文字编辑 → editMessageCaption
针对图片、视频、文件等媒体的 caption（说明文字）编辑，使用专用接口：
// 更新媒体消息的说明文字
await telegramBot.editMessageCaption({
chat_id: chatId,
message_id: messageId,
caption: "新的说明文字",
parse_mode: "MarkdownV2"
});
3. 智能降级：文本编辑失败时回退到标题编辑
当系统尝试编辑文本但 Telegram 返回”消息无可编辑文本”时，自动降级为标题编辑模式：
// 伪代码：OpenClaw 内部路由逻辑
async function editMessage(messageId, newContent) {
try {
// 优先尝试文本编辑
return await editMessageText(messageId, newContent);
} catch (error) {
// 检测特定错误码，回退到 caption 编辑
if (error.error_code === 400 &&
error.description.includes("message is not modified")) {
return await editMessageCaption(messageId, newContent);
}
throw error;
}
}
—
开发者如何启用新功能？
环境要求
- OpenClaw ≥ 最新 commit
0f1767a - Node.js ≥ 18.x
- 有效的 Telegram Bot Token
配置示例
克隆最新代码
git clone https://github.com/openclaw/openclaw.git
cd openclaw
安装依赖
npm install
配置环境变量
export TELEGRAM_BOT_TOKEN="your-bot-token"
export OPENCLAW_TELEGRAM_EDIT_ROUTING="smart" # 启用智能路由
代码集成
import { TelegramAgent } from 'openclaw';
const agent = new TelegramAgent({
token: process.env.TELEGRAM_BOT_TOKEN,
// 新配置项：媒体消息编辑策略
mediaEditStrategy: 'auto', // 'auto' | 'caption' | 'text'
});
// 发送带按钮的图片消息
const sentMessage = await agent.sendPhoto({
chat_id: userId,
photo: 'https://example.com/image.jpg',
caption: '原始标题',
reply_markup: {
inline_keyboard: [[
{ text: '按钮1', callback_data: 'btn1' }
]]
}
});
// 编辑标题（自动路由到 editMessageCaption）
await agent.editMessage({
message_id: sentMessage.message_id,
caption: '更新后的标题'
});
// 仅编辑按钮（自动路由到 editMessageReplyMarkup）
await agent.editMessage({
message_id: sentMessage.message_id,
reply_markup: {
inline_keyboard: [[
{ text: '新按钮', callback_data: 'btn2' }
]]
}
});
—
测试与回归覆盖
本次更新包含完整的测试套件，验证三种编辑场景：
运行 Telegram 模块的编辑功能测试
npm test -- --grep "telegram.edit.media"
预期输出：
✓ 纯文本编辑调用 editMessageText
✓ 媒体标题编辑调用 editMessageCaption
✓ 按钮编辑调用 editMessageReplyMarkup
✓ 文本编辑失败时回退到 caption 编辑
—
常见问题 (FAQ)
Q1: 旧版本 OpenClaw 会遇到什么问题？
当尝试编辑媒体消息的标题时，旧版本会调用 editMessageText，Telegram 返回 400 Bad Request: message is not modified: specified new message content and reply markup are exactly the same as a current content and reply markup of the message，导致编辑失败。
Q2: 如何确认我的 Bot 已启用新功能？
检查 OpenClaw 版本 commit hash：
git log --oneline -1
应显示 0f1767a 或更新
或在代码中验证：
console.log(agent.features.mediaMessageEdit); // 应输出 true
Q3: 可以强制使用特定的编辑 API 吗？
可以。通过 mediaEditStrategy 配置项：
'auto'（默认）：智能路由'caption'：强制使用editMessageCaption'text'：强制使用editMessageText
Q4: 这个更新会影响现有消息的发送吗？
不会。本次更新仅影响编辑操作（editMessage* 系列 API），消息发送逻辑保持不变。
Q5: 如果 Telegram 未来更新 API，OpenClaw 如何适配？
OpenClaw 采用策略模式封装 API 调用，新增适配器即可支持变更。关注 OpenClaw GitHub 获取更新通知。
—
总结与下一步
本次更新解决了 Telegram 媒体消息编辑的长期痛点，通过三层智能路由策略，确保：
1. 按钮编辑不触碰媒体内容
2. 标题编辑使用正确的 API
3. 异常场景自动降级处理
建议操作：
- 升级至最新 commit 验证功能
- 检查现有 Bot 的媒体消息编辑场景
- 参考 OpenClaw 文档 了解完整配置选项
—
相关阅读
—
参考来源
- GitHub Commit: 0f1767a – support media message edits
- Telegram Bot API – editMessageCaption
- Telegram Bot API – editMessageReplyMarkup
- 阅读原文：OpenClaw 教学小站
“`