AI Frontier

OpenClaw × Headroom プロキシで API コスト最大 80% 削減：2026 年 macOS 実践ガイド

MacHTML Lab•2026.06.04• ~12 min read
OpenClaw Headroom プロキシによる Anthropic API トークン削減 2026

OpenClaw の夜間リポジトリ監査は、リンター、テストランナー、grep の洪水をシェル実行し、数メガバイトの JSON をモデルのコンテキストへ返します。生のバイトすべてに Anthropic の定価を払えば、規律ある自動化でも四桁ドルの API 費目に膛らみます。Headroom はゲートウェイとプロバイダーの間に入り、リクエストが api.anthropic.com に届く前に、ツール出力・ログ・履歴を SmartCrusher / CodeCompressor / CCR で圧縮する既定ポート 8787 のローカルプロキシです。公開ベンチマークでは SRE 系トレースで 92%、コード検索系で 73–92% のトークン削減を示しており、本ガイドは Skill の Markdown を変えずにツール集約ターンで 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 を返す Skill（テスト出力や find の結果）を起動して比較します：

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 と差分を取る
  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 を許可するか、診断の 1 ターンだけ 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 のプリフィル固着を解消。

クラウド Mac mini で OpenClaw + Headroom を検証

Apple Silicon でプロキシとゲートウェイを SSH/VNC 検証。本番キーを載せる前にポートと LaunchAgent 順序を確認。

プロキシ検証のヒント 詳細を見る
Headroom + OpenClaw
10 ステップ手順 — 価格表記なし