proxycrab README

项目的 README,来自 github.com/Yricky/proxycrab。合并为一个 markdown 文件:README.md。

ProxyCrab

English | 简体中文

支持 Agent 协作的 HTTP/HTTPS 抓包与调试工具。

通过 Lua 定制请求与响应,检查 WebSocket 双向消息,把 Session 分享给同事或 Agent。支持桌面应用,也支持通过 CLI 运行并在浏览器中管理。

ProxyCrab 主界面:Session、业务自定义列与请求详情

本页截图来自实际运行的 CLI 浏览器管理界面,使用独立演示工作区和本机生成的示例流量。

核心能力

与 Agent 一起调试真实流量

ProxyCrab 提供管理 HTTP API 和配套 Skill,让 Agent 直接读取抓包数据、配置调试规则,并将操作结果同步到界面。

你可以让 Agent:

例如:

检查这个 Session 中登录失败的请求,将响应里的业务错误码添加为一列,并说明失败原因。

工作区支持 AGENTS.md 行为预设,可选择只读取现有数据,或允许 Agent 调整调试配置。管理 API 提供按操作配置的权限,桌面端还支持人工审批。

Agent 能力由外部 Agent 配合 ProxyCrab Skill 提供。

用 Lua 控制请求与响应

为每个 Session 组织独立的请求、响应拦截器链,按顺序执行、启停和调整脚本。

例如,在响应拦截器中修改 JSON:

local data = resp.body:as_json()
if data then
    data.message = "Hello from ProxyCrab"
    resp.body:replace_with_string(json.encode(data))
end

脚本后续发生变化,也可以通过抓包记录查看当时实际执行的版本。

Lua 调试:暂停结算响应并执行临时脚本

详见 Lua API。

分享调试现场,复用调试配置

为 Session 创建只读链接,让接收者直接通过浏览器查看流量,无需安装 ProxyCrab。

分享页面支持:

链接可以临时使用,也可以设置为重启后保留;关闭分享后立即失效。可为分享链接配置读取时脱敏策略,在支持的读取范围内隐藏或替换敏感字段,同时保留原始抓包数据。

需要复用调试配置时,还可以开放 Session 配置下载,打包相关拦截器、过滤器、自定义列和选定资源。接收者拖入 ZIP,选择要导入的 Session,并处理文件冲突。

配置包不包含抓包历史,脚本使用的资源需要由分享者选择。

详见 Session 配置分享与导入。

更多调试方式

WebSocket 双向消息调试

在双向时间轴中检查客户端与服务端消息,查看文本或二进制内容,并追踪连接状态。

通过 Lua 消息回调,可以:

例如,在请求拦截器中注册回调,拦截客户端的 ping 并直接回复 pong:

req:on_ws_message(function(ws)
    local message = ws.message
    if message.direction == "request"
        and message.type == "text"
        and message.body == "ping" then
        ws:drop()
        ws:send("response", "pong", "text")
    end
end)

当前支持通过 HTTP/1.1 Upgrade 建立的 WebSocket 连接。

WebSocket 调试:双向消息时间轴与 Lua 生成消息的来源

把业务字段放进抓包列表

除了方法、URL、状态码等内置列,还可以通过 Lua 从请求和响应中提取业务字段,创建自定义列与过滤条件。

例如,将响应中的业务错误码显示为一列:

local data = entry.resp and entry.resp.body:as_json()
return data and data.code or nil

适合检查“HTTP 状态码为 200,但业务处理失败”等情况,也可以用于展示订单号、请求标识或业务状态。

每个 Session 保存自己的列配置和过滤条件。

业务自定义列:按错误码筛选 HTTP 200 的结算失败请求

桌面操作与远程浏览器管理

在本机使用桌面应用,或在远程调试机上启动 CLI,通过浏览器管理代理。

两种运行方式共享代理核心和主要调试界面。CLI 内嵌浏览器管理页面,不需要另外部署前端服务。

运行方式 当前构建目标
桌面应用 macOS ARM64(DMG)、Linux x64(AppImage)、Windows x64(EXE / MSI)
CLI Linux x64 / ARM64、macOS ARM64、Windows x64

部分宿主能力有所区别:桌面端提供人工审批和 Skill 路径管理;CLI 提供允许/拒绝权限配置,并通过本地命令安装 Skill。

其他能力

功能 用途
请求编辑与重放 修改并重新发送请求,经过所选 Session 的拦截器链
CA 下载与 Clash 订阅 通过证书下载、订阅链接和二维码配置设备接入
Session 归档与恢复 按问题或调试阶段保存、整理抓包记录
Lua 分流规则 决定流量进入当前活跃 Session,或直接转发
Body 查看与下载 查看文本、图片及 Protobuf/gRPC 数据结构,下载完整解码内容
HAR 导出 导出当前筛选结果中的 HTTP 请求记录
工作区资源 为 Mock、Body 替换和请求重放管理可复用文件
调试小工具 Base64 编解码、JWT 解码与验签、二维码、文本比对

快速开始

桌面应用

  1. 启动 ProxyCrab,创建一个 Session 并将其设为活跃。
  2. 打开“连接”中的“证书配置”,下载 CA;需要抓取 HTTPS 时,在被调试设备上安装并信任它。
  3. 将设备或应用的 HTTP/HTTPS 代理指向 ProxyCrab 所在机器,默认代理端口为 8089。
  4. 在 ProxyCrab 中启动代理。
  5. 发起请求,在 Session 中查看捕获结果。

使用 Clash 接入时,可以在“代理连接”页面选择本机 IP,开启并导入订阅。

桌面应用启动时代理默认停止。没有活跃 Session 时,流量直接转发;选择分流脚本后,由脚本决定是否捕获。

CLI 与浏览器管理

proxycrab-cli run --workspace /path/to/workspace

CLI 启动后运行代理,并输出浏览器管理地址和 Access Token。打开地址,输入 Token,即可进入管理界面。

默认端口:

服务 端口
HTTP/HTTPS 代理 8089
管理界面与 HTTP API 18089

可通过启动参数覆盖监听配置:

proxycrab-cli run \
  --workspace /path/to/workspace \
  --proxy-port 8089 \
  --api-port 18089

远程访问可使用 SSH 端口转发,或通过配置了认证和 TLS 的反向代理访问。默认 HTTP 连接不加密,应在可信网络中使用。

配置 Agent Skill

桌面端打开 AI → 管理 Skill,配置 Agent 使用的 Skill 父目录并同步。

CLI 用户可以运行:

proxycrab-cli install-skill --parent ~/.agents/skills

随后让支持该 Skill 的 Agent 读取 ProxyCrab 工作区,或提供 Session 分享链接进行排查。

详见 ProxyCrab Skill。

使用说明

文档

开发

项目使用 Rust、Tauri 和 Vue。桌面应用与 CLI 复用代理核心、管理接口和前端代码。

目录 内容
crates/proxy-crab-mitm 代理、TLS、抓包存储与 Lua 执行
crates/proxy-crab-mgr 管理接口、权限契约与分享服务
src-tauri 桌面应用集成
cli-app CLI 与内嵌浏览器管理服务
src Vue 管理界面与 Session 分享页面
src/api/generated ts-rs 从 Rust 类型生成的 TS 绑定(cargo test --workspace 产出,提交入库,CI 校验未漂移)
skills/proxycrab Agent Skill、脚本与参考文档

安装前端依赖:

pnpm install

启动桌面开发环境:

pnpm tauri dev

构建 CLI 时,先生成需要嵌入的前端资源:

pnpm build
cargo build --release -p proxycrab-cli

检查与测试:

cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
pnpm test:unit
pnpm build

Linux AppImage 的 WebKit 开发方式及其他实现细节见运行与开发细节。

CI 构建与 Release

推送 build/* 分支或手动运行 Build Artifacts 工作流,会构建上表中的全部 Desktop 和 CLI 目标,并上传 CI 产物。

推送以 build/v 开头的分支时,全部构建成功后自动发布正式 Release。例如,build/v1.2.0 对应标签和标题 v1.2.0。再次推送同一分支会更新该 Release 的附件,并将标签移至本次构建的提交。手动运行工作流不发布 Release。

Release 附件直接提供 Linux AppImage、macOS DMG、Windows EXE / MSI 安装包,以及四个平台的 CLI 压缩包。

支持作者

ProxyCrab采用 MIT 协议开源,完全免费使用。如果觉得这款软件对你有用,可以通过以下渠道支持一下作者

友情链接

Linux.do

proxycrab (Yricky/proxycrab)

正在搜索数据库…

这是什么?ProxyCrab 是一款开源的 HTTP/HTTPS 流量捕获与调试工具,面向开发者和 AI Agent 打造。你可以筛选出失败的请求、跟踪调试过程中的修改,并与他人分享捕获的会话。
这是桌面应用还是命令行工具?两者都有。桌面应用支持 macOS、Linux 和 Windows。另外还有一个 CLI,可在一台机器(通常是远程调试机器)上运行代理,并通过浏览器进行管理,无需单独部署前端。
如何让它运行起来?启动桌面应用,创建一个会话并将其设为活动状态,然后下载 CA 证书。将设备或应用的 HTTP/HTTPS 代理指向运行 ProxyCrab 的机器的 8089 端口,并启动代理。CLI 启动时会输出浏览器管理地址和访问令牌。
使用前是否需要先安装其他软件?README 中未列出任何运行时依赖。桌面安装包和 CLI 压缩包都发布在 Releases 页面。AI 工作流需要一个使用 ProxyCrab Skill 的外部 Agent,CLI 用户则通过一条本地命令安装该 Skill。
HTTPS 捕获是否总能成功?只有客户端信任 ProxyCrab 的 CA 时才行。启用证书固定(certificate pinning)的客户端可能无法被直接捕获。WebSocket 支持仅覆盖通过 HTTP/1.1 Upgrade 建立的连接。
支持哪些平台?桌面应用支持 macOS ARM64(DMG)、Linux x64(AppImage)和 Windows x64(EXE/MSI)。CLI 支持 Linux x64 和 ARM64、macOS ARM64 以及 Windows x64。README 中未列出 Intel 版 Mac 的构建。
能否在远程服务器上运行?可以,通过 CLI 实现。README 指出默认的 HTTP 管理连接未加密,因此请使用 SSH 端口转发,或使用带身份验证和 TLS 的反向代理,并将其保持在可信网络中。
我能分享调试配置,而不只是流量吗?可以。你可以导出一个配置包,其中包含拦截器、过滤器、自定义列以及所选的资源。接收方将 ZIP 文件拖入应用,并选择要导入到哪个会话。捕获历史不包含在内。
我能根据响应数据添加自定义列吗?可以。Lua 可以从请求和响应中提取业务字段(如错误码或订单 ID),用于自定义列和过滤器。每个会话都保留各自的列设置。
它能处理 WebSocket 消息吗?可以。双向时间线会以文本或二进制形式显示客户端和服务器的消息。Lua 回调可以丢弃、发送或替换消息,并且可以查看每条消息的来源。
作者
Yricky
大小
6.1 MB
星标
313
时长
1个月
提交 · 90 天