Qwen Code Telegram 频道接入实战从 Bot 创建到多模态消息处理的完整指南【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本指南以 Qwen Code 的 Telegram 频道适配器为核心完整讲解如何在 Telegram 上接入一个由 Qwen Code 驱动的 AI 编程 Agent从 BotFather 创建机器人、获取用户 ID到在~/.qwen/settings.json中配置频道参数再到群聊、图片/文件消息、消息格式化与故障排查。文中所有配置项、命令与行为均结合仓库内 Telegram 适配器源码 与 channels 总览文档 进行深度印证读完即可独立完成一个可运行的 Telegram 编程助手。为什么选择 Telegram 作为 Qwen Code 的远程入口Qwen Code 是一个运行在终端中的开源 AI 编程 Agent见仓库根目录 README.md。默认情况下你只能在本地终端与它交互而 Channels 机制让它可以住进即时通讯软件——你从手机或桌面聊天软件发消息Agent 就像在 CLI 中一样完成代码阅读、搜索、文件读写等任务并把结果发回聊天窗口。Telegram 是官方内置频道之一另有微信、QQ、钉钉、WeCom、飞书、GitHub 等见 channels 目录。它具备几个突出优势Bot API 开放且成熟通过 grammy 库实现官方 Bot API 无需额外鉴权服务器媒体处理原生支持照片、文档、语音消息均可直接下载处理见下文图片与文件章节主动推送能力适配器实现了supportsProactiveSend()返回true见 TelegramAdapter.ts因此支持定时 Channel Loop 与后台任务结果主动投递。前置准备开始前你需要一个 Telegram 账号一个 Telegram Bot Token获取方式见下节。创建 BotBotFather 流程在 Telegram 中搜索BotFather发送/newbot按提示为机器人选择显示名称和用户名BotFather 会返回一个形如1234567890:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx的 token请妥善保存它等同于机器人的密码泄露后任何人即可操控你的机器人。创建完成后建议在 BotFather 里用/mybots→ 你的机器人 →Edit Bot关闭不必要的权限并为群聊场景关闭隐私模式见下文群聊章节。获取你的 Telegram 用户 ID配置senderPolicy: allowlist白名单或pairing配对时需要用到你的用户 ID——注意这是数字 ID不是用户名。最简单的获取方式在 Telegram 中搜索userinfobot给它发送任意消息它会立即回复包含你数字 ID 的信息。群聊的 chat ID 获取方式不同群 ID 是负数如-5170296765。详见下文群聊章节的专门说明。配置文件settings.json 全参数解析频道统一配置在~/.qwen/settings.json的channels键下。Telegram 频道的最小可用配置如下{ channels: { my-telegram: { type: telegram, token: $TELEGRAM_BOT_TOKEN, senderPolicy: allowlist, allowedUsers: [YOUR_USER_ID], sessionScope: user, cwd: /path/to/your/project, instructions: You are a concise coding assistant responding via Telegram. Keep responses short., groupPolicy: disabled, groups: { *: { requireMention: true } } } } }核心配置项详解配置项是否必填说明type是固定为telegram。适配器通过 plugin 注册表 的channelType: telegram识别token是TelegramBot Token支持$ENV_VAR语法从环境变量读取model否指定该频道使用的模型如qwen3.5-plus覆盖默认模型。多模态模型才能处理图片输入senderPolicy否谁能与机器人对话allowlist默认、open、pairingallowedUsers否允许使用机器人的用户 ID 列表allowlist与pairing策略使用sessionScope否会话作用域user默认、chat_thread、singlecwd否Agent 的工作目录默认为当前目录approvalMode否频道会话的工具审批模式无人值守 webhook 任务要求yoloinstructions否注入到每个会话首条消息的系统指令groupPolicy否群聊访问策略disabled默认、allowlist、pairing、opendmPolicy否私聊访问open默认或disabled静默丢弃所有私聊适用于群聊专用机器人groups否按群 ID 的逐群设置键为群 chat ID 或*默认值以上参数表完整覆盖并扩充自 channels 总览文档。三种 Sender Policy 的差异allowlist默认只有allowedUsers中列出的用户能发消息其余用户被静默忽略——最安全pairing未知发送者会收到一个 8 位配对码由你在 CLI 审批后加入持久化白名单allowedUsers中的用户直接跳过配对。详见下文DM 配对open任何人可发消息谨慎使用。Session Scope 的会话隔离语义user默认每个用户一个会话同一用户的所有消息共享同一段对话chat_thread每个聊天线程/主题一个会话由该线程参与者共享single全频道共享一个会话所有人共享同一段对话。建议个人使用user配合/clear随时开启全新对话。Token 安全不要明文写进配置文件Bot Token 不应直接写在settings.json里应使用环境变量引用{ token: $TELEGRAM_BOT_TOKEN }然后在 shell 中导出或写入启动前被 source 的.env文件export TELEGRAM_BOT_TOKENyour-token-from-botfather源码层面适配器通过new Bot(this.config.token, ...)构造 grammy Bot 实例见 TelegramAdapter.tstoken 仅保存在内存中。启动频道# 只启动 Telegram 频道 qwen channel start my-telegram # 或一次性启动所有已配置频道 qwen channel start启动后打开你的机器人发送一条消息应当立刻看到Working...提示随后收到 Agent 的回复。运行机制单 Agent 进程 多频道根据 channels 总览文档qwen channel start会从settings.json读取频道配置通过 Agent Client Protocol (ACP) 派生一个共享的 Agent 进程连接各消息平台开始监听将入站消息路由给 Agent并把响应发回正确的聊天。所有频道共享一个 Agent 进程但会话按用户隔离每个频道可有自己独立的cwd、模型和指令。服务管理命令# 查看服务是否运行、运行时长与各频道会话数 qwen channel status # 从另一个终端优雅停止服务 qwen channel stop频道服务使用 PID 文件~/.qwen/channels/service.pid跟踪运行实例重复启动会报错而非拉起第二个实例。若 Agent 进程意外崩溃服务会在 3 秒内自动重启并恢复活动会话连续崩溃 3 次后退出会话数据持久化在~/.qwen/channels/sessions.json而优雅关闭CtrlC 或qwen channel stop会清空会话数据下次启动总是全新状态。守护进程托管模式可选实验性的 daemon 托管模式可通过qwen serve运行# 在 daemon 生命周期下启动一个频道 qwen serve --channel my-telegram # 启动所有已配置频道 qwen serve --channel all该模式下频道工作进程由qwen serve归属管理适配器崩溃不会拖垮 daemon 本体。注意qwen serve --channel与qwen channel start是两个不同的服务前者要求每个频道的cwd解析到 daemon 已注册的工作区。详见 overview 的 Daemon-Managed 模式。群聊配置默认机器人只响应私聊groupPolicy: disabled。要在 Telegram 群组中使用机器人将groupPolicy设置为allowlist、pairing或open在 BotFather 中关闭隐私模式/mybots→ 选择机器人 → Bot Settings → Group Privacy →Turn Off。不关闭的话机器人看不到群里的非命令消息将机器人加入群组。如果它已经在群里必须先移除再重新添加——Telegram 会缓存机器人加入时的隐私设置若使用groupPolicy: allowlist需要把群的 chat ID 加入groups配置若使用groupPolicy: pairing需在 CLI 批准一次群的配对请求。注意群一旦被批准群内任何成员都可以使用机器人senderPolicy与allowedUsers不再对已批准群的成员生效。四种 Group Policydisabled默认忽略所有群消息最安全allowlist只在groups中显式列出的群内响应。注意*键只提供默认设置并不等于通配放行pairing陌生群内有人刻意 或回复机器人时为整个群创建一次配对请求批准后所有成员都可在该群使用机器人senderPolicy继续约束私聊open在所有加入的群内响应谨慎使用。Mention 门控避免机器人刷屏默认情况下群内机器人只响应提及它或回复它消息的发言。可按群覆盖{ groups: { *: { requireMention: true }, -100123456: { requireMention: false } } }*所有群的默认设置仅设默认值不是白名单条目群 chat ID针对特定群的覆盖优先于*requireMention默认truefalse时机器人响应群内所有消息适合专用任务群。查找群 chat ID若机器人正在运行先停止它在群里发一条 机器人 的消息用 Telegram Bot API 查询排队的更新curl -s https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates | python3 -m json.tool在响应中查找message.chat.id——群 ID 是负数例如-5170296765与用户的正数 ID 区分开。群消息的评估顺序源码与文档确认一条群消息依次经过如下门控详见 overview1. groupPolicy — 该群是被禁用、列出、配对还是开放(否 → 忽略/进入配对流程) 2. dmPolicy — 这条私聊是否允许(disabled → 忽略) 3. requireMention — 是否 了机器人或回复了它(否 → 忽略) 4. senderPolicy — 发送者是否被批准(已配对群跳过否则否 → 进入用户配对流程) 5. 路由到会话DM 配对Pairing流程当senderPolicy: pairing时未知用户需要经过审批未知用户给机器人发消息机器人回复一个 8 位配对码如VEQDDWXJ用户把配对码转告给你机器人运营者你在 CLI 批准qwen channel pairing approve my-channel VEQDDWXJ批准后该用户 ID 会保存到频道的工作区级白名单~/.qwen/channels/workspace-scope/name-allowlist.json后续消息正常通行。配对状态按工作区隔离两个工作区使用同名频道时审批互不影响。配对 CLI 命令# 列出待处理的配对请求 qwen channel pairing list my-channel # 按码批准请求 qwen channel pairing approve my-channel CODE请在频道的 workspace 目录下执行或传--cwd dir——配对状态按工作区存储。配对规则要点配对码为 8 位大写字符使用无歧义字母表不含0/O/1/I配对码 1 小时后过期每个频道最多 3 个待处理请求每个发送者最多 1 个——额外的请求会被拒绝直到有请求过期或被批准allowedUsers中列出的用户跳过用户配对但groupPolicy: pairing下群本身仍需批准已批准用户存储于~/.qwen/channels/workspace-scope/name-allowlist.json请将该文件视为敏感数据。图片与文件消息处理Telegram 频道不止支持文本。源码中适配器分别注册了message:text、message:photo、message:document、message:voice四类消息处理器见 TelegramAdapter.ts对应不同的处理链路。图片Photo发送照片后适配器会选取尺寸最大的照片msg.photo[msg.photo.length - 1]通过getFilehttps://api.telegram.org/file/bottoken/file_path下载将图片转为 base64 放入信封的imageBase64字段imageMimeType固定为image/jpegTelegram 始终将照片转为 JPEG见 源码注释图片作为视觉输入直接传给模型。要求分析图片需要多模态模型——在频道配置中加入{ channels: { my-telegram: { type: telegram, model: qwen3.5-plus, ...: ... } } }照片的说明文字caption会作为消息文本传给 Agent。文档/文件Document发送 PDF、代码文件或任意文档时适配器会下载文件字节流保存到临时目录os.tmpdir()/channel-files/uuid/下见 源码将本地文件路径放入envelope.attachmentsAgent 即可用文件读取工具读取内容。文件处理不需要多模态模型任何模型都支持。Telegram 的文件大小上限为20MB。语音消息Voice适配器同样处理message:voice语音被下载并保存为voice_timestamp.ogg临时文件以audio类型附件交给 Agent见 源码。下载失败的降级行为三类媒体消息都有完整的降级逻辑若下载失败适配器会把占位文案如(User sent an image but download failed)拼入消息文本保证 Agent 至少感知到用户发了文件但下载失败不会静默丢失消息见 源码。该行为同样有 测试覆盖。消息格式化Markdown 自动转 HTMLAgent 的 Markdown 回复会自动转换为 Telegram 兼容的 HTML——代码块、粗体、斜体、链接、列表均受支持。实现上适配器使用telegram-markdown-formatter包见 package.json 依赖将文本转换为 HTML并针对 Telegram 的4096 字符单条消息上限做了精细处理见 splitTelegramHtmlAtLimit超长 HTML 按 token 切分自动保持标签闭合先补闭合标签再重开标签保证每一段都是合法 HTML纯文本按字符边界切分并避免在代理对surrogate pair如 emoji中间截断若某段 HTML 发送失败自动降级为去标签的纯文本重发。这也是文档建议instructions 中加一句keep responses short的底层原因——短回复能减少被拆分的概率提升阅读体验。Typing 指示器源码还实现了正在输入状态任务开始后每 4 秒发送一次sendChatAction(typing)Telegram 的 typing 状态 5 秒过期见 源码注释多会话共享同一聊天时按会话计数全部结束后才停止——这就是你看到Working...提示的机制来源。相关行为在 TelegramAdapter.test.ts 中有完整单测覆盖含生命周期事件映射、多会话计数、disconnect 清理。实用建议指令保持简洁聚焦Telegram 单条消息 4096 字符限制。加上保持回复简短这类指令有助于 Agent 输出不超限使用sessionScope: user每个用户拥有独立对话需要重新开始时用/clear限制访问固定用户集用senderPolicy: allowlist允许新用户自助申请用pairing配合 CLI 审批利用/cancel与/statusTelegram 适配器注册了start/help/new/cancel/status五个机器人命令见 源码常量其中/cancel目前仅 Telegram 注册可用于中断正在运行的任务。故障排查机器人不响应检查 token 是否正确、环境变量是否已设置若使用senderPolicy: allowlist确认你的用户 ID 在allowedUsers中若使用pairing确认已批准查看终端输出中的错误信息。机器人在群里不响应确认groupPolicy已设为allowlist、pairing或open默认是disabled若使用allowlist确认群的 chat ID 已加入groups配置若使用pairing确认群的配对请求已批准确认 BotFather 中Group Privacy 已关闭——否则机器人看不到群里的非命令消息如果修改隐私模式前机器人已在群里请移除后重新添加默认要求 或回复。用yourbotname hello测试。提示 Sorry, something went wrong processing your message这通常意味着 Agent 内部出错。查看终端输出获取详情。源码层面该提示由 reportInboundError 生成错误会被写入 stderr并向用户回复这条兜底文案。机器人响应很慢Agent 可能正在执行多个工具调用读文件、搜索等。Working... 指示器在 Agent 处理期间持续显示复杂任务可能需要一分钟以上。若长期卡住可发送/cancel中断当前任务。进阶扩展方向本文聚焦 Telegram 频道的完整接入。若需要更深入的能力可在仓库中继续探索定时 Channel LoopTelegram 适配器支持主动投递supportsProactiveSend()为true可让 Agent 按 cron 表达式定时运行任务并推送结果回聊天命令为/loop add cron prompt、/loop list等多会话multiSession在sessionScope: user基础上开启multiSession: true可为同一用户在同一聊天中保留最多 8 个命名任务自定义频道插件Telegram 之外的平台可通过 Plugins 机制以扩展形式接入注册方式与 telegram 插件入口 一致。小结从创建 Bot、配置settings.json、启动频道到群聊门控、媒体消息与格式化细节本指南完整覆盖了 Qwen Code Telegram 频道的全部核心环节并逐项给出了 适配器源码 与 总览文档 中的依据。按上述步骤操作你即可拥有一个随时随地通过手机驱动的 AI 编程助手。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Qwen Code Telegram 频道接入实战：从 Bot 创建到多模态消息处理的完整指南
Qwen Code Telegram 频道接入实战从 Bot 创建到多模态消息处理的完整指南【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本指南以 Qwen Code 的 Telegram 频道适配器为核心完整讲解如何在 Telegram 上接入一个由 Qwen Code 驱动的 AI 编程 Agent从 BotFather 创建机器人、获取用户 ID到在~/.qwen/settings.json中配置频道参数再到群聊、图片/文件消息、消息格式化与故障排查。文中所有配置项、命令与行为均结合仓库内 Telegram 适配器源码 与 channels 总览文档 进行深度印证读完即可独立完成一个可运行的 Telegram 编程助手。为什么选择 Telegram 作为 Qwen Code 的远程入口Qwen Code 是一个运行在终端中的开源 AI 编程 Agent见仓库根目录 README.md。默认情况下你只能在本地终端与它交互而 Channels 机制让它可以住进即时通讯软件——你从手机或桌面聊天软件发消息Agent 就像在 CLI 中一样完成代码阅读、搜索、文件读写等任务并把结果发回聊天窗口。Telegram 是官方内置频道之一另有微信、QQ、钉钉、WeCom、飞书、GitHub 等见 channels 目录。它具备几个突出优势Bot API 开放且成熟通过 grammy 库实现官方 Bot API 无需额外鉴权服务器媒体处理原生支持照片、文档、语音消息均可直接下载处理见下文图片与文件章节主动推送能力适配器实现了supportsProactiveSend()返回true见 TelegramAdapter.ts因此支持定时 Channel Loop 与后台任务结果主动投递。前置准备开始前你需要一个 Telegram 账号一个 Telegram Bot Token获取方式见下节。创建 BotBotFather 流程在 Telegram 中搜索BotFather发送/newbot按提示为机器人选择显示名称和用户名BotFather 会返回一个形如1234567890:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx的 token请妥善保存它等同于机器人的密码泄露后任何人即可操控你的机器人。创建完成后建议在 BotFather 里用/mybots→ 你的机器人 →Edit Bot关闭不必要的权限并为群聊场景关闭隐私模式见下文群聊章节。获取你的 Telegram 用户 ID配置senderPolicy: allowlist白名单或pairing配对时需要用到你的用户 ID——注意这是数字 ID不是用户名。最简单的获取方式在 Telegram 中搜索userinfobot给它发送任意消息它会立即回复包含你数字 ID 的信息。群聊的 chat ID 获取方式不同群 ID 是负数如-5170296765。详见下文群聊章节的专门说明。配置文件settings.json 全参数解析频道统一配置在~/.qwen/settings.json的channels键下。Telegram 频道的最小可用配置如下{ channels: { my-telegram: { type: telegram, token: $TELEGRAM_BOT_TOKEN, senderPolicy: allowlist, allowedUsers: [YOUR_USER_ID], sessionScope: user, cwd: /path/to/your/project, instructions: You are a concise coding assistant responding via Telegram. Keep responses short., groupPolicy: disabled, groups: { *: { requireMention: true } } } } }核心配置项详解配置项是否必填说明type是固定为telegram。适配器通过 plugin 注册表 的channelType: telegram识别token是TelegramBot Token支持$ENV_VAR语法从环境变量读取model否指定该频道使用的模型如qwen3.5-plus覆盖默认模型。多模态模型才能处理图片输入senderPolicy否谁能与机器人对话allowlist默认、open、pairingallowedUsers否允许使用机器人的用户 ID 列表allowlist与pairing策略使用sessionScope否会话作用域user默认、chat_thread、singlecwd否Agent 的工作目录默认为当前目录approvalMode否频道会话的工具审批模式无人值守 webhook 任务要求yoloinstructions否注入到每个会话首条消息的系统指令groupPolicy否群聊访问策略disabled默认、allowlist、pairing、opendmPolicy否私聊访问open默认或disabled静默丢弃所有私聊适用于群聊专用机器人groups否按群 ID 的逐群设置键为群 chat ID 或*默认值以上参数表完整覆盖并扩充自 channels 总览文档。三种 Sender Policy 的差异allowlist默认只有allowedUsers中列出的用户能发消息其余用户被静默忽略——最安全pairing未知发送者会收到一个 8 位配对码由你在 CLI 审批后加入持久化白名单allowedUsers中的用户直接跳过配对。详见下文DM 配对open任何人可发消息谨慎使用。Session Scope 的会话隔离语义user默认每个用户一个会话同一用户的所有消息共享同一段对话chat_thread每个聊天线程/主题一个会话由该线程参与者共享single全频道共享一个会话所有人共享同一段对话。建议个人使用user配合/clear随时开启全新对话。Token 安全不要明文写进配置文件Bot Token 不应直接写在settings.json里应使用环境变量引用{ token: $TELEGRAM_BOT_TOKEN }然后在 shell 中导出或写入启动前被 source 的.env文件export TELEGRAM_BOT_TOKENyour-token-from-botfather源码层面适配器通过new Bot(this.config.token, ...)构造 grammy Bot 实例见 TelegramAdapter.tstoken 仅保存在内存中。启动频道# 只启动 Telegram 频道 qwen channel start my-telegram # 或一次性启动所有已配置频道 qwen channel start启动后打开你的机器人发送一条消息应当立刻看到Working...提示随后收到 Agent 的回复。运行机制单 Agent 进程 多频道根据 channels 总览文档qwen channel start会从settings.json读取频道配置通过 Agent Client Protocol (ACP) 派生一个共享的 Agent 进程连接各消息平台开始监听将入站消息路由给 Agent并把响应发回正确的聊天。所有频道共享一个 Agent 进程但会话按用户隔离每个频道可有自己独立的cwd、模型和指令。服务管理命令# 查看服务是否运行、运行时长与各频道会话数 qwen channel status # 从另一个终端优雅停止服务 qwen channel stop频道服务使用 PID 文件~/.qwen/channels/service.pid跟踪运行实例重复启动会报错而非拉起第二个实例。若 Agent 进程意外崩溃服务会在 3 秒内自动重启并恢复活动会话连续崩溃 3 次后退出会话数据持久化在~/.qwen/channels/sessions.json而优雅关闭CtrlC 或qwen channel stop会清空会话数据下次启动总是全新状态。守护进程托管模式可选实验性的 daemon 托管模式可通过qwen serve运行# 在 daemon 生命周期下启动一个频道 qwen serve --channel my-telegram # 启动所有已配置频道 qwen serve --channel all该模式下频道工作进程由qwen serve归属管理适配器崩溃不会拖垮 daemon 本体。注意qwen serve --channel与qwen channel start是两个不同的服务前者要求每个频道的cwd解析到 daemon 已注册的工作区。详见 overview 的 Daemon-Managed 模式。群聊配置默认机器人只响应私聊groupPolicy: disabled。要在 Telegram 群组中使用机器人将groupPolicy设置为allowlist、pairing或open在 BotFather 中关闭隐私模式/mybots→ 选择机器人 → Bot Settings → Group Privacy →Turn Off。不关闭的话机器人看不到群里的非命令消息将机器人加入群组。如果它已经在群里必须先移除再重新添加——Telegram 会缓存机器人加入时的隐私设置若使用groupPolicy: allowlist需要把群的 chat ID 加入groups配置若使用groupPolicy: pairing需在 CLI 批准一次群的配对请求。注意群一旦被批准群内任何成员都可以使用机器人senderPolicy与allowedUsers不再对已批准群的成员生效。四种 Group Policydisabled默认忽略所有群消息最安全allowlist只在groups中显式列出的群内响应。注意*键只提供默认设置并不等于通配放行pairing陌生群内有人刻意 或回复机器人时为整个群创建一次配对请求批准后所有成员都可在该群使用机器人senderPolicy继续约束私聊open在所有加入的群内响应谨慎使用。Mention 门控避免机器人刷屏默认情况下群内机器人只响应提及它或回复它消息的发言。可按群覆盖{ groups: { *: { requireMention: true }, -100123456: { requireMention: false } } }*所有群的默认设置仅设默认值不是白名单条目群 chat ID针对特定群的覆盖优先于*requireMention默认truefalse时机器人响应群内所有消息适合专用任务群。查找群 chat ID若机器人正在运行先停止它在群里发一条 机器人 的消息用 Telegram Bot API 查询排队的更新curl -s https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates | python3 -m json.tool在响应中查找message.chat.id——群 ID 是负数例如-5170296765与用户的正数 ID 区分开。群消息的评估顺序源码与文档确认一条群消息依次经过如下门控详见 overview1. groupPolicy — 该群是被禁用、列出、配对还是开放(否 → 忽略/进入配对流程) 2. dmPolicy — 这条私聊是否允许(disabled → 忽略) 3. requireMention — 是否 了机器人或回复了它(否 → 忽略) 4. senderPolicy — 发送者是否被批准(已配对群跳过否则否 → 进入用户配对流程) 5. 路由到会话DM 配对Pairing流程当senderPolicy: pairing时未知用户需要经过审批未知用户给机器人发消息机器人回复一个 8 位配对码如VEQDDWXJ用户把配对码转告给你机器人运营者你在 CLI 批准qwen channel pairing approve my-channel VEQDDWXJ批准后该用户 ID 会保存到频道的工作区级白名单~/.qwen/channels/workspace-scope/name-allowlist.json后续消息正常通行。配对状态按工作区隔离两个工作区使用同名频道时审批互不影响。配对 CLI 命令# 列出待处理的配对请求 qwen channel pairing list my-channel # 按码批准请求 qwen channel pairing approve my-channel CODE请在频道的 workspace 目录下执行或传--cwd dir——配对状态按工作区存储。配对规则要点配对码为 8 位大写字符使用无歧义字母表不含0/O/1/I配对码 1 小时后过期每个频道最多 3 个待处理请求每个发送者最多 1 个——额外的请求会被拒绝直到有请求过期或被批准allowedUsers中列出的用户跳过用户配对但groupPolicy: pairing下群本身仍需批准已批准用户存储于~/.qwen/channels/workspace-scope/name-allowlist.json请将该文件视为敏感数据。图片与文件消息处理Telegram 频道不止支持文本。源码中适配器分别注册了message:text、message:photo、message:document、message:voice四类消息处理器见 TelegramAdapter.ts对应不同的处理链路。图片Photo发送照片后适配器会选取尺寸最大的照片msg.photo[msg.photo.length - 1]通过getFilehttps://api.telegram.org/file/bottoken/file_path下载将图片转为 base64 放入信封的imageBase64字段imageMimeType固定为image/jpegTelegram 始终将照片转为 JPEG见 源码注释图片作为视觉输入直接传给模型。要求分析图片需要多模态模型——在频道配置中加入{ channels: { my-telegram: { type: telegram, model: qwen3.5-plus, ...: ... } } }照片的说明文字caption会作为消息文本传给 Agent。文档/文件Document发送 PDF、代码文件或任意文档时适配器会下载文件字节流保存到临时目录os.tmpdir()/channel-files/uuid/下见 源码将本地文件路径放入envelope.attachmentsAgent 即可用文件读取工具读取内容。文件处理不需要多模态模型任何模型都支持。Telegram 的文件大小上限为20MB。语音消息Voice适配器同样处理message:voice语音被下载并保存为voice_timestamp.ogg临时文件以audio类型附件交给 Agent见 源码。下载失败的降级行为三类媒体消息都有完整的降级逻辑若下载失败适配器会把占位文案如(User sent an image but download failed)拼入消息文本保证 Agent 至少感知到用户发了文件但下载失败不会静默丢失消息见 源码。该行为同样有 测试覆盖。消息格式化Markdown 自动转 HTMLAgent 的 Markdown 回复会自动转换为 Telegram 兼容的 HTML——代码块、粗体、斜体、链接、列表均受支持。实现上适配器使用telegram-markdown-formatter包见 package.json 依赖将文本转换为 HTML并针对 Telegram 的4096 字符单条消息上限做了精细处理见 splitTelegramHtmlAtLimit超长 HTML 按 token 切分自动保持标签闭合先补闭合标签再重开标签保证每一段都是合法 HTML纯文本按字符边界切分并避免在代理对surrogate pair如 emoji中间截断若某段 HTML 发送失败自动降级为去标签的纯文本重发。这也是文档建议instructions 中加一句keep responses short的底层原因——短回复能减少被拆分的概率提升阅读体验。Typing 指示器源码还实现了正在输入状态任务开始后每 4 秒发送一次sendChatAction(typing)Telegram 的 typing 状态 5 秒过期见 源码注释多会话共享同一聊天时按会话计数全部结束后才停止——这就是你看到Working...提示的机制来源。相关行为在 TelegramAdapter.test.ts 中有完整单测覆盖含生命周期事件映射、多会话计数、disconnect 清理。实用建议指令保持简洁聚焦Telegram 单条消息 4096 字符限制。加上保持回复简短这类指令有助于 Agent 输出不超限使用sessionScope: user每个用户拥有独立对话需要重新开始时用/clear限制访问固定用户集用senderPolicy: allowlist允许新用户自助申请用pairing配合 CLI 审批利用/cancel与/statusTelegram 适配器注册了start/help/new/cancel/status五个机器人命令见 源码常量其中/cancel目前仅 Telegram 注册可用于中断正在运行的任务。故障排查机器人不响应检查 token 是否正确、环境变量是否已设置若使用senderPolicy: allowlist确认你的用户 ID 在allowedUsers中若使用pairing确认已批准查看终端输出中的错误信息。机器人在群里不响应确认groupPolicy已设为allowlist、pairing或open默认是disabled若使用allowlist确认群的 chat ID 已加入groups配置若使用pairing确认群的配对请求已批准确认 BotFather 中Group Privacy 已关闭——否则机器人看不到群里的非命令消息如果修改隐私模式前机器人已在群里请移除后重新添加默认要求 或回复。用yourbotname hello测试。提示 Sorry, something went wrong processing your message这通常意味着 Agent 内部出错。查看终端输出获取详情。源码层面该提示由 reportInboundError 生成错误会被写入 stderr并向用户回复这条兜底文案。机器人响应很慢Agent 可能正在执行多个工具调用读文件、搜索等。Working... 指示器在 Agent 处理期间持续显示复杂任务可能需要一分钟以上。若长期卡住可发送/cancel中断当前任务。进阶扩展方向本文聚焦 Telegram 频道的完整接入。若需要更深入的能力可在仓库中继续探索定时 Channel LoopTelegram 适配器支持主动投递supportsProactiveSend()为true可让 Agent 按 cron 表达式定时运行任务并推送结果回聊天命令为/loop add cron prompt、/loop list等多会话multiSession在sessionScope: user基础上开启multiSession: true可为同一用户在同一聊天中保留最多 8 个命名任务自定义频道插件Telegram 之外的平台可通过 Plugins 机制以扩展形式接入注册方式与 telegram 插件入口 一致。小结从创建 Bot、配置settings.json、启动频道到群聊门控、媒体消息与格式化细节本指南完整覆盖了 Qwen Code Telegram 频道的全部核心环节并逐项给出了 适配器源码 与 总览文档 中的依据。按上述步骤操作你即可拥有一个随时随地通过手机驱动的 AI 编程助手。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考