★ FEATURED ARTICLE 最近帮一个同事排查问题场景很典型SSH 连远程服务器一切正常密码和密钥都过了服务器上的服务也跑得没问题。结果他想在这台远程服务器上用 codex 登录命令敲下去终端直接甩了一个 403 错误。更让人头大的是日志里还冒出一句 “cc switch local proxy failed while handling codex endpoint /responses”。当时我们两个对着屏幕看了半天第一反应是“SSH 权限出问题了”但仔细一想SSH 都连上了跟登录 codex 有什么关系这篇文章就把这次排查的完整过程写下来。如果你也在远程服务器上跑 codex遇到登录 403或者日志里出现类似 local proxy 的报错这篇文章应该能帮你省掉不少弯路。我会把每一步的排查思路、命令、背后原理都讲清楚包括一些文档里不会写的细节。整个排查思路不只适用于 codex任何通过 SSH 远程操作客户端登录第三方服务时报 403都可以参考。1. 先分清403 到底是 SSH 给的还是 codex 对端给的1.1 一个典型的报错现场先还原一下现场。同事的机器是一台 Linux 服务器他用 SSH 登录后执行codex login没过几秒输出类似这样的内容Error: 403 Forbidden Provider: codex Endpoint: /responses cc switch local proxy failed while handling codex endpoint /responses. provider...第一眼看到这个报错很容易把注意力放在 SSH 上因为标题里同时出现了 SSH、codex、403 三个关键词。但这里有个非常重要的判断SSH 连接成功说明 SSH 层的认证是没问题的。403 是 HTTP 状态码是 codex 客户端发请求之后服务端或者中间代理/网关返回的响应。也就是说这个 403 基本不可能是 SSH 服务本身给的除非你连的是一个奇怪的堡垒机在 Shell 层面给你返回 HTTP 状态码。我们当时做了一件事先看 codex 的详细日志。codex 在 Linux 上通常会把日志写到~/.codex/logs/目录下你可以直接打开最近一个日志文件或者用tail -f边执行边看tail -f ~/.codex/logs/*.log日志里除了上面那句 local proxy 之外还会记录完整的请求 URL、请求头、响应状态码和响应体。很多时候真正的错误原因藏在响应体里而不是状态码本身。比如响应体里写了invalid_api_key那就是 key 的问题如果写了ip_not_allowed那就是出口 IP 被限制如果写了request_time_too_skewed那就是服务器时间不对。所以遇到 403第一件事不是改配置而是翻日志看响应体。1.2 403 与 401 的区别以及响应体的价值这里要顺手科普一下 401 和 403 的区别很多人会混。401 Unauthorized服务器没认出你是谁常见于没带 token、token 格式错误、token 过期。403 Forbidden服务器认出你了或者至少收到了你的请求但拒绝你执行这个操作。可能是权限不足也可能是 IP 被拒、地域被拒、组织被禁用、请求被防火墙策略拦截后网关统一回 403。但在实际排查中很多服务因为安全考虑会把 401 和 403 混着用甚至统一返回 403所以不要死抠状态码语义。关键是响应头里的WWW-Authenticate、响应体里的error字段、以及请求头里的Authorization是否真实传递。我在那次排查里做了一件事直接curl请求同样的端点观察返回内容。下面这一步非常关键它能帮我们把“SSH 问题”和“codex 应用问题”彻底分开。2. 第一轮排查从 SSH 到 codex 的网络链路2.1 确认 SSH 链路本身没有问题虽然已经 SSH 连上了但仍要确认一下这台服务器的出网能力。因为 codex 在远程服务器上运行时请求是从“服务器”发出去的不是从你本地电脑发出去的。这一点很多人会忽略本地能登录 codex不代表服务器能登录 codex。先确认 SSH 层的基本状态ssh -vvv your_useryour_server如果能看到debug1: Authentication succeeded说明 SSH 没问题。另外检查一下服务器上的/etc/ssh/sshd_config里有没有奇怪的限制比如AllowUsers把你限制在某个 IP 段不过这通常不会导致 codex 403只是顺手排除。真正的重点在于codex 需要访问自己的后端服务而这些访问往往走 HTTPS 443 端口。如果服务器只开了 22 端口出站 443 被防火墙或安全组拦截codex 就会报连接类错误但如果网关是统一返回 403 的那就会伪装成权限错误。所以第一步要验证服务器能不能正常访问 HTTPS。2.2 在远程服务器上直接测试 codex 的 API 端点用 curl 直接打一下 codex 的认证或对话端点。注意不同版本的 codex 端点略有差异但总体都是 HTTPS 请求。你可以先抓日志里的完整 URL然后用curl -i原样复制curl -i -X POST https://your-codex-endpoint/responses \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/json \ -d {message: ping}这里的-i会显示响应头-v可以看更详细的握手信息。如果 curl 能正常返回 JSON哪怕返回的是业务错误也说明 443 出网没问题如果 curl 直接返回 403或者连接超时那就要继续查网络。那次我们遇到的情况很典型本机 curl 直接返回 403响应体里写着blocked by gateway。这就说明根本还没到 codex 真正的服务端而是被中间的某个代理网关拦了。顺着这个线索我们很快就发现服务器的环境变量里被人设置了一个HTTPS_PROXY指向一个已经失效的内部代理地址。codex 客户端会读取这个环境变量把请求都转发给那个代理代理转发失败后直接回了 403。给读者的建议在远程服务器上执行下面的命令看看有没有代理环境变量残留env | grep -i proxy比如http_proxy、https_proxy、HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、all_proxy。如果有先不要急着删可以临时把代理清掉再测试unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy codex login如果清了代理之后能正常登录那就说明 403 确实是代理导致的。这里要说明一下我讲的都是正常的 HTTP(S) 代理场景比如公司内网出口代理、调试用的本地代理工具而不是任何特殊用途的工具。在企业开发环境里代理配置错误是 403 的高发原因。2.3 服务器时间不同步会让认证“偶然”失败有次排查另一个服务时发现一个特别隐蔽的问题服务器时间比真实时间慢了大概 8 分钟。很多 token 签发和校验是与时间绑定的客户端发起请求时带上过期时间戳服务端校验时发现偏差超过宽容窗口就会拒绝请求。有些服务返回 401有些服务统一返回 403甚至还会在日志里写一段类似 time skew 的提示。所以遇到 403 先顺手看一眼服务器时间date -u如果偏差明显用 chrony 或 ntp 同步一下sudo systemctl status chronyd sudo chronyc makestep同步之后再跑 codex 登录有时问题就莫名其妙消失了。时间偏差导致的认证失败往往只在你执行登录的那一刻出现平时 SSH 操作没影响所以特别容易忽略。3. codex 登录态与配置为什么服务端会返回 4033.1 登录态存在哪里token 过期即 403把网络层的问题排掉之后就该看 codex 自己的登录态了。codex 的登录态一般保存在用户目录下常见路径是~/.codex/auth.json或~/.codex/config.toml。里面存的是 API Key、Access Token、组织 ID 之类的信息。如果你在远程服务器上安装 codex 之后从没登录过那 auth 文件可能压根不存在。这时候直接执行codex login会走一个交互式流程。问题在于很多远程服务器是没有桌面浏览器的codex 的默认登录方式需要你在本地浏览器里打开一个授权链接输完 code 之后再回到终端。如果这个流程被跳过或者授权链接已经被使用过服务端会拒绝请求返回 403。检查方式cat ~/.codex/auth.json如果文件存在看一下expires_at或 token 创建时间。如果 token 已经过期服务端在验证 JWT 签名时就会拒绝返回 403。很多工具在 token 过期后并不会给一句“token expired”而是直接给一个笼统的 403这一点非常误导人。顺便说一句如果你在远程服务器上使用sudo执行了 codex 登录然后又以普通用户身份登录可能会出现“配置在 root 名下但你用的是普通用户”的诡异现象。排查时记得确认当前用户是谁whoami echo $HOME登录态文件必须放在当前用户的$HOME/.codex下否则客户端找不到正确的 token。3.2 服务端风控与 IP、设备标识被拒还有一种 403纯粹是服务端风控在起作用。codex 这类 AI 编程工具的后端通常有比较严格的风控策略比如数据中心 IP 段可能被列入高风险名单、某个 IP 在短时间内请求频率过高、或者组织管理员限制了某些成员的访问权限。如果你是在一台云服务器上首次登录 codex而之前从来没有在该 IP 段成功登录过服务端可能把这个请求当成异常登录直接返回 403。这时候服务端响应体里通常会给出提示类似denied by risk control或device not trusted。你需要做的不是反复重试而是先确认当前服务器的出口 IPcurl -4 -s https://ifconfig.me或者curl -4 -s https://ipinfo.io/ip拿到 IP 之后再看看是否在 codex 服务端支持的区域或组织允许列表里。如果你所在网络环境本身有访问限制请走企业合法的出口代理而不是在服务器上挂任何非常规工具。我在这里不展开说因为这不是技术重点而且容易踩合规红线。3.3 日志里的 local proxy 到底在说什么回到文章标题里提到的那个日志cc switch local proxy failed while handling codex endpoint /responses。这句话看着吓人其实拆开就三块cc是 codex 客户端内部某个组件的代号不用深究。local proxy指的是 codex 运行时配置的本地代理地址通常是某种调试代理或者请求转发组件。failed while handling codex endpoint /responses表示它在处理/responses这个请求时切换代理失败了。换句话说codex 客户端把请求发到了一个“本地代理”但这个代理没有正常工作导致连接失败或返回 403。排查思路很直接找配置里有没有base_url、proxy_url、local_proxy之类的字段。常见位置cat ~/.codex/config.toml如果配置文件里有类似[api] base_url http://127.0.0.1:5090/v1而这个 5090 端口本地根本没有服务监听那所有请求都会失败。我们用ss -lntp看一下端口ss -lntp | grep 5090没有输出就说明本地代理没有起来。要么注释掉这行配置要么启动对应的代理服务。我们在排查时发现同事之前为了调试某个特性手动改过 config.toml把请求指向了本地 5090 端口后来忘了改回来。这就是“cc switch local proxy failed”的直接原因。如果你在配置里看到类似host 5090 hostname 10.11.225.193 user user identityfile ...这样的内容也别急着奇怪那可能是 SSH config 里的逗号分隔写法被解析成了别的字段但本质上不会导致 codex 403。遇到花里胡哨的配置先备份再清理比反复对比要快得多。我当时的做法是cp ~/.codex/config.toml ~/.codex/config.toml.bak然后把疑似代理相关的一行注释掉重新登录问题解决。4. 在远程无头服务器上正确使用 codex 登录4.1 浏览器 OAuth 在 SSH 里行不通改用设备码或 API Key远程服务器没有图形界面这是很多 codex 登录问题的根源。codex 默认的登录方式之一是在本地浏览器完成授权但你在 SSH 终端里执行codex login时它可能只会输出一段 URL要求你复制到浏览器打开然后输入一个一次性代码。如果在服务器终端里没法弹出浏览器或者你根本没有本地浏览器就很容易卡住。更稳妥的方式是用支持“无头”登录的方式来认证。不同版本的 codex 参数略有差别但通常有一个--headless标志codex login --headless或者直接使用 API Keyexport OPENAI_API_KEYsk-xxxx codex login注意环境变量的方式只对当前会话有效如果你重开一个 SSH 会话环境变量会丢失。建议写进~/.bashrc或~/.zshrc但要注意别把密钥提交到 Git 仓库里。我自己喜欢用的是配置文件形式比如在~/.codex/auth.json里写清楚 key然后把它设置成 600 权限chmod 600 ~/.codex/auth.json chmod 700 ~/.codex这个细节虽然简单但真的能挡住 90% 因为权限过大导致的“配置无法读取”问题。很多工具为了安全性会拒绝读取权限过大的密钥文件如果读不到 token自然就会 403。4.2 配置 API Key 的正确姿势与环境变量清理有些朋友在服务器上配置了 API Key但还是 403为什么最常见的原因是环境变量名写错或者配置里包含了多余的空格和引号。比如你写export OPENAI_API_KEYsk-xxxx这个没问题。但如果你写成export OPENAI_API_KEY sk-xxxxshell 会直接把整个字符串当成命令执行自然也不行。更隐蔽的是配置base_url时写错了协议比如把https://写成了http://或者地址末尾多了一个/v1导致请求路径变成了/v1/v1/responses服务端找不到对应资源可能返回 403。如果你不确定就开 debug 日志看实际请求的 URLRUST_LOGdebug codex login或者你用的版本支持--verbose也一并打开。我见过最离奇的一次是配置文件里用了 Windows 风格的路径比如C:\Users\yx\.ssh\id_rsa在 Linux 服务器上直接解析失败最终导致认证相关配置读取异常。虽然看起来是 SSH 密钥问题实际上影响的是 codex 的配置加载流程。后来我把路径统一改成绝对路径问题就没了。4.3 配置文件权限、目录归属这类“看不见”的问题用 root 还是普通用户登录对 codex 的影响很大。假设你用root登录并执行了codex login然后在另一个会话里用dev用户登录并尝试 codex它会去读/home/dev/.codex/auth.json。如果这个文件不存在就相当于没有 token403 就来了。反过来如果你用dev用户登录却用了sudo codex logintoken 会写到/root/.codex/auth.jsondev用户的 codex 客户端同样读不到。排查时可以用一条命令看当前用户下是否有配置ls -la ~/.codex/重点关注属主和权限stat -c %U %G %a %n ~/.codex/auth.json正常的配置应该是当前用户拥有权限 600 或 400。如果出现 root 所有但你以普通用户运行那就重新以普通用户登录一次或者把文件拷贝过来并改属主sudo chown -R dev:dev /home/dev/.codex这个细节几乎不会出现在官方文档里但在实际运维中非常常见。当时我们排查了很久最后发现是同事用sudo -i登录过把一堆配置写到了 root 目录后来切回普通用户自然就 403 了。4.4 防火墙、安全组与出站代理的核对最后一个隐蔽点云服务器的安全组。很多公司为了安全会限制服务器对公网的出站访问只允许 80/443 等少数端口。如果只允许 22 端口而你在服务器上跑 codex请求发不出去会被网关拦截返回 403。这种问题用 curl 测一下就知道。另外如果 codex 的客户端配置里指定了组织 ID而你的 API Key 不属于该组织服务端也会返回 403。检查一下当前登录的组织codex whoami如果显示的组织和你的 Key 不对应那就要在登录时手动指定组织参数或者在网页端把 Key 加到对应组织下。否则无论换什么网络403 都会稳定复现。5. 疑难杂症速查表与我的几点实战经验5.1 问题现象、原因与处理方式速查表整理一份速查表方便以后遇到 403 时按图索骥。现象可能原因快速排查与处理SSH 正常codex login 返回 403token 过期检查~/.codex/auth.json中的有效期重新登录日志里出现 local proxy failed配置了本地代理但端口未监听检查 config.toml 的 base_url注释掉或启动对应服务curl 直接 403响应体有 blocked by gateway环境变量代理指向失效代理env | grep -i proxy临时 unset 后重试服务器时间偏差大JWT 时间戳校验失败date -u确认用 chronyc 同步用 sudo 登录后普通用户无法使用token 写错目录ls -la ~/.codex/改属主或用普通用户重新登录浏览器 OAuth 在无头环境卡住没有浏览器完成授权用--headless或配置 API Key请求 URL 是http://base_url 协议错误改成https://始终返回“organization not allowed”Key 不属于当前组织换 Key 或在组织下添加该 KeyIP 被风控拒绝数据中心 IP 被列入风险名单走企业合法出口代理或更换对外 IP这张表不是万能的但覆盖了我在 SSH codex 场景里见过的大部分 403。核心思想就一句话403 不是错误终点而是入口后面一定还有更具体的响应信息。5.2 几个我亲手踩过的坑第一个坑把日志级别默认关了。codex 默认日志输出很克制遇到 403 你不一定能看到背后的响应体。后来我养成习惯在任何登录报错场景下先把环境变量设成 debugexport CODEX_LOG_LEVELdebug codex login这样能看到请求头、响应头、代理配置等完整信息。很多官方文档不会教你这个但比瞎猜快得多。第二个坑改配置时不备份。我那次把 config.toml 里的 base_url 注释掉之后虽然解决了 403但顺手把之前设置的模型参数也删了导致 codex 后端模型找不到。后来所有配置文件改动我都先备份成.bak再慢慢改。第三个坑在服务器上测试时用了sudo把问题弄复杂了。建议能不用 sudo 就不用 sudocodex 配置放在普通用户目录里不要纠缠于 root 和普通用户的权限关系。第四个坑过于相信“本机能用服务器也能用”。服务器和本地电脑的网络环境、环境变量、DNS 解析、防火墙规则完全不同。凡是遇到 403我都会先curl -v在服务器上打一次原始请求看它到底到不到服务端。5.3 最小化复现步骤留着下次用最后分享一下我的标准排查顺序你直接照做就行# 1. 确认当前用户和目录 whoami echo $HOME # 2. 检查时间偏差 date -u # 3. 检查代理环境变量 env | grep -i proxy # 4. 检查 codex 配置和日志 ls -la ~/.codex/ tail -n 200 ~/.codex/logs/*.log # 5. 清理代理环境变量后重试 unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy codex login --headless如果这一步后还是 403接着用 curl 打原始端点拿到响应体再回到速查表对应原因。这个流程我基本不跳步因为少一步都有可能误判。我在实际排查中体会最深的一点是403 是一个极其“懒惰”的错误码服务端不想暴露太多内部信息中间代理也懒得做透传最后呈现给你的就是一个干巴巴的 403。但只要你把它当作一次网络链路和认证状态的总检查从 SSH 链路、代理环境变量、时间同步、登录态文件、服务端 IP 风控一路排查下来大多数问题都能在十分钟内定位。最后再分享一个小技巧如果你修改了 codex 配置之后还是 403可以试试完全退出进程再重新登录因为 codex 的某些配置读取是一次性的不会实时刷新。我在远程服务器上排查时经常是改完配置忘了重开终端然后浪费五分钟反复看同一个错误。先重启会话再谈其他往往会有惊喜。
阅读完成 · 觉得有帮助？
