科技 · 实用指南
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存在。路径存在仍不等于它是预期agent；它可能来自OpenSSH、GNOME Keyring、gpg-agent、1Password、KeePassXC、硬件令牌或转发会话。
运行 `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列表中，先修正加载方式或第三方agent的可用范围。
指纹存在时运行 `ssh-add -T ~/.ssh/id_ed25519.pub`。当前OpenSSH会请求agent签名并验证结果；退出码0证明当前socket现在能使用匹配私钥。若失败，调查agent是否锁定、授权窗口是否被遮住、pinentry是否可用、硬件令牌是否需要触摸/PIN，或provider是否故障。
旧版ssh-add可能没有-T，某些第三方agent只实现部分协议。未知选项不等于签名失败；记录 `ssh -V` 和agent产品，改用该产品的正式签名测试或日志。
3. 证明SSH客户端实际选择了什么
运行 `ssh -G your-host | grep -Ei '^(identityagent|identityfile|identitiesonly|forwardagent) '` 查看该别名的最终配置。Host、Match和Include规则可能让结果不同于你记得修改的那一行。
再运行一次 `ssh -vvv user@your-host`，找到agent/identity、实际提供的指纹和拒绝行。如果指纹不同于通过ssh-add -T的钥匙，应只约束这个主机的IdentityFile/IdentityAgent，不要删除其他身份。
IdentityAgent可优先于SSH_AUTH_SOCK。远程工作站上的本地第三方agent配置可能遮住从笔记本转发来的socket；修正会话或主机专用路由，而不是全局转发或复制私钥。
4. 按第一个失败边界分流
没有socket或ssh-add无法联系：在本会话启动或重新连接预期agent，再复核路径。不要复制另一次登录的旧socket路径。
agent列表没有目标钥匙：用该agent支持的方法加载文件钥匙，或在第三方agent中允许该钥匙。只有看到明确的私钥权限警告时才修改对应私钥；目录、公钥和私钥的合理权限不同，不能一刀切chmod。
钥匙已列出但ssh-add -T失败：agent知道公钥，却当前不能或不愿签名。检查锁定、授权、pinentry、触摸/PIN、provider和同时间戳日志。
ssh-add -T成功但ssh -vvv仍拒绝：比对实际指纹和IdentityAgent；若使用转发或目的地约束，确认当前跳点和目标被允许。需要批准的agent应授权真正发起请求的终端或IDE。
相同钥匙能签名且已被SSH提供，但服务器仍报Permission denied：agent边界已健康，转查用户名、authorized_keys、证书principal和服务器策略。
5. 不削弱转发与硬件密钥
Agent转发只转发签名能力，不复制私钥。仅对可信主机按需启用ForwardAgent；在转发会话中验证SSH_AUTH_SOCK和ssh-add -l，并在真正持有密钥的机器上批准。
FIDO或PKCS#11拒绝可能是刻意安全边界。触摸、PIN、中间件provider或目的地约束都可能必需。不要为了消除报错而关闭web-safety限制或远程加载provider；先证明请求确实是你想要的SSH认证。
修复后重复同一个ssh-add -T和同一个ssh -vvv命令，并记录工作socket、指纹与最终配置。证据比一次重启更能防止下一终端或IDE再次选错agent。
决策表
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 与服务器策略
