Telegram 机器人常被当成「写完命令就能交付」。实际上，上线后真正决定能不能稳定运行的，往往是 Token 归属、Webhook / 轮询方式、服务器权限、日志位置，以及出问题时谁能改、谁不能改。功能演示通过，却没有交接清单，三个月后换人维护就会变成黑盒。

安稳科技做机器人相关交付时，会把「能用」和「可交接」分成两段验收：前者看流程与命令；后者看权限、配置与文档是否可独立续命。

背景：机器人交付容易漏什么

BotFather 发出的 Token 相当于钥匙；Webhook 指向的 URL、证书与密钥决定流量进哪台机器；若还有支付、数据库、第三方 API，密钥散落在聊天记录里，风险更高。缺少运行说明时，重启、换域名、换服务器都会变成紧急事故。

决策对照：现在算不算「可交付」？

状态结论补什么
命令能跑，Token 仍在开发者个人 BotFather未完成交接转移控制权或明确归属与备份
Webhook 可用，但无文档写域名/路径/证书位置高风险补一页部署说明，并现场按文档重启一次
管理员写死在代码里后续运维成本高改为配置或后台名单
功能验收通过，密钥只在聊天记录不安全迁到约定密钥存放处并轮换
有日志与回滚步骤，权限已落到约定主体可进入观察期约定已知问题与迭代边界即可

「能用」和「可交接」是两段验收。前者看主流程；后者看别人能否按一页纸把服务拉起来。少了后者，三个月后换人就会变成黑盒排障。

观察期不必很长，但要写清：反馈窗口、已知限制、哪些改动算新需求。避免上线后一切口头「再优化一下」都算在原范围里。

交付时应对齐的内容

  • 机器人身份：Bot 用户名、BotFather 控制权归属、是否需转移所有权。
  • 运行方式：Webhook 或长轮询；域名、证书、回调路径；进程守护方式。
  • 密钥与配置：Token、数据库连接、第三方 API Key 的存放位置（避免只在聊天里）。
  • 权限模型：管理员名单、命令权限、是否限制群组 / 私聊场景。
  • 功能清单：已实现命令、异常提示、限流与日志策略。
  • 维护入口：谁可以发版、如何回滚、监控与告警是否有最小方案。

建议的交接步骤

  1. 功能验收：按用例走通主流程（含失败提示）。
  2. 配置验收：在文档中写明环境变量与部署路径，现场能按文档重启一次。
  3. 权限验收：确认 Token 与服务器访问权落到约定主体，而不是个人临时账号。
  4. 文档验收：README 或一页纸说明「如何启动 / 如何改配置 / 出问题先看哪里」。
  5. 观察期：约定短观察窗口，记录已知问题与后续迭代边界。

常见坑点

  • Token 仍在开发者个人 BotFather，客户无法接管。
  • Webhook 绑死旧域名，换服务器后无人知道改哪里。
  • 管理员列表写死在代码，增删人员要重新发版。
  • 没有日志，用户说「机器人没反应」时无法定位。
  • 把演示环境密钥直接用于生产。
  • 交接会议只口头说，没有可执行的一页纸。
  • 观察期边界不清，上线后所有口头优化都算原范围。
机器人需求差异很大（客服、通知、查询、订单、自动化）。沟通时说明场景与是否需要 Webhook / 数据库，比只说「做个机器人」更容易估范围。

上线后的最小运维

即使早期没有完整监控，也应保留：进程是否在跑、Webhook 是否返回 200、关键错误是否写入日志。换域名或证书前，先在文档里写下回滚步骤。管理员变更通过配置完成，避免每次改人员都发版。

交接自检清单

  • Bot 控制权与 Token 归属已明确
  • Webhook / 轮询与部署方式已文档化
  • 密钥不散落在聊天记录，有约定存放处
  • 管理员与命令权限可配置或可说明
  • 启动、重启、回滚步骤可按文档执行
  • 已知限制与后续迭代边界已写清
  • 观察期与问题反馈窗口已约定
  • 按文档现场重启一次已通过

若你正在做或准备交付 Telegram 机器人，可通过 Telegram 说明使用场景、是否已有 Bot、是否需要 Webhook 与数据存储，我们帮你对齐功能范围与交接标准。