proxycrab README

The project's README from github.com/Yricky/proxycrab. As one markdown file: README.md.

ProxyCrab

支持 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 分享页面
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 压缩包。

支持作者

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

友情链接

Linux.do

proxycrab (Yricky/proxycrab)

Searching Database…

247 ·GitHub
Proxycrab
What is this?ProxyCrab is an open-source HTTP/HTTPS traffic capture and debugging tool built for developers and AI agents. It lets you filter failing requests, track debugging changes, and share a captured session with others.
Is it a desktop app or a command-line tool?Both. There is a desktop app for macOS, Linux and Windows. There is also a CLI that runs the proxy on a machine, often a remote debugging one, and is managed from a browser with no separate frontend deployment.
How do I get it running?Start the desktop app, create a Session and set it active, then download the CA certificate. Point the HTTP/HTTPS proxy of your device or app at the machine running ProxyCrab on port 8089, and start the proxy. The CLI prints a browser management address and an access token on startup.
Do I need anything else installed first?The README lists no runtime dependencies. Desktop installers and CLI archives are published on Releases. AI workflows need an external Agent that uses the ProxyCrab Skill, and CLI users install that Skill with a local command.
Does HTTPS capture always work?Only if the client trusts the ProxyCrab CA. Clients with certificate pinning may not be captured directly. WebSocket support covers only connections made through HTTP/1.1 Upgrade.
Which platforms are supported?The desktop app targets macOS ARM64 (DMG), Linux x64 (AppImage) and Windows x64 (EXE/MSI). The CLI targets Linux x64 and ARM64, macOS ARM64 and Windows x64. The README lists no Intel Mac build.
Can I run it on a remote server?Yes, via the CLI. The README says the default HTTP management connection is unencrypted, so use SSH port forwarding or a reverse proxy with authentication and TLS, and keep it on trusted networks.
Can I share a debugging setup, not just the traffic?Yes. You can export a config bundle with interceptors, filters, custom columns and chosen resources. The recipient drags the ZIP in and picks which Session to import into. Capture history is not included.
Can I add custom columns from response data?Yes. Lua can pull business fields such as error codes or order IDs out of requests and responses into custom columns and filters. Each Session keeps its own column setup.
Does it handle WebSocket messages?Yes. A two-way timeline shows client and server messages as text or binary. Lua callbacks can drop, send or replace messages, and you can see where each message came from.
What are similar projects?brook, mitmproxy, MasterHttpRelayVPN-RUST, dev-sidecar, clash-nyanpasu, proxypin, dbx, rayburst
Which topics is it in?packet-capture, mock, mitm, lua, debugging, tauri, vue, proxy, networking, agent-skills, rust, chinese
Creator
Yricky
Size
5.3 MB
Stars
247
Updated
CommitNov 01Releasev1.1.0Nov 01
Age
1mo
Commits · 90 Days