remote-codex-proxy-guide

KO | EN

gitlite — search

#python #hacktoberfest #ai #golang #go #android #machine-learning #rust #linux #docker #java #awesome #pytorch #mcp

remote-codex-proxy-guide

(★ 19)

远程服务器在 Cursor / VSCode 中使用 Codex 配置指南

remote-codex-proxy-guide 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 远程服务器在 Cursor / VSCode 中使用 Codex / Copilot 配置指南

## 适用场景

- 你通过 Cursor 或 VSCode 的 Remote SSH 连接到远程服务器（如 AutoDL、深度学习云服务器、实验室集群等）
- 远程服务器**无法直接访问外网**
- Codex / Copilot 等 AI 插件登录后一直显示 `thinking` / `reconnecting`，或扩展市场打不开、pip 很慢

## 原理说明

远程环境用的是**服务器的网络**，不是你本地的网络。服务器本身无法翻墙，但你的**本地电脑**（Mac / Windows）运行着代理软件（如 Clash）。我们通过 SSH 的 `RemoteForward` 功能，把远程服务器的某个端口**隧道转发**到你本地的代理端口，让远程服务器借助你本地的代理访问外网。

```
远程服务器 (127.0.0.1:7897) ──SSH 隧道──> 本地电脑 (localhost:7897) ──Clash──> 外网
```

---

## 前提条件

1. 本地电脑已安装并运行代理软件（Clash / ClashX / Clash Verge 等）
2. 知道本地代理的 **HTTP 端口号**（本文以 `7897` 为例，请根据自己的实际端口替换）
3. 已安装 Cursor 或 VSCode，并装好 Remote SSH 插件
4. 已有远程服务器的 SSH 连接信息（地址、端口、用户名）

---

## 第一步：确认本地代理端口

### macOS

1. 打开你的代理软件（Clash Verge / ClashX 等）
2. 在设置或主界面找到 **HTTP 代理端口**，记下来（例如 `7897`）

### Windows

1. 打开 Clash for Windows
2. 在 **General** 页面找到 **Port**（HTTP 端口），记下来（例如 `7890`）

### 验证本地代理是否正常

打开**本地终端**（Mac 的 Terminal / Windows 的 PowerShell），运行：

```bash
curl -I https://pypi.org/simple/ --max-time 5 -x http://127.0.0.1:7897
```

> 把 `7897` 替换为你的实际端口。

如果返回类似 `HTTP/1.1 200 OK` 的内容，说明本地代理正常工作。如果失败，请先排查本地代理软件是否正确运行。

---

## 第二步：修改 SSH 配置文件

### macOS

1. 打开 **Terminal**（终端）
2. 输入以下命令打开 SSH 配置文件：

```bash
nano ~/.ssh/config
```

> 如果文件不存在会自动创建。你也可以用 `vim` 或 `code ~/.ssh/config`（VSCode 打开）。

3. 找到你远程服务器的 Host 条目，添加 `RemoteForward` 和心跳配置。完整示例：

```
Host my-server
    HostName your-server-address.com
    Port 22
    User root
    RemoteForward 7897 localhost:7897
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

**字段说明：**

| 字段 | 说明 |
|------|------|
| `Host` | 你给这个连接起的别名，随意取 |
| `HostName` | 服务器的域名或 IP 地址 |
| `Port` | SSH 端口（默认 22，云服务器可能不同） |
| `User` | 登录用户名 |
| `RemoteForward 7897 localhost:7897` | 把远程的 7897 端口转发到本地的 7897 端口 |
| `ServerAliveInterval 60` | 每 60 秒发送心跳，防止 SSH 断连 |
| `ServerAliveCountMax 3` | 连续 3 次心跳无响应才断开 |

4. 保存文件：
   - 如果用 `nano`：按 `Ctrl + O` → 回车确认 → `Ctrl + X` 退出
   - 如果用 `vim`：按 `Esc` → 输入 `:wq` → 回车

### Windows

1. 按 `Win + R`，输入 `notepad %USERPROFILE%\.ssh\config`，回车打开配置文件
2. 如果提示文件不存在，选择"是"创建新文件
3. 添加同样的配置内容（参考上面的示例）
4. 保存并关闭

---

## 第三步：重新建立 SSH 连接并验证

### 关闭旧连接

> ⚠️ 这一步非常重要！修改 config 后，**必须断开旧的 SSH 连接重新连**，新配置才会生效。

- 如果你在终端里 SSH 连着，输入 `exit` 退出
- 如果你用 Cursor / VSCode Remote SSH 连着，关闭整个 IDE 窗口

### 重新连接

在**本地终端**中运行：

```bash
ssh my-server
```

> 把 `my-server` 替换为你在 config 里写的 Host 别名。

### 验证代理转发

连上远程服务器后，在**远程终端**中运行：

```bash
curl -I https://pypi.org/simple/ --max-time 5 -x http://127.0.0.1:7897
```

**预期结果：**

- ✅ 返回 `HTTP/1.1 200 OK` → 代理转发成功，继续下一步
- ❌ 返回 `Connection refused` → 转发未生效，请检查：
  1. 本地代理软件是否在运行
  2. SSH config 中的 `RemoteForward` 是否写对（格式：`RemoteForward 远程端口 localhost:本地端口`）
  3. 是否用新的 SSH 连接（旧连接不会带上新配置）

---

## 第四步：配置 IDE 远程代理设置（Remote 作用域）

这一步让 IDE **在远程服务器上的扩展**（Codex、Copilot 等）走代理。

### 方式一：通过命令面板编辑 JSON（推荐）

1. 用 Cursor 或 VSCode 通过 Remote SSH 连接到远程服务器

2. 打开命令面板：
   - **macOS**：按 `Cmd + Shift + P`
   - **Windows**：按 `Ctrl + Shift + P`

3. 在命令面板中输入：

```
Preferences: Open Remote Settings (JSON)
```

> ⚠️ **一定要选 Remote Settings**，不是普通的 Settings！

4. 在打开的 JSON 文件中，加入以下内容：

```json
{
  "http.proxy": "http://127.0.0.1:7897",
  "http.proxySupport": "override",
  "http.proxyStrictSSL": false
}
```

> 注意：`http.proxySupport` 建议设为 `"override"` 而不是 `"on"`，这样可以强制所有扩展都走代理，避免部分扩展绕过。

5. 按 `Cmd + S`（Mac）或 `Ctrl + S`（Windows）**保存**

### 方式二：通过 GUI 设置界面

1. 按 `Cmd + ,`（Mac）或 `Ctrl + ,`（Windows）打开设置
2. 顶部切换到 **Remote [SSH: xxx]** 标签页
3. 搜索 `http proxy`
4. 在 **Http: Proxy** 中填入 `http://127.0.0.1:7897`
5. 将 **Http: Proxy Support** 改为 `override`
6. 取消勾选 **Http: Proxy Strict SSL**

---

## 第五步：配置 IDE 本地代理设置（User 作用域）

> ⚠️ 这一步很多教程没提到，但**非常关键**！

Copilot / Codex 登录时获取 token 是在**本地**（User 作用域）完成的，走的是本地网络。如果你本地没配代理，登录认证会超时。

1. 按 `Cmd + ,`（Mac）或 `Ctrl + ,`（Windows）打开设置
2. 顶部切换到 **User** 标签页（不是 Remote）
3. 搜索 `http proxy`
4. 在 **Http: Proxy** 中填入 `http://127.0.0.1:7897`
5. 将 **Http: Proxy Support** 改为 `override`

> 这里的端口是你**本地**的 Clash 端口，和远程配置用的是同一个端口号（因为本地和远程最终都指向你本地的 Clash）。

---

## 第六步：重启 IDE 并验证

1. 完全退出 Cursor / VSCode（不是只关闭窗口，要彻底退出应用）
   - **macOS**：`Cmd + Q`
   - **Windows**：右键任务栏图标 → 退出
2. 重新打开 Cursor / VSCode
3. 通过 Remote SSH 重新连接远程服务器
4. 打开 Codex / Copilot，应该可以正常使用了

---

## 常见问题排查

### Q：登录时提示"无法登陆 GHE" / "GHE.com" 相关错误

这通常是因为 Auth Provider 被设成了 GitHub Enterprise。如果你用的是普通 GitHub 账号：

1. 打开设置（`Cmd + ,` / `Ctrl + ,`）
2. 搜索 `github copilot auth`
3. 找到 **GitHub > Copilot > Advanced: Auth Provider**
4. 将其**清空**或改为 `github`
5. 重启 IDE 后重新登录

### Q：配好了代理但 Copilot 还是登录不了

检查是否完成了**第五步**（User 作用域代理配置）。登录认证走的是本地网络，不是远程。

如果 User 作用域也配了还是不行，可能是系统底层流量绕过了应用层代理。去 Clash 设置中**开启 TUN 模式**（虚拟网卡），让所有系统流量都走代理：

- **Clash Verge**：设置 → 开启 TUN Mode
- **ClashX Pro**：增强模式（Enhanced Mode）
- **Clash for Windows**：General → TUN Mode

### Q：每次都要开着代理吗？

是的。这个方案依赖 SSH 隧道 + 本地代理，所以你的 **SSH 连接必须保持活跃**，本地的**代理软件也必须运行**。断开任何一个，远程服务器就失去外网访问能力。

### Q：换了服务器实例怎么办？

如果服务器地址变了（比如 AutoDL 重新开了机器），只需要更新 SSH config 中的 `HostName` 和 `Port`，然后重新连接即可。IDE 的远程代理设置不需要改。

### Q：端口冲突怎么办？

如果远程服务器的 `7897` 端口已被其他程序占用，可以换一个端口，比如 `8899`：

```
RemoteForward 8899 localhost:7897
```

相应地，IDE 的远程设置也要改成：

```json
"http.proxy": "http://127.0.0.1:8899"
```

### Q：不用 SSH config，能用命令行参数吗？

可以。直接在 SSH 命令中加 `-R` 参数：

```bash
ssh -R 7897:localhost:7897 -p 22 root@your-server-address.com
```

但每次都要手动输入，不如写在 config 里方便。

### Q：如何确认 SSH 隧道是否在运行？

在远程服务器上运行：

```bash
ss -tlnp | grep 7897
```

如果看到 `127.0.0.1:7897` 处于 `LISTEN` 状态，说明隧道正常。

---

## 进阶方案：使用 autossh 替代 SSH config

### 为什么需要 autossh？

SSH config 的 `RemoteForward` 方案有两个已知问题：

1. **VSCode 端口回映射**：VSCode 的 Remote SSH 会自动检测远程端口并映射回本地，可能与 `RemoteForward` 冲突，导致代理不稳定
2. **断连后丢失转发**：服务器断开重连时，VSCode 有时不会重新建立端口转发，导致重连后代理失效

`autossh` 是一个专门维护 SSH 隧道的工具，会自动检测断连并重连，隧道独立于 VSCode 运行，更加稳定。

### 安装

**macOS：**

```bash
brew install autossh
```

**Ubuntu / Debian：**

```bash
sudo apt install autossh
```

**Windows：**

Windows 下没有原生 autossh，可以用 WSL 安装，或使用 Git Bash + 脚本模拟重连。

### 使用

在**本地终端**运行：

```bash
autossh -M 0 -f -N -R 7897:localhost:7897 my-server
```

**参数说明：**

| 参数 | 说明 |
|------|------|
| `-M 0` | 使用 SSH 自带的心跳检测，不额外开监控端口 |
| `-f` | 后台运行 |
| `-N` | 不执行远程命令，只做端口转发 |
| `-R 7897:localhost:7897` | 远程端口转发（和 config 里的 `RemoteForward` 效果一样） |
| `my-server` | SSH config 中定义的 Host 别名 |

运行后，隧道会在后台持续维护。即使 VSCode 断连重连，代理隧道也不受影响。

### 停止 autossh

```bash
# 查找进程
ps aux | grep autossh

# 杀掉进程
kill <PID>
```

### 配合 autossh 时的 SSH config

如果使用 autossh，SSH config 中**不需要**再写 `RemoteForward`，避免重复转发：

```
Host my-server
    HostName your-server-address.com
    Port 22
    User root
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

autossh 会单独负责端口转发，SSH config 只保留连接信息和心跳即可。

---

## 完整配置速查

### 方案一：SSH config（简单，适合大多数场景）

**~/.ssh/config：**

```
Host my-server
    HostName your-server-address.com
    Port 22
    User root
    RemoteForward 7897 localhost:7897
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

### 方案二：autossh（稳定，适合频繁断连的场景）

**~/.ssh/config（不写 RemoteForward）：**

```
Host my-server
    HostName your-server-address.com
    Port 22
    User root
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

**本地终端运行：**

```bash
autossh -M 0 -f -N -R 7897:localhost:7897 my-server
```

### IDE 设置（两种方案通用）

**Remote 作用域（远程代理）：**

```json
{
  "http.proxy": "http://127.0.0.1:7897",
  "http.proxySupport": "override",
  "http.proxyStrictSSL": false
}
```

**User 作用域（本地代理，用于登录认证）：**

```json
{
  "http.proxy": "http://127.0.0.1:7897",
  "http.proxySupport": "override"
}
```

remote-codex-proxy-guide

remote-codex-proxy-guide 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

remote-codex-proxy-guide

remote-codex-proxy-guide 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README