1. 背景与核心问题
Qoder CN 是基于 VSCode 生态的 AI IDE，远程连接能力与 VSCode Remote-SSH 同源，因此同样存在 VSCode 系的经典坑：
Couldn't get identities from OpenSSH agent
Error: Failed to connect to agent
根因：IDE 内置 ssh2 库对 Windows ssh-agent 兼容性极差，即使 agent 服务正常运行也会读取失败。
根治方案：不依赖 agent，手动指定私钥 + 强制仅使用指定私钥（IdentityFile + IdentitiesOnly yes）。
2. 连接架构（先理解再动手）
Windows 宿主机 WSL2（NAT 虚拟机）
┌──────────────────────┐ ┌──────────────────────┐
│ Qoder CN │ localhost │ sshd │
│ └─ Remote-SSH ──────┼──── :2222 ───▶│ └─ 监听 0.0.0.0:2222 │
│ ~/.ssh/config │ │ ~/projects/mxtd2026 │
│ ~/.ssh/id_ed25519 │ │ （仓库在 WSL 内） │
└──────────────────────┘ └──────────────────────┘
- WSL2 是 NAT 网络，并非本地局域网；Windows 通过
localhost:2222反向连接 WSL - WSL 内 SSHD 监听 2222 端口（项目约定，非默认 22，避免与 Windows OpenSSH 冲突）
- 仓库必须放 WSL 内部文件系统（如
~/projects/mxtd2026），禁止放/mnt/c，否则文件监听 / HMR 失效（见 项目开发环境配置说明书 §13）
3. 完整部署流程（标准步骤）
步骤 1：Windows 开启 ssh-agent 服务
管理员 PowerShell：
Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent
Get-Service ssh-agent # 状态必须为 Running
步骤 2：生成 ED25519 密钥（不用老旧 RSA）
ssh-keygen -t ed25519
三次回车：无路径、无密码、无确认密码，实现免密登录。ED25519 安全性与速度均优于 RSA，现代环境首选。
步骤 3：私钥加入 Windows ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519
步骤 4：公钥下发到 WSL Ubuntu
cat $env:USERPROFILE\.ssh\id_ed25519.pub | wsl --user pidaqing tee -a ~/.ssh/authorized_keys
把
pidaqing替换为你的 WSL 用户名。
步骤 5：WSL 权限修复（SSH 最容易踩坑）
进入 WSL 执行：
mkdir -p ~/.ssh
touch ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
原理：SSH 对权限极度严格，目录必须 700、authorized_keys 必须 600，否则直接拒绝公钥登录。SSH 免密失败 80% 都是权限问题，而非密钥问题。
步骤 6：WSL 开启公钥认证
sudo nano /etc/ssh/sshd_config
确认以下两行已开启（取消注释）：
PubkeyAuthentication yes
PasswordAuthentication yes
重启并确认监听 0.0.0.0:2222：
sudo systemctl restart ssh
sudo systemctl status ssh
ss -tlnp | grep 2222
若发行版默认监听 22 端口，需将
sshd_config中Port 22改为Port 2222后重启。
步骤 7：Windows ~/.ssh/config 配置（核心根治）
路径：C:\Users\<你的用户名>\.ssh\config
Host wsl-ubuntu
HostName localhost
Port 2222
User pidaqing
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
两行核心配置：
IdentityFile：强制指定本次连接使用的私钥IdentitiesOnly yes：禁止调用 ssh-agent，彻底规避 agent 报错
步骤 8：PowerShell 验证免密
ssh wsl-ubuntu
直接进入系统、无需密码 = 部署成功。
注意：
wsl-ubuntu别名只存在于 Windows 的.ssh/config，在 WSL 内部执行ssh wsl-ubuntu解析失败是正常的。
4. Qoder CN 连接 WSL2
4.1 发起连接
- 打开 Qoder CN，左下角 「打开远程窗口」（或命令面板
Ctrl+Shift+P→Remote-SSH: Connect to Host...） - 选择
wsl-ubuntu（Qoder CN 复用 Windows 侧~/.ssh/config，与 VSCode 一致） - 首次连接会在 WSL 内自动安装远程服务端组件，等待完成
- 「打开文件夹」→ 选择 WSL 内的仓库路径（如
/home/pidaqing/projects/mxtd2026）
4.2 连接后必做
- 扩展安装到远端：ESLint / Prettier / Prisma / Vue - Official 等扩展需在远程侧安装一次（推荐扩展清单见说明书 §4.1）
- 确认仓库内置配置生效：仓库根
.vscode/settings.json（formatOnSave、Prettier、TS tsdk）对 Qoder CN 同样生效，无需重建 - 终端即 WSL：连接后内置终端直接落在 WSL，
pnpm dev:server/pnpm dev:web等命令与说明书一致
4.3 若仍报 agent 错误（最终稳定方案）
Qoder CN 设置（settings.json）中加入：
{
"remote.SSH.useLocalServer": true
}
作用：让 IDE 使用 系统原生 ssh.exe，放弃有 bug 的内置 ssh2 库。配合步骤 7 的 IdentitiesOnly yes，agent 类报错可完全根除。
5. 踩坑总结
| 坑 | 现象 | 解法 |
|---|---|---|
| IDE 内置 ssh2 库不兼容 Windows agent | Failed to connect to agent |
IdentitiesOnly yes + remote.SSH.useLocalServer: true |
WSL 内执行 ssh wsl-ubuntu 解析失败 |
报 host 不存在 | 正常现象，别名只在 Windows 侧 config 中 |
| 公钥已写入但仍要密码 | 登录始终提示输密码 | 99% 是 ~/.ssh（700）/ authorized_keys（600）权限不对 |
| sshd 默认关闭公钥登录 | 配置无误仍走密码 | PubkeyAuthentication 默认被注释，手动开启 |
| WSL2 NAT 端口不通 | localhost:2222 连接超时 |
Windows 侧配置 portproxy 端口转发（netsh interface portproxy） |
仓库放 /mnt/c 后连接正常但 HMR 失效 |
改代码不热更、lint 缓慢 | 仓库迁入 WSL 内部文件系统（~/projects/） |
| 断点空心、无法命中源码 | 调试器停在编译产物 | 必须以 WSL 环境打开项目（Remote-SSH 已满足），详见 说明书 §10.1 |
6. 经验结论（可复用）
- ED25519 密钥安全性、速度优于 RSA，现代环境首选
- SSH 免密失败 80% 是权限问题，而非密钥问题
- Remote-SSH 系插件（VSCode / Qoder CN 同源）的 agent 报错是经典通病，标准解法：
IdentitiesOnly yes - WSL2 属于 NAT 虚拟机，
localhost端口连通性是常见坑点 - 连上之后一切操作都在 WSL 内进行：依赖安装、启动服务、调试、Git，不要在 Windows 侧碰 node_modules（pnpm 符号链接跨文件系统会损坏）
