跳到主要内容

无界面模式

让 Proxyman 在没有窗口、程序坞图标和对话框的情况下运行，使 AI 智能体和脚本可通过 MCP 抓取并解密 HTTPS。适用于 Proxyman 26.6.0 或更高版本。

无界面模式（Headless）让 Proxyman 在没有窗口、没有程序坞或菜单栏图标、也没有对话框的情况下运行。你的 AI 智能体（如 Claude Code、Codex 或 Cursor）可以通过 MCP 自行启动 Proxyman、抓取并解密 HTTPS、读取流量并创建调试规则。它的用法类似 mitmproxy，并且支持 Proxyman 的所有工具。

信息

无界面模式适用于 Proxyman 26.6.0 或更高版本。与 Proxyman MCP 的其他功能一样，它需要付费的 Proxyman 许可证。

Claude Code 以无界面模式启动 Proxyman，无需对话框即可创建证书，通过 127.0.0.1:9090 发送 HTTPS 请求并读取已解密的请求记录。全程不会打开 Proxyman 窗口。

1. 设置​

在命令末尾加上 --headless，将 Proxyman MCP 添加到你的智能体。

Claude Code​

claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless

Codex​

codex mcp add proxyman -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless

Cursor 和其他 MCP 客户端​

{
  "mcpServers": {
    "proxyman": {
      "command": "/Applications/Proxyman.app/Contents/MacOS/mcp-server",
      "args": ["--headless"]
    }
  }
}

Setapp 版本请使用 /Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server。

这样就完成了。你无需打开 Proxyman，也无需开启 Settings → MCP：首次调用工具时会以无界面模式启动 Proxyman，智能体完成工作后 Proxyman 会自动退出。

提示

已经添加了不带 --headless 的 Proxyman MCP？请让智能体“以无界面模式启动 Proxyman”，它会调用 open_proxyman 并传入 headless: true。

2. 无需对话框即可抓取 HTTPS​

例如，你可以这样对智能体说：

以无界面模式启动 Proxyman，无需对话框创建它的 CA，并解密 api.example.com。然后通过 127.0.0.1:9090 运行我的测试，告诉我哪些请求失败了。

智能体会按以下步骤操作：

  1. 启动 Proxyman： 调用 open_proxyman 并传入 headless: true。它会返回代理地址，默认为 http://127.0.0.1:9090。
  2. 创建证书： 调用 install_certificate 并传入 mode: generate_only，会创建 Proxyman CA 并将其添加到登录钥匙串，但不设为信任，因此 macOS 不会弹出对话框。它会返回 certificate_path（PEM 文件）和 spki_sha256。
  3. 解密域名： 对 api.example.com 或通配符（如 *.example.com）调用 enable_ssl_proxying。参阅 SSL Proxying。
  4. 发送流量： 每个客户端自行使用代理并信任该 CA（见下表）。
  5. 读取流量： get_flows、filter_flows 和 get_flow_detail 会返回已解密的请求和响应。
客户端代理和证书
curlcurl -x http://127.0.0.1:9090 --cacert <certificate_path> https://api.example.com
Node.js 22.21+ 或 24.5+HTTPS_PROXY=http://127.0.0.1:9090 NODE_USE_ENV_PROXY=1 NODE_EXTRA_CA_CERTS=<certificate_path> node app.js
Python（requests、httpx）HTTPS_PROXY=http://127.0.0.1:9090 SSL_CERT_FILE=<certificate_path> REQUESTS_CA_BUNDLE=<certificate_path> python app.py
任意 Shell 工具在同一个 Shell 中运行 get_terminal_manual_command 返回的命令。它会为 Node.js、Python、Ruby 和 curl 设置代理和证书，也适用于旧版 Node.js。
Chrome、Playwright、Puppeteer--proxy-server=http://127.0.0.1:9090 --ignore-certificate-errors-spki-list=<spki_sha256> --user-data-dir=<temp folder>。没有 --user-data-dir 时，Chrome 会忽略 SPKI 列表。
Firefox使用 firefox 调用 run_guided_setup（请先退出 Firefox）。参阅 Firefox。
iOS Simulatorinstall_ios_simulator_certificate。参阅 iOS Simulator。

使用 curl 手动完成相同的步骤：

# 1. certificate_path from install_certificate or get_certificate_status
CA="$HOME/Library/Application Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem"

# 2. Send an HTTPS request through Proxyman
curl -x http://127.0.0.1:9090 --cacert "$CA" https://httpbin.org/json

3. 无界面模式下有哪些变化​

  • 始终在记录。 Proxyman 不会更改 macOS 系统代理，因此只有你指向 127.0.0.1:9090 的客户端才会被抓取。如需抓取所有应用，请让智能体调用 set_system_proxy，或使用 Network Extension。
  • 没有提示框或窗口。 原本会弹出的提示会改为输出到 stdout。Breakpoint 不会打开窗口：智能体通过 list_pending_breakpoints 和 resolve_breakpoint 来处理。
  • 所有 MCP 工具均可使用， 只有少数仅用于改变窗口显示内容的工具除外，例如 open_proxyman_screen 和 set_flow_filter。请改用 get_flows 或 filter_flows 进行过滤。
  • 会话文件： open_session_file 会将会话、HAR 或日志文件作为智能体读取的会话打开，close_session_file 则返回实时流量。
  • Access Control 不会询问。 任何能访问代理端口的设备都可以使用它。如果只想接受这台 Mac，请让智能体通过 update_settings 开启 proxy.listen_on_localhost_only。参阅 Access Control。
  • 随时显示窗口： 打开 Proxyman.app，或调用 open_proxyman 并传入 headless: false。已抓取的流量会保留。
  • 同一时间只运行一个 Proxyman： 如果 Proxyman 已带窗口打开，MCP 会使用它，不会再启动第二个无界面实例。

4. 仍需你手动完成一次的操作​

无界面模式绝不会显示对话框，因此以下步骤需要你亲自完成一次：

  • Safari、使用 macOS 信任库的应用（URLSession）和 Go： 它们只接受已受信任的证书。请运行一次 install_certificate 并传入 mode: automatic，macOS 会要求输入密码。它会创建新的 CA，因此之后请重新完成上述各客户端的信任设置。
  • set_system_proxy： Helper Tool 首次使用时会要求输入密码。
  • Network Extension： macOS 会要求你允许一次。
  • iPhone 或 Android 真机： 在设备上安装并信任证书。参阅在设备上调试。

5. 在 Shell 或 CI 中运行​

你也可以不借助智能体，直接启动无界面的 Proxyman：

/Applications/Proxyman.app/Contents/MacOS/Proxyman --headless &

它会在 stdout 输出状态信息，一直运行到你按下 Ctrl+C 或执行 kill <pid>。你可以使用 proxyman-cli 与它配合，例如导出已抓取的流量：

proxyman-cli export-log -m all -f har -o session.har
注意

不要使用 open -a Proxyman --args --headless 启动。如果 Proxyman 已在运行，macOS 会丢弃该参数并显示窗口。

了解更多​

最后于 更新