新同事加入共用一把聚合站 key：从零接管的分步清单

先讲清一件事：key 只是凭证，不是配置

新同事拿到的如果只有一个字符串，他大概率会在第一个请求上卡住。交接时先把「这把 key 能做什么、发到哪里」说清楚，比让他自己去翻文档省时间。

聚合站的关键特征是：一把 key 调用多个模型，接口按 OpenAI 兼容方式提供。也就是说大部分客户端不需要专用 SDK，只要把 base URL 指过来、把模型名换成站点支持的标识即可。

第一步：交代 base URL 和协议

告诉新人两件事就够起步：

• 请求地址的 base URL（通常以 /v1 结尾，具体以站点文档为准）。
• 这是 OpenAI 兼容接口，/chat/completions 这类路径和主流 SDK 一致。

不要让他去猜是不是自研协议。协议一致意味着他可以直接沿用已有的调用代码，只改两个变量：地址和模型名。

第二步：用环境变量，别把 key 写进代码

交接时要明确要求：key 只进环境变量或密钥管理服务，不进仓库、不进配置文件、不进聊天记录。

常见的变量名约定：

• OPENAIAPIKEY：多数 OpenAI 兼容客户端默认读这个。
• OPENAIBASEURL（或客户端对应的 base URL 变量）：指向聚合站地址。

如果团队用 .env，就要同时确认 .env 在 .gitignore 里，并且仓库里只放 .env.example，值留空。

第三步：客户端配置的最小可用写法

不同客户端配置方式不同，但结构一致：地址 + 凭证 + 模型名。给新人一个能跑通的最小示例，比让他读完整文档更快。

• 官方 SDK：初始化时传入 baseurl 和 apikey；模型名用站点支持的标识。
• 第三方 GUI 客户端：在设置里填「API Base / 自定义端点」和 key，模型列表可能需要手动填。
• 命令行工具：优先看它是否支持自定义 base URL；不支持就只能用官方端点，这一点要提前说明。

跑通标准建议定成：发一条最简单的对话请求，能拿到正常返回，就算环境通了。

第四步：交代模型名的来源

聚合站一把 key 对应多个模型，但模型标识不是随便写的。交接时说明：

• 可用模型清单以站点文档或模型列表接口为准，不要凭记忆写。
• 不同模型的上下文长度、是否支持图片、是否支持工具调用并不相同，选型前先确认。
• 换模型只需要改模型名，不需要换 key 或换地址。这是聚合站最省事的地方。

第五步：明确什么绝对不能一起给

这是清单里最容易被跳过、后果最重的一条。

• 不要把 key 直接贴在群聊、工单、文档正文里。要传就放进团队的密钥管理工具，或让对方自己在控制台生成/领取。
• 不要给出账户级凭证：登录密码、控制台会话、充值相关的支付凭证，和 API key 是两回事，不要因为「方便」一起打包。
• 不要共享计费主体的敏感信息：余额、充值记录属于账户侧信息，按需告知用量情况即可。
• 不要给能签发新 key 的权限，除非对方确实需要。

一句话原则：能只给一把受限的 key，就不要给账户。

第六步：讲清共享 key 的边界

多人共用一把 key 会带来两个实际问题，交接时提前说：

• 用量归因困难：调用都记在同一把 key 上，出了异常用量不容易定位到人。如果站点支持为不同用途建多个 key，优先一人一把或一项目一把。
• 轮换成本高：一旦泄露，所有使用方都要同时改配置。共享范围越大，轮换越痛。

如果只能共用，至少约定：谁在什么场景用、异常用量找谁、轮换时由谁统一通知。

第七步：给出第一周的验收动作

让新人自己完成这几件事，比口头交代更可靠：

1. 在本地配好环境变量，跑通一次对话请求。
2. 换一个模型名，确认同一把 key 能调通第二个模型。
3. 在代码里确认没有硬编码 key，提交前自查一次。
4. 记录下他能看到的用量入口，知道去哪里看消耗。

交接清单收束

把上面收成一份可以照着念的清单：地址与协议、环境变量约定、客户端最小配置、模型名来源、不可共享项、共享边界、首周验收。核心只有一句：key 是凭证，配置和权限要分开交代。做到这点，新同事接管一把聚合站 key 通常不会超过半天。