`codex --remote` 适合把终端客户端连接到另一个正在运行的 App Server，但它与普通 HTTP API 地址不是一回事。连接失败时，最常见的原因不是模型不可用，而是把 `https://` 地址当成 WebSocket、服务只监听本机、端口没有开放，或认证令牌没有从指定环境变量读取。排查时要先证明远端 App Server 可达，再检查协议与令牌，最后才看会话和模型配置。

一、理解 --remote 连接的对象

远程模式连接的是 Codex App Server 端点，用来复用远端会话和执行环境。它不是 OpenAI API 的 Base URL，也不是随便一个兼容接口。把模型网关地址填给 `--remote`，即使域名和证书都正常，也会因为协议和消息格式不匹配而失败。

当前远程地址可以使用 `ws://`、`wss://`，在支持的系统上也可以使用 Unix socket。`ws` 是未加密 WebSocket，`wss` 是通过 TLS 加密的 WebSocket。跨机器或跨网络使用时应优先选择 `wss`，不要让认证信息和会话数据在不受控网络中明文传输。

二、先确认服务器是否真的在监听

到 App Server 所在机器查看进程和监听端口，确认服务没有启动后立即退出。很多“远程连接超时”其实是服务只绑定了 `127.0.0.1`，本机可以访问，其他电脑却无法连接。如果需要局域网访问，应按部署要求绑定合适接口，同时用防火墙限制来源地址。

端口开放不代表应用协议正确。用端口检测只能证明 TCP 可达，不能证明 WebSocket 握手和 App Server 消息正常。服务器日志中如果完全看不到连接请求，应检查地址、路由、防火墙和代理；能看到握手却马上断开，则继续看路径、TLS 或认证。

三、ws、wss 和反向代理怎么选

本机实验可以使用 `ws://127.0.0.1:端口`。远程访问建议由可信反向代理提供 `wss`，正确转发 WebSocket 的 Upgrade 和 Connection 头，并配置有效证书。普通 HTTP 反向代理若没有启用 WebSocket 转发，浏览器访问健康页可能正常，Codex 却会在握手阶段失败。

公司网关有时会终止长连接或限制空闲时间。连接刚建立就周期性掉线，要检查代理超时、负载均衡会话保持和中间设备策略。不要只增加客户端重试次数，因为持续重连会掩盖根因，还可能产生多条不完整会话。

四、认证令牌要通过环境变量传入

需要 bearer token 的远程服务，可以用 `--remote-auth-token-env` 指定环境变量名。参数里填写的是变量名称，不是令牌内容。例如先在当前安全环境设置一个变量，再告诉 Codex 从该变量读取。这样可以避免令牌直接出现在命令历史和进程参数中。

安全限制也很重要：令牌只应发送到 `wss://` 地址，或明确属于本机范围的 `ws://` 地址。如果地址不安全，客户端拒绝发送令牌是合理保护，不应通过把密钥硬编码进 URL 来绕过。确认变量是否存在时只检查长度或是否为空，不要把完整值打印到共享终端和日志。

五、环境变量明明设置了却读不到

Windows PowerShell、命令提示符、WSL、容器和 IDE 终端拥有不同环境。你在一个窗口设置变量，另一个已打开窗口通常不会自动获得。服务由计划任务、系统服务或 CI 启动时，还要看运行账户是谁，不能假设它继承个人桌面的变量。

排查时在启动 Codex 的同一个终端检查变量是否存在，再运行远程命令。变量名区分大小写的环境中要保持完全一致。若通过脚本启动，确认脚本没有清理环境或覆盖空值。长期令牌应放进合规的密钥管理系统，并设置轮换和失效时间。

六、连接成功后仍找不到会话怎么办

远程模式支持的命令包括启动、恢复、分支以及部分会话管理操作，但并非所有本地子命令都接受 `--remote`。某个子命令直接拒绝远程参数时，先查命令是否支持，不要把它误判为服务器故障。连接成功却看不到预期会话，还要确认远端用户、数据目录和工作区是否与之前一致。

App Server 上的会话属于远端环境。客户端电脑当前目录存在同名仓库，并不会自动让远端会话指向它。恢复任务前记录远端项目路径、分支和会话标识，避免在错误仓库继续修改。远端代码状态与本地代码状态也要通过版本控制或明确同步机制对齐。

七、用最小连接逐步验证

第一步在服务器本机连接本机地址，排除服务自身问题。第二步在同一局域网使用实际地址连接，不经过公网代理。第三步启用 `wss` 和认证。第四步再加入反向代理、域名和外部网络。分层测试能迅速判断故障落在哪一段。

每一步都保存时间点和双方日志。客户端显示 timeout 时，对照服务器同一时刻是否收到连接；显示 unauthorized 时，检查令牌变量和服务器校验；TLS 报错则核对证书域名、证书链和系统时间。不要在同一轮同时更换证书、端口和令牌。

如果大家想体验一线 AI 编程模型 codex 和 claude，用它们完成远程开发、代码修改和测试审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg

八、生产使用必须补上的安全措施

不要把 App Server 直接暴露到公网并使用长期静态令牌。至少需要 TLS、来源限制、短期凭据、访问日志和令牌轮换。能够访问远端 Codex 会话，往往意味着能够间接访问代码、工具和执行环境，其风险高于普通只读网页。

还应限制远端进程可读写的目录，使用独立低权限账户，并把生产环境与开发环境隔离。令牌泄漏后要能立即吊销，日志里不要记录完整认证头。团队应明确谁能建立远程会话、谁能审批高风险命令、谁负责审计异常连接。

九、稳定性验收看什么

一次握手成功还不够。连续完成创建会话、读取项目、执行只读命令、恢复会话和正常断开，观察代理是否中途重置连接。再模拟客户端网络短暂中断，确认恢复行为不会重复执行危险操作。涉及写入时先用测试仓库，检查 diff 和日志是否完整。

最终记录可用的远程地址格式、证书更新方式、令牌变量名、服务启动账户、监听范围和故障日志位置。把这些信息做成团队检查表，远比只留一条能运行的命令可靠。远程连接的关键不是多试几个 URL，而是逐层证明 App Server、WebSocket、TLS、认证和会话环境都正确。