http-toolkit-intercept

HTTP Toolkit 拦截

当你需要权威证据来确认程序向远程 API 发送了什么，以及在验证代码更改时收到了什么，请使用此技能。它适用于任何运行时——Node.js、Bun、Deno、Python、Go、Ruby、Java/JVM、.NET、PHP、Rust、shell 脚本等——只要进程遵循代理设置即可。

可靠的做法是：

1. 正确启动 HTTP Toolkit。
2. 通过代理运行程序，并使用可生成机器可读日志的模式（例如 --output-format json、调试日志或结构化 stdout）。
3. 从 HTTP Toolkit 导出出站 HTTP 请求。
4. 将出站 HTTP 导出内容与程序的入站会话日志配对。

如果问题涉及请求负载、身份验证标头或线路级行为，请勿只依赖 TUI 截图。

前置条件 / 已验证的启动方式

启动 HTTP Toolkit

在 Linux/无头环境中，直接运行 httptoolkit 通常会因沙箱/X11 问题而失败。建议使用：

xvfb-run --auto-servernum httptoolkit --no-sandbox

如果端口 45456/45457 上已有过期服务在运行，请先将其停止：

pkill -f "HTTP Toolkit Server|httptoolkit|xvfb-run --auto-servernum httptoolkit" || true

验证代理是否可访问

# HTTP Toolkit's admin API lives on port 45456/45457 by default.
# Treat 200/401/403 as "reachable"; only connection failure means the server is dead.
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:45456/config

快速开始

1. 设置代理环境变量并启动程序

大多数运行时都会遵循以下标准环境变量：

HTTP_PROXY="http://127.0.0.1:8000" \
HTTPS_PROXY="http://127.0.0.1:8000" \
ALL_PROXY="http://127.0.0.1:8000" \
NO_PROXY="" \
<your-program> <args>

有些运行时需要额外的环境变量或标志——请参阅下文的“运行时代理矩阵”。

如果运行时不信任 HTTP Toolkit CA，TLS 验证将失败。请参阅下文的“TLS 安全性”。仅在受控的本地调试中才适合禁用 TLS 验证。

2. 捕获入站会话日志

如果程序支持机器可读的输出模式（例如 --output-format stream-json、--json、--log-level debug、结构化 stdout 或写入文件），请将其输出通过管道写入文件：

<your-program> exec --output-format stream-json "your input" \
  > /tmp/session-stdout.log 2> /tmp/session-stderr.log

3. 从 HTTP Toolkit 导出出站 HTTP

以下方式任选其一：

• 使用 HTTP Toolkit GUI 导出（File → Export → JSON / HAR），或
• 直接调用管理 API。具体端点取决于 HTTP Toolkit 版本；请检查 HTTP Toolkit UI 中的 DevTools，以查看其发出的请求。

4. 交叉核对这两类数据流

• 出站 HTTP（来自 HTTP Toolkit）：可权威确认请求正文、标头、身份验证令牌和重试时序。
• 入站会话日志（来自程序）：可权威确认代码如何处理响应。

两者结合即可回答：“我们发送了什么？”以及“我们如何处理响应？”

最终验证负载时有效的方法

以下关键做法已证实可靠：

1. 验证负载时使用非交互式 / 执行模式，而非 TUI

   • 交互式 TUI 速度较慢，也更难分析。
   • 使用程序提供的脚本运行选项（--output-format、--json、--headless、--batch）。

2. 将出站和入站数据视为两种独立的证据来源

   • HTTP Toolkit 提供出站 HTTP 请求。
   • 程序的会话日志提供入站助手/工具/应用行为。
   • 你需要两者才能回答：“远程服务返回了什么？”以及“程序实际上对此做了什么？”

3. 设置特定运行时所遵循的代理环境变量

   • HTTP_PROXY/HTTPS_PROXY 适用于大多数运行时，但有些（例如 Bun、Java）需要额外的变量或标志。
   • 请参阅下文的“运行时代理矩阵”。

4. 仅在必要的受控本地调试中禁用 TLS 验证

   • 如果本地不信任 HTTP Toolkit CA，请使用运行时专用的绕过方式跳过验证。
   • 更建议在操作系统/语言信任存储中信任该 CA。
   • 生产环境复现中绝不要禁用 TLS。

5. 控制运行时长

   • 网络活动繁重的长会话可能需要一些时间。
   • 如果你只需证明请求格式，在观察到相关请求后即可导出——不一定要等到完整运行结束。

关键事实

• 代理环境变量因运行时而异 — 请确认你的运行时支持哪些变量
• HTTP Toolkit 管理 API 以请求为导向 — 出站 HTTP 流量来自 HTTP Toolkit，入站行为则来自程序日志
• 默认会验证 TLS — 运行时专用的跳过验证标志仅用于本地开发时绕过验证

运行时代理对照表

运行时	代理环境变量 / 标志	绕过 TLS 验证（仅限本地开发）
Node.js	HTTP_PROXY、HTTPS_PROXY、NO_PROXY（大多数库）；某些 HTTP 客户端需要 --proxy 标志或显式指定 agent: 选项	NODE_TLS_REJECT_UNAUTHORIZED=0 或 NODE_EXTRA_CA_CERTS=/path/to/ca.pem
Bun	BUN_CONFIG_PROXY（必需 — Bun 自带的 fetch 会静默忽略普通的 HTTP_PROXY / HTTPS_PROXY）	NODE_TLS_REJECT_UNAUTHORIZED=0
Deno	HTTP_PROXY、HTTPS_PROXY	--unsafely-ignore-certificate-errors
Python（requests、httpx）	HTTP_PROXY、HTTPS_PROXY、ALL_PROXY	将 REQUESTS_CA_BUNDLE / SSL_CERT_FILE 指向 HTTP Toolkit CA，或在代码中使用 verify=False
Python（urllib）	相同的环境变量	SSL_CERT_FILE，或禁用上下文验证
Go（net/http）	HTTP_PROXY、HTTPS_PROXY、NO_PROXY（通过 http.ProxyFromEnvironment 生效）	SSL_CERT_FILE，或在传输配置中设置 InsecureSkipVerify: true
Ruby	HTTP_PROXY、HTTPS_PROXY	SSL_CERT_FILE，或 OpenSSL::SSL::VERIFY_NONE
Java / JVM	-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8000 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8000；JVM 不支持环境变量	将 CA 导入信任库，并传入 -Djavax.net.ssl.trustStore=...
.NET / C#	HTTP_PROXY、HTTPS_PROXY、ALL_PROXY（较新的运行时），或显式配置 HttpClient	在操作系统证书库中信任 CA，或使用 HttpClientHandler.ServerCertificateCustomValidationCallback
PHP（curl / cli）	HTTP_PROXY、HTTPS_PROXY（或按调用设置 CURLOPT_PROXY）	CURLOPT_SSL_VERIFYPEER => false
Rust（reqwest）	HTTP_PROXY、HTTPS_PROXY	在客户端上设置 danger_accept_invalid_certs(true)
curl / shell	HTTP_PROXY、HTTPS_PROXY 环境变量，或 -x / --proxy 标志	-k / --insecure
Docker 容器	使用 -e HTTP_PROXY=... 传入环境变量；使用 host.docker.internal（Mac/Win）或 --network=host（Linux），以便容器连接代理	将 CA 挂载到镜像中并安装，或使用运行时专用的绕过验证标志

相比禁用验证，更推荐在运行时 / 操作系统的信任库中信任 HTTP Toolkit CA。绕过验证标志仅应在本地开发时使用。

TLS 安全防护

• 尽可能保持启用 TLS 验证。
• 相比禁用验证，更推荐在本地信任库中信任 HTTP Toolkit CA。
• 仅在开发期间进行受控的本地调试时，使用运行时专用的 TLS 绕过验证标志。
• 拦截生产流量时，绝不要禁用 TLS。

检查捕获的日志

仅筛选相关事件

如果程序输出的是以换行符分隔的 JSON，请使用 jq：

jq -c 'select(.type == "tool_call" or .type == "message")' /tmp/session-stdout.log

调整筛选条件，使其匹配程序的事件架构。对于纯文本日志，请使用 rg / grep 模式。

将出站 HTTP 与入站事件对应起来

按时间戳对两个流排序，然后交错排列。序列通常如下所示：

outbound POST /api/endpoint        (from HTTP Toolkit)
inbound  event received             (from program log)
inbound  follow-up action           (from program log)
outbound POST /api/endpoint        (next request)

如果程序日志显示有出站请求，但 HTTP Toolkit 未捕获该请求，则说明代理配置有误。

故障排查

问题	原因	修复方法
程序挂起，启动后没有事件	代理环境变量未传递到进程，或 TLS 验证受阻	使用适用于你所用运行时的正确环境变量重新运行（参见矩阵）；如有必要，仅在开发环境中启用运行时的 TLS 绕过
每次请求都出现 ECONNRESET / connection reset	缺少特定运行时的代理环境变量（例如，Bun 的 BUN_CONFIG_PROXY、Java 的 JVM -D 标志）	使用正确的特定运行时代理配置
通过代理时出现 TLS 证书错误	此运行时不信任 MITM CA	将 HTTP Toolkit CA 添加到运行时 / OS 证书存储中，或仅在开发环境中启用运行时的 TLS 绕过
HTTP Toolkit API 在 /config 上返回 403	配置端点需要身份验证	将 200/401/403 视为可访问；只有连接失败才表示服务已停止
导出的数据中有出站数据，但没有匹配的入站事件	未捕获程序日志	在启动命令中添加 > /tmp/session.log 重定向
HTTP Toolkit 漏掉第一个请求	在进程启动后才开始捕获	先启动 HTTP Toolkit，再启动程序
容器 / VM 无法访问 127.0.0.1:8000	回环地址仅在容器内部有效	使用 host.docker.internal（Docker Desktop）或 --network=host（Linux）
程序完全忽略环境变量	运行时不遵循环境变量（例如 JVM）	使用特定运行时的标志（例如，JVM 使用 -Dhttp.proxyHost=...）