본문으로 건너뛰기

헤드리스 모드

창, Dock 아이콘, 대화상자 없이 Proxyman을 실행해 AI 에이전트와 스크립트가 MCP로 HTTPS를 캡처하고 복호화합니다. Proxyman 26.6.0 이상에서 사용할 수 있습니다.

헤드리스 모드는 창, Dock 또는 메뉴 막대 아이콘, 대화상자 없이 Proxyman을 실행합니다. Claude Code, Codex, Cursor 같은 AI 에이전트가 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이 헤드리스로 시작되고, 에이전트가 작업을 마치면 종료됩니다.

팁

--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를 만들어 신뢰 설정 없이 로그인 Keychain에 추가하므로 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
모든 셸 도구같은 셸에서 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 목록을 무시합니다.
Firefoxfirefox로 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가 그것을 사용하며, 두 번째 헤드리스 Proxyman은 시작되지 않습니다.

4. 한 번은 직접 해야 하는 작업​

헤드리스 모드는 대화상자를 표시하지 않으므로, 다음 작업은 한 번 직접 해야 합니다.

  • Safari, macOS 신뢰 저장소를 사용하는 앱(URLSession), Go: 신뢰된 인증서만 허용합니다. install_certificate를 mode: automatic으로 한 번 실행하세요. macOS가 암호를 요청합니다. 새 CA가 만들어지므로 그 후에 위의 클라이언트별 신뢰 설정을 다시 하세요.
  • set_system_proxy: 처음에는 Helper Tool이 암호를 요청합니다.
  • Network Extension: macOS가 허용 여부를 한 번 묻습니다.
  • 실제 iPhone 또는 Android 기기: 기기에 인증서를 설치하고 신뢰하세요. 기기에서 디버깅을 참고하세요.

5. 셸 또는 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가 인수를 무시하고 창을 표시합니다.

더 알아보기​

최종 수정: 에