直接上一个我最近在空隙时间里折腾完的东西把 Postman 里的 API 集合做成 Codex 可以直接调用的智能体 Skill。简单说就是让 AI 代理能像人一样用 Postman 里的接口去查数据、发请求、跑流程而不是只能对着文档“空谈”。这个方向最近变得很实际。Postman 早就不是简单的“接口调试工具”了它沉淀了一个团队对接口、对测试、对参数的所有理解。Codex 这类代码智能体最需要的恰恰就是这种结构化的 API 能力。两者一接等于把“API 资产”直接变成了“智能体的可操作技能”效果有点类似于给 Agent 装上一个标准的“API 工具箱”它不用再看文档、猜参数、手拼 URL而是按 Skill 描述直接执行。我实际跑下来之后最大的感受是这件事真正的难点不在“调用”而在“包装”。把接口暴露给 Codex 的方式决定了 Agent 到底是在“会用工具”还是在“瞎试”。这篇文章不聊概念直接讲清楚怎么设计、怎么实现、怎么避坑。适合想把 API 能力开放给 AI Agent、又不想只停留在“接了个模型”层面的开发者和技术负责人。1. 为什么要把 Postman 和 Codex 接在一起1.1 一句话先讲明白“插件”站在哪里很多人一看“Postman 给 Codex 做插件”会以为要把 Postman 整个界面搬进 Codex其实不是。这里的插件本质是一个“适配层”一层让 Codex 把 Postman 集合里的接口当成函数来调用的中间件。举个例子。你在 Postman 里有一个“订单详情”接口定义了 GET /orders/{id}参数、鉴权方式、Header、示例响应全都在集合里。没有插件之前Codex 想用这个接口得自己理解接口文档、猜参数名、拼请求而有了插件之后Codex 只需要看到一个名为“查询订单详情”的 Skill它知道这个 Skill 接收订单号就能完成调用了。Postman 的角色更像一个配置中心接口定义、环境变量、鉴权信息、Mock 数据、测试脚本都从这里来。Codex 的角色则是一个执行大脑它根据用户的需求自主决定调用哪个 Skill、传什么参数、如何处理结果。插件是中间的桥梁负责把 Postman 侧的“静态资产”翻译成 Codex 侧的“动态工具”。1.2 传统 API 网关和智能体 Skill 有什么区别做后端的人听到这第一反应可能是“这不就是 API 网关或者 BFF 吗”还真不一样。传统网关的核心是把接口统一暴露给前端解决的是一致性和安全问题而智能体 Skill 的核心是把接口的“使用方式”描述给模型让模型能自主完成一次工具选择与参数计算。这里有个专业上的细微差别Skill 不只是接口的代理它给 Agent 提供了“调用的理解能力”。比如一个接口要求时间戳而不是日期字符串普通网关不会管这件事调用方得自己转换但 Skill 可以在描述里写明“时间参数请转换为时间戳”Codex 就会自动完成转换再调用。这比传统 API 层更接近“任务意图”层面。也因此一个 Skill 不应该对应 Postman 里的一个裸请求我更建议按“任务能力”来划分。比如“查询订单详情”是一个 Skill“批量导出订单”是另一个 Skill而不是把 GET、POST、PUT 拆成三个 Skill。这能显著降低 Codex 做工具选择时的决策成本调用更稳定。1.3 什么场景下不建议这样接不是所有 API 都适合做成 Skill。如果一个接口已经封装得足够简单调用方用几行代码就能完成那做成 Skill 反而多了一层解析损耗。反过来如果一个接口需要复杂的流程编排比如先获取签名、再请求 A、然后根据 A 的结果决定是否请求 B这类接口也不建议直接暴露成 Skill更适合让 Codex 组合多个原子 Skill 来完成。我在这个项目里的判断标准很简单是否有“判断分支”。接口背后如果只是一次数据查询或提交适合做成 Skill涉及多步骤状态机、回调通知、分布式事务的接口先别急着暴露。把简单的先接上跑通流程再逐步开放复杂的比一次性铺开更踏实。2. 整体设计与核心思路拆解2.1 从 Postman 集合到 Skill 的“三层映射”真正动手前我先把整个结构理成三层这样后面每写一步都有对应关系不容易乱。第一层是 Postman 侧的数据资产。包括集合、环境变量、认证配置、Mock 服务、测试脚本。这些内容是团队已经沉淀好的我不去改动它只是把它作为数据源。第二层是 Skill 定义层用一份结构化描述文件描述每个 Skill 的名字、用途、参数、返回值、调用方式类似给人看的接口说明但面向的是模型。第三层是执行层一份轻量代码负责真正发出 HTTP 请求、处理鉴权、解析响应、抛出错误。这样的好处是Postman 集合变了只需要重新生成 Skill 描述文件不用改 Codex 这边的逻辑Codex 增加新能力也只需要新增一个 Skill不需要动 Postman。两层各自演进耦合极小。实操里我建议把三层分开放到不同目录。Postman 导出的集合文件放在一个单独目录Skill 描述文件放在另一个目录执行层的脚本再单独存放。不要所有文件混在一个文件夹里尤其当你准备维护几十个 Skill 的时候分目录结构能救你一命。2.2 一个 Skill 描述文件到底该写什么Skill 描述文件是整个插件系统的核心它的质量直接决定了 Codex 能不能用对。我起初参考了常见插件包的写法不断试错后总结出一份够用的结构字段包括name、description、parameters、returns、executor、tags。其中 description 是重中之重。模型不会看代码它只看 description 来理解这个 Skill 什么时候该用、怎么用。我写 description 时会明确写清“什么时候用”和“什么时候不用”。比如订单查询 Skill我会写“当用户询问订单状态、物流、详情时使用当用户要求修改订单时不要使用请调用订单修改 Skill”。这种排斥性描述能显著减少误调用。parameters 部分要写清楚每个参数的类型、是否必填、取值范围、默认值。Codex 会根据这里来组织参数。我踩过一个坑某个接口的 user_id 参数从前端传过来时是字符串但后端要求整数如果参数说明里没写类型约束Codex 可能直接传字符串接口就报 500。所以参数声明别偷懒越是类型敏感的接口越要描述清楚。returns 部分则用来告诉 Codex 怎么解析结果。我倾向于把返回的 JSON 结构做一层简化比如只保留核心字段。这能减少模型被大量无关字段干扰的问题也让后续结果处理更稳定。2.3 执行层的设计用低代码还是完全自研执行层我试过两种方案一种是用现成的 HTTP 客户端库基于 OpenAPI 或 Postman Collection 自动生成调用代码另一种是手写一个轻量执行器。两者各有适用场景。用 OpenAPI 自动生成的好处是省事Postman 集合可以直接导出 OpenAPI 格式然后通过一些工具生成对应的客户端代码再用统一的入口包装成 Skill。这个方案适合接口规范、团队已经维护了 OpenAPI 文档的场景。坏处是生成的代码往往很臃肿而且一旦接口的某些特殊逻辑比如自定义加密参数没体现在 OpenAPI 里生成的代码就不对。手写执行层的优点是灵活可以针对每个 Skill 定制也方便加入日志、重试、限流等通用逻辑。缺点是需要自己维护。我的建议是起步阶段先手写 3 到 5 个核心 Skill 的执行器摸清套路后再考虑用代码生成来扩展。别一上来就搞自动化生成容易失控。3. 实操复刻把 Postman 集合做成 Codex 可调的 Skill3.1 第一步把 Postman 集合整理成“Agent 友好”的格式Postman 集合本身是给人看的结构里会有大量对 Agent 无用的信息比如描述文字、示例代码片段、测试脚本。直接把它丢给 Codex 会导致上下文被撑爆模型反而抓不住重点。我的做法是先把集合导出成 JSON然后写一个清洗脚本把每个请求转成一条精简的接口定义。清洗后的格式我用的是类似这样{ endpoint: /orders/{id}, method: GET, params: [ {name: id, type: integer, required: true, in: path}, {name: expand, type: string, required: false, in: query} ], auth: bearer-token, notes: 查询单个订单详情返回状态、金额、物流信息 }这一步做一次就够了之后集合里有新增接口只要重新跑一遍清洗脚本。我把它做成了一个简单的内部命令行工具输入 Postman 的 Collection JSON输出一个 agent-friendly 的接口清单。这样后续维护成本很低。清洗时要特别注意过滤掉内部注释、敏感示例数据、调试用的临时环境变量。有一次我忘了过滤掉集合里的一个示例请求体结果 Codex 在调用时直接用了那个示例里的假数据查了半天才发现是数据源不干净。3.2 第二步编写 Skill 描述文件有了清洗后的接口清单接下来为每个接口或每个任务编写 Skill 描述文件。我这里给一个实际能用的模板你可以直接参考name: query_order description: | 基于订单号查询订单详情适用于用户询问订单状态、订单金额、收货地址等场景。 不要使用该工具进行订单创建、订单取消、退改操作。 parameters: order_id: type: integer required: true description: 订单号纯数字例如 1002345 expand: type: string required: false description: 需要扩展返回的字段可选值为 items、payments多个用英文逗号分隔 returns: type: object fields: order_id: integer status: string total_amount: number items: array executor: type: httpx config: method: GET url_template: https://api.example.com/orders/{order_id} auth: bearer_tokendescription 一定要写“什么时候不要用”这一步很关键。模型在不确定选择哪个 Skill 时会靠这种负向描述来做排除。如果没有这句话Codex 很可能会拿“查询订单”的 Skill 去硬处理“取消订单”的请求轻则报错重则产生误解。parameters 的 description 也别太随意。Codex 是很字面理解的你写“订单号纯数字”它就知道去提取数字而不是把用户说的“订单号是 abc-123”整个传进去。参数描述越精确模型的表现越好。3.3 第三步实现执行器并处理认证Skill 描述文件只是“说明书”真正发请求的是执行器。我用的方案是基于 Python 的 httpx 写了一个通用执行函数通过读 yaml 描述文件来动态构造请求。这样新增 Skill 时只需要加 yaml 文件不用改代码。认证是这一步最容易出问题的地方。Postman 集合里常见的认证方式有 Bearer Token、API Key、OAuth2。我的建议是统一走一个 token 管理模块所有 Skill 在执行时都从这个模块拿 token不要在 Skill 描述文件里写死 token 值。import httpx, os, yaml skill yaml.safe_load(open(skills/query_order.yaml, r)) cfg skill[executor][config] token os.environ.get(API_TOKEN) headers {Authorization: fBearer {token}} resp httpx.request( cfg[method], cfg[url_template].format(order_id12345), headersheaders, timeout30 )这里有两个细节值得提。第一token 不要放在代码库里用环境变量或密钥管理服务注入第二要区分“token 未配置”和“token 已过期”两种错误给 Codex 的报错信息里要写明“请先检查 API_TOKEN 环境变量是否设置”这样 Agent 才能给出正确的下一步建议。我还给执行器加了一层动作遇到 401 时先尝试用 Postman 里配置的刷新逻辑去换新 token换完重试一次如果重试还失败才返回带明确错误码的失败信息。这个小逻辑投入产出比很高能救回不少因为 token 轮换导致的失败请求。3.4 第四步在 Codex 里注册 Skill 并联调不同 Codex 环境的插件注册方式会有差异但整体思路是一致的Skill 描述文件放到插件包的 skills 目录Codex 加载插件包后就能识别。注册完成后先用最简单的问法做冒烟测试“帮我查一下订单 1002345 的状态。”如果正常Codex 会选中 query_order 这个 Skill生成带 order_id1002345 的工具调用执行器发出请求然后返回结果。你只需要在终端里观察日志看整个链路是否顺畅。冒烟测试跑通还不算完我会做一轮“负向测试”故意问一些模棱两可的问题比如“这个订单能不能退”如果 Codex 误调用了查询 Skill就说明 description 里的负向约束没写好得回改 yaml。这一步非常重要但不能只靠一次测试下结论我通常会准备十几种问法分别覆盖正常、边界、歧义和恶意输入。3.5 第五步从单个 Skill 扩展到多接口流程单个 Skill 跑通后最有价值的扩展是让 Codex 编排多个 Skill 完成一个完整任务。比如“查询订单并展示物流轨迹”就涉及查询订单 Skill、查询物流 Skill 两个工具的先后调用。Codex 自动处理这种编排的逻辑但前提是每个 Skill 的返回结构足够清晰。我实际发现一个规律Skill 的返回字段如果命名规范比如都用 status、total_amount、created_at 这套统一命名Codex 在串联两个 Skill 时表现明显更好。因为模型在做跨 Skill 推理时对同名同义字段更容易建立关联。所以哪怕 Postman 里字段叫 st、amt我在执行器里也会把它转换成 status、amount 再返回。这里我也建议把“流程型 Skill”和“原子型 Skill”分开维护。原子型 Skill 对应一次 API 调用流程型 Skill 内部引用多个原子 Skill。这样拆Codex 在复杂任务里就能组合得比较灵活而不是只能记忆一套写死的流程。4. 跑通的三个真实场景复盘4.1 场景一自然语言直接查订单第一个跑通的场景是做电商的 A 同学手里最基础的“帮我把订单 1002345 查一下”。接入前人工登后台看订单至少要两三分钟接入后Codex 听到这句话直接调 query_order Skill返回订单状态、金额、商品列表整个过程大概十几秒。这个场景虽然简单但意义在于验证了整个调用链的可用性。真正要打磨的是返回结果的处理早期我直接把接口原始 JSON 返回给 Codex发现它在总结时容易堆砌所有字段显得啰嗦。后来我在执行器里做了一层提炼只保留用户真正关心的高层字段Codex 的回答就简洁很多。我建议每个 Skill 都定义“默认返回字段”和“可选返回字段”。默认返回只给最关键的三四个字段Codex 生成结果更快更准需要更多细节时Codex 会基于参数说明重新发起调用带上 expand 之类参数。4.2 场景二多接口编排完成下单前检查第二个场景比第一个复杂用户在下单前要完成库存检查、价格确认、优惠券校验三个动作。原本这些动作散落在不同接口里人工操作要在多个页面来回切。用 Skill 编排后Codex 会依次调用库存查询、价格查询、优惠券校验三个 Skill并在中间做逻辑判断。这个场景里对比最明显的是如果这三步都由我写死在代码里那每加一个规则都要改代码而让 Codex 编排相当于把“流程控制权”交给了模型的推理能力。比如优惠券过期了Codex 会自动跳过优惠校验并且告诉用户“优惠券已过期建议继续下单还是换一张”这个判断分支是没法在传统流程里预埋全的。当然风险也很明显编排的不确定性意味着每一次执行结果都可能略有不同。我的应对方式是给每个 Skill 加上模式化输出约束不让模型自由发挥字段。比如价格查询必须返回 amount、currency、is_available 三个字段模型就只能在限定结构里做文章。4.3 场景三Mock 服务与自动化测试联动第三个场景是我个人觉得最有意思的用 Skill 把 Postman Mock 服务变成 AI 的自动化测试助手。以前跑测试要先在 Postman 里确认 Mock 服务启动、再手动拼几个测试用例接入后Codex 可以直接调用“创建 Mock”“运行测试”“查看测试报告”这几个 Skill自主完成一轮接口 Mock 测试。这个场景的扩展价值在于它让“测试”这件事从人的例行操作变成了 Agent 的自主任务。比如我可以直接说“帮我针对订单查询接口跑一轮正常、超时、参数缺失三个用例”Codex 会调 Mock 相关 Skill 建立数据、执行器发出不同参数的请求、再把结果汇总成报告。不过这个场景对契约的要求更高。Postman 里的 Mock 服务建立在 Collection 的 Schema 基础上如果 Schema 与真实接口不一致测出来的结果没有意义。所以做这个玩法前一定先把 Mock 和真实接口的响应结构对齐我见过太多人忽略这一步最后测了一堆假数据。5. 踩坑记录与排查技巧5.1 Postman 变量作用域在 Agent 上下文里失效第一个让我折腾最久的坑Postman 集合里用了大量环境变量比如 {{base_url}}、{{token}}这些变量在 Postman 里能正常解析但导出成 JSON 后并不会自动带值。直接把集合丢给 Codex 调请求全打到了“{{base_url}}”这个字面量上面。排查这个问题的思路其实不复杂看执行日志里实际发出的请求 URL 就明白了。解决方式是在清洗脚本里做变量替换读取集合的同时结合环境配置把 {{var}} 全部替换成真实值输出一份“运行时可用”的接口定义。注意这份运行时定义不要回写库它只是临时产物。后来我还写了一个检查项清洗完成后跑一遍 grep 确认生成的接口定义里没有 “{{” 残留。这个小动作帮我拦截过至少三次低级错误推荐你也加上。5.2 认证令牌过期导致 Skill 静默失败第二个坑是 token 过期后接口返回 401但我的执行器只是把 401 原样返回给 Codex。Codex 看到 401 会怎么处理它会尝试自行“修复”有时会反复重试同一个请求不仅浪费 token还拖慢响应。后来我在执行器里加了认证描述让返回的错误信息里带上明确的下一步建议“401 Unauthorizedtoken 已过期已自动尝试刷新刷新失败请联系管理员检查 API_TOKEN 环境变量。”Codex 收到这种结构化错误信息后会停止无意义重试并且把问题如实反馈给用户。这个经验的核心是给 Agent 的错误信息不是越简单越好而是要给“出发下一步的关键线索”。Agent 不会像人一样去翻日志它只能根据返回文本做判断所以错误信息要写得像给另一个工程师的交接条。5.3 OpenAPI 参数格式与 Codex 工具参数不匹配第三个大坑是类型不匹配。Postman 导出的 OpenAPI 里很多参数标的是 string但真实接口接收的是 integer。Codex 读描述文件时会严格遵守我写的类型如果描述文件写 integer它就会传整数如果描述文件含糊它就可能传字符串。这类问题排查起来最费劲因为报错往往出现在后端逻辑深处返回的错误根本不指向参数类型。我的排查经验是给执行器加一层“参数预检”在发请求前先根据 Skill 描述文件里的参数类型做一次校验类型不对就直接报“参数类型错误order_id 期望 integer收到 string”。这样问题在入口就暴露了不用在后端日志里翻半天。5.4 日志与追踪Agent 出问题时不靠猜整个过程中我最重视的是日志。没有日志时Codex 一旦行为异常你完全不知道它选了什么 Skill、传了什么参数、后端回了什么。我搭建了一套很轻量的追踪机制每次 Skill 调用记录 skill 名称、入参摘要、响应码、耗时、返回摘要输出成结构化日志。这套日志后来建成了回放能力某次执行不对我能从日志里还原 Codex 当时的完整工具调用链。我强烈建议只要开始做 Skill 化先别急着加功能先把日志框架搭好不然后面所有问题的排查都会变得非常痛苦。6. 进阶方向与个人体会6.1 从单个 Skill 到 Skill 市场Skill 数量超过十个之后管理方式就要升级。单层的 skills 目录会越来越乱我开始按业务域划分比如订单域、用户域、支付域各自一个子目录。进一步还可以做一个内部 Skill 索引让 Codex 在加载插件时先扫一遍索引再按需加载具体 Skill能有效降低上下文开销。有跨团队协作需求的时候可以考虑把 Skill 做成可分享的包封装好描述文件、执行器、依赖清单打包发到内部仓库。另一个团队只需要把包装进自己的 Codex 环境就能复用这套 API 能力不需要重新对接。6.2 把调用日志变成 Skill 的迭代依据我建议不要把日志只当成排查工具它是 Skill 质量的数据源。通过统计每次调用的成功率、超时率、模型误用率你就能知道哪些 Skill 表达得还不够清晰。比如某 Skill 有 30% 的请求都被判定为“模型误选”那十有八九是 description 写得太宽泛该做拆分或加负向约束了。这个闭环做起来不费什么成本但价值很大。Skill 本质上是用文字指导模型行为文字质量只能靠数据反馈来迭代。空对空的“我觉得写清楚了”基本不可靠。6.3 最后分享一点实际体会折腾完这套插件后我对“AI 原生 API 层”的理解深了一层。API 能力变成 Skill并不是简单换个外壳而是一次“从人读文档到模型读描述”的范式转移。模型通过描述文件来理解接口的语义这意味着你的接口文档不仅要准确还要写得够“语境化”。我这里有一个很主观的结论给智能体用的接口描述和给人用的接口文档风格应该完全不同。人看重的是完整性和准确性智能体看重的是“何时用、何时不用、参数怎么取值”的决策导向信息。如果你能把接口描述写出这个味道那你的 Skill 大概率会比别人接得更顺。以后我大概率会把更多复杂接口逐步开放给 Agent同时继续保持“先记录日志再评估效果”的习惯。这个内容的后续空间还很大但根基一定是先把手头的每个 Skill 写清楚、跑稳不要急着铺摊子。