Codex + HTTPeep CLI Skill：从真实网络会话中调试 API 调用

AI 辅助编码已经很擅长读代码、解释逻辑、修改实现和运行测试。但在调试 API 调用时，它经常缺少一个关键输入：真实网络会话。

代码里看起来请求了正确的 URL，参数也像是没问题；但真实发出去的请求可能完全是另一回事。

比如：

• Authorization header 没带上。
• token 已经过期，但前端状态里看起来还在。
• query 参数被拼成了错误格式。
• request body 和后端 schema 不一致。
• 请求实际打到了 staging、test 或本地服务，而不是你以为的环境。
• 后端返回的是业务错误，但前端只暴露了一个泛化的 Network Error。

如果 Codex 只能读代码，它只能基于代码推断请求会怎样发生。它可能会给出合理的猜测，但仍然是猜测。

HTTPeep CLI Skill 的价值，是把真实 HTTP/HTTPS 会话交给 Codex。让 agent 不只看代码里的意图，也能看到请求真正发成了什么样、服务端真正返回了什么。

hp 是 httpeep-cli 的别名, 使用 hp 代替 httpeep-cli 更加简短好记忆和输入

没有网络上下文，AI 只能猜

传统的 AI 调试流程通常是这样的：

1. 你告诉 Codex：“这个接口返回 401，帮我看看。”
2. Codex 阅读登录、鉴权、请求封装、状态管理相关代码。
3. 它推测可能是 token 没写入、请求拦截器没执行、后端 session 过期，或者环境变量配置错了。
4. 你再去浏览器 DevTools、终端日志、后端日志里复制更多信息。
5. Codex 根据你补充的信息继续推理。

这个流程的问题不是 Codex 不够聪明，而是它看不到关键证据。

API 调试经常不是“代码里有没有这行逻辑”的问题，而是“真实请求里这行逻辑有没有生效”的问题。只看源码，Codex 很难确认：

• 请求最终 URL 是什么。
• header 是否真的被注入。
• body 是否真的按预期序列化。
• cookie 是否被浏览器带上。
• 服务端返回的 status、header、body 到底是什么。
• 失败发生在应用层、代理层、TLS 层，还是上游服务。

没有真实会话上下文时，AI 的回答很容易停留在“可能是鉴权问题”“建议检查 CORS”“确认 token 是否过期”这一类方向性建议上。

方向可能没错，但还不够。

拥有真实会话上下文后，Codex 可以检查证据

接入 HTTPeep CLI Skill 之后，调试方式会变得更直接。

Codex 可以先查看 HTTPeep 捕获到的会话，再回到代码里定位问题：

1. 列出最近的 API 请求。
2. 找出 4xx、5xx 或响应异常的会话。
3. 读取具体 session 的 request 和 response。
4. 对照代码中的请求构造逻辑。
5. 给出基于真实请求/响应的判断。
6. 修改代码后再次触发请求，用新的会话验证结果。

这和“把报错贴给 AI”有本质区别。

你不再需要把 DevTools 里的 header、payload、response body 分段复制给 Codex。Codex 可以通过 HTTPeep CLI 看到实际网络上下文，然后把这个上下文和代码放在一起分析。

这会显著降低两类常见误判：

• 代码意图和真实请求不一致：代码里写了 header 注入，但真实请求里没有。
• 前端假设和后端响应不一致：前端以为返回 { user }，真实响应却是 { data: { user } } 或错误结构。

HTTPeep 在这里不是替代 Codex，而是给 Codex 补上它默认缺失的网络证据。

安装 HTTPeep CLI Skill

HTTPeep CLI Skill 是给 Codex / agent 使用的技能说明。它让 agent 更稳定地知道如何调用 HTTPeep CLI、如何查看会话、如何检查代理状态，以及如何排查证书相关问题。

安装命令：

npx skills add HTTPeep/agent-skills --skill httpeep-cli

安装完成后，Codex 就能在调试网络问题时优先使用 HTTPeep CLI，而不是完全依赖代码推断。

如果你的项目使用 AGENTS.md，建议加入一条明确提示：

调试 API、网络请求、代理、证书或真实 HTTP 会话时，优先使用 HTTPeep CLI Skill 查看实际会话。

这类提示很有用。它会让 agent 在遇到 API 问题时先去检查真实请求，而不是直接开始猜测应用代码。

首次使用：安装并信任证书

如果要调试 HTTPS 请求，HTTPeep 需要安装并信任本地 CA 证书。这样 HTTPeep 才能在本机代理链路中解密 HTTPS 流量，显示明文 request 和 response。

首次使用时，一行命令即可完成：

httpeep-cli cert install

安装完成后，再确认代理状态：

httpeep-cli proxy status

如果代理没有运行，可以启动它：

httpeep-cli proxy start

如果你只能看到 CONNECT，但看不到 HTTPS 请求的 path、header 和 body，通常说明证书信任或 HTTPS MITM 链路还没有准备好。先确认本地 CA 已安装并被系统信任，再重新触发目标请求。

证书只用于本地调试。处理生产 token、cookie、用户数据或第三方敏感响应时，仍然应该保持最小暴露原则，不要把不必要的敏感内容发送到公共对话或外部系统。

捕获一次真实 API 调用

准备好 HTTPeep 代理后，在你的应用里复现一次 API 调用。

这可以是浏览器里的前端页面，也可以是桌面应用、移动设备、CLI 工具、SDK、本地服务或测试进程。关键是目标流量需要经过 HTTPeep 代理。

然后用 CLI 查看最近会话：

httpeep-cli sessions list

如果希望 Codex 或脚本更容易解析，可以使用 JSON 输出：

httpeep-cli sessions list --format json

在真实调试中，你通常会让 Codex 做两件事：

• 先找出最近失败或异常的请求。
• 再读取具体 session 的详细 request / response。

这里可以放一张 HTTPeep 捕获 API 会话的示意图或 GIF：

![HTTPeep 捕获 API 会话示例](./images/codex-httpeep-cli-sessions.gif)

后续你可以把这张图替换成真实演示素材，比如 Codex 调用 HTTPeep CLI、列出 sessions、选择失败请求的完整过程。

让 Codex 读取失败请求

当 HTTPeep 已经捕获到会话后，不要只对 Codex 说“接口失败了”。更好的方式是让它直接检查 HTTPeep 会话。

可以这样提示：

请用 HTTPeep CLI 查看最近失败的 API 请求，找出 4xx/5xx 的共同点。

或者：

请读取这个 session，判断失败原因更像是前端参数、鉴权、环境路由，还是后端返回。

再进一步：

根据真实 request body，检查代码里构造 payload 的逻辑是否一致。

Codex 读取会话时，重点不是“有没有请求”，而是这些字段是否符合预期：

• method 和 URL 是否正确。
• query 参数是否完整。
• request headers 是否包含鉴权、content type、trace id 等关键字段。
• request body 是否符合后端接口协议。
• response status 是业务失败、鉴权失败、网关失败，还是网络异常。
• response body 是否和前端解析逻辑一致。
• timing 是否显示上游响应慢、连接失败或被代理规则影响。

这些信息直接决定修复方向。

如果真实请求里没有 Authorization header，就不应该先去改后端。如果真实 response body 结构和前端类型定义不一致，就不应该继续怀疑浏览器缓存。如果请求打到了错误域名，就应该先检查环境、DNS Override、代理或 base URL 配置。

这些判断都来自真实会话，而不是猜。

修复完成后，再触发一次请求，让 Codex 用 HTTPeep CLI 验证新的 session：

请再次查看最新的 /api/me 请求，确认它已经带上 Authorization header，并且响应状态为 200。

这里可以放一个 Codex 读取 HTTPeep CLI 会话并定位 401 的 GIF：

![Codex 读取 HTTPeep CLI 会话并定位 401](./images/codex-debug-401-with-httpeep.gif)

这类演示图很适合展示“AI 不是凭空分析，而是在读取真实网络证据”。

进一步：用 HTTPeep 规则复现和验证问题

HTTPeep 不只是一个会话查看器。它的核心能力是把网络调试动作沉淀成可复用规则。

当 Codex 已经通过真实会话定位问题后，还可以进一步建议或操作 HTTPeep 规则，帮助你复现和验证。

比如：

• 用 Map Local 返回本地 JSON，模拟后端尚未完成的接口。
• 用 Map Remote 把匹配请求路由到本地服务或预发服务。
• 用 Modify Response 模拟字段缺失、错误状态或边界响应。
• 用 Delay / Throttle 复现慢接口、弱网和超时行为。
• 用 Breakpoint 暂停请求或响应，在流量经过时手动检查和修改。

这时 Codex 的角色不是“自动替你决定一切”，而是基于真实 session 给出可检查的调试动作。

例如：

请根据刚才失败的 session，帮我设计一条 HTTPeep 规则，用本地 JSON 模拟同样的错误响应，方便我验证前端错误处理。

或者：

请基于这个请求创建一个 Map Remote 调试方案，把 api.example.com 的 /api/me 临时转发到本地服务。

规则的好处是可见、可关闭、可复用。你不用把一次性调试状态散落在 hosts 文件、临时代码、环境变量和记忆里。

Skill、CLI 和 MCP 是什么关系

这几个概念容易混在一起，可以简单区分：

• HTTPeep CLI 是命令行工具，用来启动代理、查看会话、管理规则、处理证书和执行终端工作流。
• HTTPeep CLI Skill 是给 Codex / agent 的使用说明，让它知道遇到网络调试任务时应该如何使用 HTTPeep CLI。
• HTTPeep MCP 是 agent 可以连接的工具接口，让 Codex、Claude 等工具直接读取和操作 HTTPeep 的运行状态。

你可以只用 CLI，也可以通过 MCP 让 agent 更直接地访问 HTTPeep。CLI Skill 的作用，是让 Codex 在合适的时机主动想到并正确使用这些能力。

常见问题

httpeep-cli 找不到怎么办？

先确认你已经安装并启动过 HTTPeep 桌面应用。桌面应用会随附 CLI。

然后在终端里检查：

httpeep-cli --version

如果命令找不到，可以到 HTTPeep 的设置里修复 CLI / PATH 安装，再重启终端。

安装了 Skill，但 Codex 没主动用怎么办？

在 AGENTS.md 里加明确说明：

调试 API、网络请求、代理、证书或真实 HTTP 会话时，优先使用 HTTPeep CLI Skill 查看实际会话。

也可以在对话里直接要求：

请先使用 HTTPeep CLI 查看真实网络会话，再判断这个 API 问题。

HTTPS 只看到 CONNECT 怎么办？

通常是证书信任链路还没准备好。先运行：

httpeep-cli cert install

然后重新启动目标应用或浏览器，再触发请求。

没捕获到请求怎么办？

优先检查三件事：

1. HTTPeep 代理是否在运行。
2. 目标应用的流量是否经过 HTTPeep。
3. 是否存在 Bypass、系统代理、应用代理或上游代理配置影响了路径。

浏览器通常可以依赖系统代理。移动设备、CLI 工具、SDK 或服务进程可能需要显式配置代理。

可以把 token、cookie、生产响应直接发给 AI 吗？

不建议。

HTTPeep 是本地优先的调试工具，但你仍然应该控制敏感信息的暴露范围。调试生产问题时，尽量脱敏 token、cookie、用户 ID、邮箱、订单号和业务敏感字段。

更好的做法是让 Codex 在本地读取必要结构，并在输出中只总结问题，不复制完整敏感值。

把 API 调试从描述问题变成检查证据

Codex 擅长读代码、做推理、修改实现和组织验证步骤。

HTTPeep CLI 提供真实请求和响应。

HTTPeep CLI Skill 把两者连接起来，让 Codex 在调试 API 时先检查网络证据，再回到代码里定位原因。

这就是这套工作流最重要的变化：AI 不再只是根据代码猜测 API 行为，而是可以基于实际网络会话调试。

当真实 request、response、status、headers、body 和 timing 都能被 agent 检查，API 调试会从“你描述问题”变成“AI 和你一起看证据”。