在使用 Codex 进行多节点部署或分布式计算时，子代理（Sub-agent）无法建立连接是常见且令人头疼的问题。这通常意味着主节点与子节点之间的通信链路断裂，导致任务无法下发或状态无法回传。面对这一故障，我们需要从网络环境、配置参数以及服务状态三个维度进行系统性排查，以快速恢复系统正常运行。
检查网络连通性与防火墙设置
绝大多数连接失败的原因源于基础的网络障碍。首先，请确认运行子代理的服务器是否处于开机状态，并检查其 IP 地址是否正确无误。其次，重点排查防火墙规则。许多云服务商默认开启了严格的入站和出站限制，若未开放 Codex 指定的通信端口（如 8080、9090 等，具体取决于版本配置），数据包将被直接丢弃。建议临时关闭防火墙进行测试，或添加相应的放行规则，确保主节点能 ping 通子节点，且 TCP 握手能够成功建立。
验证配置文件与认证凭证
如果网络层面一切正常，问题可能出在软件配置上。请仔细核对子代理启动时的配置文件（通常为 config.yaml 或 .env 文件）。检查主节点的 API 地址、端口号以及密钥（Token/Key）是否与主节点生成的完全一致。特别注意，复制粘贴时容易引入不可见的空格或换行符，这将导致认证失败。此外，确认子代理的版本是否与主节点兼容，不同大版本间的协议差异也可能导致握手拒绝。
查看日志定位深层错误
当上述步骤均无效时，深入分析日志文件是解决问题的关键。进入子代理的工作目录，查看 stdout 或 stderr 输出的详细报错信息。常见的错误代码如 ECONNREFUSED 表示目标端口未监听，TIMEOUT 表示网络延迟过高或中间路由阻断。根据具体的错误堆栈，可以进一步判断是 DNS 解析失败、SSL 证书过期还是资源耗尽。通过精准定位日志中的异常点，往往能迅速找到被忽视的配置漏洞或服务依赖缺失问题，从而彻底修复连接障碍。