把模型地址改成本机代理后，客户端仍能打开，模型菜单里也出现了新名字，但发送请求却失败。此时问题可能在客户端配置、本地代理、上游账号或协议转换中的任何一层。只换一个模型重试，很难知道哪一层出了问题。
OpenCodex 是第三方开源项目，主要提供本地代理、提供商接入和路由管理，不能把它与 OpenAI 官方产品混为一谈。本文依据 2026 年 9 月 23 日的项目文档，解释如何检查这条请求链路。文中的命令是文档核对后的检查入口；本次没有连接个人账号执行安装、授权或模型调用，因此不宣称任何提供商组合已经实测兼容。
先画出请求到底经过哪里
最简单的部署包含三个位置：你使用的客户端、本机运行的 OpenCodex，以及最终处理请求的提供商。客户端把请求发给代理，代理按配置选择目标并处理协议差异，上游返回后，再把结果传回客户端。项目仓库提供功能说明和当前文档入口。
“在本地运行”只描述代理的位置。如果上游是远程模型，发出的提示、工具结果和相关上下文仍然会离开本机。只有选用本地模型并核对其他依赖后，才有理由进一步讨论本地处理范围。不能仅凭地址栏里出现 127.0.0.1，就判断数据始终留在电脑上。
不同客户端和提供商也未必使用同一种协议。接入文档写支持某种客户端，表示项目为它安排了适配路径，并不意味着所有工具调用、图像、流式事件和上下文恢复都完全等价。普通文本问答成功以后，还需要测试你实际依赖的功能。
一个适合初次检查的任务是：让客户端读取测试目录里一份不含敏感信息的短文件，再回答其中的字段值。保留工具调用与结果，可以同时检查文本往返和工具消息。如果一开始就用复杂代码仓库，错误日志容易被大量上下文淹没，也会把尚未验证的通道用于真实项目资料。
初始化会改配置，先保存原来的入口
按当前安装说明，npm 安装路径要求 Node.js 18 及以上，并由已发布包安排运行所需的 Bun；源码开发另有要求，不能把两种安装方式混在一起。项目还提供其他分发形式，应选择一种可追踪版本的路径使用。
安装前保存客户端现有配置，并记录原先怎样启动。ocx init 是交互初始化，会写入 OpenCodex 配置并接入 Codex，还可能提供按需启动的 shim 选项。它不是一个只读检查命令。若机器上已经存在工作中的客户端，应该先理解这些改动，再决定是否启用自动启动方式。
项目默认状态目录与客户端目录各有用途。排查时记录实际生效位置，不要看到两个目录就随意删除其中一个。服务由不同用户启动、终端设置了不同环境变量，或者同时存在多个安装来源，都可能让你修改的文件与进程读取的文件不一致。
启动代理使用 ocx start，默认端口为 10100。当前文档说明，首选端口已占用时，启动会停止并指出占用者，而不是悄悄寻找另一个端口。碰到这种错误，应先确认是否已经有一个代理实例在运行，再决定停止旧实例或显式选择新端口。新端口也必须与客户端配置保持一致。
进程活着、配置就绪与模型能用分开检查
当前项目提供几个容易混淆的状态入口：ocx status 用于查看运行状态，ocx health 检查即时存活，ocx ready 检查同步之后的就绪状态。诊断时应从前往后查，避免把进程存在当成模型可用。
例如代理已经监听端口，但配置同步还未完成，存活检查可能正常，就绪检查仍未通过。项目文档说明 /readyz 在 ready 时返回 200，pending 或 failed 时返回 503；命令行可以用 ocx ready --wait --timeout 60 等待一段限定时间。这段等待只是就绪检查，不能替代向目标模型发送请求。
如果就绪失败，先保留状态与日志，再查配置格式、同步结果和启动参数。如果就绪成功而调用失败，则继续查提供商授权、模型标识和上游响应。旧代理版本未实现相关接口时，也要结合版本说明解释结果，别把接口不存在误判为账号失效。
上游返回 401、403 或 429 时，要分别考虑身份验证、访问权限与限流或配额。具体含义仍以对应提供商响应为准。修改请求地址通常不会修复失效凭据，也不会自动增加账号额度。排障记录里保留经过脱敏的状态码和错误类型即可，不需要复制完整令牌。
模型菜单不是实际路由的证据
OpenCodex 支持提供商与模型路由，也允许设置组合模型。使用者需要区分客户端提交的名称、代理解析后的目标，以及上游实际返回的模型信息。菜单中的名字可以是别名；只截图菜单，无法证明请求最终交给了哪个提供商。
按模型路由文档，可以使用提供商与模型的组合标识。具体名称应从你的配置和提供商当前列表确认，不要照抄文章中不存在于账号里的型号。尤其是模型标识本身带斜杠时，项目还有相应的别名处理规则，排查应对照当前版本。
组合模型则需要阅读Combos 说明。故障转移和加权轮转解决的问题不同：前者关注某个目标失败后如何继续，后者关注请求怎样分配。选择策略时，应把成本、能力差异和失败条件一起考虑，不能只按菜单里是否有“自动”选项决定。
先用普通文本测试确认目的地，再加入一次工具调用，然后测试第二轮是否能正确引用第一轮结果。切换提供商后，如果历史工具消息的格式或标识不被接受，就可能出现第一问正常、追问失败的情况。此时需要检查协议与会话兼容，反复清空缓存未必能解决。
账号亲和性也有条件。当前项目说明，新会话可以依据额度选择账号，已有会话通常尽量保持原账号，但失效恢复、账号排除、亲和性过期或配额重新评估等情形可能重新绑定。不要据此承诺一段会话永远只使用同一账号；有审计要求时，应保留实际路由记录。
远程部署要同时管理数据通道和控制入口
本机使用通常不需要把端口开放到公网。当前默认绑定在回环地址，远程暴露需要显式配置和认证。把主机绑定改成 0.0.0.0，仅仅改变了监听范围，不能代替 TLS、访问限制与凭据管理。
若确实需要多设备访问，可以参考项目的Remote Hub 指南。先区分客户端调用的数据通道与修改配置的管理入口，再安排哪些设备可以访问、使用什么凭据，以及凭据撤销后怎样确认访问失效。日志中若保存了请求内容，备份和查看权限也应一并考虑。
准备放在独立服务器上时，资源需求取决于并发、日志保存和是否同时运行本地模型。单纯转发远程接口与在服务器上加载大模型，配置需求差别很大；下面的服务器入口可作为选型时的一个参考，具体地区、价格和可用资源应以购买页面为准。
第一次上线远程代理时，使用权限受限的测试凭据和无敏感任务完成验收。确认认证、路由和日志符合预期后，再接入需要的客户端。本文没有对上述服务商做性能对比，也没有据此为任何模型通道背书。
退出代理也要确认客户端恢复
临时试用结束，可以按文档使用 ocx stop 停止并恢复原生 Codex 入口。若此前安装了后台服务或 shim，还要按对应管理命令处理；只关闭一个终端窗口，未必会停止后台进程。完整卸载则应按当前卸载说明执行，避免手工删掉仍需恢复的状态。
恢复之后重新打开客户端，检查请求是否还指向本地端口，再执行一个无敏感内容的测试。配置文件看起来恢复了，但旧进程可能仍持有先前的配置；因此文件检查与新会话验证都应保留。
日常维护最好记录安装版本、配置备份、启动方式和一组最小验收任务。升级后先复测纯文本、工具往返和连续对话，再恢复自动路由。遇到问题时，这些材料可以帮助判断是客户端升级、代理改动还是上游接口变化，减少在几个设置页面之间盲目切换的时间。