Windows Claude Code GitHub SSH 排錯

一句話定義：Windows 舊 OpenSSH 撞上 GitHub 新金鑰交換算法導致 plugin 安裝失敗，用 git insteadOf 把 SSH URL 改寫成 HTTPS 即可繞過整段。

背景／動機

在 Windows 上用 /plugin install <name>@<marketplace> 安裝 Claude Code plugin 時，若 plugin 來源是 GitHub repo，常撞 SSH 相關錯誤而裝不起來。根因是 Windows 內建的舊 OpenSSH 與 GitHub 的新連線要求不相容。此為 2026-05-27 安裝 Webwright plugin（三次才成功）的踩坑實錄。

核心內容

故障鏈：兩道牆

/plugin install xxx@yyy
       │
       ▼
[牆 1] SSH host key verification failed
       │ known_hosts 沒有 github.com 指紋
       │ 且 Windows 舊 OpenSSH 不支援 GitHub 的新 KEX 算法 → ssh-keyscan 也拿不到
       ▼
[牆 2] Permission denied (publickey)
       │ GitHub 沒設 SSH key，或本機沒對應私鑰
       ▼
繞過：git insteadOf 把 SSH URL 改寫成 HTTPS，整段 SSH 不走

根本原因

Windows 舊版 OpenSSH 不支援 GitHub 現用的金鑰交換（KEX）算法 sntrup761x25519-sha512，所以連 ssh-keyscan 都握手失敗、拿不到 host key。這是牆 1 的真正源頭。

根本解：升級到 Windows OpenSSH 9.x，或改用 PowerShell 7 內建版本。實務上不急，用下方繞道即可。

解法 SOP（三步繞過）

步驟 1：手動寫入 GitHub host keys

ssh-keyscan 失敗時，改從 GitHub 官方 meta API 撈：

$keys = Invoke-RestMethod https://api.github.com/meta | Select-Object -ExpandProperty ssh_keys
$keys | ForEach-Object { "github.com $_" } | Add-Content $env:USERPROFILE\.ssh\known_hosts

寫入後對照 GitHub 公告 fingerprint 驗證：

• ED25519：SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU
• ECDSA：SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM
• RSA：SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s

步驟 2：設定 git insteadOf，改走 HTTPS

git config --global url."https://github.com/".insteadOf "git@github.com:"

這條讓所有 git@github.com: 形式的 SSH URL 透明改寫成 HTTPS，直接跳過 SSH 握手（連帶也讓步驟 1 變成備援）。

步驟 3：重試安裝並套用

/plugin install <plugin-name>@<marketplace-name>
/reload-plugins

副作用警告

• ⚠️ insteadOf 影響全域 — 之後所有 GitHub repo 操作都走 HTTPS。
• ⚠️ 私有 repo push 需要 PAT（Personal Access Token），不是密碼。
• 復原：git config --global --unset url.https://github.com/.insteadof

與其他概念的關係

• 承接 Claude Code 五層架構：Plugin 是第五層（分發層），此文是它在 Windows 實機安裝時的排錯路徑。

應用／範例

• 2026-05-27 安裝 Webwright（Microsoft browser agent framework）plugin，三次 install 才過（牆 1 → 牆 2 → 成功）。

開放問題／待探索

• 升級 Windows OpenSSH 9.x / PowerShell 7 後能否純 SSH 直連、免 insteadOf？（根本解未驗）
• 是否可用 repo 層級（非全域）insteadOf 縮小影響範圍？

來源

• 2026-05-27_Windows-CC-plugin-GitHub安裝-SSH排錯：主要依據