Codex 添加自定义 Skill 实战指南：从零构建到生产环境部署

共计 2105 个字符，预计需要花费 6 分钟才能阅读完成。

为什么需要自定义 Skill？

对接过 Codex API 的开发者常遇到这些头疼问题：

• 每次请求都要处理复杂的 JWT 鉴权流程
• 响应格式校验会吃掉 30% 的开发时间
• 本地测试和线上环境行为不一致
• 上下文对话状态管理像在走钢丝

这些痛点让很多好想法卡在对接阶段。今天我们用一个天气预报 Skill 的实战案例，带你打通全流程。

一、从 manifest 开始

Skill 的身份证就是 manifest.json，建议用 VS Code 的 JSON Schema 功能实现自动校验：

{
  "skillId": "weather-forecast-v1",
  "version": "0.1.0",
  "name": "天气助手",
  "description": "提供国内主要城市三天天气预报",
  "entryPoint": "https://your-api.com/weather",
  "authentication": {
    "type": "JWT",
    "algorithm": "HS256"
  },
  "contexts": ["city", "date"]
}

关键字段说明：

• entryPoint 建议先配置本地调试地址如 http://localhost:5000
• contexts 声明本 Skill 需要维护的对话上下文
• 生产环境记得配置 rateLimit 字段

二、用 Python 搭建处理框架

推荐使用 FastAPI 快速搭建服务，这个异步框架对 Codex 的 Webhook 调用非常友好：

from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel
import jwt

app = FastAPI()

# 鉴权中间件
async def verify_token(req: Request):
    token = req.headers.get("Authorization")
    try:
        payload = jwt.decode(token, "YOUR_SECRET", algorithms=["HS256"])
        return payload
    except jwt.PyJWTError:
        raise HTTPException(status_code=401)

# 请求体结构
class WeatherRequest(BaseModel):
    city: str
    date: str = None  # 可选参数
    context: dict = None

@app.post("/weather")
async def get_weather(req: WeatherRequest, auth=Depends(verify_token)):
    # 业务逻辑
    return {"text": f"{req.city} 明天晴转多云",
        "context": {"last_city": req.city}  # 更新上下文
    }

几个关键点：

1. 使用 Pydantic 做自动参数校验
2. JWT 鉴权通过依赖注入实现
3. 返回结构必须包含 text 字段

三、调试技巧

在 VS Code 中配置 launch.json 实现一键调试：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Skill",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": ["main:app", "--reload"],
      "env": {"SECRET_KEY": "your_local_key"},
      "jinja": true
    }
  ]
}

调试时建议使用 Postman 构造带上下文的请求：

{
  "city": "北京",
  "context": {"last_choice": "温度"}
}

四、生产环境优化

当流量上来后要注意：

1. 连接池 ：aiohttp.ClientSession 要全局复用

   async def get_forecast(city):
       async with session.get(f"{API_URL}?city={city}") as resp:
           return await resp.json()

2. 缓存 ：对城市数据用 LRU 缓存

   @lru_cache(maxsize=32)
   def get_city_code(city_name):
       return db.query(City).filter_by(name=city_name).first().code

3. 安全 ：

4. 使用 HTTPS 加密
5. 城市参数要做白名单校验
6. 定期轮换 JWT 秘钥

五、常见踩坑点

1. 部署 403 错误
2. 检查 manifest 的 entryPoint 是否已更新为生产地址

3. 确认服务器时间与 NTP 同步（JWT 校验对时间敏感）

4. 上下文丢失

5. 确保每次响应都返回完整 context

6. 对话超时建议设置 10 分钟

7. 性能瓶颈

8. 用 async/await 避免阻塞调用
9. 第三方 API 调用添加 timeout 限制

思考题

当用户问 ” 北京和上海下周哪里更适合旅游 ” 时，如何设计多 Skill 协作流程？是否需要引入调度中心？欢迎在评论区分享你的架构设计。

通过这套方法，我们团队将 Skill 开发周期从 3 周压缩到了 5 天。关键是先吃透 manifest 规范，再通过自动化测试覆盖主要对话路径。现在你可以试着把查天气改成查航班，体会下 Codex 的扩展性有多强。