国内环境用 AI 编程工具，一半的坑不在代码里，在网络里：直连失败、下载超时、克隆报权限、agent 卡死。这篇把本库各档案里已经取证过的网络类坑汇总成一个清单，五类现象、每条带处置方案，出处链接直接附在条目后，点开即核对原文。

包管理器（PyPI/npm/OpenUPM）是国内用户的主要安装通道，镜像与超时问题多发生在这一层。

一、模型服务直连失败

现象：工具配置完一跑就超时，或登录卡死。原因：部分工具默认调用海外 API 端点，大陆网络无法直连。处置（出自七牛云的 Codex 配置指南）：在 config.toml 的 model_providers 里把 API 端点替换为兼容 OpenAI 协议的国内服务，切换模型只改一个 model 字段；关键限制——ChatGPT 账号登录方式不能替换端点（它仍然连官方服务器），要走国内端点必须用 API key 模式。

出处：国内如何使用 OpenAI Codex CLI：完整配置指南（七牛云）