Codex WebFetch 403 排查指南：四层链路定位与解决

1. 先别急着改配置：403 到底卡在哪一层

Codex 的 WebFetch 报 403，是这两年被问得最多的一类问题。很多人一看到 403 就开始翻配置文件、换模型、重装 CLI，折腾一整天还是红的。问题出在哪？出在大家把 403 当成一个"错误"，而不是当成一个"信号"。403 是服务端明确告诉你"我收到了你的请求，但我不打算给你这个资源"，它和 404（找不到）、401（没认证）、429（限流）是完全不同的语义。你只有先定位这个 403 是从哪一层返回的，才知道该动哪块。

我先把结论摆出来：Codex 的 WebFetch 403，绝大多数情况下不是 Codex 本身的问题，而是请求链路上某一层被拦了。这条链路大致是这样的——Codex CLI 或 IDE 插件发起请求，经过本地配置的 endpoint，可能经过一层本地代理或转发，再到达目标服务，目标服务再决定放不放行。403 可能出现在这条链路的任何一个环节，而每个环节的排查手段完全不同。

所以这篇东西的核心思路就一句话：分层定位，逐层排除。我会把这条链路拆成四层来讲，每层告诉你 403 长什么样、怎么确认、怎么处理。这套方法我在实际排查里用过很多次，比盲目改配置高效得多。

适合谁看？如果你正在用 Codex 的 WebFetch 或 web_search 功能，遇到了 403，或者你正在配置 Codex 接入某个自定义 endpoint，这篇文章基本能覆盖你 90% 的场景。哪怕你是刚装完 Codex 的新手，跟着分层思路走一遍，也能自己判断问题出在哪。

2. 把请求链路拆开看：四层结构决定排查方向

2.1 为什么必须分层，而不是直接改配置

我见过太多人一遇到 403 就去改config.toml，改完重启，还是 403，然后开始怀疑人生。这种做法的根本问题是：你不知道 403 是谁返回的，改配置就是在赌。赌对了是运气，赌错了浪费时间，更糟的是你可能把本来正常的配置改坏了，引入新的问题。

分层排查的价值在于，它把"一个 403"变成了"四个可能的位置"，每个位置有独立的验证方法。你只要按顺序验证，就能快速收敛到真正的问题点。这就像家里跳闸，你不会一上来就把所有电器都换掉，而是先看是总闸跳了还是分闸跳了，再定位到具体回路。

2.2 四层链路的具体划分

我把 Codex WebFetch 的请求链路分成这四层，从内到外：

层级	位置	典型 403 特征	排查手段
第一层	Codex 本地配置与鉴权	请求根本没发出去，或发出即被拒	看 CLI 日志、检查 token 状态
第二层	本地转发/代理层	转发进程报错，endpoint 返回 403	检查转发服务日志、端口连通性
第三层	目标服务入口	服务端明确拒绝，返回结构化 403	用 curl 直接打目标地址
第四层	目标资源本身	资源级权限不足，路径或方法不对	换路径、换方法验证

这个划分不是绝对的，不同人的环境会有差异，但大方向是一致的。下面我逐层展开。

2.3 一个容易被忽略的前提：先确认 403 的来源标识

在动手之前，先做一件事：把 403 的完整响应体抓下来。很多人只看状态码，不看响应体，这是大忌。403 的响应体里往往藏着关键信息——是哪个服务返回的、拒绝原因是什么、有没有 request id。

如果你用的是 Codex CLI，可以在启动时加上详细日志参数，把请求和响应都打出来。如果响应体里出现了类似token endpoint returned status 403这样的字样，那基本可以确定问题在鉴权环节，而不是资源权限。如果响应体是目标服务自己的错误格式，那问题就在目标服务那一侧。

提示：抓响应体的时候注意别把敏感信息（比如 token、密钥）贴到公开地方。自己看就行。

3. 第一层：Codex 本地配置与鉴权，最常见的 403 源头

3.1 鉴权失败为什么表现为 403 而不是 401

这是很多人困惑的点。按 HTTP 语义，没认证应该是 401，认证了但没权限才是 403。但现实里很多服务在 token 无效、过期、格式不对的时候，直接返回 403。原因很简单：有些服务不想暴露"你这个 token 存在但无效"这个信息，统一用 403 糊弄过去，避免被探测。

所以当你看到 403，第一件要确认的事是：你的鉴权凭证到底有没有被正确带上、有没有过期、格式对不对。这一步确认不了，后面全是白费。

3.2 检查 token 状态的实操步骤

我一般按这个顺序查：

1. 确认配置文件里 token 字段的拼写和位置。Codex 的配置对字段名很敏感，一个字母错了它可能不报错，但请求就是带不上凭证。
2. 确认 token 有没有过期。很多 token 是有有效期的，尤其是通过某种交换流程拿到的短期凭证。
3. 确认 token 的作用域（scope）是否覆盖了 WebFetch 需要的权限。有些 token 只能做基础对话，不能调 WebFetch。
4. 用最小请求验证 token 本身是否有效，比如打一个最简单的接口，看返回是 200 还是 403。

这里有个细节：如果你是通过某种 token 交换流程拿凭证的，交换本身可能就失败了。响应里如果出现token exchange failed这类字样，说明你连凭证都没拿到，后面自然全 403。这种情况下要往回查交换流程的配置，而不是查 WebFetch。

3.3 配置字段的常见坑

Codex 的配置里，有几个字段特别容易出问题：

• endpoint 地址末尾多了或少了一个斜杠，导致请求路径拼接错误，打到不存在的路径上，有些服务会返回 403 而不是 404。
• 模型名称写错。响应里如果出现model is not supported之类的提示，说明你请求的模型在当前 endpoint 下不可用，有些服务会用 403 表达这个意思。
• 配置里有多余的、不被识别的字段。Codex 有时会提示ignoring unrecognized configuration setting，虽然它说"忽略"，但某些情况下这些多余字段会干扰请求构造。

注意：改配置之前先备份。我吃过亏，改坏了一次配置，原来的备份又被覆盖了，只能从头配。

3.4 鉴权层的排查清单

把这一层的排查整理成清单，方便你对照：

• [ ] token 字段拼写正确、位置正确
• [ ] token 未过期
• [ ] token 作用域覆盖 WebFetch
• [ ] token 交换流程（如果有）成功
• [ ] endpoint 地址格式正确，无多余斜杠
• [ ] 模型名称正确且被 endpoint 支持
• [ ] 配置中无干扰性的多余字段

这一层能解决掉相当一部分 403。如果这一层全部确认无误，还是 403，那就往下走。

4. 第二层：本地转发与代理层，最隐蔽的 403 来源

4.1 转发层为什么会引入 403

很多人为了让 Codex 接入某个服务，会在本地跑一个转发进程，把 Codex 的请求转成目标服务能接受的格式。这个转发进程本身可能出问题，导致 403。典型场景是：转发进程启动失败、端口没监听、转发规则配错、或者转发进程自己需要鉴权但没配。

响应里如果出现local proxy failed while handling codex endpoint这类字样，基本可以锁定问题在转发层。这时候你改 Codex 的配置是没用的，因为请求压根没到目标服务，是转发进程自己挂了。

4.2 确认转发层是否正常工作的步骤

1. 确认转发进程在运行。用系统工具看进程列表，或者看它有没有输出启动成功的日志。
2. 确认端口在监听。用netstat或lsof看转发进程配置的端口有没有被监听。
3. 直接打转发进程的端口，看它返回什么。如果返回 403，说明转发进程自己拒绝了请求。
4. 看转发进程的日志。这是最关键的一步，转发进程的日志会告诉你它为什么拒绝。

我遇到过一种情况：转发进程启动了，端口也在监听，但它的转发规则里目标地址配错了，导致它把请求转到了一个不存在的地址，目标返回 403，转发进程原样透传。这种情况下，光看 Codex 这边是看不出来的，必须看转发进程的日志。

4.3 转发层的常见配置错误

转发层的配置错误集中在几个地方：

• 目标地址写错，包括协议、域名、端口、路径。
• 请求头没有正确透传，尤其是鉴权头。有些转发进程默认会过滤掉某些头，导致目标服务收不到凭证，返回 403。
• 请求方法被改写。比如原本是 POST 被改成了 GET，目标服务不认，返回 403。
• 转发进程自己的鉴权没配。有些转发进程要求调用方带一个本地密钥，没带就 403。

这些错误的共同点是：它们都不在 Codex 的配置里，而在转发进程的配置里。所以排查的时候一定要把转发层单独拎出来看。

4.4 转发层排查的实操心得

我的经验是，转发层的问题最好用"绕过法"定位。具体做法是：先不用 Codex，直接用 curl 打转发进程的端口，模拟 Codex 的请求。如果 curl 也 403，那问题就在转发层或更外层；如果 curl 正常，那问题就在 Codex 到转发进程这一段。

这个绕过法能快速把问题范围缩小一半。我每次遇到转发相关的 403，第一步就是 curl 一下，屡试不爽。

提示：curl 的时候把请求头、请求方法、请求体都尽量模拟成 Codex 的真实请求，否则测出来的结果不准。

5. 第三层：目标服务入口，403 最"名正言顺"的地方

5.1 目标服务返回 403 的几种典型原因

如果前两层都排除了，403 就是目标服务返回的。目标服务返回 403 的原因很多，常见的有：

• 请求来源不被允许。有些服务对请求来源有要求，来源不符就 403。
• 请求频率超限。有些服务把限流也用 403 表达。
• 请求的资源需要更高权限。你的凭证有效，但权限不够。
• 请求的路径或方法不对。服务端认为你不该访问这个路径。
• 服务端有额外的校验，比如某个特定的请求头缺失。

响应体里如果出现country这类字样，说明服务端在做来源校验，这时候你要检查的是请求的来源标识，而不是 Codex 的配置。

5.2 用 curl 直接验证目标服务

这一步是分层排查里最关键的一步。用 curl 直接打目标服务的地址，带上和 Codex 一样的请求头和请求体，看返回什么。

curl -v -X POST "https://目标服务地址/路径" \ -H "Authorization: Bearer 你的token" \ -H "Content-Type: application/json" \ -d '{"你的请求体"}'

-v参数会把完整的请求和响应都打出来，包括请求头、响应头、状态码。这样你能看到到底哪个环节出了问题。

如果 curl 返回 200，说明目标服务本身没问题，问题在 Codex 到目标服务这一段（也就是第一层或第二层）。如果 curl 也返回 403，说明问题在目标服务这一侧，你要检查的是请求本身是否符合目标服务的要求。

5.3 目标服务 403 的应对策略

确认是目标服务的 403 之后，处理方向就明确了：

• 如果是来源校验，检查你的请求来源标识是否符合要求。
• 如果是限流，降低请求频率，或者申请更高的配额。
• 如果是权限不足，检查你的凭证作用域，或者申请更高权限。
• 如果是路径或方法不对，对照目标服务的文档，修正请求。
• 如果是缺少特定请求头，补上。

这里要强调一点：目标服务的 403 往往不是 Codex 能"修"的，而是你的请求本身不符合目标服务的要求。这时候改 Codex 配置没用，要改的是请求本身，或者你的账号权限。

5.4 一个真实的排查案例

我之前遇到过一个 403，响应体里有一串很长的错误信息，大意是请求的模型在当前条件下不被支持。我一开始以为是 Codex 配置的模型名写错了，改了好几次都没用。后来用 curl 直接打目标服务，发现是目标服务对某个模型有额外的限制条件，需要满足特定条件才能调用。这个信息在 Codex 的报错里是看不到的，只有直接打目标服务才能看到。

这个案例说明：Codex 的报错信息往往是经过包装的，不一定完整。要拿到最原始的信息，必须绕过 Codex，直接打目标服务。

6. 第四层：资源级权限，最容易被误判的 403

6.1 资源级 403 和入口级 403 的区别

入口级 403 是"你连门都进不去"，资源级 403 是"你进了门，但这个房间不让你进"。两者的区别在于：入口级 403 通常和鉴权、来源、限流有关，资源级 403 通常和具体资源的权限有关。

区分方法很简单：如果你打目标服务的基础接口是 200，打具体资源接口是 403，那就是资源级 403。如果打基础接口就 403，那是入口级 403。

6.2 资源级 403 的常见场景

资源级 403 常见于这几种场景：

• 你请求的路径需要特定权限，而你的凭证没有。
• 你请求的方法（GET/POST/PUT/DELETE）不被该资源支持。
• 你请求的资源属于其他账号，你没有访问权。
• 资源有额外的访问条件，比如需要特定的请求头或参数。

WebFetch 这个功能本身，在很多服务里是需要单独授权的。如果你的凭证只有基础对话权限，没有 WebFetch 权限，那调用 WebFetch 就会 403。这种情况下，你要做的是申请 WebFetch 权限，而不是改配置。

6.3 验证资源级权限的方法

验证资源级权限，我一般用"对比法"：

1. 先用凭证打一个确定有权限的接口，确认凭证本身有效。
2. 再用同一个凭证打目标资源接口，看是否 403。
3. 如果第一步 200、第二步 403，那就是资源级权限问题。
4. 如果第一步就 403，那是凭证本身的问题，回到第一层排查。

这个方法能快速区分"凭证问题"和"权限问题"，避免在错误的方向上浪费时间。

6.4 资源级 403 的处理思路

资源级 403 的处理，核心是"补权限"或"改请求"：

• 如果是权限不足，去申请对应权限。
• 如果是方法不对，改成正确的方法。
• 如果是资源不属于你，换成你有权限的资源。
• 如果是缺少参数或请求头，补上。

这里有个经验：很多服务的权限体系是分层的，基础权限和高级权限是分开的。WebFetch 往往属于高级权限，需要单独开通。如果你是新账号，很可能默认没有这个权限，需要手动申请。

7. 常见问题速查表与避坑经验

7.1 403 问题速查表

把常见的 403 场景和对应处理整理成表，方便你快速对照：

现象	可能层级	排查方向	处理方式
请求根本没发出	第一层	看 CLI 日志	检查配置、token
token exchange failed	第一层	看交换流程	修正交换配置
local proxy failed	第二层	看转发日志	修正转发配置
端口无监听	第二层	看进程和端口	重启转发进程
curl 直接打也 403	第三层	看响应体	修正请求或申请权限
基础接口 200 资源接口 403	第四层	对比法	申请资源权限
响应体含 country 字样	第三层	看来源校验	检查来源标识
模型不支持	第一层或第三层	看模型名	换支持的模型

7.2 我踩过的坑

第一个坑：只看状态码不看响应体。早期我排查 403，只看状态码，结果绕了很多弯路。后来养成习惯，每次都把响应体完整打出来，效率提升一大截。

第二个坑：改配置不备份。有一次改配置改坏了，原来的配置又没备份，只能从头配。从那以后我改任何配置前都先复制一份。

第三个坑：忽略转发层。有段时间我一直以为是 Codex 的问题，查了半天没结果，最后发现是本地转发进程挂了。转发层是最隐蔽的一层，因为它夹在中间，两边的日志都不一定完整。

第四个坑：把限流当权限问题。有些服务限流返回 403，我一开始以为是权限不够，去申请权限，结果发现是请求太频繁。后来学会看响应体里的限流提示，才不再误判。

7.3 提高排查效率的几个技巧

• 每次排查前先抓完整响应体，这是最重要的习惯。
• 用 curl 绕过 Codex 直接打目标服务，快速定位问题层级。
• 转发层单独看日志，不要只看 Codex 的日志。
• 改配置前备份，改完记录改了什么，方便回滚。
• 遇到不确定的，先用最小请求验证，不要一上来就改一堆配置。

提示：排查的时候把每一步的结果记下来，形成自己的排查记录。下次遇到类似问题，直接对照记录，效率会高很多。

8. 从 403 排查延伸出去的几个实用思路

8.1 把 403 当成配置健康检查

其实 403 排查的过程，本质上是一次配置健康检查。你按四层走一遍，等于把 Codex 的配置、转发层的配置、目标服务的请求、资源权限都检查了一遍。这个过程本身就有价值，能帮你发现一些平时没注意到的配置问题。

我现在养成了一个习惯：每次配置完 Codex，主动用 curl 打一遍目标服务，确认链路通畅。这样在真正用的时候，就不会突然遇到 403 手忙脚乱。

8.2 建立自己的排查模板

排查多了之后，我把这套流程固化成了一个模板：

1. 抓完整响应体，确认 403 来源。
2. 检查第一层：配置、token、模型名。
3. 检查第二层：转发进程、端口、转发规则。
4. 用 curl 打目标服务，确认第三层。
5. 用对比法确认第四层。
6. 根据结果处理，记录过程。

这个模板我用了很久，基本能覆盖绝大多数 403 场景。你也可以根据自己的环境调整，形成自己的模板。

8.3 关于 Codex 配置的一点个人体会

Codex 的配置体系比较灵活，灵活的另一面就是容易配错。我的体会是：配置尽量简单，不要加不必要的字段。每多一个字段，就多一个出错的可能。尤其是那些"看起来有用但实际用不上"的字段，能不加就不加。

另外，Codex 的版本更新比较频繁，配置格式偶尔会变。升级之后如果突然 403，先检查配置格式有没有变化，再看其他层。这个顺序能帮你快速定位是不是版本升级引入的问题。

最后分享一个小技巧：如果你不确定某个配置字段的作用，先注释掉它，看请求是否正常。如果注释掉之后正常了，说明这个字段就是问题所在。这个方法比逐个试错高效得多。