# 无界面模式 > 让 Proxyman 在没有窗口、程序坞图标和对话框的情况下运行，使 AI 智能体和脚本可通过 MCP 抓取并解密 HTTPS。适用于 Proxyman 26.6.0 或更高版本。 无界面模式（Headless）让 Proxyman 在没有窗口、没有程序坞或菜单栏图标、也没有对话框的情况下运行。你的 AI 智能体（如 Claude Code、Codex 或 Cursor）可以通过 [MCP](https://proxyman.com/docs/zh-cn/mcp) 自行启动 Proxyman、抓取并解密 HTTPS、读取流量并创建调试规则。它的用法类似 mitmproxy，并且支持 Proxyman 的所有工具。 > **备注:** 无界面模式适用于 Proxyman 26.6.0 或更高版本。与 Proxyman MCP 的其他功能一样，它需要付费的 Proxyman 许可证。

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

## 1. 设置 {#1-set-up} 在命令末尾加上 `--headless`，将 Proxyman MCP 添加到你的智能体。 ### Claude Code {#claude-code} ```bash claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless ``` ### Codex {#codex} ```bash codex mcp add proxyman -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless ``` ### Cursor 和其他 MCP 客户端 {#cursor-and-other-mcp-clients} ```json { "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 {#2-capture-https-with-no-dialogs} 例如，你可以这样对智能体说： > 以无界面模式启动 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](https://proxyman.com/docs/zh-cn/basic-features/ssl-proxying)。 4. **发送流量：** 每个客户端自行使用代理并信任该 CA（见下表）。 5. **读取流量：** `get_flows`、`filter_flows` 和 `get_flow_detail` 会返回已解密的请求和响应。 | 客户端 | 代理和证书 | | --- | --- | | curl | `curl -x http://127.0.0.1:9090 --cacert 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= node app.js` | | Python（requests、httpx） | `HTTPS_PROXY=http://127.0.0.1:9090 SSL_CERT_FILE= REQUESTS_CA_BUNDLE= 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= --user-data-dir=`。没有 `--user-data-dir` 时，Chrome 会忽略 SPKI 列表。 | | Firefox | 使用 `firefox` 调用 `run_guided_setup`（请先退出 Firefox）。参阅 [Firefox](https://proxyman.com/docs/zh-cn/debug-devices/firefox)。 | | iOS Simulator | `install_ios_simulator_certificate`。参阅 [iOS Simulator](https://proxyman.com/docs/zh-cn/debug-devices/ios-simulator)。 | 使用 curl 手动完成相同的步骤： ```bash # 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. 无界面模式下有哪些变化 {#3-what-changes-in-headless-mode} * **始终在记录。** Proxyman 不会更改 macOS 系统代理，因此只有你指向 `127.0.0.1:9090` 的客户端才会被抓取。如需抓取所有应用，请让智能体调用 `set_system_proxy`，或使用 [Network Extension](https://proxyman.com/docs/zh-cn/advanced-features/network-extension)。 * **没有提示框或窗口。** 原本会弹出的提示会改为输出到 stdout。[Breakpoint](https://proxyman.com/docs/zh-cn/advanced-features/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](https://proxyman.com/docs/zh-cn/advanced-features/access-control)。 * **随时显示窗口：** 打开 Proxyman.app，或调用 `open_proxyman` 并传入 `headless: false`。已抓取的流量会保留。 * **同一时间只运行一个 Proxyman：** 如果 Proxyman 已带窗口打开，MCP 会使用它，不会再启动第二个无界面实例。 ## 4. 仍需你手动完成一次的操作 {#4-what-still-needs-you-once} 无界面模式绝不会显示对话框，因此以下步骤需要你亲自完成一次： * **Safari、使用 macOS 信任库的应用（URLSession）和 Go：** 它们只接受已受信任的证书。请运行一次 `install_certificate` 并传入 `mode: automatic`，macOS 会要求输入密码。它会创建新的 CA，因此之后请重新完成上述各客户端的信任设置。 * **`set_system_proxy`：** Helper Tool 首次使用时会要求输入密码。 * **Network Extension：** macOS 会要求你允许一次。 * **iPhone 或 Android 真机：** 在设备上安装并信任证书。参阅[在设备上调试](https://proxyman.com/docs/zh-cn/debug-devices/ios-device)。 ## 5. 在 Shell 或 CI 中运行 {#5-run-it-from-a-shell-or-ci} 你也可以不借助智能体，直接启动无界面的 Proxyman： ```bash /Applications/Proxyman.app/Contents/MacOS/Proxyman --headless & ``` 它会在 stdout 输出状态信息，一直运行到你按下 Ctrl+C 或执行 `kill `。你可以使用 [proxyman-cli](https://proxyman.com/docs/zh-cn/command-line) 与它配合，例如导出已抓取的流量： ```bash proxyman-cli export-log -m all -f har -o session.har ``` > **注意:** 不要使用 `open -a Proxyman --args --headless` 启动。如果 Proxyman 已在运行，macOS 会丢弃该参数并显示窗口。 ## 了解更多 {#learn-more} * [MCP](https://proxyman.com/docs/zh-cn/mcp) * [命令行](https://proxyman.com/docs/zh-cn/command-line) * [Proxyman 现已支持为 AI 智能体提供无界面模式](https://proxyman.com/posts/2026-11-13-proxyman-headless-mode-for-ai-agents)