最近我折腾了一件很有成就感的事把Postman里沉淀了多年的API资产批量转成Codex的Skill让代码智能体在写代码时能直接调真实接口。以前每次让Codex对接接口基本靠猜——URL拼错、忘记带Token、不知道响应结构最后还得自己去翻Postman里的历史请求。做了这个插件之后现在只要说一句“把订单状态同步到CRM”它就会从Postman集合里找到对应接口自己处理好鉴权和参数把结果完整拿回来。这篇文章不打算讲空泛的概念只讲实际操作。适合手里有一堆Postman集合同时想让Codex这类智能体去干活的工程师。核心就一句话把API能力变成智能体Skill比让模型读文档靠谱得多。1. 为什么非得把Postman的API资产交给Codex1.1 智能体最大的问题看不见真接口代码模型训练时见过大量公共API但企业自建的接口、内网服务、带复杂鉴权的接口它真的没学过。把接口文档直接贴给Codex也不现实一个稍微像样的系统光接口清单就有几百条全塞进对话上下文成本太高而且模型看文档生成的请求往往对不上真实环境。我在Postman里维护了十几个集合环境变量、预请求脚本、断言脚本都沉淀在里面。这些是人类团队调试接口的经验如果智能体用不上每次写API调用都是从头开始。打个比方新同事入职明明公司有完整的接口管理平台你却只给他一张打印版URL清单他照样填不对参数。智能体也是一样。1.2 三个痛点逼着我做插件第一个痛点是接口资产不可达。Postman集合在云端或本地工作区里Codex默认没有通道去读取这些内容。第二个痛点是鉴权是动态的不是静态文字。比如接口的Token需要先调一个OAuth接口刷新然后才能访问业务接口这种时序逻辑是代码不是一行描述。第三个痛点是响应结构复杂模型需要真实响应样本而不是OpenAPI里的字段说明。这三个痛点绕不开所以我决定做一个桥接插件把Postman集合里的API变成Codex能调用、能看到返回结果的Skill。1.3 为什么“Skill化”比“喂文档”强文档是给人读的Skill是给智能体执行的。一份Skill包含触发描述、入参定义、请求模板和响应处理规则。模型只需要判断“用户意图匹配哪个Skill”剩下的事情由运行时解决。读文档还需要自己拼请求、处理返回值而Skill是一键调用。我实际测试下来用Skill后接口调通率从不到一半提升到接近九成。关键原因是所有请求细节都被模板固定了模型不需要自由发挥。2. Codex插件机制解构一个Skill的里子2.1 插件机制不是黑魔法是一张工具注册表我用的插件机制大体是这样智能体启动时插件SDK会扫描Skill目录把每个Skill的名字、描述、参数结构注册到模型的工具列表里。当用户在对话里提出请求模型会从工具列表里选一个最匹配的Skill告诉SDK“调用它”。SDK负责去执行真实的HTTP请求把响应整理好再返回给模型。整套机制和“给模型读一份手册”有本质区别。手册只能增加认知不能产生动作Skill注册表是真正可执行的动作集合。2.2 一个最小Skill的配置文件长什么样直接上我常用的配置结构{ skill_name: query_order_status, description: 根据订单号查询订单实时状态。订单号格式SO后跟8位数字例如SO20250201。, parameters: [ { name: order_id, type: string, required: true, description: 订单号例如SO20250201 } ], request_template: { method: GET, url: https://api.example.com/v1/orders/${order_id}/status, headers: { Authorization: Bearer ${POSTMAN_TOKEN} } }, response_handling: { mode: summary, extract: [$.code, $.data.status, $.data.updated_at] } }字段不复杂但有几个值得多说两句。description必须写清楚触发条件和参数示例模型是根据描述决定要不要调用它的描述写得太抽象它会选错request_template里的变量用了${}占位${POSTMAN_TOKEN}不是一个神秘变量而是由插件运行时从环境变量读取后替换进去response_handling告诉SDK该把响应的哪些部分带回给模型避免整包JSON全塞进上下文。2.3 注册Skill的两种方式方式适用场景优点缺点目录扫描日常静态Skill改文件即可调试方便新增/改名后需要重启代码注册动态生成Skill支持运行时按需注册和业务代码耦合不好维护我建议日常开发用目录扫描把Skill文件丢进~/.codex/skills/目录插件启动时自动加载只有需要动态生成Skill时才用代码注册在初始化阶段调用register_tool()方法传入定义。3. 实操把Postman集合转成Codex Skill3.1 从Postman拿接口定义的两个办法第一条路是界面导出。在Postman的集合菜单里选“导出”格式选OpenAPI 3.0会得到一个JSON文件。好处是快但环境变量和鉴权信息不会出现在里面后期要单独处理。第二条路是用Postman API在线拉取适合集合频繁变动的场景curl -s -H X-Api-Key: $POSTMAN_API_KEY \ https://api.getpostman.com/collections/{collection_uid} \ -o collection.json拿到的是Postman Collection格式比OpenAPI多了很多运行时细节比如auth、event脚本、变量定义转换时信息更全。我一般先导出OpenAPI跑通流程再切到API Key方式做自动同步。3.2 转换脚本一次性生成整个Skills目录下面这个Python脚本输入OpenAPI文件输出多个Skill JSON文件。核心逻辑是遍历paths下的每一个接口提取参数和请求模板import json from pathlib import Path def build_skill(path, method, op): params [] for p in op.get(parameters, []): params.append({ name: p[name], type: p.get(schema, {}).get(type, string), required: p.get(required, False), description: p.get(description, ) }) url_template https://api.example.com path.replace({, ${) return { skill_name: op.get(operationId) or (method _ path.replace(/, _).replace({, ).replace(}, )), description: op.get(summary) or op.get(description) or 调用接口 method.upper() path, parameters: params, request_template: { method: method.upper(), url: url_template, headers: { Authorization: Bearer ${POSTMAN_TOKEN} } } } spec json.loads(Path(openapi.json).read_text()) out Path(skills) out.mkdir(exist_okTrue) count 0 for path, methods in spec.get(paths, {}).items(): for method, op in methods.items(): if method.lower() in (get, post, put, delete, patch): skill build_skill(path, method, op) fname skill[skill_name].replace( , _) .json (out / fname).write_text(json.dumps(skill, ensure_asciiFalse, indent2)) count 1 print(generated, count, skills)注意path.replace({, ${)这一行是把OpenAPI里的/orders/{order_id}转成Skill模板里的/orders/${order_id}这样参数才能被运行时正确替换。脚本里我偷懒统一加了Authorization头真实项目应根据每个接口在Postman里配置的鉴权类型去生成这一步值得花时间做精细。3.3 把生成的Skill注册进Codex我使用的插件SDK支持通过环境变量指定Skill目录export CODEX_SKILLS_DIR$HOME/.codex/skills把脚本生成的JSON文件拷贝到这个目录重启Codex。加载时日志里会出现类似loaded skill query_order_status的信息。建议加载后用一条最简单的命令验证直接问“列出当前可用技能”。如果模型能正确说出几个Skill名字和用途说明注册生效。3.4 第一次真实调用长这样我在会话里输入查一下订单 SO20250201 的状态Codex选择了query_order_status插件SDK实际执行了GET https://api.example.com/v1/orders/SO20250201/status Authorization: Bearer ****返回{code:0,data:{status:SHIPPED,updated_at:2025-02-01 12:33:44}}插件SDK按照response_handling提取了code、data.status、data.updated_at三个字段连同状态码200一起还给模型。模型据此回答“订单已发货更新时间是2月1日12:33。”整个过程不再需要人工复制URL和参数。4. 调试与避坑让Skill稳定跑起来4.1 鉴权信息千万别硬编码Skill文件是会被提交到代码仓库的一旦Token写死在JSON里等于把密钥广播出去了。我一直坚持用环境变量占位在运行时替换。具体做法export POSTMAN_TOKEN你从Postman生成的token不要提交插件启动后SDK会先扫描所有Skill的request_template发现未替换的${}占位符就直接报错避免把未鉴权的请求发出。这个校验逻辑虽然简单但能省掉很多排查时间。4.2 响应体太大模型会原地爆炸一个分页接口默认返回几十条记录每条几百个字段全量回传给模型很容易触发类似maximum context length的报错。我在response_handling里做了两层保护第一层只提取固定字段第二层给返回内容加长度上限超过就截断并追加提示“响应过长已截断可调整分页参数后重试”。response_handling: { mode: summary, extract: [$.code, $.data.items[:5], $.data.total], max_length: 2000 }实测下来截断策略不仅降低了报错概率还让模型回答更聚焦。模型不需要关心无关字段反而能更快找到关键信息。4.3 参数描述写得太泛模型就会乱填我踩过的一个典型坑查询订单接口要求create_date格式是YYYY-MM-DD我在描述里只写了“创建日期”模型直接传了2025/02/01。后端不认返回参数错误。后来我把所有参数的description改成带示例的完整句创建日期格式YYYY-MM-DD例如2025-02-01支持范围是最近90天。同时给参数增加examples字段SDK在调用前做一次正则校验不符合格式就直接拦下并提示模型重新生成。这一项改动把参数类错误减少了大概一半。4.4 本地网络配置异常导致Codex endpoint请求失败调试时我遇到过一整个会话都报failed while handling codex endpoint /responses的情况。一开始以为是插件问题后来发现Codex自己访问endpoint时就不通插件连注册都完成不了。排查顺序建议是先用命令行工具直接请求CODEX_ENDPOINT指向的地址比如发一个最简单的GET /health确认服务是否真的可达。检查当前shell环境变量里是否有残留的网络转发相关配置如果有先清掉再启动Codex。确认本机hosts和路由没有把endpoint地址重定向到错误位置。排到没问题后重启Codex再看日志。这套顺序基本能解决大部分“endpoint不可达”的报错。重点是先确认基础连通性再动插件配置不要一上来就怀疑Skill写错。4.5 Postman动态变量转换后会失效OpenAPI导出时Postman的{{base_url}}、{{$timestamp}}这类变量会被保留为字面量直接放进Skill模板会请求到不存在的路径。我维护了一张映射表VARIABLE_MAPPING { {{base_url}}: ${API_BASE_URL}, {{token}}: ${POSTMAN_TOKEN}, {{$timestamp}}: now_unix }转换脚本在生成Skill时统一替换并把now_unix这类特殊变量交给SDK运行时生成具体值。这一步不做的话后患无穷。5. 进阶从“单接口Skill”到“业务技能组合”5.1 把多个接口封装成一个复合Skill真实业务往往是流程式的。比如“批量退款”需要查订单、校验状态、执行退款、发通知四个步骤。如果每个步骤都是独立Skill模型需要连续调四次中间任何一次理解偏差都会导致流程中断。我在插件里实现了复合Skill用代码把一个流程写死对外只暴露一个入口def batch_refund(operator, order_ids): result [] for oid in order_ids: order query_order(oid) if order[data][status] not in (PAID, PARTIAL_REFUND): result.append({order_id: oid, error: 不可退款状态}) continue refund do_refund(oid, operator) notify(operator, oid, refund_done) result.append({order_id: oid, refund_id: refund[data][refund_id]}) return {results: result}Codex只需要管“把哪些订单号传给这个Skill”内部逻辑全部由插件控制。这样既减少了模型出错的机会又把业务规则收敛到代码里方便测试和审计。5.2 把Postman断言脚本变成Skill的自动检查器Postman集合里本来就有Tests脚本用来判断接口正不正常。我把这些断言转换成verification配置verification: [ {type: json_path, path: $.code, expected: 0, error_message: 业务返回码不为0} ]每次API调用返回后SDK先执行这些断言再决定把什么样的结果写给模型。如果断言失败模型拿到的不是原始响应而是一条明确的“该接口异常原因业务返回码不为0”。这让智能体在调接口时具备一定的自我纠错能力。5.3 让Skill跟Postman集合持续同步Postman集合是活的接口会加字段、改地址。如果Skill创建完就不管过两周就会和真实接口脱节。我做了一个定时任务每天凌晨从Postman API拉取最新集合跑转换脚本生成Skill然后对变更的Skill执行一轮冒烟测试测试通过才覆盖到生效目录。这套同步链路跑下来Codex手里的Skill一直是新鲜的不需要人工维护。5.4 一个有趣的实验让Codex基于现有Skill发明新Skill基础接口都开放成Skill之后模型能做的事比我预想的多。有一次我问它能不能把“查库存”和“下采购单”两个接口组合成一个自动补货工具它真的基于现有Skill的结构生成了一段新的复合Skill草稿我审了一下逻辑稍微改两句就能用。这个方向很有价值但也提醒我要注意权限管控。Skill一旦开放组合就相当于把内部系统能力开放出去必须保证每个底层接口都有独立鉴权不能因为复合Skill的存在而绕过权限。最后再分享一个小体会把API能力交给智能体本质上是把执行权交给模型。一定要先划清楚边界Skill里只暴露该暴露的字段凭证全部环境变量注入入参加强校验。我这次实践最有价值的收获不是省了多少手工活儿而是验证了一套“Postman资产→Codex Skill→自动执行→自动校验”的闭环目前已经在团队里推广开了。