Codex 用 ChatGPT 账号登录后,内置的 web_search 工具会调 POST https://chatgpt.com/backend-api/codex/alpha/search 联网搜索。我把这个接口接进 pi,做成了扩展 websearch。
下面顺带测了下它的调用方式、额度消耗、并发上限和搜索质量(数据均来自 2026 年 9 月 1 日实测)。
接口
接口地址和请求格式翻自 GitHub 上的 Codex 源码:codex-rs/codex-api/src/endpoint/search.rs 负责发请求,codex-rs/codex-api/src/search.rs 定义请求和响应结构。
请求头需带两项凭据:
Authorization:Bearer加 ChatGPT 登录后拿到的 access token。chatgpt-account-id:账号 ID,从 access token(JWT)的https://api.openai.com/auth.chatgpt_account_id字段里取。
请求体:
{
"id": "会话 ID,同一会话里的 open、find 会用到前面搜索的结果",
"model": "gpt-6-luna",
"commands": {
"search_query": [{ "q": "Astro 7 release date" }],
"response_length": "short"
},
"settings": {
"search_context_size": "medium",
"allowed_callers": ["direct"],
"external_web_access": true
},
"max_output_tokens": 6000
}
commands 支持在单次请求里组合多个命令:
| 命令 | 作用 |
|---|---|
search_query、image_query | 文字搜索、图片搜索。search_query 最多 4 条 |
open、click、find、screenshot | 打开搜索结果或任意网址,点击页面链接,页内查找文字,截图 |
weather、time、finance、sports | 天气、时间、股价、体育比分 |
response_length | short、medium 或 long,控制每条结果带多少正文 |
响应包含三个字段:
output:给模型读的纯文本,包含标题、网址、发布与抓取时间,以及带引用编号(如turn0search0)的网页正文。results:结构化结果列表,每条含title、url、domain、snippet和ref_id。encrypted_output:Codex 内部用的加密字段,不用管。
普通搜索大约 2~3 秒返回。
不消耗额度
可以通过 GET https://chatgpt.com/backend-api/wham/usage 查账号用量,返回每周已用百分比 used_percent 和精确到小数点后 10 位的余额 credits.balance。
实测连跑 204 次搜索、拉回 400 多万字符的网页内容,前后两项数据完全没变:
| 测试前 | 测试后 | |
|---|---|---|
| 每周用量 | 48% | 48% |
| 额度余额 | 52512.7638435000 | 52512.7638435000 |
另外,调模型接口 /codex/responses 时响应头都会带 x-codex-primary-used-percent、x-codex-credits-balance 等计费字段,而搜索接口的响应头里完全没有——说明搜索确实不计入模型额度。
并发
用同一个账号同时发出 10、25、50、100 个搜索请求。10~50 并发时轮流用 20 个关键词,100 并发时每个请求的关键词都不同:
| 并发数 | 成功 | 失败 | 中位延迟 | 最慢 |
|---|---|---|---|---|
| 10 | 10 | 0 | 2.5 s | 5.8 s |
| 25 | 25 | 0 | 2.6 s | 3.9 s |
| 50 | 50 | 0 | 2.7 s | 6.2 s |
| 100 | 98 | 2(503) | 4.9 s | 13.4 s |
全程没有触发 429 限流。100 并发下只有 2 个请求报 503(upstream connect error or disconnect/reset before headers),属于上游连接断开,重试即可;中位延迟也只从 2.7 秒升到 4.9 秒。日常给 agent 跑几个并发完全够用。
质量
时效性不错,比如搜“Astro 7 release date”,第一条就是两天前刚抓取的 Astro 官方博客。
几个好用的点:
output直接带网页正文而不只是摘要,agent 拿到就能直接读,大部分时候不用再调open进网页。- 单次请求最多塞 4 条查询。实测 4 条合在一起返回 41 条结果,耗时 2.5 秒,和单查 1 条差不多。
- 天气、时间、股价这类查询直接给结论,比如查北京天气会直接返回当前温度和未来几天预报。
open支持直接打开任意网址,不需要先搜索。
也有几个坑:
- 输出有截断上限:
max_output_tokens默认 6000,实测最多输出 24003 字符,超出直接截断。拉满到 128000 后,response_length设short、medium、long分别能拿到约 1.6 万、2.5 万和 3.5 万字符。 - 域名限定不够准:限定搜
docs.astro.build时,排在前面的反而是v7-2.previews.docs.astro.build这类预览站和v5.docs.astro.build旧文档。 - 中文结果偏杂:搜“荒野乱斗 最新 平衡性调整”,会混进《荒野行动》的新闻,靠前的也多是低播放量的 YouTube 视频。
find不会只返回匹配行,而是从第 0 行开始截一段原文。我在扩展里加了一层本地过滤,只保留匹配行及上下两行。- 请求体里的
model字段基本是摆设,随便填个不存在的no-such-model也能正常返回 200。
在 pi 里使用
安装扩展:
pi install git:github.com/Mist-wu/pi-extensions
然后在 pi 里跑 /login 登录 OpenAI Codex 即可(扩展直接复用 pi 保存的凭据,不读 ~/.codex/auth.json)。
可通过环境变量调整输出:
export PI_CODEX_WEB_SEARCH_CONTEXT_SIZE=high # low、medium、high,默认 medium
export PI_CODEX_WEB_SEARCH_MAX_OUTPUT_TOKENS=8000 # 1 到 128000,默认 6000
风险
/codex/alpha/search 毕竟是未公开的内部 alpha 接口,随时可能改格式或下线。扩展里把发请求的代码收拢在一处,真改了也方便跟进。