"Could not open a connection to your authentication agent" 怎么解决
这个错误说明当前 shell 无法连接 ssh-agent，可能是代理未运行或 SSH_AUTH_SOCK 丢失、失效。先检查并复用已有代理，无可用代理时再启动并用 ssh-add 添加密钥。本文给出完整排查步骤。
一句话回答：这个错误是因为 ssh-agent 没有运行，或者当前 shell 拿不到它的 SSH_AUTH_SOCK 环境变量。在当前终端执行 eval "$(ssh-agent -s)" 启动代理并注入环境变量，然后 ssh-add ~/.ssh/id_rsa 加载私钥即可。新终端应优先复用登录会话/桌面提供的 agent，避免每次启动一个新进程。
标准解决步骤
第一步：检查并连接 ssh-agent
先运行 ssh-add -l：返回 0 表示可访问且有密钥，返回 1 可能只是没有密钥，返回 2 才表示无法连接代理。优先恢复登录会话提供的 socket；确实没有可复用代理时再启动：
eval "$(ssh-agent -s)"
# 输出：Agent pid 12345
ssh-agent -s 会启动代理并输出设置环境变量的命令，eval 让这些变量在当前 shell 生效（关键是 SSH_AUTH_SOCK 和 SSH_AGENT_PID）。
第二步：添加私钥
ssh-add ~/.ssh/id_rsa # 按实际密钥路径替换
# 若有 passphrase，加载时会提示；代理锁定、密钥过期等可能需再次解锁
第三步：验证
ssh-add -l # 列出已加载的密钥指纹
ssh -T git@github.com # GitHub 认证成功提示也会返回 1，因为不提供 shell
为什么新终端又报错
eval $(ssh-agent) 只对当前 shell 有效。独立登录会话、部分 tmux 或 CI 环境可能没有继承变量，也可能继承了失效的 socket；不是所有新终端都会丢失。解决方案按场景选：
仅在没有会话管理器时手动启动（个人开发机）：
先用 ssh-add -l 检查连接，只有无法连接且没有可复用 agent 时，才运行上面的启动命令。不要只检查 SSH_AUTH_SOCK 是否为空，也不要在每个 shell 的启动文件中重复创建 agent。
用 keychain 工具复用同一个 agent（推荐）：
sudo apt install keychain
# ~/.bashrc 中加：
eval "$(keychain --eval --agents ssh id_rsa)"
空变量判断不能识别失效 socket，也可能为多个终端重复启动 agent。keychain 可协助同一用户复用 agent；重启、密钥过期或代理锁定后仍可能需要解锁。
桌面环境（GNOME/KDE/macOS）： 一般已内置 agent（macOS 用 ssh-add --apple-use-keychain 存进钥匙串），出错多为变量被覆盖，检查 echo $SSH_AUTH_SOCK 是否为空。
CI/CD 环境
CI 里没有交互式 agent，常见做法：
set +x
eval "$(ssh-agent -s)"
trap 'ssh-agent -k >/dev/null' EXIT
printf '%s\n' "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - # 从受保护的 CI 密钥变量加载
# 作业结束后终止本作业启动的 agent；禁用 shell 跟踪，勿把私钥输出到日志
常见问题（FAQ）
Q：明明运行了 ssh-agent，为什么还报这个错？
A：多半是只运行了 ssh-agent 而没用 eval 包裹——代理进程启动了，但环境变量没有注入当前 shell。应优先恢复既有代理的 socket 环境；仅在确需新代理时用 eval "$(ssh-agent -s)"。
Q：ssh-add -l 显示 "The agent has no identities"？
A：agent 在运行但没加载任何密钥，执行 ssh-add ~/.ssh/id_rsa 添加即可。
Q：Windows 上遇到这个错误？
A：Git Bash 下同样用 eval $(ssh-agent)；PowerShell 下可由管理员配置 Windows 自带的 OpenSSH Agent 服务：Set-Service ssh-agent -StartupType Automatic; Start-Service ssh-agent。
核查依据
本文依据官方文档核对，示例未在实际业务环境运行；上线前请按部署版本、权限与数据范围验证。
