Telegram 账号代理使用指南

Telegram 账号代理为你本人拥有的个人 Telegram 账号提供独立、常驻的 MCP 与 REST 接口。每个实例只服务一个账号；容器内不含 AI，登录会话保存在该实例的独立持久卷中。

这不是 Telegram Bot API 机器人。请勿用于垃圾消息、批量冷发或绕过 Telegram 限制。向第三方发送、编辑或删除内容前，应由你的 Agent 获取明确确认。

部署与登录

在控制台 → 应用创建 Telegram 账号代理，开通订阅后点击部署。实例资源由平台自动配置。
实例就绪后点击「生成登录二维码」。二维码短期有效，过期后可重新生成。
在 Telegram 打开设置 → 设备 → 链接桌面设备并扫描二维码。
如果状态变为 password_required，在控制台输入 Telegram 两步验证密码。密码只提交到你的租户实例，不会写入平台配置。
状态变为 authenticated 后，控制台显示当前账号、MCP 地址和 Bearer 访问令牌。

授权会话存储在持久卷中，正常重启和升级会复用它。控制台「退出账号」会调用 /api/auth/logout 撤销 Telegram 会话；「销毁实例」还会删除工作负载与持久卷。

鉴权与健康检查

除 /health 和 /readyz 外，登录、REST 与 MCP 接口都要求：

Authorization: Bearer <访问令牌>

服务只接受请求头鉴权，不支持把令牌拼到 URL。请像保护账号密码一样保护它。

curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz

/health 只表示 HTTP 进程存活：

{"status":"ok"}

/readyz 表示 MTProto 连接是否可用。已连接时返回 HTTP 200，即使账号仍在扫码或等待两步验证：

{
  "status": "ready",
  "gateway_connected": true,
  "login_state": "login_required"
}

断连时，Kubernetes 对 Pod 的直接探测返回 HTTP 503，实例会在后台自动重连。此时 Pod 会被临时移出公网 Service，不保证能通过实例域名读取诊断 JSON；请在控制台等待 Deployment 恢复 Ready。login_state 常见值包括 login_required、waiting_scan、password_required、authenticated；进行账号消息操作前仍需达到 authenticated。

连接 MCP 客户端

Claude Code

claude mcp add \
  --transport http \
  --header "Authorization: Bearer <访问令牌>" \
  telegram \
  https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp

Cursor 等支持静态请求头的客户端

按客户端当前文档配置 Streamable HTTP 地址，并添加 Authorization 请求头。例如支持下列结构的客户端可使用：

{
  "mcpServers": {
    "telegram": {
      "type": "http",
      "url": "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer <访问令牌>"}
    }
  }
}

这不是所有 MCP 客户端的通用配置格式。Claude Desktop / Claude.ai 的远程连接器由云端建立，不读取本地 claude_desktop_config.json 中的任意 HTTP 请求头；当前如需静态 Bearer 请求头，请使用 Claude Code 或明确支持该能力的客户端。

MCP 工具

工具	作用
`telegram_whoami`	查看当前授权账号
`telegram_list_chats`	列出最近会话，可仅看未读
`telegram_contacts`	列出联系人
`telegram_read_messages`	读取指定会话的最近消息
`telegram_search_messages`	搜索一个会话或全部会话
`telegram_send_message`	发送消息，可回复指定消息
`telegram_edit_message`	编辑当前账号发送的消息
`telegram_delete_message`	删除有权限删除的消息
`telegram_react`	使用 Unicode 表情回应消息
`telegram_mark_read`	将会话标记为已读

target 可以是会话 ID、用户名或精确会话名称；名称有歧义时优先使用 ID 或用户名。

REST API

所有成功响应使用 {"data": ...}，失败响应使用 {"error": "..."}。

示例

# 当前账号
curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN"

# 最近会话
curl "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/chats?limit=20&unread_only=false" \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN"

# 给 Saved Messages 发一条测试消息
curl -X POST https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer $PROXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"me","text":"Hello from my Telegram proxy"}'

完整接口

方法与路径	主要参数	作用
`POST /api/auth/qr`	—	生成登录二维码 URL
`GET /api/auth/status`	—	查询登录状态与账号信息
`POST /api/auth/password`	`{password}`	提交两步验证密码
`POST /api/auth/logout`	—	撤销实例保存的会话
`GET /api/whoami`	—	查看当前账号
`GET /api/chats`	`?limit=&unread_only=`	列出会话与未读数
`GET /api/contacts`	—	列出联系人
`GET /api/chats/{target}/messages`	`?limit=`	读取消息
`GET /api/messages/search`	`?q=&target=&limit=`	搜索消息；省略 target 时跨会话搜索
`POST /api/messages`	`{target,text,reply_to?}`	发送或回复消息
`PATCH /api/chats/{target}/messages/{message_id}`	`{text}`	编辑消息
`DELETE /api/chats/{target}/messages/{message_id}`	—	删除消息
`POST /api/chats/{target}/messages/{message_id}/reactions`	`{emoji}`	添加 Unicode 表情回应
`POST /api/chats/{target}/read`	—	标记会话已读

常见问题

401：Bearer 令牌缺失或错误。确认令牌放在请求头，不是 URL 查询参数。
503：代理访问令牌未配置，或 Telegram 客户端尚未就绪。先检查 /readyz；若代理访问令牌未配置，受保护接口也会返回 503。
400：参数或 JSON 无效；搜索必须提供 q，limit 必须是大于等于 1 的整数。
403 / 404：当前账号没有权限，或 target / message ID 不存在。
429：触发 Telegram 频率限制。读取 retry_after 并等待，不要并发重试。
二维码一直未完成：重新生成二维码，并确认使用的是 Telegram「链接桌面设备」扫码入口。
重启后要求重新登录：检查实例持久卷是否正常；主动退出、在 Telegram 设备列表撤销会话或会话失效后需要重新扫码。

验证范围

源码和自动化测试覆盖登录状态、Bearer fail-close、REST 参数校验、错误映射与会话持久化实现。生产使用仍应先在 target=me（Saved Messages）完成只读与消息创建/编辑/删除 smoke，再允许 Agent 操作第三方会话。

入门

核心概念

AI 聊天

AI 图像

AI 视频

AI 音频

网络与数据

验证码

身份验证

高级

Coding

更多指南

Telegram 账号代理使用指南

部署与登录

鉴权与健康检查

连接 MCP 客户端

Claude Code

Cursor 等支持静态请求头的客户端

MCP 工具

REST API

示例

完整接口

常见问题

验证范围

​部署与登录

​鉴权与健康检查

​连接 MCP 客户端

​Claude Code

​Cursor 等支持静态请求头的客户端

​MCP 工具

​REST API

​示例

​完整接口

​常见问题

​验证范围

部署与登录

鉴权与健康检查

连接 MCP 客户端

Claude Code

Cursor 等支持静态请求头的客户端

MCP 工具

REST API

示例

完整接口

常见问题

验证范围