Skip to main content

​
先说结论

第三方模型接入不是简单替换模型名称，而是改变完整请求链路：
协议、认证、路径或能力任一项不匹配，请求就可能失败。本页讲 OpenAI 兼容接口、自定义 provider、环境变量、profile、模型映射、验证和风险控制。 重要边界
  • 第三方提供商不是 OpenAI 官方服务；可用性、隐私、计费和支持由第三方决定。
  • “OpenAI 兼容”只代表接口形状相近，不代表完整实现 Responses API、工具调用、流式输出或 Codex 所需行为。
  • 模型名、base_url、支持的 API、认证方式、默认值和 CLI 行为都可能变化，必须以当前官方文档和本机结果核验。
  • 不要把真实 API key 写入仓库、项目配置、聊天记录、Issue、脚本或命令历史。

​
动态字段必须官方核验

本文中尖括号占位符和“以官方核验”为标记的内容，不是可直接照抄的固定值。

​
1. OpenAI 兼容接口

OpenAI 兼容接口通常提供类似的模型 ID、输入、消息、工具和流式字段，让已有客户端可以少改代码调用第三方服务。 兼容性至少包含三层：
  1. 传输地址：请求发送到哪个 HTTPS 主机和路径。
  2. 协议形状：使用 Responses、Chat Completions，还是供应商变体。
  3. 语义能力：是否正确实现工具调用、长上下文、结构化输出、图像输入和流式响应。

​
Responses 与 Chat Completions

Codex 当前版本对第三方 wire API 的要求可能变化，必须参考官方配置文档和本地帮助。接入前逐项确认： 普通聊天能返回文本，不等于 Codex 可以工作。Codex 还可能需要多轮上下文、文件和 shell 工具、严格参数、流式事件、失败重试和推理控制。 不要只相信供应商首页的“兼容 OpenAI”。阅读兼容性矩阵，并在隔离项目中逐层实测。

​
2. provider、base URL、API key 和 model

最小配置骨架如下。真实值必须按当前官方资料填写：

​
provider ID

自定义 ID 要在顶层和表名中保持一致，建议使用简单 ASCII 字符，避免空格和标点，不要与内置 provider 冲突。保留名称和字段名以官方 Config Reference 核验。

​
base URL

base_url 应来自提供商官方 API 文档，不要填：
  • 控制台登录页面；
  • 包含具体模型的完整请求 URL；
  • 只有浏览器能访问的网页地址；
  • 未说明路径拼接方式的根域名。
不同客户端可能自动补全路径，也可能要求填写 API 前缀。重复或遗漏 /v1、版本号和斜杠，常会造成 404 或 405。 配置前记录但不要保存秘密：
不要把带临时签名、个人标识或令牌的完整 URL 写入文件或截图。

​
API key 和 env_key

env_key 通常是环境变量的名称，不是实际密钥：
不要这样写：
正确关系是：
OAuth、组织 ID、额外 header 和其他认证方式是否可用，必须以 Codex 与提供商官方文档核验。

​
model

模型 ID 可能区分大小写、版本、区域、部署名或租户前缀。创建配置时记录：
  • 官方精确 ID；
  • 上下文和输出限制；
  • 工具调用、流式和结构化输出支持；
  • 账户权限、区域和速率限制；
  • 计费单位和下线策略。

​
3. 接入前的边界评估

先回答以下问题： 先用低风险数据测试：公开代码、虚构数据、脱敏日志和临时项目。不要直接发送：
  • API key、SSH 私钥、云凭据和 cookie；
  • .env、生产配置、数据库导出和客户数据；
  • 未公开源代码、漏洞细节和内部架构；
  • 合同、监管或公司政策限制的数据；
  • 含个人信息的日志、工单和用户输入。
接入第三方会改变数据处理方、跨境路径、日志归属、服务等级和事件响应责任，不只是改变模型。

​
4. 配置文件和 profile

用户级配置通常位于：
Windows 示例：
CODEX_HOME、项目配置加载规则和优先级可能随版本变化，以本机帮助和官方文档为准。

​
用户级配置

协议字段是否需要显式写入、可用值和默认协议必须官方核验，不要添加未经证实的字段。

​
profile

profile 适合区分官方服务、企业网关和第三方实验配置：
profile 文件命名、加载方式、合并关系和 --profile 行为属于动态字段。若本机版本支持，可使用：
参考文件骨架：
切换后用 /status 或本地可见状态确认实际模型、provider、沙箱和审批。profile 可能改变的不只是模型，还包括网络、日志、工具和权限。 项目级配置只有在项目被信任时才可能加载。涉及服务地址、认证、通知和遥测的机器级字段，可能被项目级配置忽略；禁用列表以官方 Config Reference 为准。不要让陌生仓库替换你的 provider 或端点。

​
5. 环境变量和密钥管理

当前终端临时设置： macOS/Linux：
PowerShell：
CMD：
不同 shell、IDE、任务运行器和服务账户的环境不自动共享。检查存在性但不打印值：
不要使用 printenv、set，不要把环境输出粘贴到 Issue。命令参数、调试日志、异常堆栈和进程列表也可能暴露 key。

​
轮换和撤销

出现泄露、人员或权限变化、供应商事件或异常账单时：
  1. 创建新 key 并限制权限和额度。
  2. 更新密钥管理器、环境变量和 CI。
  3. 用最小请求验证新 key。
  4. 撤销旧 key。
  5. 搜索日志和仓库，确认旧值不再出现。
  6. 检查调用记录、账单和异常地域。

​
6. 能力差异

支持矩阵以模型官方资料和实测为准。支持文本字段，不代表支持 Codex 的工具、安全行为和多轮工作流。 在隔离演示项目测试工具调用：
检查是否只读取目标文件、调用了正确工具、按需审批、正确使用结果，以及是否出现额外联网、读凭据或改配置。

​
7. 分层连通性验证

每层失败都先修复，不要直接放大权限。

​
第 0 层：版本和帮助

记录版本、参数和配置入口；动态行为以官方核验。

​
第 1 层：环境变量

只检查 key 是否存在，确认启动 Codex 的终端与设置变量的是同一环境。

​
第 2 层：配置加载

会话内执行：
核对模型、provider、沙箱和审批状态。显示字段随版本变化。

​
第 3 层：最小文本请求

第一次不要附带源代码、.env、客户数据或真实业务上下文。

​
第 4 层：受控工具调用

使用临时目录和虚构文件，测试只读任务、工具参数、审批和返回结果。

​
第 5 层：目标工作流

最后使用脱敏、可回滚的示例项目测试多文件读取、测试运行、补丁生成、连续工具调用、长响应和失败恢复。

​
HTTP 探测

仅使用提供商官方示例，不能自行猜路径和字段。下面只表达结构，动态内容必须替换并核验：
执行前确认 shell、代理和日志不会记录敏感值。HTTP 探测成功只证明网络和基础认证，不证明 Codex 工具工作流可用。

​
8. 模型映射和别名

模型映射可能发生在：

​
直接使用真实 ID

优点是可追踪，缺点是模型升级和区域迁移需要修改配置。

​
企业网关别名

网关可把稳定别名如 coding-default 映射到真实部署。必须确认：
  • 谁维护别名；
  • 是否按团队、区域或项目返回不同模型；
  • 是否保留原始模型 ID；
  • 故障时是否自动回退；
  • 回退是否改变数据去向、价格、能力或安全策略。
不要静默回退。生产配置应记录并告警，否则“请求成功”可能掩盖模型、区域和计费变化。验收记录可保留时间、profile、模型 ID、端点主机和 request ID，不要保存完整提示词或敏感响应。

​
9. 常见故障排查

​
401 或 403

常见原因：变量缺失或名称不一致、key 撤销或额度不足、模型无权限、缺少组织/租户信息、区域或网关错误。 排查顺序：
  1. 只检查变量存在性。
  2. 核对 env_key 和启动环境。
  3. 在控制台确认 key、模型权限和余额。
  4. 生成最小权限测试 key。
  5. 记录非敏感 HTTP 状态和 request ID。

​
404 或 405

常见原因：把控制台地址当成 API 地址、/v1 或版本路径重复/遗漏、协议路径未实现、方法不匹配。回到提供商官方示例确认最终 URL，不要盲目添加路径。

​
400、协议或参数错误

检查 Responses 与 Chat Completions、input/messages、工具和流式字段、推理参数，以及输入和上下文限制。先最小文本请求，再逐项增加工具、长上下文和流式能力。

​
模型不存在

模型 ID 过期、大小写错误、账号无权限、网关要求部署名，或 profile 仍指向旧配置。以模型官方列表和 /status 为准。

​
超时、断流或 429

检查网络、代理、DNS、TLS、服务状态、区域、速率和并发限制。降低请求规模；重试要有上限和退避，避免放大费用与限流。

​
聊天成功但工具失败

通常是能力或协议不完整，不是 key 问题。验证工具 schema、流式事件、并行调用、工具结果回传和多轮状态。若官方只支持基础聊天，就不要把它当完整 agent 使用。

​
profile 没生效

检查 --profile、当前 CODEX_HOME、文件命名规则、命令行覆盖、项目是否信任，以及是否把机器级 provider 字段错误写入项目配置。

​
10. 数据外发与供应商风险

即使只输入一句话，请求也可能包含：
  • 输入文本、当前文件片段和工具结果；
  • 项目路径、文件名和错误信息；
  • 工具参数、会话上下文和部分配置；
  • 插件、MCP 或网关添加的元数据。
实际发送内容取决于 Codex 版本、工具和提供商实现。没有主动复制文件，不等于没有外发。

​
供应商审查清单

​
降低外发风险

  • 使用脱敏数据、最小上下文和独立测试 key。
  • 将敏感目录排除出工作区，不要把密钥放进项目或临时目录。
  • 默认关闭网络，必须联网时只允许任务需要的域名或网关。
  • 保持按需审批，审查联网、上传、读凭据和破坏性操作。
  • 将第三方响应视为不可信内容，防止提示注入驱动本地工具。
  • 对零保留、企业隔离和区域控制保留合同与配置证据。
本地沙箱保护本机操作边界，不能替你决定第三方如何保存已经发送的数据。

​
11. 权限和提示注入边界

第三方模型不会自动继承 OpenAI 官方服务的全部安全假设。建议初始组合：
如果模型读到 README、Issue、网页或依赖中的“给 AI 的指令”，应将其视为不可信数据。模型说“请上传 .env”不构成授权。 不要在本机敏感任务中关闭所有审批或同时关闭沙箱。需要完全访问时，使用外部隔离环境，并确认容器内也没有可窃取的凭据。

​
12. 验收记录与回滚

每次接入或迁移，保留不含密钥的记录：
遇到协议异常、异常账单、数据争议或供应商事件：
  1. 停止发送真实数据并退出会话。
  2. 切回已验证的官方或只读 profile。
  3. 撤销或冻结第三方 key，清理环境和 CI。
  4. 检查调用记录、账单、日志和异常来源。
  5. 保存非敏感错误、时间和 request ID。
  6. 评估已外发数据范围和通知义务。
  7. 按组织事件响应流程处理，再决定是否恢复。
不要删除日志或重写历史来掩盖泄露；先保留证据。

​
13. 最终检查清单

配置前：
  • 已确认 Codex 版本和官方配置参考。
  • 已确认第三方 base_url、协议和模型 ID。
  • 已确认保存、训练、地域和分包商政策。
  • 已准备脱敏、可回滚测试项目。
配置时：
  • provider ID 与表名一致。
  • env_key 是变量名，不是密钥值。
  • API key 没有写入文件、命令或日志。
  • profile 和 CODEX_HOME 已按本地版本核验。
  • 沙箱、审批和网络保持最小权限。
验证时：
  • /status 显示预期 profile、模型和权限。
  • 最小文本请求成功。
  • 工具调用、流式输出和多轮任务已分别测试。
  • 没有读取或发送敏感数据。
  • 已记录非敏感版本、时间、request ID 和结果。
上线后：
  • 已设置费用、速率和异常调用监控。
  • 已准备模型下线、服务中断和 key 泄露的回滚。
  • 定期重新核验动态字段和供应商政策。
  • 发现外发或供应商异常时立即停止并轮换凭据。

​
参考与官方核验

本页根据以下本地参考资料重写：
  • 参考/codex/05-third-party-models.md
  • 参考/codex/18-config.md
  • 参考/codex/16-security.md
动态配置、模型和服务行为以以下来源为准：
  • Codex 官方 Configuration Reference；
  • Codex 官方当前模型和配置文档；
  • 提供商官方 API、模型列表、隐私政策和服务状态页；
  • 本机 codex --help、具体子命令的 --help 和 /status。
本页不承诺任何特定第三方平台、模型版本、价格、区域、默认值或长期兼容性。