很多开发者用 VSCode 连远程服务器写代码时，想用上 智能体 AI编码助手，却总遇到登录失败、联网超时、地区不支持、插件加载失败等问题。核心原因：远程服务器不能与本地共享网络，必须通过 SSH 远程端口转发，把远程的网络请求代理到本地已打通的网络环境。

这篇教程把每一个点击、每一行配置、每一个隐藏细节都拆到最细，新手跟着做就能 100% 成功，还包含全场景报错排查 + 一键恢复方案。

0 前置准备（缺一不可！先做完再开始）

在动手配置前，必须先确认以下所有条件，否则 90% 会失败。

0.1 本地电脑必备

  1. 安装 VSCode（最新版，避免兼容问题）
  2. 本地魔法工具正常运行
    • 工具：如图 等（任意能正常访问 Ww 的 魔法）
    • 关键：记住本地代理端口（默认大多是 7897，部分是 10809，必须记准！）

  1. 本地已安装并登录 智能体编码 插件
    • 本地 VSCode 装 CodeX → 登录 OpenAI 账号 → 自动生成 auth.json 认证文件
    • (本地使用魔法使用CodeX编码后默认生成位置在)

  2. 本地已安装 Git（含 SSH 工具）
    • 用于 SSH 连接、SCP 传文件，Windows 直接装 Git 就自带 SSH

0.2 远程服务器必备

  1. 本地能正常 SSH 连接远程服务器（IP、端口、账号、密码 / 密钥正确）
  2. 远程服务器系统：Linux（CentOS/Ubuntu/Debian 等，本文通用）
  3. 远程服务器已安装 curl 命令（用于测试网络，默认都有，没有就装：yum install curl 或 apt install curl）

0.3 核心原理（看懂就不会配错）

通过 SSH 的 RemoteForward 功能：远程服务器 127.0.0.1:17897 → 转发 → 本地电脑 127.0.0.1:7897（本地代理端口）让远程服务器 “借” 本地(需使用魔法科学上网)的网络访问 Codex/OpenAI 服务。

1 步骤 1：安装 VSCode 必备插件（本地 + 远程双端）

1.1 本地安装 Remote-SSH（远程连接核心）

  1. 打开本地 VSCode → 点击左侧扩展图标（四个方块）
  2. 搜索框输入：Remote-SSH
  3. 找到 Microsoft 官方的 Remote - SSH 插件 → 点击安装
  5. 安装完成后，左侧会出现远程资源管理器（显示器图标）

1.2 远程服务器安装 CodeX 插件（必须装在远程！）

  1. 本地 VSCode 点击左侧远程资源管理器
  2. 下拉选择 SSH Targets → 点击右上角 + 号
  4. 输入 SSH 连接命令：ssh 远程用户名@远程服务器IP -p 远程SSH端口
    • 示例：ssh root@192.168.1.100 -p 22
  5. 选择配置文件保存位置：C:\Users\你的用户名\.ssh\config（默认即可）

  7. 点击刚添加的远程主机 → 选择 在当前窗口连接
  8. 输入远程服务器密码 / 选择密钥 → 成功连接远程（底部状态栏显示远程主机名）
  9. 关键：在远程 VSCode 的扩展商店搜索 Codex → 点击 安装到 SSH: 你的远程主机
    • 绝对不要装在本地！装在本地远程用不了

2 步骤 2：同步本地 CodeX 认证文件 auth.json 到远程

智能体 的登录信息存在 auth.json，远程没有这个文件就无法登录，必须精准同步。

2.1 找到本地 auth.json 文件（Windows 详细路径）

  1. 打开文件资源管理器 → 顶部地址栏输入：%USERPROFILE% 回车
    • 直接跳转到：C:\Users\你的电脑用户名
  2. 开启显示隐藏项目：
    • 点击资源管理器顶部 查看 → 勾选 隐藏的项目
  3. 找到文件夹 .codex → 进入后就能看到 auth.json
    • 完整路径：C:\Users\你的用户名\.codex\auth.json
    • 没有这个文件：回到本地 VSCode，打开 Codex 插件登录 OpenAI 账号，自动生成

2.2 远程服务器创建存放目录

  1. 远程 VSCode 打开终端（顶部菜单栏 → 终端 → 新建终端）
  2. 执行命令创建 .codex 文件夹：（使用codex后也会默认生成）

运行

mkdir -p ~/.codex
  1. 修改文件夹权限（避免权限不足）：

运行

chmod 755 ~/.codex

2.上传 auth.json

方法 1：VSCode 直接拖拽上传（最简单）
  1. 本地找到 auth.json 文件 → 选中拖拽到远程 VSCode 左侧文件浏览器的 ~/.codex/ 目录下
  2. 等待上传完成，远程目录出现 auth.json 即成功

3 步骤 3：修改本地 SSH Config 配置（端口转发核心）

这一步是远程能联网的关键，必须精准配置。

3.1 找到本地 SSH Config 文件

  1. 本地 VSCode 按 Ctrl + Shift + P → 输入 Remote-SSH: Open Configuration File...
  2. 选择你的配置文件：C:\Users\你的用户名\.ssh\config
  3. 自动用 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：远程自定义端口（随便选，只要不冲突，推荐用 9999）
  • 7897：本地代理端口（必须和你本地代理工具的端口完全一致！）

3.3 检查端口是否冲突（可选）

本地 CMD 执行，查看 9999 端口是否被占用：

运行

netstat -ano | findstr "9999"
  • 无输出：端口可用
  • 有输出：换一个远程端口，比如 17898、18888

4 步骤 4：重启 VSCode 远程连接（配置生效必须做）

修改完 SSH Config 后，不重连配置永远不生效！

  1. 关闭当前远程 VSCode 窗口（直接关掉整个窗口）
  2. 重新打开本地 VSCode → 远程资源管理器 → 再次连接远程主机
  3. 等待 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失败原因：

失败原因：

  • 本地代理没开
  • 代理端口填错
  • 代理节点不支持 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：快捷命令（推荐）
  1. 远程 VSCode 按 Ctrl + Shift + P
  2. 搜索：Preferences: Open Remote Settings (JSON)
  3. 点击打开，自动跳转到远程配置文件
方法 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"
}
  1. 按 Ctrl + S 保存文件

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 永久生效（重启终端仍有效）

  1. 远程终端执行，把代理写入 ~/.bashrc：

运行

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
  1. 生效配置：

运行

source ~/.bashrc
  1. 验证是否生效：

运行

echo $HTTP_PROXY
  • 输出 http://127.0.0.1:9999 即成功

8 步骤 8：登录 智能体 插件（最终激活）

所有配置完成，现在登录 Codex 就能用了！

  1. 远程 VSCode 左侧点击 Codex 插件图标
  2. 插件界面选择 通过 ChatGPT 登录（或 API 密钥登录）
  3. 本地电脑自动弹出浏览器登录页面
  4. 输入你的 OpenAI 账号密码 → 完成登录
  5. 登录成功后，页面提示 Signed in to Codex，关闭页面即可
  6. 远程 VSCode 智能体 插件显示已登录，可以正常使用智能补全、对话

  7. 9 全场景报错排查（99% 问题都能解决）

    9.1 报错：地区不支持

    {"error":{
    "code":"unsupported_country_region_territory",
    "message":"Country, region, or territory not supported"
    }
}

    解决方法：

    1. 本地代理切换全局模式（不要规则模式）
    2. 更换魔法的节点（选择支持的）
    3. 重启本地代理 + 重连 VSCode 远程

9.2 报错：连接超时 Operation timed out

解决方法：

  1. 点击 智能体 插件的 Try again 重试
  2. 关闭 VSCode 完全退出，重新打开连接远程
  3. 重新执行步骤 5，验证端口转发是否正常

9.3 远程 curl 测试无响应

解决方法：

  1. 确认本地代理已开启
  2. 检查 SSH Config 的 RemoteForward 端口是否正确
  3. 重启 Remote-SSH 连接
  4. 本地代理端口和 config 里的端口完全一致

9.4 智能体 插件加载失败 / 不显示

解决方法：

  1. 远程 VSCode 卸载 智能体 插件 → 重新安装
  2. 重启远程 VSCode
  3. 检查 auth.json 权限是否为 644

9.5 提示无权限读取 auth.json

解决方法：远程终端执行：

运行

chmod 644 ~/.codex/auth.json
chmod 755 ~/.codex

10 步骤 9：恢复远程服务器默认网络（取消）

如果不需要用 Codex，按以下步骤彻底清空代理，恢复远程原始网络：

10.1 删除 SSH 端口转发

  1. 打开本地 ~/.ssh/config 文件
  2. 注释 / 删除行：RemoteForward 17897 127.0.0.1:7897

10.2 清空远程 settings.json

  1. 打开远程 settings.json
  2. 删除所有内容，改为空对象：{}

10.3 取消终端临时代理

远程终端执行：

运行

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

10.4 删除 bashrc 永久代理

  1. 远程终端编辑 ~/.bashrc：

运行

vim ~/.bashrc
  1. 删除之前添加的 4 行 export 代理语句
  2. 生效配置：

运行

source ~/.bashrc

10.5 重连远程

关闭 VSCode 远程窗口 → 重新连接，完成恢复。

11 终极总结（核心 3 点，记牢就不会错）

  1. 端口必须一致：本地代理端口、SSH Config 转发端口、远程 settings.json 代理端口，三者一一对应
  2. 文件必须同步：本地 auth.json 必须上传到远程 ~/.codex/，且权限正确
  3. 必须重连生效：修改任何配置后，都要重启 VSCode 远程连接

只要严格按步骤做，远程服务器用 智能体AI编码 就和本地一样流畅！

# vscode # ssh # 服务器
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

OpenClaw 个人AI助手使用教程：从配置到实战

openclaw v2.0使用篇上线

avatar 2048 AI社区

AI Agent的竞品分析：从功能对比到战略定位

为了进行有效的竞品分析，我们首先需要明确定义AI Agent解决的问题空间。自主性维度：从完全手动控制到完全自主决策任务复杂度维度：从简单单一任务到复杂多步骤任务环境交互维度：从纯数字环境到物理世界交互时间尺度维度：从即时响应到长期规划与执行协作维度：从单智能体操作到多智能体协作在这一问题空间中，不同的AI Agent产品定位在不同的区域，解决不同类型的问题。理解这些定位差异是竞品分析的关键。

avatar 2048 AI社区
cover

开源 AI 组件的隐性风险

avatar 2048 AI社区