OpenClaw와 Headroom 프록시로 API 비용 최대 80% 절감: 2026 macOS 실전 가이드

OpenClaw 야간 저장소 감사는 린터, 테스트 러너, grep 폭주를 셸로 실행해 수 MB의 JSON을 모델 컨텍스트로 돌려줍니다. 모든 원시 바이트에 Anthropic 정가를 지불하면 잘 통제된 자동화도 네 자릿수 달러 API 비용 항목이 됩니다. Headroom은 게이트웨이와 공급자 사이에 위치합니다. 요청이 api.anthropic.com에 닿기 전에 SmartCrusher / CodeCompressor / CCR로 도구 출력·로그·이력을 압축하는 기본 포트 8787의 로컬 프록시입니다. 공개 벤치마크는 SRE 계열 트레이스에서 92%, 코드 검색 워크로드에서 73–92%의 토큰 절감을 보여 주며, 본 가이드는 Skill 마크다운을 바꾸지 않고 도구 집약 턴에서 60–80%+ 절감을 목표로 합니다.

이를 OpenClaw 토큰 예산과 도구 스로틀 가이드의 지출 가드, macOS의 LaunchAgent와 cron 게이트웨이 스케줄링과 함께 사용하세요. 시크릿 관리는 openclaw.json과 .env 프로필에 있습니다.

고지: MacHTML은 게이트웨이 검증용 클라우드 Mac mini 대여를 선택적으로 제공합니다. 본 런북은 공급사 중립이며 모든 macOS 호스트에서 작동합니다.

왜 OpenClaw + Headroom이 독특한 스택인가

OpenClaw은 상시 게이트웨이에 강합니다. Slack/Telegram 수신, 도구 허용 목록, 거대한 워크스페이스 트리를 다시 읽는 다단계 Skill 등입니다. Headroom은 컨텍스트 압축에 강하며, 의도를 요약하는 게 아니라 도구가 반환하는 내용을 줄입니다. 대부분의 팀이 한 가지 레버만 선택하기에 이 조합은 드뭅니다.

레버	줄이는 대상	맹점
OpenClaw 스로틀만	턴 수, 동시성	50 KB linter JSON을 그대로 전송
더 작은 모델만	입력/출력 $/토큰	복잡한 감사에서 발견 누락
Skill 내 수동 로그 절단	임시방편	cron 실행 간 재현성 깨짐
Headroom 프록시 + OpenClaw	공급자 이전의 도구/RAG/로그 토큰	로컬 Python 3.10+ 프로세스 필요

Headroom README는 OpenClaw을 일급 통합(ContextEngine 플러그인 경로와 범용 OpenAI 호환 프록시)으로 나열합니다. OpenClaw의 오케스트레이션은 유지하고, Headroom은 모델이 보는 페이로드 형태를 다시 씁니다.

외부 참고: Headroom GitHub, Headroom 프록시 문서, Anthropic API.

아키텍처: 게이트웨이 → 프록시 → Anthropic

┌─────────────┐   HTTP/SSE    ┌──────────────────────┐   HTTPS    ┌─────────────────┐
│ OpenClaw    │ ────────────► │ Headroom proxy       │ ────────► │ api.anthropic.com│
│ gateway     │ 127.0.0.1:8787│ SmartCrusher + CCR   │           │ (real API key)   │
│ :8788 tools │               │ /v1/messages         │           └─────────────────┘
└─────────────┘               └──────────────────────┘
        ▲                              │
        │ tool stdout/json             │ headroom_retrieve if model needs originals
        └──────────────────────────────┘

라우팅 규칙: OpenClaw은 환경(~/.openclaw/.env)과 openclaw.json에서 공급자 Base URL을 읽습니다. Anthropic 트래픽을 공개 엔드포인트가 아니라 Headroom으로 보내세요. Headroom은 프록시 프로세스 환경의 실제 ANTHROPIC_API_KEY로 전달합니다. OpenClaw은 같은 키 변수를 유지할 수 있지만 호스트는 로컬이어야 합니다.

포트 규율: Headroom 프록시 기본값은 8787로, 많은 OpenClaw 게이트웨이 예제와 같은 포트입니다. 프로덕션에서는 Headroom을 8787, OpenClaw 게이트웨이를 8788로 분리하세요(반대도 가능). LaunchAgent plist에 쌍으로 기록하세요. 서울 리전 클라우드 Mac mini에서는 프록시를 게이트웨이와 동일 호스트에 두면 지연이 안정적입니다.

단계별 런북 (macOS 2026)

1. proxy 추가 기능과 함께 Headroom 설치

python3 --version   # must be 3.10+
pip install "headroom-ai[proxy]"
headroom --version

Apple Silicon에서는 디스크가 허용하면 pip install "headroom-ai[all]"도 무방합니다. proxy 전용은 이미지를 더 작게 유지합니다.

2. 로깅과 통계를 켜고 프록시 시작

export ANTHROPIC_API_KEY="sk-ant-..."   # real key — proxy forwards upstream
headroom proxy \
  --host 127.0.0.1 \
  --port 8787 \
  --log-file ~/.headroom/openclaw-proxy.jsonl

상태를 확인합니다:

curl -s http://127.0.0.1:8787/health | python3 -m json.tool
curl -s http://127.0.0.1:8787/stats | python3 -m json.tool

테스트 트래픽 후 optimize: true와 늘어나는 tokens_saved가 보여야 합니다.

3. OpenClaw의 Anthropic 호출을 프록시로 라우팅

~/.openclaw/.env를 편집합니다(chmod 600):

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=http://127.0.0.1:8787
# If you use OpenAI-compatible models in the same gateway:
# OPENAI_BASE_URL=http://127.0.0.1:8787/v1

게이트웨이 시작 전에 OpenClaw이 env를 해석하는지 확인하세요——JSON과 .env 프로필 참고. 이 줄들은 커밋하지 마세요.

4. 필요하면 OpenClaw 게이트웨이를 8787에서 이동

Headroom이 8787을 사용할 때 ~/.openclaw/openclaw.json에서 게이트웨이 수신 포트를 8788로 설정합니다:

{
  "gateway": {
    "port": 8788,
    "host": "127.0.0.1"
  }
}

게이트웨이를 재시작합니다. 헬스 프로브는 Headroom 포트가 아니라 8788을 향해야 합니다.

5. 선택 — Headroom 네이티브 OpenClaw 플러그인 경로

Headroom은 OpenClaw을 ContextEngine 플러그인(headroom/providers/openclaw)으로 문서화합니다. 원시 Base URL보다 플러그인 모드를 선호한다면:

pip install "headroom-ai[all]"
headroom wrap openclaw   # when available in your installed version

wrap openclaw가 없으면 proxy + ANTHROPIC_BASE_URL을 유지하세요——프록시 문서가 제시하는 보편 경로입니다.

6. 큰 도구 출력으로 압축 스모크 테스트

큰 JSON(테스트 출력 또는 find 결과)을 반환하는 Skill을 트리거해 비교하세요:

curl -s http://127.0.0.1:8787/stats | python3 -m json.tool
tail -n 5 ~/.headroom/openclaw-proxy.jsonl

목표: 첫 실제 감사에서 savings_percent가 ≥40% 경향, 도구 집약 야간에는 흔히 60–80%를 넘습니다.

7. launchd로 Headroom 상주 (OpenClaw과 병행)

~/Library/LaunchAgents/ai.headroom.proxy.plist를 만들고, ProgramArguments에서 headroom proxy --host 127.0.0.1 --port 8787을 호출하며, ANTHROPIC_API_KEY용 EnvironmentVariables와 ~/.headroom/logs/ 아래 StandardOutPath를 설정합니다. 게이트웨이 부팅 시 Base URL이 해석되도록 ai.openclaw.gateway보다 먼저 로드하세요——패턴은 LaunchAgent cron 가이드에 있습니다.

8. MCP / Claude Code 사이드카 연결 (선택)

Headroom은 MCP 도구(headroom_compress, headroom_retrieve, headroom_stats)를 노출합니다. OpenClaw Skill에 공급하는 Claude Code 샌드박스에는 MCP를 한 번 설치합니다:

headroom mcp install

OpenClaw Skill은 대시보드용으로 동일한 압축 통계 엔드포인트 http://127.0.0.1:8787/stats를 호출할 수 있습니다.

9. 프록시에 예산 가드레일 설정

headroom proxy --port 8787 --budget 50.0 --log-file ~/.headroom/openclaw-proxy.jsonl

--budget 50.0은 Headroom 내부에 USD 일일 상한을 둡니다——OpenClaw 턴별 스로틀을 대체하지 않고 보완합니다.

10. openclaw doctor로 검증

openclaw doctor

doctor는 게이트웨이가 8788에서 정상, 공급자가 127.0.0.1:8787로 도달 가능, 중복 포트 바인드(EADDRINUSE)가 없음을 보여야 합니다.

야간 감사 파이프라인 패턴

보통 로컬 02:00 cron 또는 LaunchAgent가 OpenClaw Skill을 실행합니다:

1. git fetch --all 후 main과 diff
2. 허용된 도구로 npm test / eslint / 맞춤 감사 스크립트 실행
3. 요약을 Slack에 게시

Headroom이 없으면 2단계는 흔히 1.5만–6.5만 토큰의 stderr를 주입합니다(공개 SRE 벤치마크: 65,694 → 5,118 토큰). 프록시 압축이 있어도 모델이 원본을 요청하면 같은 FATAL 줄을 CCR 검색으로 찾을 수 있습니다.

인용 가능: OpenClaw의 Anthropic 트래픽을 127.0.0.1:8787의 Headroom으로 라우팅하면 CCR로 가역성을 유지하면서 도구 집약 컨텍스트를 60–92% 줄일 수 있습니다——대체가 아니라 지출 통제를 위해 OpenClaw 스로틀과 함께 쌓으세요.

메모리 압축과 HTTP 계층 도구 압축을 분리한다면 Hermes 대 OpenClaw에서 하네스 선택을 비교하세요.

문제 해결

채팅에서 게이트웨이가 502 / 연결 거부 반환

증상: 프록시 활성화 직후 OpenClaw 로그에 업스트림 오류가 나타납니다.

해결: Headroom이 수신 중인지 확인하세요(curl http://127.0.0.1:8787/health). 게이트웨이와 프록시가 모두 8787을 시도했다면 포트를 분리하세요(4단계). LaunchAgent를 순서대로 재로드: Headroom 먼저, OpenClaw 다음.

/stats에서 절감이 0% 근처에 머묾

증상: tokens_saved가 평평하고 transforms가 비어 있습니다.

해결: 트래픽이 실제로 프록시를 통과하게 하세요——ANTHROPIC_BASE_URL은 대화형 셸뿐 아니라 게이트웨이 프로세스 환경에 설정해야 합니다. 패스스루 디버깅은 잠시 headroom proxy --no-optimize를 실행해 비교하세요. 큰 페이로드는 작은 프롬프트가 아니라 도구/메시지 본문이어야 합니다.

모델이 스택 트레이스 세부를 "잃음"

증상: 압축된 턴이 감사자가 기대하는 줄 번호를 생략합니다.

해결: Headroom CCR은 원본을 로컬에 저장합니다. Skill 텍스트에서 headroom_retrieve를 허용하거나 진단 한 턴에 x-headroom-bypass: true를 설정하세요. 야간 실행에서 압축을 전역으로 끄지 말고 검색 정책을 고치세요.

Mac mini에서 EMFILE 또는 CPU 급등

증상: 동시 감사 + ML 압축(--llmlingua)이 Apple Silicon을 포화시킵니다.

해결: 최대 축소가 필요 없으면 --llmlingua를 제거하세요. 도구 병렬성 / ulimit 한도에 맞추세요. cron 시간대에는 OpenClaw 동시 도구 호출을 3–5로 제한하세요.

FAQ

Headroom이 OpenClaw 토큰 스로틀을 대체하나요?

아니요. Headroom은 모델에 들어가는 양을 줄이고, OpenClaw은 도구가 발화하는 빈도를 제한합니다. 둘 다 쓰세요——토큰 예산 런북 참고.

80% 절감 주장은 보장되나요?

Headroom은 워크로드별로 60–95% 범위를 공개합니다. 도구 집약 OpenClaw 감사는 흔히 60–92%이며, 짧은 대화 턴은 덜 절감됩니다. 저장소에서 /stats를 측정하세요.

Anthropic이 프록시 요청을 차단하나요?

Headroom은 당신의 키로 공식 API에 전달합니다——SDK 직접 사용과 동일합니다. ANTHROPIC_API_KEY는 프록시 호스트에만 두고, 로그 유출 시 교체하세요.

Headroom을 Linux, OpenClaw을 macOS에서 실행할 수 있나요?

네——방화벽이 허용하면 ANTHROPIC_BASE_URL=http://linux-host:8787을 설정하세요. 지연에 민감한 게이트웨이는 같은 Mac mini에 공치된 프록시를 선호합니다.

Hermes 궤적 압축과 어떻게 다른가요?

Hermes는 에이전트 메모리 트랜스크립트를, Headroom은 HTTP 계층에서 도구 출력과 메시지를 압축합니다. 하네스 선택은 Hermes 대 OpenClaw를 읽으세요——스택은 서로 다른 호스트에서 공존할 수 있습니다.

로컬 Ollama를 Anthropic 대신 쓰나요? 동일한 Headroom 프록시가 온디바이스 모델의 도구 페이로드를 줄입니다. Headroom + Ollama 로컬 지연 가이드로 16 GB Mac mini 프리필 멈춤을 해결하세요.