/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
前言
在本地 Cursor 中安装并登录 Codex 后，切换到 Remote SSH 窗口，有时会再次出现未登录、请求失败或连接中断等问题。
这类问题通常不是插件本身损坏，而是因为 Remote SSH 模式下，本地环境和远程环境彼此独立：
本地电脑：运行 Cursor 界面
远程服务器：运行项目、终端和远程扩展
因此，本地已经登录并不代表远程扩展也能直接读取同一份认证状态；本地终端能够联网，也不代表远程扩展进程继承了相同的网络配置。
本文记录一套适用于 Windows 本地端和 Linux 远程端的排查方法。
本文只讨论正常的远程开发、认证同步和组织授权网络环境配置。远程服务器如不具备合规的服务访问条件，应联系服务器或网络管理员处理。
1. 先确认 Codex 扩展运行在哪一端
在 Cursor 通过 Remote SSH 打开服务器目录后，扩展可能有两种运行位置：
- Local：运行在本地电脑。
- SSH: <远程主机>：运行在远程服务器。
在扩展页面找到 Codex，确认它是否显示：
Installed in SSH: <远程主机>
如果显示：
Install in SSH: <远程主机>
说明当前只安装了本地版本，需要为远程主机安装扩展。
远程 Codex 扩展通常会从远程用户目录读取配置：
~/.codex/
因此，后续检查都应在 Cursor 的远程终端中执行。
2. 检查本地认证文件
在 Windows PowerShell 中执行：
Test-Path "$env:USERPROFILE\\.codex\\auth.json"
返回：
True
说明本地存在 Codex 认证文件。
文件通常位于：
C:\\Users\\<Windows用户名>\\.codex\\auth.json
auth.json 属于敏感认证信息：
- 不要上传到 Git 仓库。
- 不要粘贴到博客、论坛或聊天记录中。
- 不要复制给其他用户。
- 仅同步到自己控制且可信的服务器账户。
3. 将认证文件同步到远程 Linux
下面假设 SSH Host 别名为：
dev-server
先创建远程目录：
ssh dev-server "mkdir -p ~/.codex && chmod 700 ~/.codex"
复制认证文件：
scp "$env:USERPROFILE\\.codex\\auth.json" "dev-server:~/.codex/auth.json"
设置权限：
ssh dev-server "chmod 600 ~/.codex/auth.json"
检查文件所有者和权限：
ssh dev-server 'stat -c "%U %a %n" ~/.codex/auth.json'
正常输出类似：
developer 600 /home/developer/.codex/auth.json
需要重点确认三点：
常见错误是使用普通用户连接服务器，却把文件放到了：
/root/.codex/auth.json
远程扩展以普通用户运行时，无法读取 root 用户目录中的认证文件。
4. 检查远程服务器的网络环境
远程 Codex 扩展由 Linux 服务器发起请求，因此服务器必须具备组织允许的网络访问条件。
如果服务器需要通过单位、实验室或企业提供的 HTTP 代理访问外部服务，可以配置标准代理环境变量。
下面使用占位地址：
http://proxy.example.internal:8080
临时配置：
export HTTP_PROXY=http://proxy.example.internal:8080
export HTTPS_PROXY=http://proxy.example.internal:8080
export http_proxy=http://proxy.example.internal:8080
export https_proxy=http://proxy.example.internal:8080
export NO_PROXY=127.0.0.1,localhost
export no_proxy=127.0.0.1,localhost
检查：
env | grep -i proxy
如果服务器没有合规的网络出口，不建议通过个人工具绕行。应联系管理员配置服务器允许使用的网络出口或代理服务。
5. 为什么终端能联网，扩展仍然失败
一个常见现象是：
env | grep -i proxy
在 Cursor 终端中能够看到代理变量，但 Codex 扩展依然无法连接。
原因是：
集成终端和远程 Extension Host 不是同一个进程。
在终端中手动执行 export，只会修改当前 Shell 及其子进程，不会自动修改已经启动的 Cursor Server 和扩展进程。
因此，需要让代理变量在远程服务启动前就存在。
6. 将环境变量写入登录配置
不同 Linux 环境读取的启动文件可能不同，常见文件包括：
~/.bashrc
~/.profile
~/.bash_profile
可以先检查：
ls -la ~/.bashrc ~/.profile ~/.bash_profile 2>/dev/null
如果远程服务通过登录 Shell 启动，通常应检查：
~/.profile
或：
~/.bash_profile
示例配置：
# Organization-approved proxy for remote development
export HTTP_PROXY=http://proxy.example.internal:8080
export HTTPS_PROXY=http://proxy.example.internal:8080
export http_proxy=http://proxy.example.internal:8080
export https_proxy=http://proxy.example.internal:8080
export NO_PROXY=127.0.0.1,localhost
export no_proxy=127.0.0.1,localhost
修改后，在当前终端加载：
source ~/.profile
或者根据实际文件执行：
source ~/.bashrc
但要注意：当前终端加载成功，并不代表旧的 Cursor Server 已经更新。后面仍需重启远程服务。
7. 配置 Cursor Remote Settings
在已经连接服务器的 Cursor 窗口中按：
Ctrl + Shift + P
打开：
Preferences: Open Remote Settings (JSON)
确认编辑的是：
Remote [SSH: dev-server]
而不是本地 User Settings。
如果组织提供 HTTP 代理，可以配置：
{
"http.proxy": "http://proxy.example.internal:8080",
"http.proxySupport": "override",
"http.proxyStrictSSL": true
}
如果文件中已经存在其他设置，应合并到同一个 JSON 对象中。
8. 检查本地设置是否覆盖远程设置
Cursor 本地 User Settings 通常位于：
C:\\Users\\<Windows用户名>\\AppData\\Roaming\\Cursor\\User\\settings.json
可以在 PowerShell 中搜索代理相关配置：
Get-ChildItem "$env:APPDATA\\Cursor\\User" `
–Recurse –File –Filter *.json `
–ErrorAction SilentlyContinue |
Select-String –Pattern 'http\\.proxy|proxySupport'
重点检查 settings.json。
如果本地 User Settings 中设置了一个仅本地可访问的代理地址，而远程扩展又继承了这个配置，远程 Linux 会把 127.0.0.1 理解为服务器自身，进而连接失败。
因此：
- 本地专用地址只应配置在本地环境。
- 远程扩展应使用服务器能够实际访问的地址。
- 不要在本地和远程配置中混用不同作用域的 127.0.0.1。
9. 重启 Cursor Remote Server
认证文件和环境变量修改完成后，需要重启远程 Cursor Server。
在 Cursor 中按：
Ctrl + Shift + P
执行：
Remote-SSH: Kill Cursor Server on Host
部分版本中可能显示：
Remote-SSH: Kill VS Code Server on Host
选择对应的远程主机，然后：
如果仍然存在旧进程，可以完全退出本地 Cursor 后重新启动。
Windows PowerShell：
Get-Process Cursor –ErrorAction SilentlyContinue |
Stop-Process –Force
10. 检查远程 Codex 进程的环境变量
重新连接服务器并打开 Codex 后，可以检查相关进程：
pgrep -af 'extensionHost|codex|cursor'
进一步查看当前用户进程继承的代理变量：
for pid in $(pgrep -u "$USER" -f 'extensionHost|codex'); do
echo "===== PID $pid ====="
ps -p "$pid" -o pid,ppid,args –no-headers
tr '\\0' '\\n' < "/proc/$pid/environ" 2>/dev/null |
grep -iE '^(HTTP_PROXY|HTTPS_PROXY|http_proxy|https_proxy)='
done
需要确认：
- 大写和小写代理变量指向同一个地址。
- 地址是远程服务器能够实际访问的。
- 不存在本地电脑专用的回环地址或端口。
11. 常见错误
11.1 本地已经登录，远程仍显示未登录
检查：
echo "$HOME"
whoami
stat -c "%U %a %n" ~/.codex/auth.json
常见原因：
- auth.json 放错用户目录。
- 文件所有者不正确。
- 文件权限过宽或不可读。
- 本地认证已经更新，但服务器仍保留旧文件。
11.2 终端正常，Codex 扩展请求失败
常见原因：
- 代理只在当前终端中临时设置。
- Cursor Server 启动时没有继承环境变量。
- 修改配置后没有重启远程服务。
- Local Settings 和 Remote Settings 存在冲突。
11.3 请求中途断开
如果扩展提示连接或流式响应中断，可以依次检查：
env | grep -i proxy
pgrep -af 'extensionHost|codex'
然后确认：
- 服务器网络出口稳定。
- 代理是组织授权且支持长连接的服务。
- 远程扩展进程继承了正确环境变量。
- 旧的 Cursor Server 已经重启。
11.4 auth.json 权限不正确
执行：
chmod 700 ~/.codex
chmod 600 ~/.codex/auth.json
chown "$USER":"$(id -gn)" ~/.codex/auth.json
12. 一份简化的排查顺序
遇到问题时，可以按以下顺序检查：
13. 总结
Remote SSH 场景下，排查 Codex 扩展问题时，应始终把本地环境和远程环境分开考虑。
可以将问题归纳为三层：
认证层：远程用户目录中是否存在有效 auth.json
网络层：远程服务器是否具备合规、稳定的服务访问条件
进程层：Cursor Server 和 Codex 进程是否继承了正确环境变量
只在本地登录、只修改当前终端环境，或者只修改 Cursor 设置中的某一层，往往都不能完整解决问题。
按照“认证文件 → 远程网络 → Remote Settings → 重启远程服务 → 检查进程环境”的顺序排查，通常能够较快定位问题。
