Capture 文档

Capture 是 macOS 上的 HTTP/HTTPS 调试代理。它记录应用发出的请求，让你查看、过滤和修改它们。

请求列表的样子。这个文档的目录也按同样的方式操作：方向键切换，/ 搜索。

从这里开始

• 第一次使用：安装，然后看快速开始。
• 开着 Shadowrocket、Clash 等 VPN：看在 VPN 下抓包。
• 想让 Claude Code 读取和操作流量：看 MCP 与 Claude Code。
• 之前用 Charles：看从 Charles 迁移。

安装

从源码构建，需要 macOS 14 或更高版本、Go 和 Xcode 命令行工具。

构建并打开

./scripts/build.sh
open build/Capture.app

构建结果在 build/Capture.app，应用内已经包含抓包核心 capture-core 和命令行工具 capture-cli。

安装命令行工具

选择 设置 → 安装命令行工具，会把 capture-cli 链接到 ~/.local/bin。详见命令行。

快速开始

三步看到第一个解密的 HTTPS 请求。

1. 安装根证书：证书 → 在此 Mac 上安装证书…
2. 让流量经过 Capture：点工具栏的系统代理，或把应用的 HTTP/HTTPS 代理设为 127.0.0.1:9090。
3. 在列表里右键一个 HTTPS 请求，选启用 SSL Proxying，再重新发起请求。

开启系统代理会修改 macOS 的网络设置。Capture 退出或崩溃后会恢复原值。

不想改系统设置

只抓某个命令时直接指定代理，系统设置不受影响：

curl -x http://127.0.0.1:9090 https://example.com

端口被占用时 Capture 会自动使用后面的端口，实际端口显示在工具栏和底部状态栏。

在 VPN 下抓包

Shadowrocket、Clash 等 TUN 模式 VPN 开启时，macOS 不采用网络服务里的系统代理。无需关闭 VPN，按范围选一种方式。

出站绕过 VPN

VPN 把流量转发给 Capture 时，Capture 需要绕过 VPN 出站，否则请求会回环。默认自动处理，可在工具 → 代理设置 → 出站绕过 VPN / TUN 切换。

请求列表

主窗口左侧按应用和域名归类，中间是请求，右侧是选中请求的详情。

常用操作

• 回车在新窗口打开请求，空格收藏，双击也可收藏。
• 右键可以重复、加断点、生成 Map Local、复制为 cURL 或代码、添加备注和高亮。
• 右键表头显示或隐藏列，列可以拖动排序。
• 把 .har、.capture、.chlsj 文件拖到窗口上即可打开。

标签和 Split View

⌃⌘T 新建列表标签，每个标签有自己的过滤条件。⌃⌘\ 打开 Split View，并排显示两个列表，菜单和详情跟随你最后操作的一侧。

自定义列

在 Capture → 设置… → 列表列添加列，来源可以是请求或响应的 Header，也可以是 JSON 字段，如 data.items.0.id。

侧栏

右键域名可以收藏、隐藏、导出或删除它的请求。隐藏的域名仍会被捕获，可在设置中恢复。

查看内容

请求和响应各有一组标签，只显示适用于当前内容的标签。

每个面板右上角的 ⋯ 菜单可以保存正文或原始报文，也可以强制按 Protobuf 或 MessagePack 解码。

调整面板

⌥⌘1 切换请求面板，⌥⌘2 切换响应面板，⌥⌘3 切换整个详情区。查看 → 分离内容窗口把当前请求放到独立窗口，内容不随列表变化。

过滤

列表上方的搜索和分类用于日常筛选，高级过滤可以按 Header 和 Body 组合条件。

搜索框

按网址搜索，也匹配方法名和状态码。写成 /正则/ 时按正则匹配。

高级过滤

⌥⌘F 打开。添加多个条件，选择满足全部或任一，应用后新流量也按此过滤。常用的条件可以保存。可用字段见过滤字段。

每个列表标签和 Split View 的每一侧都有独立的过滤条件。

概览、差异与时序

从整体看流量，或者比较两个请求。

概览

⇧⌘O 打开流量仪表盘：请求趋势、状态分布、耗时分布、域名和应用排行。点击条目跳到对应请求，报告可以复制或保存为 Markdown。

差异

选中两个请求后右键比较这两个请求，并排显示差异。JSON 会先规范化再比较。

瀑布图

⌥⌘W 把选中或当前过滤的请求排在同一时间轴上。单个请求的各阶段耗时在响应面板的时序标签。

断点

暂停匹配的请求或响应，修改后再放行。

1. 右键请求选断点…，或在工具 → 断点…（⇧⌘B）新建。
2. 命中时弹出编辑窗口，可以改方法、URL、Header、Body 和状态码。
3. 选择执行发送修改后的内容，按原样继续，或中止。

5 分钟内没有处理的消息会自动按原样继续。

原始报文和模板

窗口顶部可切换到原始报文，直接编辑完整文本。常用的 Header 和 Body 可通过模板保存和套用。

Map Local 和 Map Remote

用本地内容回答请求，或把请求转到另一个地址。

Map Local

响应可以来自自定义内容、本地文件或目录，请求不会发到服务器。右键请求选Map Local（用此响应）…会预填当前响应。

要 Mock 多个接口，选中它们后右键把所选响应生成 Mock，规则会放进一个新文件夹。

Map Remote

替换协议、主机、端口、路径前缀和查询参数，例如把线上接口切到本地服务：

匹配  https://api.example.com/*
目标  http://localhost:3000

也可以映射到 ws:// 或 wss://。

重放和构建请求

重放和新建的请求同样经过 Capture，会被记录，规则也会生效。

• ⌘R 原样重复选中的请求。右键重复多次…最多可连续发送 1000 次。
• ⌥⌘R 编辑后重复。
• ⌘N 新建请求。

编辑器

左侧可在 Header、Query、Cookie、Form 之间切换。Form 非空时会作为 multipart 请求体发送，每行写一项：

title=测试
file=@/Users/me/photo.png

发送过的请求保存在右上角的历史中。

导出为代码

右键复制为代码，可生成 Swift、Python、JavaScript、Go 或 HTTPie。

规则管理

所有调试规则集中在工具 → 规则管理器…（⌥⌘U）。

• 排在前面的规则先匹配，可以拖动调整顺序。
• 文件夹停用时，里面的规则全部停用。
• 每条规则显示命中次数，⌘Z 撤销修改。
• 右键底部状态栏的工具胶囊，可以启用或停用整个工具。

规则没有生效

工具 → 测试规则匹配…输入 URL，会列出命中的全部规则和未启用的规则，也显示是否解密、走哪个外部代理。这个测试不发送请求，也不计入命中次数。

规则的写法见 URL 匹配语法。

黑白名单与网络条件

都在工具菜单里，规则支持按 URL 匹配。

脚本

用 JavaScript 修改请求、响应和 WebSocket 消息。⌥⌘I 打开脚本列表。

async function onRequest(context, url, request) {
  request.headers["X-Debug"] = "1";
  return request;
}

async function onResponse(context, url, request, response) {
  if (typeof response.body === "object") response.body.debug = true;
  return response;
}

勾选作为 Mock API 后不访问服务器，由 onResponse 生成响应。脚本默认 5 秒超时，出错时请求继续，错误显示在控制台。

WebSocket

function onWebsocket(context, url, message) {
  // message: { direction: "client" | "server", isBinary, data }
  if (message.data.includes("ping")) return null; // 丢弃
  message.data = message.data.replace("old", "new");
  return message;
}

二进制消息的 data 是 base64 字符串。

引用模块

脚本不能访问文件和网络，但可以 require Addons 目录里的模块。脚本 → 打开 Addons 目录。

const sign = require("@addons/sign.js");

自定义预览器

工具 → 自定义预览器…中定义 onPreview(context, url, request, response)，返回的文本显示在响应的自定义标签中。

证书

解密 HTTPS 需要客户端信任 Capture 的根证书，并把域名加入 SSL 代理列表。

信任根证书后，持有这张证书私钥的程序可以解密这台 Mac 的 TLS 流量。不再使用时选证书 → 移除已安装的根证书…

SSL 代理列表

⇧⌘L 打开，支持通配符和正则。只有列表中的域名会被解密，排除列表优先。

证书菜单

• 导出为 PEM 或 DER，或导入自己的根证书。导入会覆盖现有根证书，且无法恢复。
• Firefox、Java、Node.js、Python 有各自的证书库，菜单中有对应指引。

客户端证书和服务端证书

在Capture → 设置… → 证书按域名添加。客户端证书用于要求 mTLS 的服务器，服务端证书替代自动签发的证书。文件需要 PEM 格式，p12 可以这样转换：

openssl pkcs12 -in client.p12 -nodes -out client.pem

TLS 密钥日志

工具 → TLS 密钥日志记录写入 SSLKEYLOGFILE 格式的文件，可供 Wireshark 解密。

这个文件能解密抓到的流量，用完后请关闭记录并删除文件。

代理设置

端口、局域网访问在工具 → 代理设置，其余选项在 Capture → 设置… → 连接。

抓包上限

在 Capture → 设置… → 抓包调整。默认保留 20000 个请求，Body 内存预算 512 MB，磁盘预算 4 GB，单个 Body 最多捕获 64 MB。

内存超过预算时，已完成请求的 Body 写入磁盘，查看时自动读回。磁盘超过预算时淘汰最旧的请求。重启后磁盘上的 Body 会被清除，需要保留时请保存会话。

模拟器、手机和终端

打开设置 → 模拟器与终端…，这些操作只影响所选设备或新窗口。

用完 Android 设备后点清除代理，否则 Capture 退出后设备会无法联网。

会话与导入导出

当前流量可以保存成文件，也可以导出给其他工具。

自动保存

在 Capture → 设置… → 抓包设置间隔，默认关闭。历史文件从文件 → 会话历史打开。

分享到 Gist

选中请求后选分享到 GitHub Gist…，需要已登录 gh。Gist 不公开列出，但拿到链接的人都能查看。

Authorization、Cookie 等 Header 会脱敏，URL 和 Body 可能仍含敏感信息，分享前请确认。

从 Charles 迁移

规则和抓包记录都可以带过来。

导入规则

1. 在 Charles 中导出设置，得到 .xml 文件。
2. 选择工具 → 导入 / 导出设置 → 从 Charles 导入规则…
3. 确认显示的规则数量后导入。

支持 Map Local、Map Remote、断点、黑白名单、DNS 欺骗、反向代理和 SSL 域名。规则放进新的“Charles 导入”文件夹，相同的规则会跳过。

在 Charles 中启用的规则导入后立即生效。反向代理默认停用，因为启用后会占用端口。

打开抓包记录

.chlsj 可以直接打开。.chls 和 .chlz 需要本机安装 Charles 来转换，也可以先在 Charles 里导出为 HAR。

MCP 与 Claude Code

连接后，Claude Code 可以读取流量、定位问题、创建调试规则。使用时 Capture 要保持运行。

连接

在工具 → MCP / AI 集成…点一键添加到 Claude Code。也可以在终端运行：

claude mcp add --scope user capture -- \
  /path/to/Capture.app/Contents/MacOS/capture-core mcp

同一窗口还提供其他客户端的 JSON 配置，以及带 Token 的 localhost HTTP 端点。

可以让它做什么

• “找出刚才所有 5xx 的请求，分析原因。”
• “把 api.example.com/v1/user 的响应 Mock 成空列表。”
• “只看响应里 code 不为 0 的请求。”

工具

隐私控制

• 默认脱敏 Authorization、Cookie、token、password 等，导出和过滤同样遵守。
• 可以指定 AI 完全看不到的域名。
• 可以开启只读模式，禁止修改规则和发送请求。

命令行

capture-cli 需要 Capture 正在运行。加 --json 输出原始 JSON。

流量

capture-cli status
capture-cli flows --host api.example.com --status 5xx
capture-cli flow 42
capture-cli search token --in response_body
capture-cli decode 42 --jq '.items[].id'
capture-cli curl 42
capture-cli repeat 42
capture-cli record off
capture-cli har out.har

规则

capture-cli rules
capture-cli map-local add 'api.example.com/v1/*' --file mock.json --folder Mocks
capture-cli map-remote add 'api.example.com/*' http://localhost:3000
capture-cli block add 'ads.example.com/*' --drop
capture-cli script add 'api.example.com/*' --file script.js
capture-cli ssl enable api.example.com

运行 capture-cli help 查看全部命令。

快捷键

也可以按 ⇧⌘P 打开命令面板，搜索任意命令。

查看

请求

工具

文件

URL 匹配语法

断点、Map、黑白名单、脚本和网络条件都用同一种写法。

GraphQL

规则可以附加 GraphQL 操作名条件，如 getUser、get* 或 /^(login|logout)$/。

域名写法

SSL 列表、DNS 欺骗、外部代理路由按域名匹配：example.com、*.example.com（同时匹配 example.com 本身）或 /正则/。

过滤字段

高级过滤和 MCP 的 filter_flows 使用同一套字段。下面的英文名用于 MCP。

运算符

故障排除

帮助 → 故障排除…会检查代理、证书和 VPN 状态。

数据目录

~/Library/Application Support/Capture