PicoClaw 接入 TelegramBot 长轮询、多媒体消息与 MarkdownV2 格式化完全指南【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawTelegram 是 PicoClaw 最常用的即时通讯渠道之一本文以仓库文档 docs/channels/telegram/README.fr.md 为主线系统讲解如何通过 Bot API 长轮询把 Telegram 变成 AI 助手的对话入口从创建 Bot、填写配置、白名单控制到语音转写、MarkdownV2 高级格式化再到源码级的多媒体发送与消息拆分原理。读完本文你将能够在本地完整跑通 Telegram 渠道并理解其底层实现的关键设计。一、Telegram 渠道能力总览PicoClaw 的 Telegram 渠道基于Bot API 长轮询long polling实现无需公网 IP、无需 Webhook 回调配置适合部署在个人电脑、开发板或内网环境中。官方文档明确列出其支持的能力文本消息收发多媒体附件照片、语音消息、音频、文档语音消息通过Groq Whisper进行转写内置命令commands管理与注册。从源码结构看渠道的核心实现在 pkg/channels/telegram/telegram.go约 1800 行并配套了init.go的工厂注册、Markdown/HTML 转换器以及完整的单元测试。渠道启动流程在Start()中通过bot.UpdatesViaLongPolling(ctx, telego.GetUpdatesParams{Timeout: 30})发起长轮询telegram.go随后把收到的消息交给消息处理器bh.HandleMessage(func(ctx *th.Context, message telego.Message) error { return c.handleMessage(ctx, message) }, th.AnyMessage())init.gopkg/channels/telegram/init.go则把config.ChannelTelegram类型注册到渠道工厂PicoClaw 启动时会根据配置中的type: telegram自动实例化该渠道。二、快速开始配置与首次启动1. 创建 Bot 并获取 Token按照官方文档的操作步骤在 Telegram 中搜索BotFather发送/newbot命令按提示输入 Bot 名称与用户名创建一个新 BotBotFather 会返回HTTP API Token形如123456789:ABCdefGHIjklMNOpqrsTUVwxyz把 Token 填入 PicoClaw 的配置文件可选配置allow_from白名单限制可交互的用户 ID——自己的用户 ID 可通过userinfobot查询。2. 配置文件示例官方文档给出的 Telegram 渠道配置如下{ channel_list: { telegram: { enabled: true, type: telegram, token: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz, allow_from: [123456789], proxy: , use_markdown_v2: false } } }需要注意这是文档为讲解参数而采用的简化扁平写法。以当前仓库 config/config.example.json 为准渠道级字段enabled、type、allow_from、reasoning_channel_id等与settings内的渠道专属参数是分开的实际推荐写法如下{ channel_list: { telegram: { enabled: true, type: telegram, allow_from: [YOUR_USER_ID], reasoning_channel_id: , settings: { token: YOUR_TELEGRAM_BOT_TOKEN, base_url: , proxy: , use_markdown_v2: false, streaming: { enabled: true } } } } }3. 参数说明表结合文档参数表与 config.go 中TelegramSettings结构体的字段定义整理如下字段类型必填说明enabledbool是是否启用 Telegram 渠道typestring是固定为telegram用于渠道工厂分发tokenstring是Telegram Bot API Token源码中使用SecureString类型存储config.goallow_fromarray否用户 ID 白名单留空表示允许所有用户proxystring否访问 Telegram API 的代理 URL例如http://127.0.0.1:7890use_markdown_v2bool否是否启用 Telegram MarkdownV2 格式化默认false使用 HTML 模式base_urlstring否自定义 API 服务器地址源码字段可用于接入 Bot API 反代或本地网关media_group_delay_msint否入站媒体组相册合并等待毫秒数默认 500mstelegram.gostreamingobject否流式输出开关示例中为{ enabled: true }除 JSON 配置外TelegramSettings的所有字段都定义了环境变量映射适合容器化或密钥注入场景config.goPICOCLAW_CHANNELS_TELEGRAM_TOKENPICOCLAW_CHANNELS_TELEGRAM_BASE_URLPICOCLAW_CHANNELS_TELEGRAM_PROXYPICOCLAW_CHANNELS_TELEGRAM_USE_MARKDOWN_V2PICOCLAW_CHANNELS_TELEGRAM_MEDIA_GROUP_DELAY_MS4. 启动验证完成配置后启动 PicoClaw日志中会出现Starting Telegram bot (polling mode)...与Telegram bot connected并附上 Bot 用户名telegram.go。此时向 Bot 私聊发送任意文本即可触发对话。三、访问控制allow_from 白名单与群组行为allow_from是渠道级的安全边界。留空数组表示放行所有用户填入 ID 后只有列表内的用户可以触发对话。在源码中每条入站消息在handleMessages()里都会先经过白名单校验校验通过后才下载附件避免为被拒绝的用户产生不必要的下载流量// check allowlist to avoid downloading attachments for rejected users if !c.IsAllowedSender(sender) { logger.DebugCF(telegram, Message rejected by allowlist, ...) return nil }见 telegram.go对于群组场景PicoClaw 引入了统一的群组触发过滤机制group_trigger支持仅 机器人时回复等策略在论坛群Forum中还会把话题 ID 编码进 ChatIDchatID/threadID使每个话题拥有独立会话telegram.go。这些行为由渠道基类channels.BaseChannel统一承载Telegram 渠道通过WithGroupTrigger(bc.GroupTrigger)接入telegram.go。四、代理与网络连通Telegram API 在部分地区不可直连因此proxy是高频配置项。源码中NewTelegramChannel对代理的处理分为两级telegram.go若配置了proxy解析 URL 并构造带http.ProxyURL的http.Transport若未配置proxy但进程环境变量中存在HTTP_PROXY/HTTPS_PROXY则自动使用http.ProxyFromEnvironment走系统代理。此外若设置base_url会通过telego.WithAPIServer(baseURL)覆盖默认的https://api.telegram.org端点telegram.go适用于自建 Bot API 服务或企业内网网关。五、进阶格式化MarkdownV21. 开启方式在配置中设置use_markdown_v2: true即可启用 Telegram 的 MarkdownV2 增强格式化能力。官方文档说明开启后 Bot 可以使用 Telegram MarkdownV2 的全部特性包括嵌套样式nested styles、spoiler||text||、自定义等宽代码块等{ channel_list: { telegram: { enabled: true, type: telegram, token: YOUR_BOT_TOKEN, allow_from: [YOUR_USER_ID], use_markdown_v2: true } } }2. 转换器源码原理MarkdownV2 对特殊字符转义极其严格_ * [ ] ( ) ~ \ # - | { } . ! 共 20 个字符需要转义直接把 LLM 输出的 Markdown 原文发给 Telegram 极易解析失败。PicoClaw 因此在 parse_markdown_to_md_v2.go 中实现了专门的转换器规则如下Markdown 标题#到######转换为*加粗文本*parse_markdown_to_md_v2.go**bold**语法转换为 Telegram 的*bold*按优先级识别实体围栏代码块、行内代码、引用块、自定义 emoji、链接、spoiler||、下划线__、粗体、斜体、删除线parse_markdown_to_md_v2.go代码块、链接、引用等verbatimEntities内部内容原样透传绝不改写其余纯文本段落的特殊字符逐一转义。3. 与默认 HTML 模式的分工发送时parseContent(text, useMarkdownV2)会根据开关选择 MarkdownV2 转换器或 HTML 转换器telegram.go。未开启时使用ModeHTML开启后使用ModeMarkdownV2。两层转换都有对应的测试文件parse_markdown_to_md_v2_test.go与parser_markdown_to_html_test.go位于 pkg/channels/telegram其中md2_all_formats.txt测试数据覆盖了全部格式组合。值得强调的是无论哪种模式sendChunk都内置了解析失败回退机制若 Telegram 返回解析错误会以纯文本方式重发原始内容保证用户永远不会看到裸露的 HTML/MarkdownV2 标签telegram.go。六、语音转写Groq Whisper 流水线文档提到渠道支持通过 Groq Whisper 的语音转写。这条链路横跨渠道层与 Agent 层下载收到语音消息Voice后渠道通过GetFile获取文件并下载为.oggtelegram.go音频则下载为.mp3入库下载文件通过 media store 注册并打上CleanupPolicyDeleteOnCleanup清理策略转写Agent 在transcribeAudioInMessage()中识别出[voice]注解调用al.transcriber.Transcribe()成功后把注解替换为[voice: 转写文本]pkg/agent/agent_transcribe.go转写服务NewGroqTranscriber(apiKey, modelID)指向 Groq 的 OpenAI 兼容端点https://api.groq.com/openai/v1转录路径为/audio/transcriptionspkg/audio/asr/whisper_transcriber.go。转写结果还会通过echo_transcription配置回显给用户形成完整的语音对话体验。七、发送链路的工程细节源码级Telegram 渠道不止收发文本其发送管线针对 Telegram 平台的约束做了大量工程化处理1. 消息长度与分块。渠道创建时通过WithMaxMessageLength(4000)限定单条消息上限telegram.go而 Telegram API 的硬限制是 4096 字符。由于 HTML 标签会放大字符串长度Send()在超限时会按比例估算安全长度用channels.SplitMessage寻找换行/空格等自然断点切分并保证代码块不被拦腰截断telegram.go。2. 多媒体发送。SendMedia()支持按类型分发照片走SendPhoto、语音 OGG 走SendVoice、音频走SendAudio、视频走SendVideo、其余类型走SendDocumenttelegram.go。其中两个细节值得注意文件名含voice且为.ogg/.oga的音频会自动用语音气泡SendVoice发送照片因尺寸问题报PHOTO_INVALID_DIMENSIONS时会自动回退为文档发送。3. 媒体组相册合并。多条图片消息会被打包成 Telegram 媒体组发送每组最多 10 张telegram.go入站侧则通过media_group_delay_ms默认 500ms缓冲同一MediaGroupID的图片避免相册被拆成多条独立消息处理telegram.go。4. 交互体验。渠道实现了TypingCapable接口通过SendChatAction(ChatActionTyping)每 4 秒发送一次正在输入状态Telegram 的 typing 指示约 5 秒过期并设有 5 分钟上限防止 LLM 卡死时无限运行telegram.go工具调用过程中的反馈动画与思考中…占位消息分别通过EditMessage、SendPlaceholder实现最终答案会原地编辑替换占位消息避免消息刷屏。5. 命令注册。启动时渠道会自动调用SetMyCommands注册内置命令列表并按指数退避策略重试确保命令菜单在 Bot 客户端可见pkg/channels/telegram/command_registration.go。八、验证与排障仓库为 Telegram 渠道提供了完整的测试覆盖可作为行为验证与二次开发的参考pkg/channels/telegram/telegram_test.go——渠道核心行为pkg/channels/telegram/telegram_dispatch_test.go——消息分发与上下文路由pkg/channels/telegram/telegram_group_command_filter_test.go——群组命令过滤pkg/channels/telegram/parse_markdown_to_md_v2_test.go 与 pkg/channels/telegram/parser_markdown_to_html_test.go——两种格式化模式的转换正确性。常见排障方向Bot 无响应检查token是否正确、进程能否连通api.telegram.org必要时配置proxyMarkdownV2 发送失败确认use_markdown_v2打开后 LLM 输出是否包含未转义的特殊字符——若仍有问题可关闭该开关退回 HTML 模式发送链路的纯文本回退会兜底语音不转写确认已配置 Whisper 兼容的语音模型与 API Key且voice相关配置已开启转写实现见 pkg/audio/asr/whisper_transcriber.go。更进一步完整的渠道配置总览可参考 docs/guides/configuration.zh.md其他聊天渠道的接入方式见 docs/guides/chat-apps.zh.mdTelegram 渠道的原文说明见 docs/channels/telegram/README.fr.md。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PicoClaw 接入 Telegram：Bot 长轮询、多媒体消息与 MarkdownV2 格式化完全指南
PicoClaw 接入 TelegramBot 长轮询、多媒体消息与 MarkdownV2 格式化完全指南【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawTelegram 是 PicoClaw 最常用的即时通讯渠道之一本文以仓库文档 docs/channels/telegram/README.fr.md 为主线系统讲解如何通过 Bot API 长轮询把 Telegram 变成 AI 助手的对话入口从创建 Bot、填写配置、白名单控制到语音转写、MarkdownV2 高级格式化再到源码级的多媒体发送与消息拆分原理。读完本文你将能够在本地完整跑通 Telegram 渠道并理解其底层实现的关键设计。一、Telegram 渠道能力总览PicoClaw 的 Telegram 渠道基于Bot API 长轮询long polling实现无需公网 IP、无需 Webhook 回调配置适合部署在个人电脑、开发板或内网环境中。官方文档明确列出其支持的能力文本消息收发多媒体附件照片、语音消息、音频、文档语音消息通过Groq Whisper进行转写内置命令commands管理与注册。从源码结构看渠道的核心实现在 pkg/channels/telegram/telegram.go约 1800 行并配套了init.go的工厂注册、Markdown/HTML 转换器以及完整的单元测试。渠道启动流程在Start()中通过bot.UpdatesViaLongPolling(ctx, telego.GetUpdatesParams{Timeout: 30})发起长轮询telegram.go随后把收到的消息交给消息处理器bh.HandleMessage(func(ctx *th.Context, message telego.Message) error { return c.handleMessage(ctx, message) }, th.AnyMessage())init.gopkg/channels/telegram/init.go则把config.ChannelTelegram类型注册到渠道工厂PicoClaw 启动时会根据配置中的type: telegram自动实例化该渠道。二、快速开始配置与首次启动1. 创建 Bot 并获取 Token按照官方文档的操作步骤在 Telegram 中搜索BotFather发送/newbot命令按提示输入 Bot 名称与用户名创建一个新 BotBotFather 会返回HTTP API Token形如123456789:ABCdefGHIjklMNOpqrsTUVwxyz把 Token 填入 PicoClaw 的配置文件可选配置allow_from白名单限制可交互的用户 ID——自己的用户 ID 可通过userinfobot查询。2. 配置文件示例官方文档给出的 Telegram 渠道配置如下{ channel_list: { telegram: { enabled: true, type: telegram, token: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz, allow_from: [123456789], proxy: , use_markdown_v2: false } } }需要注意这是文档为讲解参数而采用的简化扁平写法。以当前仓库 config/config.example.json 为准渠道级字段enabled、type、allow_from、reasoning_channel_id等与settings内的渠道专属参数是分开的实际推荐写法如下{ channel_list: { telegram: { enabled: true, type: telegram, allow_from: [YOUR_USER_ID], reasoning_channel_id: , settings: { token: YOUR_TELEGRAM_BOT_TOKEN, base_url: , proxy: , use_markdown_v2: false, streaming: { enabled: true } } } } }3. 参数说明表结合文档参数表与 config.go 中TelegramSettings结构体的字段定义整理如下字段类型必填说明enabledbool是是否启用 Telegram 渠道typestring是固定为telegram用于渠道工厂分发tokenstring是Telegram Bot API Token源码中使用SecureString类型存储config.goallow_fromarray否用户 ID 白名单留空表示允许所有用户proxystring否访问 Telegram API 的代理 URL例如http://127.0.0.1:7890use_markdown_v2bool否是否启用 Telegram MarkdownV2 格式化默认false使用 HTML 模式base_urlstring否自定义 API 服务器地址源码字段可用于接入 Bot API 反代或本地网关media_group_delay_msint否入站媒体组相册合并等待毫秒数默认 500mstelegram.gostreamingobject否流式输出开关示例中为{ enabled: true }除 JSON 配置外TelegramSettings的所有字段都定义了环境变量映射适合容器化或密钥注入场景config.goPICOCLAW_CHANNELS_TELEGRAM_TOKENPICOCLAW_CHANNELS_TELEGRAM_BASE_URLPICOCLAW_CHANNELS_TELEGRAM_PROXYPICOCLAW_CHANNELS_TELEGRAM_USE_MARKDOWN_V2PICOCLAW_CHANNELS_TELEGRAM_MEDIA_GROUP_DELAY_MS4. 启动验证完成配置后启动 PicoClaw日志中会出现Starting Telegram bot (polling mode)...与Telegram bot connected并附上 Bot 用户名telegram.go。此时向 Bot 私聊发送任意文本即可触发对话。三、访问控制allow_from 白名单与群组行为allow_from是渠道级的安全边界。留空数组表示放行所有用户填入 ID 后只有列表内的用户可以触发对话。在源码中每条入站消息在handleMessages()里都会先经过白名单校验校验通过后才下载附件避免为被拒绝的用户产生不必要的下载流量// check allowlist to avoid downloading attachments for rejected users if !c.IsAllowedSender(sender) { logger.DebugCF(telegram, Message rejected by allowlist, ...) return nil }见 telegram.go对于群组场景PicoClaw 引入了统一的群组触发过滤机制group_trigger支持仅 机器人时回复等策略在论坛群Forum中还会把话题 ID 编码进 ChatIDchatID/threadID使每个话题拥有独立会话telegram.go。这些行为由渠道基类channels.BaseChannel统一承载Telegram 渠道通过WithGroupTrigger(bc.GroupTrigger)接入telegram.go。四、代理与网络连通Telegram API 在部分地区不可直连因此proxy是高频配置项。源码中NewTelegramChannel对代理的处理分为两级telegram.go若配置了proxy解析 URL 并构造带http.ProxyURL的http.Transport若未配置proxy但进程环境变量中存在HTTP_PROXY/HTTPS_PROXY则自动使用http.ProxyFromEnvironment走系统代理。此外若设置base_url会通过telego.WithAPIServer(baseURL)覆盖默认的https://api.telegram.org端点telegram.go适用于自建 Bot API 服务或企业内网网关。五、进阶格式化MarkdownV21. 开启方式在配置中设置use_markdown_v2: true即可启用 Telegram 的 MarkdownV2 增强格式化能力。官方文档说明开启后 Bot 可以使用 Telegram MarkdownV2 的全部特性包括嵌套样式nested styles、spoiler||text||、自定义等宽代码块等{ channel_list: { telegram: { enabled: true, type: telegram, token: YOUR_BOT_TOKEN, allow_from: [YOUR_USER_ID], use_markdown_v2: true } } }2. 转换器源码原理MarkdownV2 对特殊字符转义极其严格_ * [ ] ( ) ~ \ # - | { } . ! 共 20 个字符需要转义直接把 LLM 输出的 Markdown 原文发给 Telegram 极易解析失败。PicoClaw 因此在 parse_markdown_to_md_v2.go 中实现了专门的转换器规则如下Markdown 标题#到######转换为*加粗文本*parse_markdown_to_md_v2.go**bold**语法转换为 Telegram 的*bold*按优先级识别实体围栏代码块、行内代码、引用块、自定义 emoji、链接、spoiler||、下划线__、粗体、斜体、删除线parse_markdown_to_md_v2.go代码块、链接、引用等verbatimEntities内部内容原样透传绝不改写其余纯文本段落的特殊字符逐一转义。3. 与默认 HTML 模式的分工发送时parseContent(text, useMarkdownV2)会根据开关选择 MarkdownV2 转换器或 HTML 转换器telegram.go。未开启时使用ModeHTML开启后使用ModeMarkdownV2。两层转换都有对应的测试文件parse_markdown_to_md_v2_test.go与parser_markdown_to_html_test.go位于 pkg/channels/telegram其中md2_all_formats.txt测试数据覆盖了全部格式组合。值得强调的是无论哪种模式sendChunk都内置了解析失败回退机制若 Telegram 返回解析错误会以纯文本方式重发原始内容保证用户永远不会看到裸露的 HTML/MarkdownV2 标签telegram.go。六、语音转写Groq Whisper 流水线文档提到渠道支持通过 Groq Whisper 的语音转写。这条链路横跨渠道层与 Agent 层下载收到语音消息Voice后渠道通过GetFile获取文件并下载为.oggtelegram.go音频则下载为.mp3入库下载文件通过 media store 注册并打上CleanupPolicyDeleteOnCleanup清理策略转写Agent 在transcribeAudioInMessage()中识别出[voice]注解调用al.transcriber.Transcribe()成功后把注解替换为[voice: 转写文本]pkg/agent/agent_transcribe.go转写服务NewGroqTranscriber(apiKey, modelID)指向 Groq 的 OpenAI 兼容端点https://api.groq.com/openai/v1转录路径为/audio/transcriptionspkg/audio/asr/whisper_transcriber.go。转写结果还会通过echo_transcription配置回显给用户形成完整的语音对话体验。七、发送链路的工程细节源码级Telegram 渠道不止收发文本其发送管线针对 Telegram 平台的约束做了大量工程化处理1. 消息长度与分块。渠道创建时通过WithMaxMessageLength(4000)限定单条消息上限telegram.go而 Telegram API 的硬限制是 4096 字符。由于 HTML 标签会放大字符串长度Send()在超限时会按比例估算安全长度用channels.SplitMessage寻找换行/空格等自然断点切分并保证代码块不被拦腰截断telegram.go。2. 多媒体发送。SendMedia()支持按类型分发照片走SendPhoto、语音 OGG 走SendVoice、音频走SendAudio、视频走SendVideo、其余类型走SendDocumenttelegram.go。其中两个细节值得注意文件名含voice且为.ogg/.oga的音频会自动用语音气泡SendVoice发送照片因尺寸问题报PHOTO_INVALID_DIMENSIONS时会自动回退为文档发送。3. 媒体组相册合并。多条图片消息会被打包成 Telegram 媒体组发送每组最多 10 张telegram.go入站侧则通过media_group_delay_ms默认 500ms缓冲同一MediaGroupID的图片避免相册被拆成多条独立消息处理telegram.go。4. 交互体验。渠道实现了TypingCapable接口通过SendChatAction(ChatActionTyping)每 4 秒发送一次正在输入状态Telegram 的 typing 指示约 5 秒过期并设有 5 分钟上限防止 LLM 卡死时无限运行telegram.go工具调用过程中的反馈动画与思考中…占位消息分别通过EditMessage、SendPlaceholder实现最终答案会原地编辑替换占位消息避免消息刷屏。5. 命令注册。启动时渠道会自动调用SetMyCommands注册内置命令列表并按指数退避策略重试确保命令菜单在 Bot 客户端可见pkg/channels/telegram/command_registration.go。八、验证与排障仓库为 Telegram 渠道提供了完整的测试覆盖可作为行为验证与二次开发的参考pkg/channels/telegram/telegram_test.go——渠道核心行为pkg/channels/telegram/telegram_dispatch_test.go——消息分发与上下文路由pkg/channels/telegram/telegram_group_command_filter_test.go——群组命令过滤pkg/channels/telegram/parse_markdown_to_md_v2_test.go 与 pkg/channels/telegram/parser_markdown_to_html_test.go——两种格式化模式的转换正确性。常见排障方向Bot 无响应检查token是否正确、进程能否连通api.telegram.org必要时配置proxyMarkdownV2 发送失败确认use_markdown_v2打开后 LLM 输出是否包含未转义的特殊字符——若仍有问题可关闭该开关退回 HTML 模式发送链路的纯文本回退会兜底语音不转写确认已配置 Whisper 兼容的语音模型与 API Key且voice相关配置已开启转写实现见 pkg/audio/asr/whisper_transcriber.go。更进一步完整的渠道配置总览可参考 docs/guides/configuration.zh.md其他聊天渠道的接入方式见 docs/guides/chat-apps.zh.mdTelegram 渠道的原文说明见 docs/channels/telegram/README.fr.md。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考