想用本地 VS Code 编辑 VPS 上的项目，顺手在同一个远端目录里运行 coding agent？先别在 VPS 上装图形桌面。VS Code 的 Remote - SSH 会通过已有的 SSH 连接安装 VS Code Server；文件、终端和大多数工作区扩展都在 VPS 上运行，本地电脑负责显示编辑器。本文以 Ubuntu VPS 和单人开发为例，从密钥连接讲到最常见的卡在 “Installing VS Code Server” 的排查。
这与浏览器版 code-server 是两条路线：你仍需在自己的电脑安装 VS Code，VPS 只需 SSH 服务与受支持的系统环境。项目代码留在 VPS，编辑器连接断开也不会替你保存终端里的交互进程；需要长时间运行的 agent，请用 tmux 管理会话。
先确认你能从本地终端登录 VPS，并在服务器上检查系统、内存、磁盘和基础工具：
ssh [email protected]
uname -m
cat /etc/os-release
free -h
df -h "$HOME"
command -v bash tar curl || true
把示例 IP 和用户名替换成自己的。203.0.113.10 是文档示例地址，不能直接连接。按 VS Code 的 Remote - SSH 文档，远端至少需要 1 GB 内存，官方建议 2 GB 内存、2 核 CPU；跑构建、测试或 coding agent 时，还要给这些程序单独留资源。当前 Linux 前置条件要求内核至少 4.18、glibc 至少 2.28、libstdc++ 至少 3.4.25，并需 OpenSSH Server、Bash、tar、curl 或 wget。Ubuntu 22.04/24.04/26.04 等较新的 glibc 系统更省心；Alpine 这类 musl 系统不适合作为本文的 Remote - SSH 主机。
如果远端缺少基础工具，在已登录 VPS的终端安装：
sudo apt update
sudo apt install -y openssh-server bash curl tar ca-certificates git tmux
sudo systemctl status ssh --no-pager
已有 SSH 会话能正常使用时，不必为了 VS Code 改 SSH 端口或关闭密码登录。尤其不要在尚未验证密钥登录前修改 sshd_config，以免把自己锁在服务器外。
下面的命令在自己的电脑执行，不是在 VPS 上。已有专用密钥可以沿用；新建时先检查目标文件是否存在，避免覆盖：
ls -l ~/.ssh/vps_dev ~/.ssh/vps_dev.pub 2>/dev/null || true
ssh-keygen -t ed25519 -f ~/.ssh/vps_dev -C "vps-remote-dev"
建议给私钥设置口令，必要时让系统的 SSH agent 记住口令。把 .pub 公钥添加到 VPS 用户的 ~/.ssh/authorized_keys。在有 ssh-copy-id 的 macOS/Linux 环境中，可执行：
ssh-copy-id -i ~/.ssh/vps_dev.pub [email protected]
ssh -i ~/.ssh/vps_dev [email protected] 'whoami'
如果本地没有 ssh-copy-id，可通过云厂商控制台的 SSH Key 功能，或在已有可信会话里将 cat ~/.ssh/vps_dev.pub 输出的公钥追加到远端 ~/.ssh/authorized_keys；不要上传私钥。首次连接前核对 VPS 的主机密钥指纹，主机密钥突然变化时先检查是否重装过机器或 IP 是否指向了别处，不要用 StrictHostKeyChecking no 掩盖问题。
编辑本地 ~/.ssh/config，给这台机器起个固定名字：
Host dev-vps
HostName 203.0.113.10
User ubuntu
Port 22
IdentityFile ~/.ssh/vps_dev
IdentitiesOnly yes
如果云厂商的 SSH 端口不是 22，修改 Port 为实际端口。保存后先在本地验证配置：
chmod 600 ~/.ssh/config ~/.ssh/vps_dev
ssh -G dev-vps | grep -E '^(hostname|user|port|identityfile) '
ssh dev-vps 'whoami; pwd'
只有这一步成功，才继续打开 VS Code。密钥被拒绝时先用 ssh -v dev-vps 看实际使用的用户名和密钥；Permission denied (publickey) 常见原因是公钥装错用户、IdentityFile 指向了错误私钥，或远端 ~/.ssh / authorized_keys 权限不对。不要反复尝试 root 密码。
在本地 VS Code 安装 Microsoft 的 Remote - SSH 扩展。按 F1（或打开命令面板），运行 Remote-SSH: Connect to Host...，选 dev-vps。首次连接会在 VPS 安装 VS Code Server，完成后再通过 File → Open Folder 打开远端项目目录，例如 /home/ubuntu/app。左下角应显示 SSH: dev-vps。
打开 VS Code 终端，执行 hostname 和 pwd：如果显示 VPS 主机名和远端项目路径，终端就在 VPS 上。此时从扩展面板安装需要在工作区运行的语言扩展，留意它是否被标为 Install in SSH: dev-vps。不要误以为本地扩展和远端扩展总是同一份；官方说明编辑器 UI 扩展通常在本地，而工作区扩展多在远端运行。
远端启动开发服务器时，让应用只监听 127.0.0.1:3000。在 VS Code 的 Ports 面板转发远端 3000 端口，再用面板显示的本地 URL 测试；本地端口被占用时，VS Code 可能分配另一个端口。这样不必为临时开发服务在 VPS 防火墙开放 3000。具体操作见 官方端口转发说明。
先确认 VS Code 终端的 pwd 是预期项目目录，再启动装在 VPS 普通用户账号下的 coding agent。这样 agent 读写的是远端仓库，消耗的 CPU、内存和磁盘也来自 VPS；模型请求仍按所用工具的认证方式发往对应服务。不要在生产站点目录直接授予 agent 无限制写入权限，先用独立开发用户和 Git 分支工作。
需要具体安装步骤，可接着看站内的 Codex CLI VPS 远程开发教程或 Claude Code VPS 教程。如果会关闭电脑或网络不稳定，在远端先运行 tmux new -s agent，然后在 tmux 会话中启动 agent；重连后用 tmux attach -t agent 回到会话。tmux 只负责保留终端会话，不能代替保存代码、提交 Git 或备份 VPS。
| 现象 | 先查什么 | 常见处理 |
|---|---|---|
ssh dev-vps 就超时 | IP、端口、云防火墙与本地网络 | 在云控制台核对公网 IP 和入站 SSH 规则；VS Code 无法修复底层 SSH 不通 |
Permission denied (publickey) | ssh -v dev-vps 的用户名、私钥路径与服务器公钥 | 校对 User、IdentityFile，确认公钥属于目标用户 |
| 终端 SSH 正常，VS Code 卡在安装 Server | VS Code 的 Output → Remote - SSH 日志、远端磁盘和下载网络 | 先查 df -h "$HOME"，再按官方建议尝试本地下载后传输 |
VS Code Server failed to start | 系统库版本、磁盘空间、远端日志 | 核对 Linux 前置条件；在命令面板执行 Remote-SSH: Kill VS Code Server on Host... 后重连 |
| 登录提示被隐藏、一直转圈 | 是否等待密钥口令或二次验证 | 在 VS Code 设置中启用 remote.SSH.showLoginTerminal，看完整交互提示 |
| 文件能打开，扩展或 agent 不能用 | 扩展安装位置、VPS 出站网络与内存 | 检查远端扩展、free -h，以及相关服务的出站连接 |
下载失败时，先看 VS Code 官方连接与下载说明：Remote - SSH 默认先让远端下载 VS Code Server，失败后可回退到本地下载并传输；在用户设置中把 remote.SSH.localServerDownload 设为 always 可强制走本地下载。某些扩展仍需远端访问 Marketplace 或自己的依赖源。不要直接删除整个 ~/.vscode-server 来“清缓存”，优先使用官方提供的 Kill/Uninstall 命令，并看日志确定原因。
确认本地 ssh dev-vps 可重复登录，远端 df -h "$HOME" 有足够空间，VS Code Ports 面板中的开发端口只供预期用户访问。涉及 SSH 改动时保持一个已有会话在线，先从第二个终端验证新连接。对于持续运行的 coding agent，把仓库、密钥、服务进程与生产业务账号分开；远端开发环境方便的是协作和计算位置，安全边界仍要由你自己配置。