【2026年4月份保姆级超详细】VSCode Remote-SSH 远程服务器完美使用 CodeX 插件（从 0 到 1 全流程 + 无死角避坑）

很多开发者用 VSCode 连远程服务器写代码时想用上 智能体 AI编码助手却总遇到登录失败、联网超时、地区不支持、插件加载失败等问题。核心原因远程服务器不能与本地共享网络必须通过SSH 远程端口转发把远程的网络请求代理到本地已打通的网络环境。这篇教程把每一个点击、每一行配置、每一个隐藏细节都拆到最细新手跟着做就能 100% 成功还包含全场景报错排查 一键恢复方案。0 前置准备缺一不可先做完再开始在动手配置前必须先确认以下所有条件否则 90% 会失败。0.1 本地电脑必备安装 VSCode最新版避免兼容问题本地魔法工具正常运行工具如图 等任意能正常访问 Ww 的 魔法关键记住本地代理端口默认大多是7897部分是10809必须记准本地已安装并登录 智能体编码 插件本地 VSCode 装 CodeX → 登录 OpenAI 账号 → 自动生成auth.json认证文件(本地使用魔法使用CodeX编码后默认生成位置在)本地已安装 Git含 SSH 工具用于 SSH 连接、SCP 传文件Windows 直接装 Git 就自带 SSH0.2 远程服务器必备本地能正常 SSH 连接远程服务器IP、端口、账号、密码 / 密钥正确远程服务器系统LinuxCentOS/Ubuntu/Debian 等本文通用远程服务器已安装curl命令用于测试网络默认都有没有就装yum install curl或apt install curl0.3 核心原理看懂就不会配错通过 SSH 的RemoteForward功能远程服务器 127.0.0.1:17897 → 转发 → 本地电脑 127.0.0.1:7897本地代理端口让远程服务器 “借” 本地(需使用魔法科学上网)的网络访问 Codex/OpenAI 服务。1 步骤 1安装 VSCode 必备插件本地 远程双端1.1 本地安装 Remote-SSH远程连接核心打开本地 VSCode → 点击左侧扩展图标四个方块搜索框输入Remote-SSH找到Microsoft 官方的Remote - SSH插件 → 点击安装安装完成后左侧会出现远程资源管理器显示器图标1.2 远程服务器安装 CodeX 插件必须装在远程本地 VSCode 点击左侧远程资源管理器下拉选择SSH Targets→ 点击右上角 号输入 SSH 连接命令ssh 远程用户名远程服务器IP -p 远程SSH端口示例ssh root192.168.1.100 -p 22选择配置文件保存位置C:\Users\你的用户名\.ssh\config默认即可点击刚添加的远程主机 → 选择在当前窗口连接输入远程服务器密码 / 选择密钥 → 成功连接远程底部状态栏显示远程主机名关键在远程 VSCode的扩展商店搜索Codex→ 点击安装到 SSH: 你的远程主机绝对不要装在本地装在本地远程用不了2 步骤 2同步本地 CodeX 认证文件 auth.json 到远程智能体 的登录信息存在auth.json远程没有这个文件就无法登录必须精准同步。2.1 找到本地 auth.json 文件Windows 详细路径打开文件资源管理器→ 顶部地址栏输入%USERPROFILE%回车直接跳转到C:\Users\你的电脑用户名开启显示隐藏项目点击资源管理器顶部查看→ 勾选隐藏的项目找到文件夹.codex→ 进入后就能看到auth.json完整路径C:\Users\你的用户名\.codex\auth.json没有这个文件回到本地 VSCode打开 Codex 插件登录 OpenAI 账号自动生成2.2 远程服务器创建存放目录远程 VSCode 打开终端顶部菜单栏 → 终端 → 新建终端执行命令创建.codex文件夹使用codex后也会默认生成运行mkdir -p ~/.codex修改文件夹权限避免权限不足运行chmod 755 ~/.codex2.上传 auth.json方法 1VSCode 直接拖拽上传最简单本地找到auth.json文件 → 选中拖拽到远程 VSCode 左侧文件浏览器的~/.codex/目录下等待上传完成远程目录出现auth.json即成功3 步骤 3修改本地 SSH Config 配置端口转发核心这一步是远程能联网的关键必须精准配置。3.1 找到本地 SSH Config 文件本地 VSCode 按Ctrl Shift P→ 输入Remote-SSH: Open Configuration File...选择你的配置文件C:\Users\你的用户名\.ssh\config自动用 VSCode 打开 config 文件3.2 写入端口转发配置找到你刚才连接的远程主机配置段在最后添加//RemoteForward 9999 127.0.0.1:7897 //注意上述的两个端口号7897软件也可自由设置是我们的魔法软件开放的端口9999自由设置是我们要转发的端口 //127.0.0.1 是本地IP RemoteForward 9999 127.0.0.1:7897 ServerAliveInterval 60 ServerAliveCountMax 3完整配置示例Host my-server # 自定义远程名称随便写 HostName 192.168.1.100 # 远程服务器IP Port 22 # 远程SSH端口默认22自定义就改 User root # 远程用户名 RemoteForward 9999 127.0.0.1:7897 # 端口转发核心行参数严格说明9999远程自定义端口随便选只要不冲突推荐用 99997897本地代理端口必须和你本地代理工具的端口完全一致3.3 检查端口是否冲突可选本地 CMD 执行查看 9999 端口是否被占用运行netstat -ano | findstr 9999无输出端口可用有输出换一个远程端口比如 17898、188884 步骤 4重启 VSCode 远程连接配置生效必须做修改完 SSH Config 后不重连配置永远不生效关闭当前远程 VSCode 窗口直接关掉整个窗口重新打开本地 VSCode → 远程资源管理器 → 再次连接远程主机等待 VSCode Server 在远程安装 / 重启完成底部状态栏显示远程主机5 步骤 5双重测试端口转发验证是否通了先测本地再测远程两步都成功才能继续。5.1 测试本地代理第一步本地 CMD 执行命令替换本地代理端口运行curl -I -m 10 -x http://127.0.0.1:7897 https://chatgpt.com/成功标志返回HTTP/1.1 200 Connection established失败原因失败原因本地代理没开代理端口填错代理节点不支持 OpenAI5.2 测试远程端口转发核心验证远程 VSCode 终端执行命令远程端口和 config 一致运行curl -I -m 10 -x http://127.0.0.1:17897 https://chatgpt.com/成功标志返回HTTP/1.1 200 Connection established失败原因SSH Config 没重连远程端口填错本地代理未开启系统代理6 步骤 6配置远程 VSCode 代理让 Codex 走转发绝对关键改的是远程 settings.json不是本地6.1 打开远程 settings.json两种方法方法 1快捷命令推荐远程 VSCode 按Ctrl Shift P搜索Preferences: Open Remote Settings (JSON)点击打开自动跳转到远程配置文件方法 2手动打开路径远程终端执行直接编辑文件vim ~/.vscode-server/data/Machine/settings.json6.2 写入代理配置复制粘贴即可清空文件原有内容粘贴以下代码远程端口和 config 一致{ // 远程VSCode代理地址SSH转发的远程端口 http.proxy: http://127.0.0.1:9999, // 本地地址不走代理避免冲突 http.noProxy: localhost,127.0.0.1,::1, // 强制开启代理支持 http.proxySupport: on }按Ctrl S保存文件7 步骤 7可选远程 Shell 配置代理终端用 Codex 专用如果只在 VSCode 插件里用 Codex直接跳过如果需要在远程终端用 Codex 命令行配置以下代理。7.1 临时生效仅当前终端远程终端执行关闭终端就失效运行export HTTP_PROXYhttp://127.0.0.1:9999 export HTTPS_PROXYhttp://127.0.0.1:9999 export http_proxyhttp://127.0.0.1:9999 export https_proxyhttp://127.0.0.1:99997.2 永久生效重启终端仍有效远程终端执行把代理写入~/.bashrc运行echo export HTTP_PROXYhttp://127.0.0.1:9999 ~/.bashrc echo export HTTPS_PROXYhttp://127.0.0.1:9999 ~/.bashrc echo export http_proxyhttp://127.0.0.1:9999 ~/.bashrc echo export https_proxyhttp://127.0.0.1:9999 ~/.bashrc生效配置运行source ~/.bashrc验证是否生效运行echo $HTTP_PROXY输出http://127.0.0.1:9999即成功8 步骤 8登录 智能体 插件最终激活所有配置完成现在登录 Codex 就能用了远程 VSCode 左侧点击Codex 插件图标插件界面选择通过 ChatGPT 登录或 API 密钥登录本地电脑自动弹出浏览器登录页面输入你的 OpenAI 账号密码 → 完成登录登录成功后页面提示Signed in to Codex关闭页面即可远程 VSCode 智能体 插件显示已登录可以正常使用智能补全、对话9 全场景报错排查99% 问题都能解决9.1 报错地区不支持{error:{ code:unsupported_country_region_territory, message:Country, region, or territory not supported } }解决方法本地代理切换全局模式不要规则模式更换魔法的节点选择支持的重启本地代理 重连 VSCode 远程9.2 报错连接超时 Operation timed out解决方法点击 智能体 插件的Try again重试关闭 VSCode 完全退出重新打开连接远程重新执行步骤 5验证端口转发是否正常9.3 远程 curl 测试无响应解决方法确认本地代理已开启检查 SSH Config 的RemoteForward端口是否正确重启 Remote-SSH 连接本地代理端口和 config 里的端口完全一致9.4 智能体 插件加载失败 / 不显示解决方法远程 VSCode 卸载 智能体 插件 → 重新安装重启远程 VSCode检查auth.json权限是否为 6449.5 提示无权限读取 auth.json解决方法远程终端执行运行chmod 644 ~/.codex/auth.json chmod 755 ~/.codex10 步骤 9恢复远程服务器默认网络取消如果不需要用 Codex按以下步骤彻底清空代理恢复远程原始网络10.1 删除 SSH 端口转发打开本地~/.ssh/config文件注释 / 删除行RemoteForward 17897 127.0.0.1:789710.2 清空远程 settings.json打开远程settings.json删除所有内容改为空对象{}10.3 取消终端临时代理远程终端执行运行unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy10.4 删除 bashrc 永久代理远程终端编辑~/.bashrc运行vim ~/.bashrc删除之前添加的 4 行export代理语句生效配置运行source ~/.bashrc10.5 重连远程关闭 VSCode 远程窗口 → 重新连接完成恢复。11 终极总结核心 3 点记牢就不会错端口必须一致本地代理端口、SSH Config 转发端口、远程 settings.json 代理端口三者一一对应文件必须同步本地auth.json必须上传到远程~/.codex/且权限正确必须重连生效修改任何配置后都要重启 VSCode 远程连接只要严格按步骤做远程服务器用 智能体AI编码 就和本地一样流畅