Back to Details

http-toolkit-intercept

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HTTP Toolkit Intercept

HTTP Toolkit 拦截操作指南

Use this skill when you need authoritative evidence of what your program sent to a remote API and what it received back while verifying a code change. Works across any runtime — Node.js, Bun, Deno, Python, Go, Ruby, Java/JVM, .NET, PHP, Rust, shell scripts, etc. — as long as the process respects a proxy.
The reliable pattern is:
  1. Start HTTP Toolkit correctly.
  2. Run the program through the proxy in a mode that produces a machine-readable log (e.g. 
    --output-format json
    , debug logging, or structured stdout).
  3. Export outbound HTTP requests from HTTP Toolkit.
  4. Pair the outbound HTTP export with the inbound program session log.
Do not rely on TUI screenshots alone when the question is about request payloads, auth headers, or wire-level behavior.
当你需要在验证代码变更时，获取程序发送给远程API的内容以及收到的响应的权威证据时，可以使用该方法。它适用于任意运行时——Node.js、Bun、Deno、Python、Go、Ruby、Java/JVM、.NET、PHP、Rust、shell脚本等——只要进程支持代理即可。
可靠的操作流程如下：
  1. 正确启动HTTP Toolkit。
  2. 通过代理以生成机器可读日志的模式运行程序（例如
    --output-format json
    、调试日志或结构化标准输出）。
  3. 从HTTP Toolkit导出出站HTTP请求。
  4. 将出站HTTP导出内容与入站程序会话日志配对。
不要仅依赖TUI截图来排查请求 payload、认证头或网络层面行为的问题。

Prerequisites / Known-Good Launch

前置条件 / 可靠启动方式

Start HTTP Toolkit

启动HTTP Toolkit

On Linux/headless environments, plain 
httptoolkit
often fails due to sandbox/X11 issues. Prefer:
bash
xvfb-run --auto-servernum httptoolkit --no-sandbox
If a stale server is already running on ports 
45456/45457
, stop it first:
bash
pkill -f "HTTP Toolkit Server|httptoolkit|xvfb-run --auto-servernum httptoolkit" || true
在Linux/无头环境中，直接运行
httptoolkit
通常会因沙箱/X11问题失败。建议使用：
bash
xvfb-run --auto-servernum httptoolkit --no-sandbox
如果端口
45456/45457
上已有过期服务器在运行，请先停止它：
bash
pkill -f "HTTP Toolkit Server|httptoolkit|xvfb-run --auto-servernum httptoolkit" || true

Verify the proxy is reachable

验证代理是否可达

bash
undefined
bash
undefined

HTTP Toolkit's admin API lives on port 45456/45457 by default.

HTTP Toolkit的管理API默认运行在端口45456/45457。

Treat 200/401/403 as "reachable"; only connection failure means the server is dead.

返回200/401/403即表示“可达”；只有连接失败才意味着服务器未运行。

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:45456/config
undefined
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:45456/config
undefined

Quick Start

快速开始

1. Launch your program with the proxy env vars set

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

The canonical env vars most runtimes honor:
bash
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>
Some runtimes require an extra env var or flag — see the "Runtime proxy matrix" below.
If the HTTP Toolkit CA is not trusted by your runtime, TLS verification will fail. See "TLS Safety" below. Disabling TLS verification is appropriate only for controlled local debugging.
大多数运行时认可的标准环境变量：
bash
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. Capture the inbound session log

2. 捕获入站会话日志

If your program supports a machine-readable output mode (e.g. 
--output-format stream-json
, 
--json
, 
--log-level debug
, structured stdout, or writing to a file), pipe it to a file:
bash
<your-program> exec --output-format stream-json "your input" \
  > /tmp/session-stdout.log 2> /tmp/session-stderr.log
如果你的程序支持机器可读输出模式（例如
--output-format stream-json
、
--json
、
--log-level debug
、结构化标准输出或写入文件），将其输出重定向到文件：
bash
<your-program> exec --output-format stream-json "your input" \
  > /tmp/session-stdout.log 2> /tmp/session-stderr.log

3. Export outbound HTTP from HTTP Toolkit

3. 从HTTP Toolkit导出出站HTTP请求

Either:
  • Use the HTTP Toolkit GUI export (File → Export → JSON / HAR), or
  • Hit the admin API directly. The exact endpoint depends on your HTTP Toolkit version; inspect DevTools in the HTTP Toolkit UI to see the requests it makes.
可以选择：
  • 使用HTTP Toolkit GUI导出（文件 → 导出 → JSON / HAR），或者
  • 直接调用管理API。具体端点取决于你的HTTP Toolkit版本；可在HTTP Toolkit UI的开发者工具中查看它发起的请求。

4. Cross-reference the two streams

4. 交叉引用两个流

  • Outbound HTTP (from HTTP Toolkit): authoritative for request bodies, headers, auth tokens, retry timing.
  • Inbound session log (from the program): authoritative for how your code reacted to the responses.
Together they answer: "what did we send?" and "what did we do with the response?"
  • 出站HTTP请求（来自HTTP Toolkit）：是请求体、请求头、认证令牌、重试时机的权威来源。
  • 入站会话日志（来自程序）：是代码如何响应返回结果的权威来源。
两者结合可以回答：“我们发送了什么？”以及“我们对响应做了什么处理？”

What finally worked for payload verification

有效验证Payload的方法

The critical correct pathways that proved reliable were:
  1. Use a non-interactive / exec mode, not the TUI, when verifying payloads
    • Interactive TUIs are slower and much harder to analyze.
    • Use whatever your program has for scripting (
      --output-format
      , 
      --json
      , 
      --headless
      , 
      --batch
      ).
  2. Treat outbound and inbound as separate evidence sources
    • HTTP Toolkit gives outbound HTTP requests.
    • The program's session log gives inbound assistant/tool/application behavior.
    • You need both to answer: "what did the remote return?" and "what did the program actually do with it?"
  3. Set the proxy env vars your specific runtime honors
    • HTTP_PROXY
      /
      HTTPS_PROXY
      cover most runtimes, but some (e.g. Bun, Java) require extra vars or flags.
    • See the "Runtime proxy matrix" below.
  4. Disable TLS verification only for controlled local debugging when needed
    • If the HTTP Toolkit CA is not trusted locally, use the runtime-specific escape hatch to skip verification.
    • Prefer trusting the CA in your OS / language trust store instead.
    • Never disable TLS in production repros.
  5. Keep runs bounded
    • Long network-heavy sessions can take time.
    • If you only need to prove request shape, export after the relevant request is observed — you do not always need to wait for full completion.
经过验证的可靠关键步骤如下：
  1. 验证Payload时使用非交互/执行模式，而非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. 限制运行时长
    • 长时间的网络密集型会话会耗费较多时间。
    • 如果你仅需要验证请求结构，在观察到相关请求后即可导出——无需等待整个会话完成。

Key Facts

关键要点

  • Proxy env vars are runtime-specific — know which ones your runtime honors
  • HTTP Toolkit admin API is request-oriented — outbound HTTP comes from HTTP Toolkit, inbound behavior comes from the program log
  • TLS is verified by default — runtime-specific skip flags are local-dev escape hatches only
  • 代理环境变量因运行时而异——了解你的运行时认可哪些变量
  • HTTP Toolkit管理API面向请求——出站HTTP请求信息来自HTTP Toolkit，入站行为信息来自程序日志
  • 默认启用TLS验证——运行时特定的跳过标志仅适用于本地开发场景

Runtime proxy matrix

运行时代理矩阵

RuntimeProxy env vars / flagsTLS bypass (local dev only)
Node.js
HTTP_PROXY
, 
HTTPS_PROXY
, 
NO_PROXY
(most libraries); some HTTP clients need 
--proxy
flags or explicit 
agent:
option
NODE_TLS_REJECT_UNAUTHORIZED=0
or 
NODE_EXTRA_CA_CERTS=/path/to/ca.pem
Bun
BUN_CONFIG_PROXY
(mandatory — plain 
HTTP_PROXY
/
HTTPS_PROXY
are silently ignored for Bun's own fetch)
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
pointing at the HTTP Toolkit CA, or 
verify=False
in code
Python (
urllib
)		Same env vars
SSL_CERT_FILE
or disable context verification
Go (
net/http
)
HTTP_PROXY
, 
HTTPS_PROXY
, 
NO_PROXY
(honored via 
http.ProxyFromEnvironment
)
SSL_CERT_FILE
or 
InsecureSkipVerify: true
in the transport
Ruby
HTTP_PROXY
, 
HTTPS_PROXY
SSL_CERT_FILE
, or 
OpenSSL::SSL::VERIFY_NONE
Java / JVM
-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8000 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8000
; env vars are not honored by the JVM		Import CA into a truststore and pass 
-Djavax.net.ssl.trustStore=...
.NET / C#
HTTP_PROXY
, 
HTTPS_PROXY
, 
ALL_PROXY
(on recent runtimes) or configure 
HttpClient
explicitly		Trust CA in OS store, or 
HttpClientHandler.ServerCertificateCustomValidationCallback
PHP (curl / cli)
HTTP_PROXY
, 
HTTPS_PROXY
(or per-call 
CURLOPT_PROXY
)
CURLOPT_SSL_VERIFYPEER => false
Rust (
reqwest
)
HTTP_PROXY
, 
HTTPS_PROXY
danger_accept_invalid_certs(true)
on the client
curl / shell
HTTP_PROXY
, 
HTTPS_PROXY
env vars or 
-x
/
--proxy
flag
-k
/ 
--insecure
Docker containersPass env vars through with 
-e HTTP_PROXY=...
; use 
host.docker.internal
(Mac/Win) or 
--network=host
(Linux) so the container can reach the proxy		Mount the CA into the image and install it, or use runtime-specific bypass flags
Prefer trusting the HTTP Toolkit CA in your runtime/OS trust store over disabling verification. Bypass flags should be local-dev only.
运行时代理环境变量/标志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 Safety Guardrails

TLS安全防护

  • Keep TLS verification enabled whenever possible.
  • Prefer trusting the HTTP Toolkit CA in your local trust store instead of disabling verification.
  • Use runtime-specific TLS-bypass flags only for controlled local debugging in development.
  • Never disable TLS when intercepting production traffic.
  • 尽可能保持TLS验证启用状态。
  • 优先选择在本地信任存储中信任HTTP Toolkit CA，而非禁用验证。
  • 仅在受控的本地开发调试场景下使用运行时特定的TLS绕过标志。
  • 拦截生产流量时绝不要禁用TLS。

Inspecting Captured Logs

检查捕获的日志

Filter to relevant events only

仅筛选相关事件

If your program emits newline-delimited JSON, use 
jq
:
bash
jq -c 'select(.type == "tool_call" or .type == "message")' /tmp/session-stdout.log
Adjust the filter to match your program's event schema. For plain-text logs, use 
rg
/
grep
patterns.
如果你的程序输出换行分隔的JSON，可使用
jq
：
bash
jq -c 'select(.type == "tool_call" or .type == "message")' /tmp/session-stdout.log
根据程序的事件模式调整筛选条件。对于纯文本日志，使用
rg
/
grep
模式。

Match outbound HTTP to inbound events

匹配出站HTTP请求与入站事件

Sort both streams by timestamp, then interleave them. The sequence usually looks like:
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)
If a program log shows an outbound request that HTTP Toolkit didn't capture, that's a proxy-config bug.
将两个流按时间戳排序，然后交叉对比。序列通常如下：
outbound POST /api/endpoint        (来自HTTP Toolkit)
inbound  event received             (来自程序日志)
inbound  follow-up action           (来自程序日志)
outbound POST /api/endpoint        (下一个请求)
如果程序日志显示有出站请求，但HTTP Toolkit未捕获到，说明代理配置存在问题。

Troubleshooting

故障排查

ProblemCauseFix
Program hangs, no events after startupProxy env vars not reaching the process, or TLS verification blockingRe-run with the right env vars for your runtime (see matrix); if necessary, enable the runtime's TLS bypass in dev
ECONNRESET
/ 
connection reset
on every request		Runtime-specific proxy env var missing (e.g. 
BUN_CONFIG_PROXY
for Bun, JVM 
-D
flags for Java)		Use the correct runtime-specific proxy config
TLS cert errors via proxyMITM CA not trusted by this runtimeTrust HTTP Toolkit CA in the runtime / OS store, or enable the runtime's TLS bypass in dev only
HTTP Toolkit API 403s on 
/config
Auth-gated config endpointTreat 200/401/403 as reachable; only connection failure means the server is dead
Export has outbound data but no matching inbound eventsDidn't capture the program logAdd 
> /tmp/session.log
redirection to the launch
HTTP Toolkit misses the first requestStarted capturing after the process launchedStart HTTP Toolkit first, THEN launch the program
Container / VM can't reach 
127.0.0.1:8000
Loopback is container-localUse 
host.docker.internal
(Docker Desktop) or 
--network=host
(Linux)
Program ignores env vars entirelyRuntime doesn't honor env vars (e.g. JVM)Use runtime-specific flags (
-Dhttp.proxyHost=...
for JVM, etc.)
问题原因解决方法
程序启动后挂起，无任何事件代理环境变量未传递到进程，或TLS验证被阻止使用适合你运行时的正确环境变量（见矩阵）；必要时在开发环境启用运行时的TLS绕过
每次请求均出现
ECONNRESET
/
connection reset
缺少运行时特定的代理环境变量（如Bun的
BUN_CONFIG_PROXY
、Java的JVM 
-D
标志）		使用正确的运行时特定代理配置
通过代理时出现TLS证书错误MITM CA未被该运行时信任在运行时/操作系统存储中信任HTTP Toolkit CA，或仅在开发环境启用运行时的TLS绕过
HTTP Toolkit API调用
/config
返回403		配置端点受认证限制返回200/401/403均视为可达；只有连接失败才意味着服务器未运行
导出内容包含出站数据，但无匹配的入站事件未捕获程序日志在启动命令中添加
> /tmp/session.log
重定向
HTTP Toolkit未捕获第一个请求在进程启动后才开始捕获先启动HTTP Toolkit，再启动程序
容器/虚拟机无法访问
127.0.0.1:8000
回环地址仅在容器内部有效使用
host.docker.internal
（Docker Desktop）或
--network=host
（Linux）
程序完全忽略环境变量运行时不认可环境变量（如JVM）使用运行时特定的标志（如JVM的
-Dhttp.proxyHost=...
等）