Skip to content
Back to search

codex-remote-bridge

SkillWorks with Claude CodeGitHub

为 AutoDL 等 GPU 服务器上的 Codex CLI 配置 SSH 反向端口转发,共享 Windows 本地 HTTP 代理或本地可直连网络,并检查代理环境、连通性和回滚。适用于服务器不能访问 Codex 服务、本地电脑可以访问的场景。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dushiqi1987--codex-remote-skill/badge.svg)](/listings/dushiqi1987--codex-remote-skill)

HTML

<a href="/listings/dushiqi1987--codex-remote-skill"><img src="/api/listings/dushiqi1987--codex-remote-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 36 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: codex-remote-bridge
  3. description: 为 AutoDL 等 GPU 服务器上的 Codex CLI 配置 SSH 反向端口转发,共享 Windows 本地 HTTP 代理或本地可直连网络,并检查代理环境、连通性和回滚。适用于服务器不能访问 Codex 服务、本地电脑可以访问的场景。
  4. ---
  5. # 本地 Codex 连接服务器 Codex CLI
  6. 让服务器 Codex CLI 的 HTTP/HTTPS 请求经由 SSH 隧道从本地电脑发出。这里连接的是网络出口;本地 Codex 与服务器 Codex 不共享会话或登录状态。
  7. ## 获取参数并选方案
  8. 从用户提供的 SSH 命令提取主机、SSH 端口、用户名和可选密钥路径。未提供的连接参数才询问,不把文档示例当成真实服务器。默认远端代理端口 `17891`,本地监听端口 `11450`,冲突时同步调整配置和隧道。
  9. - **本地有代理软件**:确认它的 HTTP 或 mixed 端口以及本地访问测试结果。直接把远端端口转发到该本地端口;不额外运行 Python 转发器。纯 SOCKS 端口不能使用 `http://` 地址冒充 HTTP 代理。
  10. - **本地网络能直接访问**:运行 `scripts/local_forward.py` 监听 `127.0.0.1:11450`,再转发到此端口。脚本使用本机正常 DNS 和路由,不自动选择某块 Wi-Fi 网卡,也不会把一个本来无法访问的网络变成可访问网络。
  11. 完整命令和分步说明见 [README.md](README.md)。遇到报错再读 [references/troubleshooting.md](references/troubleshooting.md)。
  12. ## 执行与验证
  13. 1. 在本地验证选定出口。直接网络方案用 `python scripts/local_forward.py`;代理软件方案用已有 HTTP 端口。监听和 SSH 窗口需要持续运行。
  14. 2. 在本地使用 `scripts/start_tunnel.ps1`,或生成 `ssh -N -T -p SSH_PORT -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -R 127.0.0.1:17891:127.0.0.1:LOCAL_PORT USER@HOST`。不要关闭 SSH 主机密钥验证;不要把密码写入文件。
  15. 3. 在服务器使用 `scripts/configure_remote.py` 写入代理环境文件。该脚本保留其他配置,变更前备份,并支持 `--dry-run`。`CODEX_HOME` 非默认时让 `--env-file` 指向对应目录。
  16. 4. 显式导出代理环境,或使用服务器端 `scripts/codex_with_proxy.py` 启动 Codex。不能假定任意版本会自动加载 `~/.codex/.env`;`config.toml` 不是 shell 环境文件,不凭空添加代理键。
  17. 5. 分别验证本地出口、服务器监听、服务器 `curl --proxy`、Codex 登录与一次实际请求。HTTP 401/403 可以表明已收到 HTTP 响应,但不能当成账号可用或完整 Codex 验证成功。不要把 `curl` 成功说成 Codex 已验证。
  18. 6. 报告实际完成的阶段、选定端口、保持运行的进程、备份路径和未完成项。没有真实服务器权限时只生成命令和本地验证证据,明确说明未进行远端验收。
  19. 用户只要求输出命令时,也附上本地出口、远端代理和 Codex 验收命令,并注明这些命令尚未执行;这样用户不会将隧道建立误当成整个链路可用。
  20. ## 运行边界与回滚
  21. 本地和远端只绑定回环地址,避免变成公开代理;服务器同一主机的其他用户仍可能访问回环监听。SSH 由本地发起,`-R` 监听在远端,右侧目标在本地解析。HTTPS/WSS 经 CONNECT 透明传输,由客户端验证 TLS。
  22. 仅改任务所需的代理变量,保留服务器 Codex 的认证、模型提供商、sandbox 和审批设置。不要复制本地 `auth.json`、API 密钥或 SSH 私钥到公开仓库。网络连通不代表账号或服务地区支持。
  23. 回滚时停止隧道和 Python 监听,按备份恢复环境文件,关闭带旧代理变量的 shell 或移除相关变量,重启 Codex。不要结束训练进程或删除其他用户配置。
README.md · README · 261 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 本地 Codex 连接服务器 Codex CLI
  2. **让 GPU 服务器上的 Codex CLI,通过 SSH 反向隧道共享本地电脑的网络出口。**
  3. Agent skill for sharing a local HTTP proxy or a directly reachable network with a remote Codex CLI over an SSH reverse tunnel. Python standard library only; Windows local machine + Linux GPU server.
  4. 大学生、研究生常在 AutoDL 等平台租用 GPU 训练模型。某些服务器的网络无法连接 Codex 服务,而自己的电脑具备可用的代理软件或网络。本项目把配置过程整理成可复用的 skill,附带端口转发、代理配置、验证和回滚脚本。
  5. 它共享的是网络出口。Codex CLI 仍然运行在服务器上,直接处理服务器上的代码、数据和训练任务;本地 Codex 和服务器 Codex 不会因此共享对话或账号登录状态。
  6. ## 两种方案
  7. | 本地条件 | 本地 HTTP 端口 | 是否运行 Python 转发器 |
  8. | --- | --- | --- |
  9. | 有可用的代理软件 | 软件的 HTTP / mixed 端口,例如 `7890` | 不需要,SSH 直接转发到软件端口 |
  10. | Wi-Fi / VPN / 系统路由本身能访问目标服务 | 本项目监听 `11450` | 需要运行 `local_forward.py` |
  11. Wi-Fi 方案的脚本使用操作系统的 DNS 和路由,不会指定某块网卡。只有浏览器能访问、命令行不能访问时,优先检查是否用了浏览器专用代理;这不满足“本地网络直连”的前提。纯 SOCKS5 端口不能当成 HTTP 代理端口。
  12. ```mermaid
  13. flowchart LR
  14. A[服务器 Codex CLI] --> B[服务器回环端口 17891]
  15. B -->|SSH 反向转发 -R| C[本地回环 HTTP 端口]
  16. C --> D{本地出口}
  17. D --> E[代理软件 HTTP / mixed 端口]
  18. D --> F[Python 11450 → 本机 DNS 和路由]
  19. E --> G[Codex 服务]
  20. F --> G
  21. ```
  22. SSH 连接由本地电脑发起。`-R` 左边的监听地址在服务器,右边的目标地址在本地电脑。无需给服务器开放公网代理端口。HTTPS / WSS 经 HTTP CONNECT 透传,TLS 仍由客户端校验。
  23. ## 准备条件
  24. - 本地:Windows PowerShell、OpenSSH 客户端(`ssh -V`)、可访问目标服务的出口。直接网络方案还需要 Python 3.9+。
  25. - 服务器:Linux、SSH 允许远程 TCP 转发、Python 3.9+(使用附带配置脚本时)、已安装 Codex CLI(`codex --version`)。
  26. - 从租赁平台获得自己的 SSH 主机、SSH 连接端口、用户名。示例中的主机和端口都应替换为自己的参数。
  27. - Codex 需要独立有效的登录或 API 凭据。网络通道不解决账号权限、额度和服务地区支持问题。
  28. ## 安装这个 skill
  29. 使用 Skills CLI 一条命令安装到 Codex(需要 Node.js 18+ 和可访问 GitHub 的网络):
  30. ```powershell
  31. npx skills add Dushiqi1987/codex-remote-bridge --skill codex-remote-bridge -g -a codex -y
  32. ```
  33. 也可以克隆后手动安装:
  34. ```powershell
  35. git clone https://github.com/Dushiqi1987/codex-remote-bridge.git
  36. ```
  37. 克隆或下载此仓库后,将**整个文件夹**复制到 Codex 的 skill 目录;保持脚本和参考文档一起安装。
  38. Windows 本地示例(在仓库的父目录执行;目标已存在时先检查,避免覆盖):
  39. ```powershell
  40. Copy-Item -LiteralPath .\codex-remote-bridge -Destination "$env:USERPROFILE\.codex\skills\codex-remote-bridge" -Recurse
  41. ```
  42. Linux 示例:
  43. ```bash
  44. mkdir -p ~/.codex/skills
  45. cp -R ./codex-remote-bridge ~/.codex/skills/
  46. ```
  47. 若你的客户端使用 `~/.agents/skills` 或自定义目录,将同一文件夹放到对应位置。新安装的 skill 在下一轮对话中可用;未显示时重新打开客户端。
  48. 可直接向本地 Codex 说:
  49. > 使用 $codex-remote-bridge 帮我连接服务器上的 Codex CLI。我的 SSH 命令是 ssh -p 你的端口 root@你的主机;本地代理软件的 HTTP 端口是 7890。
  50. 或者:
  51. > 使用 $codex-remote-bridge。我的本地网络能直接访问目标服务,请用 Python 监听 11450,把服务器 17891 反向转发到本地。
  52. ## 手动操作:三个窗口
  53. 以下本地命令均在仓库根目录执行。**步骤 1、2 的窗口需要保持运行,步骤 3 在单独的服务器 SSH 终端执行。**
  54. ### 1. 本地电脑:准备出口
  55. **方案 A:本地代理软件。** 查看软件中的 HTTP 或 mixed 端口。假设为 `7890`,在本地 PowerShell 验证:
  56. ```powershell
  57. curl.exe --noproxy "" --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 30 -I https://api.openai.com
  58. ```
  59. 不用启动本项目的 Python 转发器。下一步将隧道右侧端口改成 `7890`。
  60. **方案 B:本地网络直接可访问。** 新开本地 PowerShell:
  61. ```powershell
  62. python .\scripts\local_forward.py
  63. ```
  64. 看到 `Local HTTP proxy: http://127.0.0.1:11450` 后,在另一个本地窗口验证:
  65. ```powershell
  66. curl.exe --noproxy "" --proxy http://127.0.0.1:11450 --connect-timeout 10 --max-time 30 -I https://api.openai.com
  67. ```
  68. 脚本支持 HTTP 请求方法和请求体、CONNECT、流式响应,以及 HTTP WebSocket Upgrade。HTTPS / WSS 的加密数据在 CONNECT 内传输。它没有 TLS 解密、上游 SOCKS 功能或全系统 VPN 功能。连接空闲超时默认 3600 秒,可用 `--idle-timeout` 调整;单次阻塞网络读写超时由 `--connect-timeout` 控制。
  69. ### 2. 本地电脑:建立 SSH 反向隧道
  70. 把 `12345` 替换为平台给你的 **SSH 连接端口**,主机替换为你的主机。下面的 `connect.nmb1.seetacloud.com` 仅沿用需求中的示例,不代表当前租赁实例。
  71. 直接网络方案:
  72. ```powershell
  73. ssh -N -T -p 12345 -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -R 127.0.0.1:17891:127.0.0.1:11450 root@connect.nmb1.seetacloud.com
  74. ```
  75. 代理软件方案(假设本地软件端口 `7890`):
  76. ```powershell
  77. ssh -N -T -p 12345 -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -R 127.0.0.1:17891:127.0.0.1:7890 root@connect.nmb1.seetacloud.com
  78. ```
  79. 也可使用参数化脚本,先输出命令再运行:
  80. ```powershell
  81. .\scripts\start_tunnel.ps1 -ServerHost connect.nmb1.seetacloud.com -SshPort 12345 -LocalPort 11450 -DryRun
  82. .\scripts\start_tunnel.ps1 -ServerHost connect.nmb1.seetacloud.com -SshPort 12345 -LocalPort 11450
  83. ```
  84. 使用 SSH 密钥时加 `-IdentityFile 'C:\path\to\your-key'`。首次连接按平台提供的指纹核验主机,不使用 `StrictHostKeyChecking=no`。`-N -T` 表示只运行隧道,成功后没有服务器 shell、窗口安静等待是正常现象。`ExitOnForwardFailure` 检查远端监听能否建立,**不保证本地代理或最终服务已连通**。
  85. 若 PowerShell 阻止 `.ps1` 执行,直接使用上面的 `ssh` 命令即可。
  86. ### 3. 服务器:配置并显式加载代理
  87. 另开 SSH 终端进入服务器。推荐把脚本通过 `scp` 上传,避免服务器必须先联网下载仓库:
  88. ```powershell
  89. scp -P 12345 .\scripts\configure_remote.py .\scripts\codex_with_proxy.py root@connect.nmb1.seetacloud.com:~/
  90. ```
  91. 然后在服务器执行:
  92. ```bash
  93. python3 ~/configure_remote.py --dry-run
  94. python3 ~/configure_remote.py
  95. python3 ~/codex_with_proxy.py --check
  96. ```
  97. 配置脚本更新 `~/.codex/.env` 的六个代理变量,保留其他配置,并在更改已有文件前生成 `.env.backup-时间戳`。设置了 `CODEX_HOME` 时跟随该目录;也可显式传入 `--env-file /path/to/.env`。预览不会打印原文件中的凭据。
  98. 如果不上传脚本,可以按你的原始流程手动写入。以下 `cat >` 会覆盖文件,所以先备份已有文件;已有其他环境配置时使用上面的配置脚本更合适:
  99. ```bash
  100. mkdir -p ~/.codex
  101. if [ -e ~/.codex/.env ]; then
  102. cp -p ~/.codex/.env ~/.codex/.env.backup-$(date +%Y%m%d-%H%M%S)
  103. fi
  104. cat > ~/.codex/.env << 'EOF'
  105. HTTP_PROXY="http://127.0.0.1:17891"
  106. HTTPS_PROXY="http://127.0.0.1:17891"
  107. NO_PROXY="localhost,127.0.0.1,::1"
  108. http_proxy="http://127.0.0.1:17891"
  109. https_proxy="http://127.0.0.1:17891"
  110. no_proxy="localhost,127.0.0.1,::1"
  111. EOF
  112. chmod 600 ~/.codex/.env
  113. ```
  114. **写入文件不等于当前进程获得环境变量。** 各版本和第三方封装可能有不同加载方式,因此此流程显式导出变量后启动 Codex,而不依赖 `.env` 自动加载。大小写同时设置,兼容不同 HTTP 客户端(例如 curl 对 HTTP 代理使用小写变量)。`HTTPS_PROXY` 的值也使用 `http://`,因为它指向 HTTP CONNECT 代理。
  115. 若 `.env` 是你自己管理的可信 shell 赋值文件,在服务器当前 shell 加载:
  116. ```bash
  117. set -a
  118. . ~/.codex/.env
  119. set +a
  120. ```
  121. 如果不想执行 `.env` 内的 shell 内容,用附带启动器:它只读取代理键,不执行其他行,也不读取或转移认证文件。
  122. ```bash
  123. python3 ~/codex_with_proxy.py
  124. # 向 Codex 传递参数时,用 -- 分隔:
  125. python3 ~/codex_with_proxy.py -- login status
  126. ```
  127. ## 验收:从网络到 Codex
  128. 在服务器依次执行:
  129. ```bash
  130. # 远端代理监听应出现在回环地址(若是公网地址请先停止并检查 SSH 服务配置):
  131. ss -lnt | grep ':17891'
  132. # 强制走指定代理,防止 NO_PROXY 绕过测试:
  133. curl --noproxy '' --proxy http://127.0.0.1:17891 --connect-timeout 10 --max-time 30 -I https://api.openai.com
  134. # 若在 shell 显式加载过 .env,验证当前环境中的代理也能生效:
  135. curl --noproxy '' --connect-timeout 10 --max-time 30 -I https://api.openai.com
  136. codex --version
  137. codex login status
  138. codex
  139. ```
  140. 也可以在启动器中运行 `login status`,再打开交互 Codex。未登录时按当前 CLI 帮助提供的登录方式操作;自己的账号凭据留在自己的服务器。向 Codex 发一个简单请求,例如“只回复连接成功,不读取或修改任何文件”,收到实际回复后才算 Codex 验收完成。
  141. `HTTP/1.1 200 Connection Established` 只是 CONNECT 建立成功。还需要后面的目标服务响应;401/403/404 等 HTTP 状态只说明收到响应,仍需检查它是否来自目标服务、是否有代理拦截,以及账号是否可用。API 域名可达也不能证明所有登录域名、模型请求或 WebSocket 路径都可用。
  142. ## 停止与回滚
  143. 1. 本地 SSH 隧道窗口按 `Ctrl+C`。
  144. 2. 直接网络方案的 Python 窗口按 `Ctrl+C`。
  145. 3. 服务器按配置脚本输出的**实际备份路径**恢复 `.env`(例如 `cp -p 备份路径 ~/.codex/.env`)。如原来没有文件,移除新建文件前确认其中没有后来添加的配置。
  146. 4. 已加载变量的服务器 shell 中执行:
  147. ```bash
  148. unset HTTP_PROXY HTTPS_PROXY NO_PROXY http_proxy https_proxy no_proxy
  149. ```
  150. 如原本有其他代理配置,恢复它们后重新加载;重新启动 Codex。正在运行的进程不会自动获得新环境。无需删除 `config.toml`、`auth.json` 或结束训练任务。
  151. ## 文件结构
  152. ```text
  153. codex-remote-bridge/
  154. ├── SKILL.md Agent 工作流
  155. ├── README.md 用户教程
  156. ├── agents/openai.yaml Codex 展示信息
  157. ├── scripts/
  158. │ ├── local_forward.py 本地 HTTP / CONNECT 转发器
  159. │ ├── start_tunnel.ps1 SSH 反向隧道启动器
  160. │ ├── configure_remote.py 服务器环境配置与备份
  161. │ └── codex_with_proxy.py 显式携带代理环境启动 Codex
  162. ├── references/troubleshooting.md 故障排查
  163. ├── tests/test_bridge.py 本地离线协议与配置测试
  164. └── evals/evals.json skill 行为测试场景
  165. ```
  166. 运行本地测试:
  167. ```powershell
  168. python -m unittest discover -s tests -v
  169. ```
  170. 测试使用本机回环上的测试服务,验证代理的请求体、CONNECT、分块流式响应、Upgrade 和配置备份;不需要账号或真实服务器。测试通过不代表已经在你的 GPU 服务器上完成端到端验收。
  171. ## 故障排查与参考
  172. 详细排查见 [troubleshooting.md](references/troubleshooting.md)。本地电脑休眠、网络切换或 SSH 退出都会让服务器失去这个出口;重新启动监听和隧道即可恢复。
  173. 两端只绑定回环地址,但同一服务器上的其他用户仍可能访问回环端口。不要公开 `.env`、`auth.json`、API 密钥或 SSH 私钥。本项目不更改模型提供商、TLS 校验、Codex sandbox 或审批设置。
  174. 参考资料(核对日期:2026-10-12):
  175. - [Codex 官方配置基础](https://learn.chatgpt.com/docs/config-file/config-basic):持久设置使用 `config.toml`。
  176. - [Codex 官方环境变量说明](https://learn.chatgpt.com/docs/config-file/environment-variables):环境变量用于进程和 shell 配置;该页面未对所有版本的 `.env` 自动加载或通用 HTTP 代理行为给出保证。
  177. - [OpenSSH ssh 手册](https://man.openbsd.org/ssh):`-R` 远程端口转发、`-N` 和 `-T`。
  178. - [Vercel Skills](https://github.com/vercel-labs/skills) / [Find Skills](https://skills.sh/vercel-labs/skills/find-skills):skill 发现与安装。
  179. - [Anthropic Skill Creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator):skill 结构与验证方法参考。本仓库为独立编写,未打包这些第三方 skill 的代码。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.