科技 · 實用指南
SSH agent 拒絕簽署？重設前先證明 socket、金鑰與簽署路徑
此錯誤表示客戶端已聯絡某個 agent，但簽署沒有完成。先確認實際 socket、比對金鑰指紋、做本機簽署測試並核對 SSH 真正採用的路徑，再處理權限、轉送或硬體權杖。
「agent refused operation」比一般 publickey 失敗更精確：SSH 客戶端已聯絡認證agent、選中公鑰並要求簽署認證挑戰，但沒有收到可用簽章。可能是目前shell指向錯誤agent、金鑰指紋不符、第三方agent等待核准、轉送socket被覆蓋，或硬體權杖暫時無法簽署。
不要先刪除金鑰或設定、關閉agent保護、把私鑰複製到遠端，或對所有主機開啟ForwardAgent。保留發生錯誤的終端，依序蒐證，在第一個失敗邊界停下。
1. 固定失敗環境並找出agent
在原本的終端、IDE shell或遠端工作階段檢查；另一個視窗可能繼承不同socket。記錄主機別名、是否使用agent轉送，以及錯誤前顯示的金鑰標籤。
執行 `printf '%s\n' "$SSH_AUTH_SOCK"`，再以 `test -n "$SSH_AUTH_SOCK" && test -S "$SSH_AUTH_SOCK" && echo agent-socket-present` 確認socket。存在的路徑仍可能屬於OpenSSH、GNOME Keyring、gpg-agent、1Password、KeePassXC、硬體agent或轉送工作階段。
用 `ssh-add -l` 看指紋、`ssh-add -L` 看公鑰。ssh-add結束碼2代表無法聯絡agent，是socket或工作階段問題。
2. 核對指紋並證明可簽署
不要只看註解名稱。對公鑰檔執行 `ssh-keygen -lf ~/.ssh/id_ed25519.pub`，對agent執行 `ssh-add -l -E sha256`。若SSH提供的指紋不在清單中，先修正載入或第三方agent的金鑰範圍。
指紋存在時執行 `ssh-add -T ~/.ssh/id_ed25519.pub`。目前OpenSSH會要求agent簽署並驗證；成功證明此socket現在能用匹配私鑰。失敗時查鎖定、核准視窗、pinentry、觸摸/PIN與provider日誌。
舊版ssh-add可能沒有-T，第三方agent也可能只實作部分協定。未知選項不是簽署失敗；記錄 `ssh -V` 並使用該產品的正式測試。
3. 證明SSH實際選擇的路徑
執行 `ssh -G your-host | grep -Ei '^(identityagent|identityfile|identitiesonly|forwardagent) '` 查看主機別名的有效設定。Host、Match與Include可能改變最後結果。
再執行 `ssh -vvv user@your-host`，找出agent、實際提供的指紋與拒絕行。若指紋不是通過ssh-add -T的金鑰，只修正該主機的IdentityFile或IdentityAgent。
IdentityAgent可優先於SSH_AUTH_SOCK。遠端工作站的本機第三方agent可能遮住筆電轉送的socket；修正主機或工作階段路由，不要全域轉送或複製私鑰。
4. 依第一個失敗點分流
沒有socket或無法聯絡：在本工作階段啟動或重新連接預期agent，勿沿用其他登入的舊socket。
清單沒有目標金鑰：用正式方式載入檔案金鑰或讓第三方agent提供它。只有看到明確權限警告才調整該私鑰；不要整個目錄套用同一chmod。
金鑰已列出但ssh-add -T失敗：檢查agent鎖定、核准、pinentry、觸摸/PIN、provider與同時間日誌。
ssh-add -T成功而SSH仍拒絕：比對指紋與IdentityAgent；轉送或目的地限制還要允許目前跳點，並核准真正發出請求的終端或IDE。
相同金鑰能簽署且已提供，但伺服器仍拒絕：轉查使用者、authorized_keys、憑證principal與伺服器政策。
5. 保留轉送與硬體金鑰的安全邊界
Agent轉送只轉送簽署能力，不複製私鑰。只對可信主機按需使用ForwardAgent，並在真正持有金鑰的電腦上核准。
FIDO或PKCS#11拒絕可能是預期保護。觸摸、PIN、provider與目的地限制都可能必需；不要為了消除錯誤而關閉web-safety或遠端載入provider。
修復後重跑同一個ssh-add -T與ssh -vvv，記錄可用socket、指紋和有效設定，避免下個終端或IDE再次選錯。
決策表
ssh-add 無法聯絡 agent — socket/工作階段故障. 啟動或重新連接預期 agent；複核 SSH_AUTH_SOCK
ssh-add -l 沒有目標金鑰 — agent 錯誤或金鑰不可用. 只載入或設定預期身分
金鑰已列出；ssh-add -T 失敗 — agent/provider 目前無法簽署. 解鎖、核准、觸摸或輸入 PIN；查看 provider 日誌
ssh-add -T 通過；SSH 提供另一把金鑰 — 客戶端路由不相符. 檢查 ssh -G 與 ssh -vvv；修正該主機的 IdentityAgent/IdentityFile
ssh-add -T 通過；提供同一金鑰；伺服器拒絕 — 伺服器授權分支. 檢查使用者、authorized_keys、憑證 principals 與伺服器政策
