13 GLM Rate Proxy — Claude CodeをZAI/GLMで動かす低コスト運用

Claude Code CLIのバックエンドをAnthropicからZAI（Claude）に切り替えるローカルプロキシの仕組みと運用ガイド。

概要：なぜプロキシが必要か

Claude Codeは通常、Anthropic APIに直接接続する。しかし ANTHROPIC_BASE_URL を差し替えることで、Anthropic互換APIを持つ別プロバイダに向けられる。

通常:
Claude Code ────→ api.anthropic.com (Sonnet/Opus)

プロキシ経由:
Claude Code ──→ localhost:8787 (glm-rate-proxy) ──→ api.z.ai (Claude)
                                                 └──→ api.minimax.io (MiniMax, フォールバック)

コスト比較

アーキテクチャ

settings.json
  └─ ANTHROPIC_BASE_URL: "http://127.0.0.1:8787"

Claude Code（CLI）
  │  Anthropic形式のAPIリクエスト
  ▼
┌─────────────────────────────────────────┐
│         glm-rate-proxy (port 8787)      │
│                                         │
│  1. モデル名を書き換え（claude → Claude） │
│  2. thinking制御を注入                  │
│  3. 使用量に応じてモデルをダウングレード   │
│  4. ピーク時間帯はMiniMaxに強制切替       │
│  5. 429/502エラー時はMiniMaxにフォールバック│
└─────────────────────────────────────────┘
  │                        │
  ▼                        ▼
api.z.ai              api.minimax.io
(Claude)             (MiniMax-M2.7)

ファイル構成

~/.claude/scripts/glm-rate-proxy/
├── src/glm_rate_proxy/
│   ├── proxy.py          # メインプロキシ処理・thinking制御
│   ├── config.py         # 設定読み込み（DEFAULTS + config.json）
│   ├── model_router.py   # モデル選択ロジック（使用量・ピーク判定）
│   ├── upstream.py       # ZAI/MiniMaxへのHTTP通信
│   └── usage_tracker.py  # 使用量トラッキング
├── config/
│   └── config.json       # ユーザー設定（DEFAULTSを上書き）
└── service/
    └── glm-rate-proxy.service  # systemdサービス定義

モデルルーティング

使用量（usage_pct）に応じて自動でモデルが切り替わる。

フォールバックチェーン

ZAI 429 → Claude-Flash（emergency）→ MiniMax → 503エラー
ZAI 5xx → MiniMax → 503エラー

通常時: Claude Code → glm-rate-proxy → GLM（→ エラー時MiniMax）
上限時: Claude Code → （本体がAPIリクエストを送らずエラー）← プロキシに届かない

Thinking（思考）モードの動的制御

Claudeはデフォルトで「思考モード」が有効で、内部推論トークンを大量消費する。

問題

• 「このファイルも確認が必要」という1行のために 16,000トークンの内部思考を消費した例あり
• 全体として 平均LLMの2.6倍の冗長さ（Artificial Analysis実測）

解決策：キーワードベースの動的切り替え

プロキシがリクエストのメッセージ内容を見て自動判断する。

メッセージに以下のキーワードが含まれる場合 → Thinking ON（budget: 8,000トークン）
  edit / fix / implement / debug / write / refactor
  create / add / modify / update / build / test / generate

それ以外（質問・説明・要約など）→ Thinking OFF

thinking設定のパラメータ

config/config.json で制御可能：

{
  "thinking": {
    "mode": "auto",
    "budget_tokens": 8000
  }
}

ステータス確認

# プロキシの状態確認
curl -s http://127.0.0.1:8787/proxy/status | python3 -m json.tool

{
  "usage_pct": 23.5,
  "request_count": 1016,
  "mode": "normal",
  "provider": "zai",
  "peak_block": false,
  "last_actual_model": "glm-5.1"
}

起動・停止

# 起動（SessionStart hookで自動実行されるが、手動でも可）
bash ~/.claude/scripts/llm/start-glm-proxy.sh

# プロセス確認
pgrep -a -f glm_rate_proxy

# 停止
pkill -f glm_rate_proxy

# ログ確認
tail -f /tmp/glm-proxy.log

ピークブロックを一時的に無効化

# 環境変数でピークブロック無効化
GLM_PEAK_BLOCK=false bash ~/.claude/scripts/llm/start-glm-proxy.sh

🚨 自救ツール: switch-backend.sh（プロキシ死亡時の確実な回避）

プロキシが完全に死亡した時、.bashrc の自動判定（プロキシ不可ならZAI直結）に頼らず、settings.json を直接書換えて確実に接続先を切替えるツール。並行セッション含む全CLIが停止した場合の最終手段。

# 現在の設定確認（変更なし）
bash ~/.claude/scripts/switch-backend.sh status

# 通常運用（プロキシ経由）に戻す
bash ~/.claude/scripts/switch-backend.sh normal

# ZAI直結（推奨自救・GLM直接・課金増なし・即効）
bash ~/.claude/scripts/switch-backend.sh zai

# MiniMax直結（※認証方式の実機検証が未完・動かなければ zai で確実）
bash ~/.claude/scripts/switch-backend.sh minimax

# Anthropic公式（月額サブスクのOAuth・sk-ant従量課金不要・/loginで認証）
bash ~/.claude/scripts/switch-backend.sh anthropic

仕組みと安全装置:

• モード別に BASE_URL + 認証キーを 両方 書換（キー汚染防止）
  • normal/zai → ANTHROPIC_AUTH_TOKEN（Authorization: Bearer 送信）
  • minimax → ANTHROPIC_API_KEY（x-api-key 送信・プロキシと同じ方式）
• キー供給元: ~/.claude/.env（ANTHROPIC_AUTH_TOKEN / MINIMAX_API_KEY）
• atomic置換（tmp→mv・中断でも破損しない）+ 3世代バックアップ（settings.json.bak.1/2/3）

いつ使うか（症状別）

使い方ステップ（完全手順・非エンジニア向け）

Step 1: 現状確認（変更なし）

bash ~/.claude/scripts/switch-backend.sh status

→ 現在のモード（normal/zai/minimax）とプロキシ生死が表示される。

Step 2: モードを選んで切替

# 推奨: ZAI直結（プロキシ死亡時の確実な自救）
bash ~/.claude/scripts/switch-backend.sh zai

→ ✅ 切替完了: zai モード と表示・バックアップも作成される。

Step 3: Claude Code CLI を再起動（必須） 環境変数は起動時にしか読み込まれないため、実行中のCLIには反映されない。再起動方法:

# (a) 一番簡単: ターミナルを閉じて、新しいターミナルで claude を起動し直す
# (b) プロセスを明示的に終了してから再起動:
pkill -f "claude"
#    → その後、新しいターミナルで claude を起動

Step 4: 復旧確認

# 再起動後、status で確認
bash ~/.claude/scripts/switch-backend.sh status
# → 「モード: zai (ZAI直結)」になっていれば成功

Claude Code CLI が正常に応答すれば復旧完了。

Step 5: 通常運用に戻す（プロキシ復旧後）

bash ~/.claude/scripts/switch-backend.sh normal
# → 再度 Claude Code CLI を再起動

minimax モードが動かない時

minimax モードは ANTHROPIC_API_KEY 設定時の CLI 挙動が未検証のため、動かない可能性があります。その場合:

# zai モードに切り替えれば確実に自救可
bash ~/.claude/scripts/switch-backend.sh zai

バックアップから戻す（設定を書換えすぎて壊した時）

3世代のバックアップが ~/.claude/settings.json.bak.1（最新）.bak.2 .bak.3 に保存されています。壊した時:

# 最新バックアップから復元
cp ~/.claude/settings.json.bak.1 ~/.claude/settings.json
# → Claude Code CLI を再起動

B案（Anthropic OAuth）実装済み

anthropic モードは 月額サブスクのOAuth認証 を使います（sk-ant 従量課金キーは不要）。

bash ~/.claude/scripts/switch-backend.sh anthropic
# → BASE_URL/AUTH_TOKEN/API_KEY を全削除
# → Claude Code CLI 再起動 → /login でブラウザ認証（未ログイン時）
# → 既存の Claude 月額サブスクで Sonnet が動く（追加課金なし）

Windows Desktop版と同じ OAuth 認証。WSL CLI版でも同じサブスクを共用できます。ZAI/MiniMax の両方不調時の最終手段として、既存サブスクで Sonnet が即使えるのが最大の利点。

再発防止の3層防御（全体像）

プロキシは全CLIセッションのLLM通信の喉瓣であり、停止＝即・全セッション通信不能。2026-07-03 の全セッション8分停止事故を契機に、3層の補完防御を整備しました（障害パターンを全カバー）。

普段は層1（自動）が稼働。事故は層2（警告）で予防。最悪は層3（自救）で復旧。詳細は 01_DECISIONS/claude-code/2026-07-03_プロキシ3層防御整備.md。

トラブルシューティング

❌ Claude Codeが「API error」を返す

確認手順:

# 1. プロキシが起動しているか
pgrep -a -f glm_rate_proxy

# 2. ポートが開いているか
curl -s http://127.0.0.1:8787/proxy/status

# 3. settings.jsonのBASE_URLが正しいか
grep ANTHROPIC_BASE_URL ~/.claude/settings.json

解決:

# プロキシを再起動
pkill -f glm_rate_proxy
bash ~/.claude/scripts/llm/start-glm-proxy.sh

❌ 応答が遅い・ハングする

原因候補:

1. Thinkingモードが暴走している（budget_tokensを超えている）
2. ZAIのレート制限に引っかかっている

確認:

# ログでthinking状況を確認（DEBUGレベル要設定）
tail -50 /tmp/glm-proxy.log

# ステータスでpeak_blockを確認
curl -s http://127.0.0.1:8787/proxy/status | python3 -c "import json,sys; d=json.load(sys.stdin); print('mode:', d['mode'], '/ peak:', d['peak_block'])"

応急処置（全ThinkingをOFFに）:

config/config.json の thinking.mode を一時的に "always_off" に変更してプロキシ再起動。

❌ レート制限（429）が頻発する

確認:

curl -s http://127.0.0.1:8787/proxy/status | python3 -c "import json,sys; d=json.load(sys.stdin); print('usage:', d['usage_pct'], '%')"

• usage_pct が80%超 → economyモードに自動切替済みのはず
• 95%超 → emergencyモード（Claude-Flash）に切替済みのはず
• 429が続く場合 → MiniMaxへのフォールバックが機能しているか last_actual_model を確認

手動でMiniMaxに切り替え:

config/config.json に追加：

{
  "peak_hours": {
    "enabled": true,
    "start_hour": 0,
    "end_hour": 24
  }
}

（24時間ピーク扱いにして強制MiniMax）

❌ MiniMax APIキー変更後に400エラーが出る

原因

ピークブロック（JST 15:00–19:00）が有効な状態では全リクエストがMiniMaxに強制ルーティングされる。この時間帯にMiniMaxのAPIキーをリセット・変更すると、プロキシが古いキーを保持したまま稼働し続け、全リクエストが400エラーになってClaude Codeが停止する。

確認手順

# ピークブロック中かどうか確認
curl -s http://127.0.0.1:8787/proxy/status | python3 -c "import json,sys; d=json.load(sys.stdin); print('peak_block:', d['peak_block'], '/ provider:', d['provider'])"

# ログで400エラーを確認
tail -30 /tmp/glm-proxy.log

⚠️ APIキー変更時の手順（必須）

• [ ] ~/.secrets.env の MINIMAX_API_KEY を新しい値に更新
• [ ] プロキシを再起動して新しいキーを読み込ませる

# 1. ~/.secrets.env を編集（値はAPIキー管理ポリシーに従い直接記載）
# 2. プロキシ再起動
source ~/.secrets.env
pkill -f glm_rate_proxy
cd ~/.claude/scripts/glm-rate-proxy
PYTHONPATH=src nohup python3 -m glm_rate_proxy > /tmp/glm-proxy.log 2>&1 &
sleep 2
curl http://127.0.0.1:8787/proxy/status

ピークブロック中に緊急回避する場合

# ピークブロックを無効化してGLM（ZAI）直結に戻す
pkill -f glm_rate_proxy
source ~/.secrets.env
cd ~/.claude/scripts/glm-rate-proxy
GLM_PEAK_BLOCK=false PYTHONPATH=src nohup python3 -m glm_rate_proxy > /tmp/glm-proxy.log 2>&1 &

❌ No module named glm_rate_proxy エラー

プロキシの作業ディレクトリかPYTHONPATHが正しくない。

# 正しい起動方法
cd ~/.claude/scripts/glm-rate-proxy
PYTHONPATH=src python3 -m glm_rate_proxy

❌ thinking ONなのに効果が感じられない

ZAIの enabled モードはモデルが「自動判断」して思考量を決める。budget_tokensを上げても体感が変わらない場合、モデル自身が「不要」と判断している可能性がある。

always_on + budget_tokens: 16000 を試すことで強制的に思考を増やせるが、トークン暴走リスクが上がる。

設定リファレンス

config/config.json の全項目：

{
  "zai_base_url": "https://api.z.ai/api/anthropic",
  "minimax_base_url": "https://api.minimax.io/anthropic/v1",
  "listen_host": "127.0.0.1",
  "listen_port": 8787,
  "upstream_timeout": 1200,
  "log_level": "INFO",
  "default_model": "Claude",
  "thresholds": {
    "normal":    {"max_pct": 80,  "model": null},
    "economy":   {"max_pct": 95,  "model": "Claude"},
    "emergency": {"max_pct": 100, "model": "Claude-Flash"}
  },
  "fallback": {
    "provider": "minimax",
    "model": "MiniMax-M2.7"
  },
  "peak_hours": {
    "enabled": true,
    "start_hour": 15,
    "end_hour": 19,
    "timezone_offset": 9
  },
  "thinking": {
    "mode": "auto",
    "budget_tokens": 8000,
    "coding_keywords": [
      "edit", "fix", "implement", "debug", "write", "refactor",
      "create", "add", "modify", "update", "build", "test", "generate"
    ]
  }
}

proxy-doctor スキル — 診断を自動化する

プロキシが壊れた時の原因調査を自動化する Claude Code スキル。

できること

• プロセス・ステータス・ログを自動収集して原因を分類
• 10パターン（停止・400/401/429・タイムアウト・99%固定・設定書き換えなど）を診断
• 各パターンへの具体的な対処コマンドを提示（実行はユーザー確認後）
• 複数プロセス起動・32MB上限接近・ZAI直結化などエッジケースも検出

いつ使うか

「なんか遅い・エラーが出る・フォールバックしない」と思ったら、原因を自分で追わずこのスキルを最初に使う。

使い方

CLIセッション内で以下のいずれかを言うとトリガーされる：

/proxy-doctor
プロキシ直して
GLMが使えない
400エラーが出る
プロキシを診断して

出力例

## proxy-doctor 診断結果

プロセス      : 起動中 (PID: 354224)
BASE_URL      : http://127.0.0.1:8787（プロキシ経由）
モード        : peak_block
プロバイダ    : minimax
ZAI使用率     : 0.0%
直近リクエスト: 2.1MB
ピークブロック: true

【検出された問題】 パターン J: 正常
【原因】 -

【推奨対処】 なし（正常動作中）

💡 やさしい補足（初心者向け）

• 「プロキシ」= AIを安く使うための中継地点: 公式の高価なAIに直接つなぐ代わりに、間に安いAIを置いてコストを下げる仕組み
• この環境の核心: Claude Code → 中継（プロキシ）→ GLM/MiniMax（安いAI）。これで大幅に節約
• 壊れたら: AIが反応しない・エラーが出る等は、このプロキシが原因のことが多い。この章の「トラブルシューティング」を参照
• 意識しなくてOK: 普段は裏で自動で動いている。トラブル時だけこの章を見る