# 헤드리스 모드
> 창, Dock 아이콘, 대화상자 없이 Proxyman을 실행해 AI 에이전트와 스크립트가 MCP로 HTTPS를 캡처하고 복호화합니다. Proxyman 26.6.0 이상에서 사용할 수 있습니다.
헤드리스 모드는 창, Dock 또는 메뉴 막대 아이콘, 대화상자 없이 Proxyman을 실행합니다. Claude Code, Codex, Cursor 같은 AI 에이전트가 [MCP](https://proxyman.com/docs/ko/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이 헤드리스로 시작되고, 에이전트가 작업을 마치면 종료됩니다.
> **팁:** `--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를 만들어 신뢰 설정 없이 로그인 Keychain에 추가하므로 macOS에 대화상자가 표시되지 않습니다. `certificate_path`(PEM 파일)와 `spki_sha256`을 반환합니다.
3. **도메인 복호화:** `api.example.com` 또는 `*.example.com` 같은 와일드카드에 `enable_ssl_proxying`을 호출합니다. [SSL Proxying](https://proxyman.com/docs/ko/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` |
| 모든 셸 도구 | 같은 셸에서 `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/ko/debug-devices/firefox)를 참고하세요. |
| iOS Simulator | `install_ios_simulator_certificate`. [iOS Simulator](https://proxyman.com/docs/ko/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/ko/advanced-features/network-extension)을 사용하세요.
* **알림이나 창이 없습니다.** 알림으로 표시되던 내용은 대신 stdout에 출력됩니다. [Breakpoint](https://proxyman.com/docs/ko/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/ko/advanced-features/access-control)을 참고하세요.
* **언제든 창을 표시할 수 있습니다.** Proxyman.app을 열거나 `open_proxyman`을 `headless: false`로 호출하세요. 캡처한 트래픽은 그대로 유지됩니다.
* **한 번에 하나의 Proxyman만 실행됩니다.** 창이 있는 Proxyman이 이미 열려 있으면 MCP가 그것을 사용하며, 두 번째 헤드리스 Proxyman은 시작되지 않습니다.
## 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/ko/debug-devices/ios-device)을 참고하세요.
## 5. 셸 또는 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/ko/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/ko/mcp)
* [명령줄](https://proxyman.com/docs/ko/command-line)
* [AI 에이전트를 위한 Proxyman 헤드리스 모드 출시](https://proxyman.com/posts/2026-11-13-proxyman-headless-mode-for-ai-agents)