Codex的workspace-write沙箱里gh pr view连不上api.github.com，GitHub任务降级成泛泛的“no internet”而不是给出“沙箱网络拒绝/DNS/TLS/认证”的精确分类，当一个网络问题需要用户自己去猜是哪一层被拦住，Agent“能连GitHub”这件事到底还能不能让人放心？

1. 问题的提出：一句 “no internet” 掩盖了什么

先还原现场。在 Codex 的 workspace-write 沙箱模式下，工作区可写、但网络访问受策略约束。此时执行 gh pr view 1234，命令失败，返回的却是一句高度泛化的 “no internet” 类提示。问题不在于“失败”本身——沙箱默认限制出网，失败是预期行为；问题在于失败的语义被压缩了：用户无法从错误信息判断，究竟是沙箱策略层主动拒绝、DNS 解析未命中、TLS 握手被中间设备打断，还是 GitHub Token 缺失导致的 401/403。

这四类原因在工程上的处置方式完全不同：策略拒绝要改沙箱配置或申请白名单；DNS 失败要检查解析器与 hosts；TLS 失败要排查证书链、SNI、企业代理的 TLS 拦截；认证失败则要补 Token 或调整权限范围。当它们被统一折叠成 “no internet”，用户被迫进入猜测—试错—再猜测的循环，而这恰恰是 Agent 工具最不该制造的成本。

本文的核心判断是：一个 Agent 是否“能连 GitHub”，不应由一次成功调用来证明，而应由它在失败时能否给出可判定的归因来证明。成功路径是窄的，失败路径才是安全性与可运维性的主战场。下文把这一性质称为“网络失败可归因性”，并以此为主线展开。

2. 背景与概念界定：沙箱、workspace-write 与失败可归因性

2.1 沙箱不是“虚拟机”，而是策略集合

现代编码 Agent 的沙箱通常不是完整虚拟化，而是能力约束（capability restriction）的组合：文件系统挂载范围、进程权限、系统调用过滤（如 seccomp）、以及网络命名空间与出站规则。workspace-write 这一命名的语义重心在“写”，但它同时隐含了对“读”和“连”的边界设定。换言之，写权限的放宽与网络权限的收紧往往是同一份策略文件的两面，这一点在排障时极易被忽略。

从实现角度看，出站限制常见有三种粒度：其一，网络命名空间隔离，容器内无默认路由，表现为 ENETUNREACH；其二，iptables/nftables 规则丢弃，表现为连接超时或 ECONNREFUSED；其三，应用层代理强制，所有流量必须经指定代理，未经代理的连接被静默丢弃。三种粒度对上层错误信息的影响截然不同，这正是后文“失真机制”的物理基础。

2.2 失败可归因性的定义

本文给出一个可操作的定义：失败可归因性（failure attributability）指系统在失败时输出的诊断信息，足以将故障定位到预先定义的、互斥且可处置的类别集合中的某一类。它包含三个要件：类别集合是有限且枚举化的；类别之间近似互斥（允许少量复合情形但需标注）；每个类别对应明确的处置动作。

本文评述：这一概念与分布式系统里的“可观测性三支柱”（日志、指标、追踪）并不等同。可观测性关注“能否看到”，可归因性关注“看到之后能否判定责任层”。一个系统可以日志极其丰富却依然不可归因——如果日志里全是 connection failed 而没有 errno 与阶段标记。因此，可归因性是一个比“日志完备”更严格、也更贴近运维实际的指标。

2.3 为什么 Agent 场景放大了这个问题

人类工程师遇到 “no internet”，会本能地依次执行 getent hosts、curl -v、openssl s_client，用经验补足缺失的语义。Agent 不具备这种“默认怀疑链”，它倾向于接受给定错误文本并据此决策。若错误文本说“没有网络”，Agent 可能选择放弃任务、改写方案、甚至尝试绕过限制——错误信息的粒度直接塑造了 Agent 的行为边界。这不是修辞，而是可被观察到的行为差异：粗粒度错误倾向于诱发“放弃或越权”，细粒度错误倾向于诱发“定向修复”。

3. 五层拒绝面模型：从 DNS 到应用层认证

为把“连不上”拆开，本文提出五层拒绝面模型（Five-Layer Denial Surface, FLDS）。它按请求生命周期自下而上分层，每层都有独立的失败模式与可观测信号。该模型不是对 OSI 七层的复述，而是按“谁能拒绝、拒绝后留下什么痕迹”重新聚类，目的是让诊断动作与错误类别一一对应。

3.1 L1：策略层的“静默丢弃”最致命

L1 的拒绝往往不产生任何 ICMP 或 RST 回包，而是直接丢弃。对上层而言，这与“网络真的断了”在现象上不可区分。这是可归因性最薄弱的一环：策略拒绝与物理断网共享同一个症状。要区分二者，唯一可靠的办法是在沙箱内主动探测默认路由与网关可达性，而非依赖应用层错误。

3.2 L2：DNS 是“半静默”层

DNS 失败通常有明确返回码（NXDOMAIN/SERVFAIL），但若解析请求本身被策略丢弃，则表现为解析超时，与 L1 混淆。实践中常见一种复合情形：api.github.com 可解析但连接被拒，此时错误会落在 L3 而非 L2，容易被误判为“DNS 没问题所以网络没问题”。

3.3 L3/L4：代理与 TLS 拦截的叠加

企业环境中，出站流量常被强制经代理并做 TLS 检查（TLS interception）。此时客户端看到的证书由企业 CA 签发，若沙箱镜像未预置该 CA，就会在 L4 失败。值得注意的是，L4 失败在部分客户端库中会被笼统报为“网络错误”，因为库层把 TLS 异常归入了传输异常大类。这是错误降级的一个典型技术来源。

3.4 L5：认证失败最不该被误判为网络问题

若前四层全通，GitHub API 仍可能返回 401/403。这类失败有明确的 HTTP 状态码，理论上最易归因。但一旦上层把“非 2xx”统一包装成“请求失败”，L5 的语义也会丢失。本文评述：把认证失败说成“没有网络”，是五层模型中最严重的一类误归因，因为它会引导用户去修网络，而真正该修的是凭据。

4. 为什么错误会被“降级”：错误传播链的失真机制

从内核 errno 到用户可见的 “no internet”，错误语义至少经过四次转译，每一次都可能丢失信息。理解这条链路，是设计修复方案的前提。

内核 errno (ENETUNREACH / ECONNREFUSED / ETIMEDOUT)
   ↓  libc / 系统调用封装
传输层库异常 (connect failed / handshake failed)
   ↓  HTTP 客户端库（如 Go net/http、Python requests）
统一异常类型 (ConnectionError / RequestException)
   ↓  CLI 工具（gh）的错误包装
泛化消息 ("no internet" / "network error")
   ↓  Agent 运行时
最终呈现给用户的单句提示

失真机制可归纳为三类：类型擦除（不同 errno 映射到同一异常类）、上下文剥离（丢弃目标主机、端口、阶段标记）、语义上推（把传输层问题概括为“网络不可用”）。三者叠加，就得到了一句看似合理、实则不可处置的提示。

本文评述：这种降级并非纯粹的工程疏忽，它有“用户体验”层面的动机——对普通用户，一句“没有网络”比 “x509: certificate signed by unknown authority” 更友好。但 Agent 场景的读者不是普通用户，而是需要据此决策的自动化系统。面向人的友好性与面向 Agent 的可归因性，在这里构成了真实的设计张力，正确的解法不是二选一，而是分层输出：面向人给摘要，面向 Agent 给结构化错误码。

5. 可操作路径：分层诊断协议与最小复现步骤

下面给出一套可在沙箱内直接执行的诊断协议。原则是自下而上、逐层证伪：每一层用一个最小命令确认“该层是否通”，一旦某层失败即停止，避免跨层误判。

5.1 步骤一：确认 L1 路由与命名空间

# 查看默认路由是否存在
ip route show default
# 查看网卡与地址
ip -brief addr
# 直接探测网关（若存在）
ping -c 1 -W 2 $(ip route show default | awk '{print $3}')

判据：无默认路由 → 判定为 L1 策略拒绝；有路由但网关不可达 → 可能是策略丢弃，记录为 L1 疑似。注意 ping 可能因 ICMP 被禁而误报，故仅作辅助证据，主证据是路由表。

5.2 步骤二：确认 L2 DNS

getent hosts api.github.com
# 或
nslookup api.github.com 2>&1 | head -20
# 检查解析配置
cat /etc/resolv.conf

判据：返回 IP → L2 通过；NXDOMAIN → 域名或解析策略问题；超时 → 解析请求被丢弃，记为 L2 疑似策略拒绝。建议同时记录返回的 IP 段，便于后续判断是否被解析到内网黑洞地址。

5.3 步骤三：确认 L3 TCP 可达

# 443 端口连通性（不涉及 TLS）
timeout 5 bash -c 'cat < /dev/null > /dev/tcp/api.github.com/443' && echo TCP_OK || echo TCP_FAIL
# 若配置了代理，检查代理变量
env | grep -iE 'https?_proxy|no_proxy'

判据：TCP_OK → L3 通过；TCP_FAIL 且 DNS 正常 → 判定为 L3 拒绝（防火墙/代理未配置）。这一步是区分“DNS 问题”与“连接问题”的关键分水岭，务必单独执行。

5.4 步骤四：确认 L4 TLS

openssl s_client -connect api.github.com:443 -servername api.github.com -brief < /dev/null
# 关注输出中的 Verify return code 与证书签发者

判据：Verify return code: 0 (ok) → L4 通过；非 0 → 证书链问题，重点看签发者是否为企业 CA。若握手直接超时，则可能是 TLS 拦截设备丢弃了非预期 SNI。

5.5 步骤五：确认 L5 认证与 API 语义

# 先看是否带凭据
gh auth status
# 用 curl 直接打 API，观察 HTTP 状态码
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

判据：200 → 全链路通；401/403 → L5 认证/权限问题；若 curl 能通而 gh 不通，则问题在 CLI 自身的配置（如 GH_HOST、代理变量继承），而非网络层。

工程建议：把上述五步封装为一个 net-diag 脚本，在 Agent 首次网络失败时自动运行，并把结果以结构化 JSON 写入日志。这样即使上层仍只显示 “no internet”，也能在日志侧保留可归因证据。这是“在不改上游的前提下提升可归因性”的最低成本路径。

6. 错误分类模型：把“连不上”拆成可判定的枚举

基于 FLDS，本文定义一个面向 Agent 的错误分类枚举。设计目标是：每个类别可由上文的诊断步骤唯一确定，且对应一个处置动作。该枚举可作为 Agent 运行时与工具之间的契约。

本文评述：这个枚举的价值不在于“多”，而在于每个码都能被一条命令证伪。任何无法被诊断步骤唯一确定的类别，都应被合并或拆分，直到满足“可判定”要求。这与软件测试里的“可复现性”是同一类工程纪律：不可复现的 bug 不算 bug，不可判定的错误码不算错误码。

7. 关键数据与案例：公开 issue、规范与实测口径

7.1 公开讨论中的共性模式

在 GitHub CLI 与各类容器化开发环境的公开 issue 中，反复出现同一类报告：容器内 gh 命令失败但错误信息不指向具体层。这类 issue 的典型讨论路径是：报告者先怀疑网络，维护者要求提供 GH_DEBUG=api 输出，最终定位到代理变量未继承、CA 缺失或 Token 未注入。本文不引用具体 issue 编号以免时效性失真，但这一“先怀疑网络、后定位配置”的模式具有跨项目的一致性，可作为经验证据。

需要说明的是，本文未对 Codex 沙箱做受控实测，上述分层判据基于通用网络栈行为与公开文档推导，属于方法学层面的可验证推理，而非对特定版本的实测结论。读者应以自身环境的诊断输出为准。

7.2 规范层面的支撑

IETF 的 HTTP 语义规范（RFC 9110）明确区分了 4xx 客户端错误与 5xx 服务端错误，这为 L5 的归因提供了标准依据；DNS 相关 RFC 定义了 NXDOMAIN 与 SERVFAIL 的语义差异，支撑 L2 的判定；TLS 1.3（RFC 8446）对握手失败原因有明确分类，支撑 L4。换言之，可归因性并非要发明新标准，而是要求实现层不要丢弃标准已经给出的区分。这是本文的一个关键论点：问题多出在“转译”而非“协议”。

7.3 一个可复用的观测口径

建议在 Agent 运行时记录如下字段，作为可归因性的度量口径：失败阶段（L1–L5）、原始 errno/异常类、目标主机与端口、是否经代理、HTTP 状态码（若有）、诊断脚本输出摘要。这套口径不依赖特定实现，可用于横向比较不同沙箱产品的错误信息质量。本文评述：把“错误信息质量”变成可度量指标，是推动工具改进的前提；否则它永远停留在“体验问题”的模糊地带。

8. 对比与局限：可归因性的代价与边界条件

8.1 三种错误信息策略的对比

8.2 边界条件

分层结构化并非万能。其一，复合失败（如 DNS 通但代理拒绝且证书异常）难以归入单一类别，需要允许“主因+次因”的复合表达。其二，安全边界：过度暴露内部网络拓扑（如具体网关地址、内部 CA 名称）可能带来信息泄露风险，需在诊断详细度与安全之间取平衡。其三，版本漂移：错误码枚举需随上游库升级维护，否则会退化为“历史遗留字段”。

本文评述：这些局限说明，可归因性应作为渐进增强而非硬性门槛来推进——先保证“至少能区分策略拒绝与认证失败”这一最小可用集，再逐步细化。一步到位地追求全枚举，反而会因维护成本过高而半途而废。

9. Agent 网络能力验收清单

把前文结论落成可执行的验收项。建议在引入任何“能联网的编码 Agent”时逐条核对，每项都应有明确的通过判据。

这八项构成一个最小可信基线。本文评述：“能连 GitHub”是一个功能陈述，“能解释为什么连不上”才是一个可信度陈述。前者可以用一次演示证明，后者只能通过失败场景的系统性覆盖来证明。对 Agent 这类会被赋予自主决策权的系统，后者才是真正的门槛。

10. 结论与展望：从“能连”到“可解释地连”

回到最初的问题：当网络问题需要用户自己去猜是哪一层被拦住，Agent “能连 GitHub”这件事还能不能让人放心？本文的答案是：不能，至少不能仅凭“能连”就放心。因为沙箱的价值恰恰在于它会拒绝，而拒绝的可解释性决定了用户能否安全地把更多任务交给它。一个在失败时只会说 “no internet” 的 Agent，把归因成本转嫁给了用户，也把误判风险留在了系统内部。

可操作的改进路径已经清晰：以 FLDS 五层模型组织诊断，以可判定枚举定义错误码，以八项清单做验收，以结构化日志保留证据。这些都不需要推翻现有架构，而是在错误传播链的每个转译点“少丢一点信息”。工程上，这往往比新增功能更能提升系统可信度。

展望未来，随着 Agent 获得更多自主权，网络失败可归因性有望从“体验优化”上升为“安全属性”：一个无法解释自身失败原因的系统，不应被授予绕过限制的权限。本文评述：把可归因性纳入 Agent 的能力评估体系，是比单纯追求“连通率”更稳健的方向。连通率衡量的是顺境，可归因性衡量的是逆境——而逆境，才是信任真正被检验的地方。

11. 参考文献与拓展资源

11.1 主要参考文献（8 篇）

1. Fielding R., Nottingham M., Reschke J. HTTP Semantics. RFC 9110, IETF, 2022.
2. Rescorla E. The Transport Layer Security (TLS) Protocol Version 1.3. RFC 8446, IETF, 2018.
3. Mockapetris P. Domain Names — Implementation and Specification. RFC 1035, IETF, 1987.
4. GitHub. GitHub CLI Manual: gh pr view / gh auth status / Environment Variables. GitHub Docs, 2024–2025.
5. OpenAI. Codex / Sandboxing and Network Access Documentation. 2025.
6. OWASP. OWASP Top 10 for Large Language Model Applications. 2025 版.
7. NIST. SP 800-190: Application Container Security Guide. 2017（持续更新引用）。
8. Beyer B., Jones C., Petoff J., Murphy N.R. Site Reliability Engineering. O'Reilly, 2016.

11.2 拓展资源（教程与视频）

• GitHub CLI 官方手册——命令与环境变量权威说明。
• GitHub REST API 文档——状态码与限流语义。
• RFC 9110 原文——HTTP 语义规范。
• OpenSSL 文档——s_client 用法与证书校验。
• TLS 握手可视化讲解（视频检索）——理解 L4 失败机理。
• 容器网络排障教程（视频检索）——L1/L3 实践。

11.3 数据与口径说明

本文未使用自建数据集或受控实验数据。文中涉及的网络分层判据来自公开 RFC 与厂商文档；错误分类枚举为本文基于通用网络栈行为提出的方法学构造，属模拟/整合性框架，非实测统计结果。若读者据此开展实测，建议记录失败阶段、原始 errno、HTTP 状态码三项核心字段，并注明采集环境版本，以便复现。