远程窗口插件不加载，须先检查extensionKind配置，将插件ID如codex-team.codegeex设为["ui","workspace"]并重启远程窗口；否则插件进程不会在远程启动。
远程窗口里插件不加载，先查 extensionKind 配置
VSCode 插件默认运行在本地（UI 端），远程 SSH 连接后，绝大多数插件不会自动出现在远程窗口里——这不是 bug，是设计行为。比如 CodeGeeX、Copilot、Pylance（部分版本）都属于 UI 类型插件，远程端根本没启动它们的进程。
必须显式告诉 VSCode：“这个插件允许在远程 workspace 环境中运行”。方法是在远程连接成功后的设置中添加：
"remote.extensionKind": {
"codex-team.codegeex": ["ui", "workspace"],
"github.copilot": ["ui", "workspace"]
}
注意：codex-team.codegeex 是插件 ID，可在扩展详情页 URL 或 package.json 中确认；改完必须关闭并重新打开远程窗口才生效，仅重载窗口不够。
pathMappings 配置错，Python 调试断点直接失效
本地打开的文件路径（如 /Users/me/project/main.py）和远程实际路径（如 /home/user/project/main.py）不一致时，VSCode 调试器根本找不到对应代码行，断点变空心，F5 启动后直接跳过——它不是“没命中断点”，而是“压根没识别到断点位置”。
launch.json 中必须手动配 pathMappings，格式为 {"本地路径前缀": "远程路径前缀"}：
"pathMappings": [
{ "localRoot": "${workspaceFolder}", "remoteRoot": "/home/user/project" }
]
常见错误：
- 用相对路径或未展开的变量（如
./或$HOME），必须是绝对路径 -
remoteRoot指向了项目子目录（如/home/user/project/src），但代码实际在父目录下 - 路径末尾是否带
/不统一，导致映射失败
远程终端能跑通，但插件调用网络失败
插件在远程端运行后，仍可能提示“未连接服务”“认证失败”或空白响应。这不是插件问题，而是远程服务器本身无法访问目标 API。
验证方式：在远程终端执行：
curl -I https://api.codegeex.cn/v1/chat/completions
若返回 Could not resolve host 或超时，说明远程网络不通。此时需：
- 确认远程服务器能否直连公网（很多云服务器默认禁 outbound 443）
- 若走代理，必须在远程端配置环境变量
HTTPS_PROXY，VSCode 设置里的http.proxy对插件进程无效 -
copilot.proxy这类插件专属代理字段，只影响 Copilot 自身，不影响 CodeGeeX 等其他插件
~/.vscode-server 权限错，连接卡在 “Connecting…”
首次 SSH 连接后，VSCode 会在远程用户家目录下部署服务端组件到 ~/.vscode-server。后续连接失败常因该目录权限异常：
- 目录被 root 创建（如用 sudo ssh 登录过），普通用户无执行权
- 磁盘满或 SELinux 启用，导致
server.sh启动失败 -
PermitUserEnvironment no（sshd 配置），使 VSCode 无法注入环境变量，调试器找不到 Python 解释器
快速检查命令：
ls -ld ~/.vscode-server ls -l ~/.vscode-server/bin/ | head -3 ssh -T user@host 'echo $SHELL'
关键点：shell 必须是 /bin/bash 或 /bin/zsh，不能是 /usr/sbin/nologin；~/.vscode-server/bin/ 下应有可执行的 server.sh 和 commit ID 子目录。
