用一把 API Key 访问多个 AI 模型，可以减少凭证数量并集中查看用量。这里的“一把 Key”是指每个 Environment 或 Workload Boundary 使用一把统一 Gateway 凭证，不是全公司共用一个无限权限的万能 Key。它也不会让 Model ID、API Protocol、Tool Call、Streaming Event、State、Rate Limit、Error 或 Output 自动变得可以互换。
安全迁移时，Key 和 Base URL 只是最小的一部分。先固定当前合同，再建立 Capability Matrix、运行代表性评测、用少量流量做 Canary（灰度），并保留 Rollback（回滚），直到新路径经受过真实负载。
一把 Key 简化了什么，又没有简化什么
统一 Key 可以简化：
- 一个服务需要保存的凭证数量；
- 在 Gateway 边界进行 Rotation 与 Revocation；
- 从同一账户发现模型；
- 集中查看 Request History 与消费；
- 为 Gateway 明确支持的客户端做 Onboarding。
它不会自动统一：
- OpenAI Responses 与 Anthropic Messages 的 Request Shape；
- 不同模型的工具、上下文限制或 Structured Output；
- Streaming 与 Error Event；
- Conversation State 与 Cache 行为；
- Provider Rate Limit 和数据控制；
- Coding Agent 工具或 Workspace 内部的 Authorization；
- 模型在你的代码仓库任务上的输出质量。
Agent.Space Developer API 指南记录了当前 Key 创建、模型发现和受支持的客户端路径。本文从完成 Setup 选择之后开始，只处理迁移安全，不再重复配置步骤。
第一步：固定当前合同
改动前，先记录生产环境依赖的行为：
- Endpoint 与 Protocol；
- Authentication Header 与 Key Owner；
- 准确的 Model ID 与 Alias；
- Request Parameter 与 Default；
- System Instruction 与 Conversation-state Strategy；
- Tool Definition、Call ID、Result 和 Side Effect；
- Streaming Event Type 与顺序假设；
- Timeout、Retry 与 Cancellation 行为；
- Rate-limit Header 与 Backoff；
- Usage Field、价格来源与预算提醒；
- 应用当前处理的 Error Type；
- Data Retention、Region 与 Logging 要求。
保存有代表性的原始 Request、去敏后的 Response 和预期业务结果。它们会成为迁移合同与回滚依据。Fixture 中不能保存真实 Secret。
OpenAI Responses Reference与 Anthropic Messages Reference说明了为什么只替换 Base URL 不够：两种 API 对 State、Content、Tool 与 Result 的表示方式不同。
第二步：建立 Capability Matrix
让每个计划暴露的模型占一行，每项必需能力占一列：
没有来源或测试证明时，填写“unknown”。模型出现在 Discovery 中，只能证明它可以被寻址，不能证明客户端的每项 Feature 都可用。
模型访问还要与 Agent harness 和 Workspace 层分开。一把 Key 可以为模型调用提供资金，但 Harness 仍然负责多步循环，Workspace 仍然负责文件、进程与持久项目状态。
第三步：把凭证与权限分开
减少上游 Key 的数量，不应该产生一把拥有无限权限的凭证。
- 为每个 Environment 或 Workload Boundary 创建独立 Key；
- 把 Key 放在服务端 Secret Store，不能放进浏览器代码或代码仓库；
- 记录 Owner、Purpose、Creation Date 与 Rotation Plan；
- 限制哪些服务能够读取 Key；
- 把 Tool Authorization 分开：Model Gateway Credential 不应该自动获得数据库、Shell、部署或生产写权限；
- 用一次真实的被拒绝请求验证 Revocation。
使用 Coding Agent Workspace 安全清单检查文件系统、网络、Secrets 和审批边界。Gateway Consolidation 不能代替 Agent Runtime 内部的最小权限。
第四步：规范模型发现与路由
把实时 Model Discovery 当成账户当前可以请求哪些模型的事实来源。除了 UI 中的 Friendly Name，还要保存 Provider 返回的 Model ID。
迁移时避免 Silent Alias。如果 default-coding-model 从一个底层模型切换到另一个，应记录最终解析出的 ID，并让这项变更可 Review。否则，质量或成本变化会看起来像随机漂移。
明确写出 Routing 行为：
- 每类工作由哪个模型处理？
- 哪些 Error 允许 Fallback？
- Fallback 能否跨 Model Family 或 Protocol？
- Fallback 会不会重复执行有副作用的工具？
- 最终解析出的模型由哪一种 Balance 或 Account 支付？
- 用户怎样知道实际运行了另一个模型？
Agent.Space 当前把 Share-funded 与 Flex-funded 模型分开，并且不会自动让一种余额为另一种余额兜底。Share 与 Flex 指南解释了这条边界。应通过产品资料和 Request History 核验当前 Funding 与 Availability，不能自行设计一条不存在的 Failover Rule。
第五步：运行代表性评测与成本检查
从真实工作中建立一组去敏后的 Evaluation Set：
- 代码仓库问答；
- 带测试的范围明确的代码改动；
- 包含正确与错误参数的工具调用；
- 长上下文任务；
- 需要审批的任务；
- 可以恢复的 Provider Error；
- 一次尝试执行禁止操作的任务。
运行模型前先定义验收。可用标准包括：测试通过、指定文件发生变化、受保护文件保持不变、Tool Schema 校验通过、不会重复副作用，以及人工接受最终 Diff。
记录 Resolved Model、Protocol、Call、Retry、Latency、Usage Category、估算成本、Tool Failure 与人工介入。不能因为两个模型都返回过一次看似合理的文字，就称它们“兼容”。
第六步：灰度切换并保留回滚
Canary 是让一小部分符合条件的流量进入新路径，同时保留之前的路径。
先选择可回退、风险低的工作。根据预先声明的阈值比较灰度结果：
- 任务验收率；
- Tool-call Validation Failure；
- Retry 与 Timeout Rate；
- Latency Distribution；
- 每个已验收任务成本；
- Rate-limit Event；
- 安全或 Policy Violation；
- 人工介入次数。
保留能够恢复旧 Endpoint、Credential、Model Mapping 和 Adapter 的回滚开关。在迁移前测试它，而不是等第一次事故发生。对有副作用的工具，重试和回滚必须保持幂等，不能重复部署、支付或执行破坏性写入。
第七步：完成观察后再停用旧 Key
灰度扩量后，至少观察一个有代表性的使用周期。确认定时任务、低频工具、备用 Region 和恢复路径都已经使用过新 Route。
之后再有计划地停用旧访问：
- 停止把新流量发送到旧路径；
- 搜索配置和 Secret Store 中是否还有引用；
- 在旧 Key 的 Owner 处撤销它；
- 验证使用旧 Key 的请求确实失败；
- 保留不含 Secret 的审计元数据与迁移记录；
- 确认不再需要回滚后，删除过时 Adapter 与 Fallback Code。
让一个不再使用的凭证为了“以防万一”继续有效，只会保留旧攻击面，并不会提供经过验证的恢复路径。
可直接使用的 Go/No-go 清单
- 当前 Request、Response、Model、Tool、Error、Usage 和 Limit 已记录；
- 每项必需能力都有官方证据或通过了代表性测试；
- 新 Key 已限制范围、保存在服务端、有明确名称并可撤销；
- Tool 与 Workspace Authorization 仍符合最小权限；
- Model ID 通过实时发现获得，最终解析 ID 会被记录；
- Routing 与 Fallback 行为明确，有副作用操作保持幂等；
- 同一套 Evaluation Set 通过约定的质量与安全阈值；
- 成本按完整任务计算，而不是只算一条 Response；
- 少量 Canary 已经在真实并发下运行；
- Rollback 已测试；
- 只有观察窗口完成后才撤销旧凭证。
只有每一项必需条件都有证据时才 Go。一把 Key 的真正价值，是在不掩盖模型与协议差异的前提下简化运维。如果要查看当前双协议入口和账户可用选项，可以在设计 Cutover 前打开 Agent.Space Developer API。