Codex 调第三方 API 总写错？用 OpenAPI 合约文件、AGENTS.md 和冒烟测试把幻觉挡在提交前

很多人第一次把 Codex 用到真实项目里，问题不是“它不会写代码”，而是它会把第三方 API 写成“看起来很像，但关键字段、权限范围、错误处理都不对”的样子。最常见的翻车方式不是语法报错，而是：

• 请求能发出去，但字段写反了。
• 示例代码能跑，但权限模型不安全。
• 文档明明写了限制，模型还是顺手补了一个“它以为合理”的参数。
• 同一个 provider，前一轮上下文和后一轮上下文互相污染，修了一处又在另一处复发。

如果你已经遇到过“接口名没写错，但业务结果一直不对”的情况，下面这套方法比单纯让 Codex “再检查一遍文档”更稳。

这篇教程适合谁

• 你在用 Codex、Claude Code、Cursor 或类似 AI 编程助手接第三方 API。
• 你已经有官方文档、SDK 或 OpenAPI，但模型还是会在认证字段、可写字段、错误处理上出错。
• 你不想把整个长文档一直塞进上下文，也不想每次都靠人工全量复查。

先复现一下，这类错误通常长什么样

假设你要接一个带权限边界的认证 API，常见错误不是“完全不会写”，而是：

1. 模型把用户可改字段和只有服务端能改的字段混在一起。
2. 模型照着文档里的教程示例写了浏览器端调用，忽略了服务端密钥边界。
3. 模型在长上下文里记住了旧例子，后面继续沿用已经被你否掉的字段结构。
4. 模型看到多个 provider 文档后，把 A 平台的错误处理套到 B 平台上。

下面这个例子就很典型：用户资料字段名看起来只差一点，但安全边界完全不同。

场景	看起来像什么	实际风险
可写字段混淆	把 user_metadata 当成权限字段	用户自己就能改权限信息
服务端接口误放到前端	在浏览器里直接用高权限管理接口	密钥暴露，整套权限边界失效
教程示例照抄	能跑但没有最小权限控制	线上留后门，后续审计很难补

根因判断：为什么“读过文档”还是会写错

这类问题通常不是单一原因，而是下面 4 件事叠在一起：

1. 真实接口真相太分散。文档、SDK、FAQ、错误码、权限说明分散在不同页面。
2. 上下文太脏。你前面讨论过的旧方案、旧字段、旧样例，会在后面继续影响实现。
3. 文档太大。你把全部文档都塞进去，模型反而会抓错“最像答案”的片段。
4. 缺少快速反馈门禁。直到最后跑集成时才发现错，返工成本很高。

第一步：先写一份 provider contract，小到只覆盖你当前要碰的接口

不要一上来就让模型读完整套 API 文档。先把这次要碰到的接口，压成一份“小而硬”的合约文件。

建议每个高风险接口至少写清楚这 7 项：

1. 精确 endpoint 和 method
2. 认证方式和所需 scope
3. 允许写入的字段
4. 禁止模型推断或擅自写入的字段
5. 一份成功请求与成功响应样例
6. 一份故意错误的请求与预期错误
7. 这条接口的禁区说明

下面是一份可以直接改名复用的模板：

# 基于官方文档验证：provider-contract.example.yaml
provider: supabase-auth-admin
surface: update-user-role
endpoint: /auth/v1/admin/users/{uid}
method: PUT
auth:
  type: service_role
  must_run_on: server
allowed_write_fields:
  - app_metadata.roles
forbidden_inference:
  - user_metadata.roles
  - browser_side_service_role
known_good:
  request:
    uid: "00000000-0000-0000-0000-000000000000"
    body:
      app_metadata:
        roles:
          - admin
  expected: "200 or provider-documented success response"
known_bad:
  request:
    body:
      user_metadata:
        roles:
          - admin
  expected: "should be rejected by your internal contract review"
danger_list:
  - "不要把 service_role 暴露到浏览器"
  - "不要把 user_metadata 当权限字段"

第二步：把 contract 放进 AGENTS.md 的执行入口，而不是临时聊天补充

如果你每次只在对话里说“记得去看文档”，那条约束很容易在长会话里被淹没。更稳的做法是把规则写进项目的 AGENTS.md。

基于官方文档验证，Codex 会在启动时构建指令链，并按目录层级合并 AGENTS.md 内容。也就是说，你可以把“第三方 API 必须先看 contract 文件”写成项目硬规则，而不是靠临时提醒。

下面是一段可以直接改的写法：

# 基于官方文档验证：AGENTS.md 片段
Before changing any third-party API integration:

  此处内容已隐藏，请付费后查看