很多开发者用 VSCode 连远程服务器写代码时，想用上 智能体 AI编码助手，却总遇到登录失败、联网超时、地区不支持、插件加载失败等问题。核心原因：远程服务器不能与本地共享网络，必须通过 SSH 远程端口转发，把远程的网络请求代理到本地已打通的网络环境。
这篇教程把每一个点击、每一行配置、每一个隐藏细节都拆到最细，新手跟着做就能 100% 成功，还包含全场景报错排查 + 一键恢复方案。
0 前置准备（缺一不可！先做完再开始）
在动手配置前，必须先确认以下所有条件，否则 90% 会失败。
0.1 本地电脑必备
- 工具：如图 等（任意能正常访问 Ww 的 魔法）
- 关键：记住本地代理端口（默认大多是 7897，部分是 10809，必须记准！）
- 本地 VSCode 装 CodeX → 登录 OpenAI 账号 → 自动生成 auth.json 认证文件
- (本地使用魔法使用CodeX编码后默认生成位置在)
-
- 用于 SSH 连接、SCP 传文件，Windows 直接装 Git 就自带 SSH
0.2 远程服务器必备
0.3 核心原理（看懂就不会配错）
通过 SSH 的 RemoteForward 功能：远程服务器 127.0.0.1:17897 → 转发 → 本地电脑 127.0.0.1:7897（本地代理端口）让远程服务器 “借” 本地(需使用魔法科学上网)的网络访问 Codex/OpenAI 服务。
1 步骤 1：安装 VSCode 必备插件（本地 + 远程双端）
1.1 本地安装 Remote-SSH（远程连接核心）
1.2 远程服务器安装 CodeX 插件（必须装在远程！）
- 示例：ssh root@192.168.1.100 -p 22
- 绝对不要装在本地！装在本地远程用不了
2 步骤 2：同步本地 CodeX 认证文件 auth.json 到远程
智能体 的登录信息存在 auth.json，远程没有这个文件就无法登录，必须精准同步。
2.1 找到本地 auth.json 文件（Windows 详细路径）
- 直接跳转到：C:\\Users\\你的电脑用户名
- 点击资源管理器顶部 查看 → 勾选 隐藏的项目
- 完整路径：C:\\Users\\你的用户名\\.codex\\auth.json
- 没有这个文件：回到本地 VSCode，打开 Codex 插件登录 OpenAI 账号，自动生成
2.2 远程服务器创建存放目录
运行
mkdir -p ~/.codex
运行
chmod 755 ~/.codex
2.上传 auth.json
方法 1：VSCode 直接拖拽上传（最简单）
3 步骤 3：修改本地 SSH Config 配置（端口转发核心）
这一步是远程能联网的关键，必须精准配置。
3.1 找到本地 SSH 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：远程自定义端口（随便选，只要不冲突，推荐用 9999）
- 7897：本地代理端口（必须和你本地代理工具的端口完全一致！）
3.3 检查端口是否冲突（可选）
本地 CMD 执行，查看 9999 端口是否被占用：
运行
netstat -ano | findstr "9999"
- 无输出：端口可用
- 有输出：换一个远程端口，比如 17898、18888
4 步骤 4：重启 VSCode 远程连接（配置生效必须做）
修改完 SSH Config 后，不重连配置永远不生效！
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失败原因：
失败原因：
- 本地代理没开
- 代理端口填错
- 代理节点不支持 OpenAI
5.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：快捷命令（推荐）
方法 2：手动打开路径
远程终端执行，直接编辑文件：
vim ~/.vscode-server/data/Machine/settings.json
6.2 写入代理配置（复制粘贴即可）
清空文件原有内容，粘贴以下代码（远程端口和 config 一致）：
{
// 远程VSCode代理地址（SSH转发的远程端口）
"http.proxy": "http://127.0.0.1:9999",
// 本地地址不走代理，避免冲突
"http.noProxy": "localhost,127.0.0.1,::1",
// 强制开启代理支持
"http.proxySupport": "on"
}
7 步骤 7（可选）：远程 Shell 配置代理（终端用 Codex 专用）
如果只在 VSCode 插件里用 Codex，直接跳过；如果需要在远程终端用 Codex 命令行，配置以下代理。
7.1 临时生效（仅当前终端）
远程终端执行，关闭终端就失效：
运行
export HTTP_PROXY=http://127.0.0.1:9999
export HTTPS_PROXY=http://127.0.0.1:9999
export http_proxy=http://127.0.0.1:9999
export https_proxy=http://127.0.0.1:9999
7.2 永久生效（重启终端仍有效）
运行
echo 'export HTTP_PROXY=http://127.0.0.1:9999' >> ~/.bashrc
echo 'export HTTPS_PROXY=http://127.0.0.1:9999' >> ~/.bashrc
echo 'export http_proxy=http://127.0.0.1:9999' >> ~/.bashrc
echo 'export https_proxy=http://127.0.0.1:9999' >> ~/.bashrc
运行
source ~/.bashrc
运行
echo $HTTP_PROXY
- 输出 http://127.0.0.1:9999 即成功
8 步骤 8：登录 智能体 插件（最终激活）
所有配置完成，现在登录 Codex 就能用了！
9 全场景报错排查（99% 问题都能解决）
9.1 报错：地区不支持
{"error":{
"code":"unsupported_country_region_territory",
"message":"Country, region, or territory not supported"
}
}
解决方法：
9.2 报错：连接超时 Operation timed out
解决方法：
9.3 远程 curl 测试无响应
解决方法：
9.4 智能体 插件加载失败 / 不显示
解决方法：
9.5 提示无权限读取 auth.json
解决方法：远程终端执行：
运行
chmod 644 ~/.codex/auth.json
chmod 755 ~/.codex
10 步骤 9：恢复远程服务器默认网络（取消）
如果不需要用 Codex，按以下步骤彻底清空代理，恢复远程原始网络：
10.1 删除 SSH 端口转发
10.2 清空远程 settings.json
10.3 取消终端临时代理
远程终端执行：
运行
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy
10.4 删除 bashrc 永久代理
运行
vim ~/.bashrc
运行
source ~/.bashrc
10.5 重连远程
关闭 VSCode 远程窗口 → 重新连接，完成恢复。
11 终极总结（核心 3 点，记牢就不会错）
只要严格按步骤做，远程服务器用 智能体AI编码 就和本地一样流畅！
