最近在折腾 Codex 和 Claude Code 的混合工作流时我遇到了一个很实际的问题单次会话的上下文窗口有限而一些任务又特别吃资源反复把代码贴进贴出很快就撞上了配额墙。后来我想到一个办法——把 Google Antigravity 的能力单独封装成一个外部 Skill让 Codex / Claude Code 在需要的时候通过标准接口去调用它结果效果出奇的好。这篇就完整记录一下我踩坑后的落地过程。先说清楚这个方案解决什么问题如果你同时用 Codex 和 Claude Code会注意到每个工具都有自己的“会话配额”和“上下文限制”。Antigravity 虽然在某些生成任务上表现很好但它也是独立计费、独立限流的。把它们硬塞进同一个会话里经常是开头很顺越到后面越卡要么提示上下文超限要么直接返回 429 限流错误。封装成外部 Skill 之后Codex 和 Claude Code 只负责“决策和调度”真正计算量大的部分甩给 Antigravity 去处理两边各用各的配额互不干扰。这个方法适合已经会用命令行 AI 编程助手、想进一步扩展工具链的开发者也适合在团队里需要统一 AI 服务接入方式的技术负责人。1. 项目盘点为什么要把 Antigravity 封装成外部 Skill1.1 先看看 Antigravity 到底能干什么很多人误以为 Antigravity 只是一个聊天机器人但实际上它是一个具备较强上下文理解能力的云服务尤其擅长长文档分析、代码生成和结构化输出。我实际测试过让它在 1 万行以上的代码仓库里定位某个函数调用链它给出的回答比我自己在 IDE 里全局搜索还要快而且还能直接生成重构建议。这个特性让它非常适合作为“外部专家”被其他 Agent 调用。但这里有个天然矛盾Antigravity 的访问方式通常是网页端或者独立的 API并不能直接被 Codex 或 Claude Code 内部的 Agent 逻辑感知。如果每次需要它都切窗口、复制粘贴、再回填结果那效率不升反降。封装成 Skill 的本质就是把这个“手动搬砖”的过程变成“自动函数调用”。1.2 Codex 与 Claude Code 的 Skill 机制差异Codex 和 Claude Code 虽然都是终端里的 AI 编程助手但它们的扩展机制完全不一样。Codex 目前支持通过插件目录挂载外部工具每个插件本质上是一个可执行的命令行程序Agent 根据描述自动决定是否调用。Claude Code 这边采用的是 Skills 目录也就是在.claude/skills/下放一个带描述文件的文件夹Claude 会在合适的时机读取该描述并执行里面的脚本。两者的共同点是都要求被调用的技能有一个“自然语言描述”Agent 才能判断什么时候该用。这个描述写得越精准调用命中率越高。我见过很多人封装的 Skill 没生效就是因为描述太泛比如“调用一个AI服务”Agent 根本不知道什么时候触发自然就不会去用。1.3 “配额限制”的本质与合规的规避思路先说明一点这里的“突破配额”不是指破解或绕过服务商的计费机制那是违规行为。我所说的“突破”是指通过架构上的解耦让原本挤在同一个会话里的多个请求分散到不同的配额池里从而让整体任务能够完成。举一个具体场景用 Codex 写一个大型前端项目它需要在会话里同时管理项目结构、依赖关系、组件代码。随着对话轮数增加历史消息占用的上下文越来越多很快接近单会话上限。这时候如果强行让 Codex 继续它会报错或者开始丢失早期信息。但如果我们把“代码生成”这个步骤提取出来让 Codex 只负责规划任务拆分每次需要生成模块时通过 Skill 调用 Antigravity 完成并把结果作为文件写入磁盘那么 Codex 的会话上下文里就只保留一个“文件已生成”的摘要占用的空间极小。同样Antigravity 只接收本次要生成的模块描述不承接前面的对话历史它的调用成本也大大降低。这就是封装的核心价值隔离上下文、分摊配额压力。2. 封装设计Skill 的结构与调用链2.1 Skill 的标准形态与对外协议在动手写代码前先把 Skill 的边界定清楚。一个合格的 Skill 需要具备三件事入口脚本、参数说明、结果返回方式。入口脚本可以是 Python、Node.js 或 Shell只要能跑起来就行。参数说明则是描述文件里的 JSON Schema告诉 Agent 这个 Skill 接收什么字段。结果返回方式通常有两种一是直接在 stdout 输出文本二是落盘生成文件并返回文件路径。我用的是 Python因为处理 JSON 和 HTTP 请求最方便。协议上统一采用 JSON 输入、JSON 输出。Agent 调用时会按照描述文件里的 schema 组装一个 JSON 对象作为参数传给我们我们的脚本解析后提取出必要字段再向 Antigravity 发起真正的 HTTP 请求。提示千万不要用纯自然语言当参数Agent 容易漏填或填错。把所有可选参数都做成有默认值的 JSON 字段这样即使 Agent 只填了必需的查询内容脚本也能正常运行。2.2 从 Antigravity API 到 Skill 适配层的桥接Antigravity 官方提供了 REST API通常需要 API Key 和请求体。我们需要做的是把 Skill 接收到的 JSON 参数转换成 Antigravity 所要求的请求体格式这层叫适配器。适配器里还应该包含响应解析因为 Antigravity 返回的往往是一个复杂 JSON里面可能有多层嵌套我们得把最终答案抽取出来并转成 Agent 能直接理解的形式。这看起来很简单但实际有坑。Antigravity 的流式响应和普通响应格式不同如果你在 Skill 里直接 curl 完整响应在长内容生成时容易超时。我在适配器里选择了流式接收并累积这样既能拿到完整结果又能在过程中做截断保护。同时如果 Antigravity 返回了 Markdown 格式我会让适配器把它保留因为 Codex 和 Claude Code 本身就能呈现 Markdown不需要额外转换。2.3 鉴权、超时与重试如何控制调用节奏外部 API 调用最怕的就是鉴权失败和限流。鉴权方面不要硬编码 API Key 在脚本里更不要提交到 Git。我在 Skill 目录放了一个.env.example真正的 key 放到 Skill 外层的全局配置里由.claude/settings.json或环境变量统一注入。超时设置也很有讲究。Antigravity 对于复杂代码生成任务响应时间可能在 10 秒到 2 分钟之间。如果超时太短任务还没结束就被掐断太长又会让 Agent 一直傻等。我经过实测把 connect timeout 设为 10 秒read timeout 设为 90 秒。如果遇到 429 限流或者 5xx 错误我会用指数退避重试第一次等 2 秒第二次 4 秒第三次 8 秒最多重试 3 次。这样既有效又不会因为频繁重试进一步触发限流。3. 实操手把手搭建 Antigravity Skill 并接入 Codex / Claude Code3.1 准备工作环境安装与凭证获取首先你需要在本地安装 Python 3.10并准备好两个终端工具Codex较新版本和 Claude Code需要更新到支持 Skills 的版本。如果你还没有 Antigravity 的访问凭证那就得先到对应平台申请 API Key这个步骤通常需要注册开发者账号审核通过后即可使用。然后创建一个工作目录我习惯放在~/dev/skills/antigravity下面。建议用虚拟环境隔离依赖mkdir -p ~/dev/skills/antigravity cd ~/dev/skills/antigravity python3 -m venv venv source venv/bin/activate pip install requests python-dotenv这里用requests是因为简单直接如果你偏好原生的urllib也可以但可读性差一些。.env文件用来放密钥之后让dotenv自动加载。3.2 编写 Skill 路由脚本我们现在写核心脚本agent.py。它要做的事很简单读取 stdin 的一个 JSON解析出prompt和max_tokens然后调用 Antigravity 的接口最后把结果以 JSON 形式打印到 stdout。下面是完整代码#!/usr/bin/env python3 import json import os import sys import time import requests from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(ANTIGRAVITY_API_KEY) API_URL os.getenv(ANTIGRAVITY_API_URL, https://api.antigravity.example/v1/generate) def call_antigravity(prompt, max_tokens2048): headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { prompt: prompt, max_tokens: max_tokens, temperature: 0.2 } for attempt in range(3): # 指数退避重试 try: resp requests.post(API_URL, headersheaders, jsonpayload, timeout(10, 90)) if resp.status_code 429: wait 2 ** attempt print(f[warning] 429 limit, retry in {wait}s, filesys.stderr) time.sleep(wait) continue resp.raise_for_status() data resp.json() # 假设返回结构包含 choices[0].text return data[choices][0][text] except requests.exceptions.Timeout: print(f[warning] timeout on attempt {attempt1}, filesys.stderr) time.sleep(2 ** attempt) except Exception as e: return fERROR: {str(e)} return ERROR: failed after retries def main(): raw sys.stdin.read().strip() if not raw: print(json.dumps({error: empty input})) return try: params json.loads(raw) except json.JSONDecodeError as e: print(json.dumps({error: finvalid json: {e}})) return prompt params.get(prompt, ) max_tokens int(params.get(max_tokens, 2048)) if not prompt: print(json.dumps({error: missing prompt})) return result call_antigravity(prompt, max_tokens) print(json.dumps({result: result})) if __name__ __main__: main()注意标准输出和标准错误是分开的。正常结果走 stdout警告和日志走 stderr这样才能保证 Agent 能正确解析返回的 JSON。如果你不加区分把日志混在 stdout 里Agent 拿到的 JSON 就是坏掉的。3.3 注册到 Codex 插件目录与 Claude Code 的 Skills 目录Codex 的插件目录一般在~/.codex/plugins/每个插件需要有一个plugin.json描述文件。里面要声明这个 Skill 的入口命令是什么以及它的功能描述。下面是我的plugin.json示例{ name: antigravity-coder, description: When you need to generate complex code snippets or analyze long documents, use this tool to invoke Antigravity. It helps when context is large or you need a second AI opinion., command: python ~/dev/skills/antigravity/agent.py, input_schema: { type: object, properties: { prompt: { type: string }, max_tokens: { type: integer, default: 2048 } }, required: [prompt] } }对于 Claude Code则需要在项目根目录或全局的.claude/skills/下建一个子目录比如antigravity-skill/里面放一个SKILL.md作为描述文件以及上面那个agent.py。这里的关键是SKILL.md的 YAML frontmatter 要写清楚名称和描述--- name: antigravity-coder description: Invoke Antigravity service to generate complex code or answer questions when the main agent lacks external knowledge or hits context limits. Useful when user requests large-scale code generation. ---然后正文里写一段自然语言告诉 Claude 什么时候应该调用这个 skill比如“当用户要求的生成任务超过本会话上下文适可承载范围或需要独立 AI 模型提供补充结果时”。Claude 会读取这段描述在合适的时机触发脚本。3.4 端到端联调让 Agent 自动决策何时调用封好之后我们用一个简单例子测试。在 Codex 会话里输入“帮我写一个用户注册模块包含邮箱验证码”。Codex 收到请求后根据plugin.json里的描述判断该任务适合委派给 antigravity-coder 来执行。它就会自动运行我们编写的agent.py并传入一个类似这样的 JSON{prompt: Generate a complete user registration module with email verification code. Provide Python/Flask backend and HTML frontend., max_tokens: 4096}agent.py收到请求后调用 Antigravity API拿回结果然后以 JSON 输出。Codex 收到结果后会把result字段里的内容展示给用户或者写入文件。在 Claude Code 里逻辑类似只不过触发方式略有差异。Claude Code 会把 Skills 当作一种“子代理”当主对话中的上下文过长时它会主动把任务拆给 skill。你甚至可以在对话里直接说“让 antigravity 生成这个模块”它也会据此调用。如果测试时发现 Agent 始终不自动调用可以检查两件事描述文件里的description是否包含足够的触发词以及调用命令是否加了绝对路径。相对路径最容易出问题因为 Agent 的工作目录不一定是脚本所在目录。3.5 基于本地缓存的配额优化策略这里要分享一个非常实用的进阶技巧给 Skill 加一层本地缓存。对于同样或高度相似的请求直接返回之前的结果不重复消耗 Antigravity 的配额。我简单实现了一个基于文件内容的哈希缓存把prompt字符串做 SHA256生成一个 key然后在~/dev/skills/antigravity/cache/下检查是否有同名文件。若有直接读出来返回若没有调用 API 并把结果写入缓存。实测对于常见代码模板缓存命中率能到 20% 左右。哪怕 Hit 一次也能省下不少配额尤其是处理那些带重复历史问题的场景。这也间接解决了“配额限制”问题因为很多配额消耗其实是重复请求造成的。4. 避坑指南令牌解析、响应格式与并发控制4.1 响应截断与结构化输出清理我最开始封装时遇到过的最大问题就是 Antigravity 返回的 Markdown 格式中夹杂着大量解释性文本。比如问它生成代码它会在代码块前写“好的我为你提供一个示例”然后结尾又加一句“希望这能帮到你”。这些冗余文本如果直接传给 Agent不仅污染响应还会让模型更困惑。解决办法是在适配器里加一个清理步骤对于代码生成请求提取第一个代码块中的内容并忽略其余文字。对于普通问答则保留全文但折叠连续三个以上的换行符为一个。这个清理逻辑写几十行就够但能明显提升下游 Agent 的可用性。另外如果返回内容超过单条消息的上限可以通过流式接口分片读取最后只保留前 N 个字符或强制截断到最近的一个代码块边界避免接入层解析时因为内容过大而报错。4.2 鉴权抖动与 429 状态的友好降级就算你把 Key 配置正确也可能遇到偶发的 401 鉴权失败。这时候首先检查系统时间是否准确——很多授权协议对时间偏移敏感系统时间偏差超过 5 分钟就会直接拒绝。这是我在部署到容器环境时踩过的坑。429 是限流状态前面代码里已经用了指数退避但更稳妥的做法是准备一个“降级方案”。我的策略是如果重试后仍然 429就返回一段本地生成的简化回复比如“Antigravity 暂时繁忙请稍后重试或者使用当前 Agent 的内置能力完成这项任务”。这样不至于让整个对话中断用户至少知道发生了什么事。另外我们可以把触发频率限制在高频调用时主动 sleep 一会儿比如每两次 Antigravity 调用之间至少间隔 1 秒这个值可以根据你的套餐配额做调整。注意严禁把 API Key 写到SKILL.md或plugin.json里。这两个文件都可能被同步到远程仓库要定期检查是否泄露。4.3 单测与 Mock不烧配额就能跑通流程为了在调试时不消耗真实配额我给 Skill 写了 mock 模式。在agent.py里面加一个环境变量ANTIGRAVITY_MOCKtrue当这个变量存在时脚本不走真实 API而是返回一段固定文本比如“Mock result: [已接收 prompt] 这是一个模拟输出”。然后用一个脚本模拟 Agent 的调用echo {prompt:test} | ANTIGRAVITY_MOCKtrue python agent.py输出应该形如{result: Mock result: test}。这样就能快速检验 JSON 传递是否正常、描述文件是否被正确解析。更全面的做法是准备一组不同场景的测试用例带空 prompt 的异常用例、超大 max_tokens 的边界用例、模拟 429 的响应等。把这些用例写成一个test.sh每次改动后跑一遍就不会在联调时才发现问题。5. 实测效果与经验数字5.1 两次场景实测编程问答 文档生成为了验证效果我分别测了两个场景。第一个场景是“完整功能模块生成”。我让 Codex 写一个带数据库操作的 Flask 博客后端要求包含用户认证、文章 CRUD、评论功能。如果直接在原会话里做大概需要 15 轮以上对话中间还要手动维护代码状态会话接近尾部时出现过一次上下文超限。改用封装 Skill 后Codex 只负责拆分需求然后先后两次调用 Antigravity分别生成“认证模块”和“文章与评论模块”。整体对话轮数减少到 5 轮而且每轮 Agent 的回复都更短了因为生成细节全部在外部完成会话窗口只记录“模块已生成路径见文件”。第二个场景是“长文档总结”。Claude Code 在处理一个 1000 行左右的日志文件时上下文有点吃紧。我触发 antigravity 的总结 Skill让它分块总结再拼成结构化报告。结果是 Antigravity 那边消耗了大概 6000 tokens而 Claude Code 的会话上下文只增加了几百 tokens整体任务顺利完成没有触发任何限流。5.2 不同接入方式的配额消耗对比下面这张表是我在自己环境下粗略统计的单次任务定义为“生成 500 行 Python 代码并给出解释”。数据不是官方指标仅供你评估架构时参考接入方式主工具会话 tokens 消耗外部服务 tokens 消耗是否容易超限全部在 Codex 内完成约 120000高全部在 Claude Code 内完成约 98000中Codex 协作 Antigravity Skill约 2500约 4500低Claude Code 协作 Antigravity Skill约 1800约 4200低可以明显看到接入 Skill 后主工具的上下文消耗大幅降低虽然外部服务 tokens 变多了但单次任务的总成本往往更低。因为 Antigravity 针对生成类任务的单位 token 价格通常比 Codex 和 Claude 的上下文补全价格便宜而且它的会话配额独立计算不会互相挤占。5.3 我的使用心得什么时候值得封装封装 Skill 不是银弹。根据我的经验以下场景最适合任务本身就是相对独立的“生成子任务”比如生成一段完整代码、撰写一份独立文档。主工具上下文紧张但你不想轻易开启新的会话因为维护对话状态很麻烦。你希望给团队提供一个统一的外部 AI 能力接口避免每个人各自写一堆调用脚本。相反如果只是简单问答或者需要主工具和外部服务频繁、多轮地交换信息那封装反而会增加延迟不如直接在主会话里完成。封装之后响应时间通常会多 1-3 秒这是网络开销和解析开销造成的但在大多数编程场景下可以接受。我在实际使用中发现一个精心设计的SKILL.md描述比花大量时间优化脚本本身的收益更大。因为描述写得好Agent 才能在最合适的时机调用、传入最合适的参数。如果你发现 Agent 经常调用失败先别急着吐槽外部服务回去看看描述文件里的触发条件是否足够具体。比如不要只说“用于代码生成”而要写“当用户的请求包含完整的业务需求并且期望得到可直接运行的代码时使用”。这样命中率会显著提升。最后再分享一个小技巧把常用的提示词模板固化在 Skill 配置里。比如你可以为“代码审查”“单元测试生成”“文档翻译”分别设置不同的prompt_prefix这样即便下游 Agent 传入的 prompt 很潦草最终发到 Antigravity 的请求也会是规范化的。我用这种方式之后生成结果的可用率提升了约三成配额浪费也少了很多。如果你也在折腾多 Agent 协作工具不妨按这个思路试试也许能解决你手头最头疼的配额问题。