背景
Coze 集成最容易出现一种假象：代码已经改了，构建也通过了，但线上接口仍然 401。原因通常不在 TypeScript 语法，而在运行时鉴权模式、环境变量、Bot 配置和真实调用路径没有对齐。
这次经验来自一条典型链路：活动封面生成走 workflow/run，网页采集和活动标准化走 /v3/chat，中间还涉及服务身份令牌、Bot ID 和 PM2 环境刷新。
这次解决了什么
这次要解决的不是“把鉴权代码写出来”，而是确认业务端点真的能用。关键问题包括：
- 当前目标模式到底是 OAuth、PAT，还是服务身份令牌。
- 代码实际读取的是哪些配置键。
- 线上
.env是否和代码里的鉴权模式一致。 - 真实 Coze 返回的状态码和错误体是否已经消失。
关键过程
先做 repo-wide audit，找出所有 Coze 调用点，而不是只改一个服务。封面生成、AI 聊天、网页采集和活动标准化可能走不同服务类，但鉴权头应该统一走同一层。
然后把目标模式固定为服务身份令牌，代码从 COZE_SERVICE_ACCESS_TOKEN 读取令牌，并通过统一方法生成 Authorization header。这个阶段的单元测试和构建只能证明代码能跑，不能证明 Coze 接受了请求。
真正关键的是第三步：重启服务时带上更新后的环境，再打真实 workflow/run 或 /v3/chat。如果返回仍然是 401，就继续对照 live env，而不是回头怀疑“是不是 TypeScript 没编译好”。
踩坑
第一个坑是历史资料干扰当前目标。仓库里可能有 OAuth 参考目录，但用户本轮已经要求改成服务身份凭证，就不能继续沿着 OAuth/PAT 当主线。
第二个坑是把 COZE_BOT_ID 这类名字看起来很通用的变量当成真实生效值。活动标准化路径实际可能读取的是另一个 Bot 配置，必须沿代码路径追到具体 service。
第三个坑是 PM2 环境没有刷新。.env 改了但进程没带新环境重启，线上仍可能拿旧 key 打请求。
最后方案
Coze 类集成的完成标准要写成链路级：
- 静态层：配置键、服务类和调用点统一。
- 构建层：测试和 build 通过。
- 运行层：PM2 使用新环境启动，服务日志正常。
- 真实层：
workflow/run或/v3/chat返回业务可用结果，而不是只返回 HTTP 200。
以后怎么做
以后只要是外部 AI 平台集成，默认不要把本地 build 当成完成。先确认目标鉴权模式，再查代码读取路径，然后做真实下游探测。遇到线上 401，优先对照 live env 和部署版本，不要先假设代码回退。