icon: 🔧 slug: 20-version-management

20 バージョン管理 — Claude Codeの更新・ダウングレード・プロキシ環境の注意

なぜこのページがあるか

Claude Codeは頻繁に細かいバージョンアップを繰り返す（2.1.19x〜2.1.20x帯）。更新で新機能が入る一方で、まれに不具合や互換性問題が起きる。本ページでは「更新の方法」「旧版に戻す方法」「GLMプロキシを使っている時の注意」を1箇所にまとめる。

バージョン確認方法

# コマンド1発（最も簡単）
claude --version

# インストール方式別の確認
npm list -g @anthropic-ai/claude-code     # npm版の場合
ls ~/.local/share/claude/versions/        # ネイティブ版の場合（バイナリ一覧）

更新方法

npm版（現在の標準）

claude update                                              # 自己更新（推奨）
# または明示的に最新へ
npm install -g @anthropic-ai/claude-code@latest

⚠️ npm update -g は semver範囲を尊重してしまうため実更新しないことがある。@latest 指定か claude update を使うこと（公式setup docs）。

ネイティブ版（Bun・auto-updater）

claude install latest    # または stable / 特定バージョン

ネイティブ版はバックグラウンドで自動更新される（後述「自動更新のON/OFF」で制御可能）。

⭐️ ダウングレード手順（旧版に戻す）

核心セクション。更新で問題が起きた時に確実に戻すための手順。方式によって確度が大きく違う。

インストール方式	ダウングレード手順	確度
npm版	`npm install -g @anthropic-ai/claude-code@<バージョン>`	✅ 確実（履歴400件以上・任意版へ即時切替）
ネイティブ版（Bun）	事前に `~/.claude.json` に `"autoUpdates": false` を追記 → `claude install <バージョン>` を再実行	🟡 戻せるがやや弱い（バイナリ管理がnpmほど洗練されていない）
Windows Desktop（MSIX）	Microsoft Store経由のみ	❌ 困難（ストア版以外のダウングレードは非現実的）

npm版の具体例（最も確実・推奨）

# 問題が出たら、1つ前のバージョンへ戻す
npm install -g @anthropic-ai/claude-code@2.1.194

# 履歴から任意の版を指定可能
npm view @anthropic-ai/claude-code versions --json | tail -20

ネイティブ版の具体例

# 1. まず自動更新を止める（戻しても勝手に上げられないよう）
# ~/.claude.json に追記: "autoUpdates": false

# 2. 旧版を再インストール
claude install 2.1.194

# または別の方法（公式インストールスクリプトにバージョン指定）
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.194

⚠️ ネイティブ版のダウングレードは GitHub Issue #20044 で「npm/dnfに比べてrollback機能が弱い」と指摘あり。確実性を重視する場合はnpm版を維持するのが安全。

自動更新のON/OFF

方法	効果
`~/.claude.json` に `"autoUpdates": false`	ネイティブ版のauto-updaterを無効化
環境変数 `DISABLE_AUTOUPDATER=1`	auto-updaterを無効化（CI/コンテナ向）
npm版	元々自動更新しない（手動 `claude update` のみ）

⭐️ GLMプロキシ環境での注意

設定ファイルは勝手に書き換わらない（安心）

Claude Codeはユーザー設定を上書きしない。claude update で以下が壊れることはない：

settings.json の env（ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 等）
プロキシ（glm-rate-proxy）への接続設定

インストール方式をnpm→ネイティブに変えても、これらは shell/configレベルの環境変数 なので引き継がれる（公式setup docs）。

本当のリスクは「新機能 × 非公式プロキシ互換性」だけ

GLMプロキシは、ZAI/MiniMaxをAnthropic API互換に非公式ラップしている。Claude Code新Verが新しいAPI機能（拡張tool use・新ストリーミング形式等）を使うようになると、プロキシ側の変換が追いつかず動作不全を起こす可能性がある。これがプロキシ環境での唯一の実リスク。

プロキシ互換性の実績

期間	更新回数	プロキシ動作
GLMプロキシ運用中	7-8回の手動更新（2.1.19x帯→2.1.20x帯）	すべて互換性維持・動作継続

実績として「手動 claude update → プロキシ動作継続」が複数回成立している。リスクは理論上だが実害は今のところゼロ。

トラブル時の対応フロー

更新後、プロキシ経由でLLMが応答しない・エラーが出る
        ↓
1. プロキシ稼働確認
   systemctl --user is-active glm-rate-proxy
        ↓ 動いている
2. Claude Codeバージョンを1つ前へ戻す（ダウングレード）
   npm install -g @anthropic-ai/claude-code@<1つ前の版>
        ↓
3. プロキシが動く版で安定稼働確認
        ↓
4. 問題の版は ssot-record 等で記録（再発防止）

自動更新への移行ロードマップ（構想）

完全自動更新（ネイティブ版＋auto-updater ON）への移行は、以下2要素が整ってからが安全：

ダウングレード手順の確証（本ページで整理済・npm版は確実・ネイティブ版は実証推奨）
プロキシ互換性の自動チェック ✅（更新後にGLM応答を自動検証するhook・実装済・check-proxy-compat.sh・2026-07-09 Phase2本番登録）

要素2は整いました（同版省略・警告のみでブロックしない設計）。残るはネイティブ版ダウングレードの実証のみなので、それまではnpm版（確実に戻れる）＋手動 claude update が最も安全な運用。