十分钟实用教程 | 让小黄鸟(Reqable)接上 Claude / Codex:把抓包变成自动 API 分析流水线

转载自公众号：敢敢AUTOHUB

0. 简介

Reqable(小黄鸟)是一款用 Flutter + C++ 写的跨平台抓包与 API 调试工具,把 MITM 代理抓包、断点改写、Python 脚本和 REST 调试揉在一个界面里。它解决的具体矛盾是:传统工作流要在抓包工具和接口测试工具之间来回复制粘贴,每一步都靠人肉搬运请求。真正让这套流程能再往前一步的,是 Reqable 已经把流量数据向外暴露的两条通道打通了——官方内置 MCP,以及社区发布到 PyPI 的 reqable-mcp,两者都让 Claude、Codex 这类 AI 助手能直接读取本机抓到的请求。从 reqable-mcp 公开的 17 个工具看,最值得关注的是它把"抓包 → 本地 SQLite → AI 分析"做成了默认不出本机的闭环。下面结合官方文档与 reqable-mcp 的公开说明,重点拆解三件事:AI 怎么读到抓包数据、能自动分析出什么、以及怎么让 AI 反过来自动改写流量。

1. 为什么值得把抓包工具接上 AI

1.1 人肉搬运的回环

先厘清动机。做接口联调的人都熟悉那套回环:抓包工具里翻请求,复制 URL、复制 Header、复制 Body,粘到 Postman 或代码里,人肉比对响应,最后再手写一份接口文档。这套流程的每一环都卡在"手"和"眼睛"上,工具再快也快不过人肉搬运的速度。日积月累,大量时间耗在"把一份数据从这个窗口挪到那个窗口"上,而这恰恰是程序最该替人干的活。

1.2 抓包工具握着一份程序可读的数据

这里的关键是,抓包工具其实握着一份结构完整的流量数据——请求方法、路径、查询参数、头、体、响应码、响应体,全都在。问题只是这份数据以前只给人看,不给程序读。一旦把它通过标准协议暴露给 AI,分析、写文档、生成代码这些活儿就能从"人肉搬运"变成"自然语言驱动"。这一步跨过去,抓包工具就从"给人看的仪表盘"变成了"给 AI 供数据的接口"。

Reqable 之所以能担这个角色,靠的是两个和 AI 结合直接相关的硬条件。 第一,它官方内置了 MCP(Model Context Protocol)支持,文档里明确点名 Claude、Cursor、Codex 可以直接和 Reqable 应用交互。第二,它内置 Python 脚本框架,onRequest / onResponse 钩子能在流量经过时改写请求和响应,天然适合承接 AI 生成的处理逻辑。加上它非浏览器套壳、启动快、数据本地存储,做本地自动化流水线的底子是够的。

直觉理解:可以把 Reqable 想象成一个会速记的书记员。以前它把每次通话内容(请求/响应)记在小本子上,只有你亲自翻本子才看得到。MCP 相当于给这个书记员配了个电话分机,Claude 打过去就能直接问"刚才那几通电话都聊了啥",不用你把本子一页页念给它听。

2. 三条打通通道:先看清全景

2.1 三种能力,三条通道

把 Reqable 和 AI 打通,不是只有一条路。实际有三条互补的通道,分别对应"读取分析""操作应用""改写流量"三种能力。写代码前先把全景摆清楚,免得后面选型时纠结。三条通道不是互斥的,实际用起来往往是通道 A 读、通道 C 改配合着上。

通道	载体	适合做什么	成熟度
A. 社区 `reqable-mcp`	PyPI 包 + 本地 SQLite	让 AI 读取/分析历史抓包,推断 API 结构、生成代码	高(推荐首选)
B. 官方 MCP	Reqable 内置	让 AI 直接操作 Reqable 应用	官方,随版本演进
C. Python 脚本	Reqable 内置脚本引擎	让 AI 生成改写请求/响应的自动化逻辑	高

2.2 主线选型:为什么以通道 A 为主

换句话说,通道 A 和 B 让 AI "读得到"你的流量,通道 C 让 AI 的判断"改得动"流量。本文以通道 A 为主线搭自动分析流水线,通道 C 作为自动改写的补充。通道 B 是官方能力,随版本演进,配置方式以官方 MCP 文档为准。之所以主推通道 A,是因为它把"读取分析"这条最高频的需求做得最完整,且默认本地闭环,适用边界最清晰,后面第 3 节会详细展开它的架构和工具。

3. 用 reqable-mcp 搭自动分析流水线

这是全文主线。reqable-mcp 是一个发布在 PyPI 上的社区包(v0.3.2,2026 年 5 月),定位是"把本机 Reqable 抓到的流量暴露给 MCP 客户端"。选它当主力,是因为它把"读取分析"这条最高频的需求做得最完整。

3.1 它的架构:全本地,默认不走云

先看清数据往哪走,再决定敢不敢把它接到真实项目上。reqable-mcp 的默认架构是本地闭环:

1. Reqable 把 HAR(JSON) 推送到  <http://127.0.0.1:18765/report>
2. (可选) 增量 WebSocket 事件推送到  <http://127.0.0.1:18765/ws/events>
3. reqable-mcp 归一化后存进本地 SQLite
4. MCP 工具只查询本地数据(默认不做云端中转)

这里的关键是第 4 条:MCP 工具查的是本机 SQLite,默认不做云端中转。流量数据不离开本机,这是能把它接到公司内部接口上的前提。 抓包数据里往往带着 Token、Cookie 这类敏感信息,如果工具默认把它们传到某个云端,这套方案在企业场景基本没法用。本地闭环这一点,决定了它的适用边界。

工程价值:很多"AI + 抓包"的设想卡在数据合规上——你不敢把带鉴权信息的真实流量喂给一个会外传的服务。reqable-mcp 默认本地 SQLite、本地查询的设计,把这道坎降低了。但要注意"默认不走云"约束的是这个包本身,你接的 AI 客户端(尤其云端大模型)会不会外传,得另外确认,这一点第 6 节还会展开。

3.2 前置条件

动手前确认三样东西齐全,这几项都是 reqable-mcp README 里列出的运行前提,缺哪一样后面都会卡住:

• 安装并打开 Reqable。

• 本机有 Node.js(提供 npx)与 uv(提供 uvx)。

• Python 版本 >= 3.10。

其中 uv 尤其别漏,后面用 uvx 免安装拉起服务这一步全靠它;缺了 uv,uvx reqable-mcp 会直接报找不到命令,链路第一步就断。装 uv 一行命令即可,官方给的方式是 curl -LsSf <https://astral.sh/uv/install.sh> | sh。

3.3 第一步:在 Reqable 里配置 Report Server

Report Server 是 Reqable 的一个功能,作用是把抓到的流量自动推给一个指定的 HTTP 端点,这里我们让它推给本机的 reqable-mcp,让抓包和数据落库自动衔接,不用手动导出。在 Reqable 里"Add Report Server",按下面四项填:

Name:reqable-mcp-local

Match rule:(或只填你要分析的目标域名,减少噪音)

Server URL:http://127.0.0.1:18765/report

Compression:None(或与接收端保持一致)

这里要厘清的是 Match rule。填 * 会把所有流量都推过去,数据全但噪音大;实际用的时候,更推荐只填目标域名,既减少无关数据,也顺带缩小了敏感信息的采集面。保存后先随手抓几个请求,后面用 ingest_status 工具就能看到收到了多少条。

3.4 第二步:把 reqable-mcp 接到 Claude / Codex

reqable-mcp 是标准 MCP 服务,任何 MCP 客户端都能接,下面给 Claude Code 和 Codex CLI 两份配置,你按用的客户端挑一份。Claude Code 用项目根目录的 .mcp.json(或用户级 MCP 配置),把 reqable 这一项加进 mcpServers:

{
  "mcpServers": {
    "reqable": {
      "command": "uvx",
      "args": ["reqable-mcp"]
    }
  }
}

Codex CLI 走的是 ~/.codex/config.toml,格式换成 TOML,但表达的是同一件事——注册一个叫 reqable 的 MCP server,用 uvx 拉起:

[mcp_servers.reqable]
command = "uvx"
args = ["reqable-mcp"]

这两份配置都用 uvx 免安装直接拉起服务——uvx reqable-mcp 会在需要时临时拉包并运行,省去手动 pip install。换句话说,只要 uv 在,你不用先装包。如果你偏好显式安装,先 pip install reqable-mcp,再把 command 换成 reqable-mcp 本体即可。具体端口和环境变量以该包 README 为准,不同版本可能有调整。

难点提示(MCP 到底连的是什么):MCP 客户端(Claude/Codex)启动时会去读这份配置,把 reqable-mcp 当成一个"工具供应商"拉起来,然后询问它"你有哪些工具"。reqable-mcp 回一份工具清单(就是 3.6 节那 17 个),之后 AI 在对话里判断"这活儿该调哪个工具"。所以这里连的不是 Reqable 应用本身,而是那个替 Reqable 保管流量数据的本地服务。

3.5 第三步:验证链路通不通

配置写完不等于跑通,按这个顺序验证,每一步都确认通过再进下一步,别跳:

1. 在 Reqable 里随便抓几个请求(打开任意 App 或网页触发流量)。

2. 在 Claude / Codex 里让 AI 调用 ingest_status,确认收到的 payload 计数大于 0。

3. 计数为 0 时按这个顺序排查:Report Server 的 URL 和端口有没有写错 → Reqable 代理是不是真的抓到了流量(看 Reqable 界面有没有请求进来)→ reqable-mcp 进程有没有起来。

这一步的意义在于把问题定位在三个环节里的哪一环。 计数为 0 只说明数据没进 SQLite,但断点可能在"没抓到"、"没推过去"、"服务没起"任意一处,逐环排查比瞎猜快。

3.6 reqable-mcp 暴露的工具清单

这是整套自动分析能力的核心。reqable-mcp 公开的 17 个工具,按用途分成三组,下面逐组过一遍,重点标出哪些是日常高频、哪些是兜底备用。HTTP 分析这一组是日常最常用的,覆盖列出、取详情、搜索、统计、推断结构、生成代码这一整条从看数据到出产物的链路:

• list_requests — 列出最近的 HTTP / WebSocket 握手请求,支持过滤。•

get_request — 按 ID 取请求详情,full 模式含原始 raw_entry。•

search_requests — 在 URL / body / 原始上传条目里做关键字检索。•

get_domains — 域名级请求统计。•

analyze_api — 推断某个域名的 API 结构,这是自动分析的主力工具。•

generate_code — 从抓到的请求生成客户端示例代码。

WebSocket 分析这一组,专门对付实时消息流,聊天、推送、行情这类长连接场景全靠它,因为普通 HTTP 工具看不到一条连接里来回推的帧序列:•

list_websocket_sessions / list_active_websocket_sessions — 列出会话 / 按最新帧列出活跃会话。•

get_websocket_session — 取会话详情与消息。•

tail_websocket_messages — 按 request_id + after_seq 游标增量拉取。•

search_websocket_messages — 按方向、类型、opcode、close code、域名等精确检索。•

analyze_websocket_session — 汇总消息方向、类型、JSON 形状、关闭事件。•

export_websocket_session_raw — 导出原始帧列表。

运维和数据质量这一组,是兜底用的,平时用不上,一旦实时推送漏帧或数据缺字段,就靠它们导入、体检和修复:

import_har — 从文件导入 HAR,实时推送漏帧时的备用入口。•

health_report — 摄取状态 + WebSocket 数据质量报告。•

repair_websocket_messages — 从原始帧回填缺失字段,支持 dry-run。

这份清单里,analyze_api 和 generate_code 是把"抓包"抬升到"自动分析"的两个支点。 前者让 AI 从一堆散乱请求里反推出接口的结构规律,后者让 AI 把某个请求直接翻译成可运行的客户端代码。其余工具大多是为这两件事供数据。

3.7 用起来:几条真实指令

配好之后,你在 Claude / Codex 里直接用自然语言驱动,AI 会自己选工具。给几条实际能用的:

• 「列出刚抓到的 api.example.com 的请求,按状态码分组统计。」AI 会调 list_requests 加 get_domains。

• 「分析 api.example.com 的接口结构,给我一份 Markdown 接口文档。」AI 会调 analyze_api,输出字段、类型、路径。

• 「把那个 POST /v1/order 请求生成一份 Python requests 客户端代码。」AI 会调 generate_code。

• 「这个 WebSocket 会话里服务端推了哪些消息类型?JSON 结构长啥样?」AI 会调 analyze_websocket_session。

直观理解是,这一步把开发者从"翻包、抄参数、拼代码"里解放出来,变成"提问、审阅、采纳"。抓包和分析在一个对话窗口里闭环,不用切工具。

4. 用 Python 脚本让 AI 自动改写流量

读得到只是一半。抓包工具真正有意思的能力,是能在流量经过时改写它——软文里那段"给响应设断点,把返回的 JSON 改几笔,放行,前端立刻看到效果"就是这个。Reqable 把这套能力开放成了 Python 脚本,而脚本这种结构化产物,恰好是 AI 最擅长生成的。

4.1 脚本结构:两个钩子函数

Reqable 脚本的核心就是两个来自 reqable 模块的钩子函数,一个管请求,一个管响应:

# @author pony
# @date 2026-07-23
# @version v1.0.0
# @last_modified 2026-07-23
# @changelog
#   - v1.0.0 (2026-07-23): 初始创建,演示请求/响应改写钩子

from reqable import *

def onRequest(context, request):
    # onRequest 在请求发往服务端之前触发,可改 method/path/queries/headers/body
    # 这里演示:给所有出站请求打一个调试标记,便于在链路里溯源
    request.headers['X-Debug-Trace'] = 'reqable-ai'
    return request  # 返回 None 表示不改动,原样放行

def onResponse(context, response):
    # onResponse 在收到服务端响应之后触发
    # 场景:后端返回的数据结构有问题,前端在等联调 —— 直接在这里改 JSON 放行,
    #      避免"改代码 -> 编译 -> 重启服务"十分钟一轮的回环
    if response.body.isText:
        response.body.jsonify()          # 把 JSON 文本解析成 dict
        response.body['status'] = 'mocked'
        response.body['data'] = {'ok': True}
    return response

这段代码来自 Reqable 官方 Python 脚本 API 的结构约定,几个要点要厘清。onRequest(context, request) 在请求发出前触发,onResponse(context, response) 在收到响应后触发。改完必须 return 对应对象才生效,return None 表示原样放行——这一点很容易踩坑,改了不返回等于没改。

能改的字段是固定的:request 可改 method / path / queries / headers / body;response 可改 code(状态码)/ headers / body。其中 body.jsonify() 是关键一步,它把 JSON 文本解析成 Python dict,之后就能用字典语法直接改字段。还有一个 context.shared,用于在同一次事务的 onRequest 与 onResponse 之间传数据,比如在请求阶段记下时间戳,响应阶段算耗时。

难点提示(为什么改响应比改代码快):后端返回的数据结构有问题时,常规做法是改后端代码、编译、重启服务,一轮十分钟。而在代理层改响应,相当于在数据"回到前端的最后一米"拦一刀,直接把 JSON 改成你想要的样子放行。前端根本不知道后端没动过,联调照常进行。代价是这只是临时 mock,真正的后端 bug 还在,得记得回头修。

4.2 和 AI 的结合点

脚本能力接上 AI,有两个高价值动作,一个是生成脚本本身,一个是把生成和前面的分析串成闭环。第一是让 AI 直接生成脚本。你说「帮我写一个 Reqable 脚本,拦截 GET /v1/user,把响应里的 vip 字段强制改成 true,其余不动」,AI 就能产出上面这种结构的脚本,你贴进 Reqable 启用即可。启用路径是菜单 Traffic -> Script -> Enable,快捷键 Shift + Ctrl + P。手写这种脚本要查 API、记字段名,让 AI 生成省掉这些。

第二是闭环诊断。这里的关键是把通道 A 和通道 C 串起来:先用通道 A 让 AI 分析抓到的异常响应,定位是哪个字段出了问题;再让它生成通道 C 的 mock 脚本,现场把那个字段改成正确的值,验证前端行为。分析和改写在同一个对话里闭环,不用你在"看数据"和"写脚本"之间反复切换脑子。

5. 完整流水线串起来

5.1 一次抓包,两路分叉

把两条通道合成一张图,能更清楚地看到数据怎么流、AI 在哪几处介入。核心问题在于理解抓包是唯一的源头,从这里数据分成两路:一路走 MCP 供 AI 读取分析,一路走脚本供 AI 改写,两路都以同一批流量为基础,互不干扰又能配合。

5.2 一次典型使用长什么样

这套流水线跑起来,典型的一次使用是这样的:抓包,然后跟 AI 说「分析这批请求,找出返回非 2xx 的接口并总结失败模式」,再追一句「给出问题接口的字段级 diff」,最后「生成一个临时 mock 脚本让前端能继续联调」。全程不复制粘贴,数据不出本机。这就是把软文里"抓包 + 测试揉一起"再往前推的一层——抓包、分析、改写揉进同一个对话。

6. 安全与边界:这一节务必读

这条流水线会让 AI 接触到你的真实流量,有几条边界必须守住,否则方便反而变成风险。这里的关键是把"数据流到哪、谁能读、能不能改、来源可不可信"这几件事一次性想清楚,而不是等出了事再补。

6.1 数据安全:敏感信息与本地边界

先说最容易出事的一环——流量里的内容。第一,流量里几乎一定有敏感信息。 抓包数据里常带 Token、Cookie、密码、个人信息。reqable-mcp 默认本地闭环、不上云,是它的优点;但你仍要确认所接的 AI 客户端不会把这些内容外传。用云端大模型时,考虑先在 Report Server 的 Match rule 里只放目标域名,从源头缩小采集面。

第二,MCP 服务只监听本地回环。127.0.0.1:18765 这个地址不要图省事改成 0.0.0.0 或用端口转发暴露到公网,否则同网段甚至外网的人都能读你的抓包数据,而这份数据里可能有生产环境的鉴权信息。本地回环是这套方案安全性的底线,守住它基本就堵住了远程窃取这条路。

6.2 使用边界:改写权限与依赖来源

这里要厘清的是权限与信任问题。第三,改写脚本只在开发/测试环境用。 通道 C 能改真实响应,威力大,但在生产流量上启用 mock 极易造成误导性 bug——你以为是前端问题,其实是脚本悄悄改了数据。用完记得关。

第四,认清依赖来源。reqable-mcp 是社区包(MIT 许可,PyPI 上标注作者 lianhua,仓库在 GitHub 的 ElonJask/reqable-mcp),不是 Reqable 官方出品。用前确认版本和仓库;对安全要求高的场景,优先用 Reqable 官方 MCP。

第五,HTTPS 抓包需要装 CA 证书,这本身会降低该设备的传输安全边界。建议测试机专用,别在主力机上长期开着抓包代理。

工程价值:这五条不是走过场。"AI + 真实流量"最大的落地障碍从来不是技术,而是数据安全边界。把采集面收窄、服务锁本地、生产禁改写、来源认清楚、证书别长开——守住这几条,这套流水线才敢用在真实项目上。

7. 参考来源

• Reqable 官方 MCP 文档(https://reqable.com/en-US/docs/mcp/)• Reqable Python 脚本文档(https://reqable.com/en-US/docs/capture/script)• reqable/python-scripting-api(https://github.com/reqable/python-scripting-api)• reqable/python-scripting-templates(https://github.com/reqable/python-scripting-templates)• reqable-mcp · PyPI(https://pypi.org/project/reqable-mcp/)• GitHub: ElonJask/reqable-mcp(https://github.com/ElonJask/reqable-mcp)• reqable/reqable-app(https://github.com/reqable/reqable-app)