> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 第三方模型接入

> 通过 OpenAI 兼容接口配置第三方模型，掌握 provider、base URL、API key、profile、模型映射、连通性验证与数据外发风险。

## 先说结论

第三方模型接入不是简单替换模型名称，而是改变完整请求链路：

```text theme={null}
Codex -> provider -> base URL -> 第三方网关 -> 模型 ID -> 响应
```

协议、认证、路径或能力任一项不匹配，请求就可能失败。本页讲 OpenAI 兼容接口、自定义 provider、环境变量、profile、模型映射、验证和风险控制。

**重要边界**

* 第三方提供商不是 OpenAI 官方服务；可用性、隐私、计费和支持由第三方决定。
* “OpenAI 兼容”只代表接口形状相近，不代表完整实现 Responses API、工具调用、流式输出或 Codex 所需行为。
* 模型名、`base_url`、支持的 API、认证方式、默认值和 CLI 行为都可能变化，必须以当前官方文档和本机结果核验。
* 不要把真实 API key 写入仓库、项目配置、聊天记录、Issue、脚本或命令历史。

## 动态字段必须官方核验

| 动态内容                          | 核验位置                                        | 核验时机              |
| ----------------------------- | ------------------------------------------- | ----------------- |
| Codex 配置键和 CLI 参数             | Codex 官方 Config Reference、本地 `codex --help` | 每次升级 Codex 后      |
| `model` 的具体值                  | 提供商官方模型列表                                   | 创建配置和换模型时         |
| `base_url`                    | 提供商官方 API 文档                                | 创建配置和迁移时          |
| Responses/Chat Completions 支持 | 提供商兼容性文档和实际响应                               | 接入前和升级后           |
| API key 变量名                   | 你的配置和启动环境                                   | 切换 shell、IDE、CI 时 |
| 默认模型、推理档位、功能                  | 官方文档、本地 `/status`                           | 运行关键任务前           |
| 价格、区域、保留期限                    | 合同、隐私政策、控制台                                 | 采购和上线前            |

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

## 1. OpenAI 兼容接口

OpenAI 兼容接口通常提供类似的模型 ID、输入、消息、工具和流式字段，让已有客户端可以少改代码调用第三方服务。

兼容性至少包含三层：

1. **传输地址**：请求发送到哪个 HTTPS 主机和路径。
2. **协议形状**：使用 Responses、Chat Completions，还是供应商变体。
3. **语义能力**：是否正确实现工具调用、长上下文、结构化输出、图像输入和流式响应。

```text theme={null}
支持 OpenAI 兼容接口
!=
完整兼容 Codex agent 工作流
```

### Responses 与 Chat Completions

Codex 当前版本对第三方 wire API 的要求可能变化，必须参考官方配置文档和本地帮助。接入前逐项确认：

| 检查项  | 要确认的问题                                    |
| ---- | ----------------------------------------- |
| 请求协议 | Codex 当前发送 Responses 还是 Chat Completions？ |
| 路径拼接 | `base_url` 后是否自动补全正确路径？                   |
| 响应字段 | 返回内容是否能被 Codex 识别？                        |
| 工具调用 | function/tool schema 和参数格式是否一致？           |
| 流式事件 | SSE 事件名、顺序和结束标志是否兼容？                      |
| 错误格式 | 401、限流、超长上下文是否给出可诊断错误？                    |

普通聊天能返回文本，不等于 Codex 可以工作。Codex 还可能需要多轮上下文、文件和 shell 工具、严格参数、流式事件、失败重试和推理控制。

不要只相信供应商首页的“兼容 OpenAI”。阅读兼容性矩阵，并在隔离项目中逐层实测。

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

| 概念         | 作用                  | 不要混淆       |
| ---------- | ------------------- | ---------- |
| `provider` | 配置中的提供商 ID，选择一组连接参数 | 不是模型名称     |
| `base_url` | API 服务基础地址          | 不是控制台网页地址  |
| API key    | 身份认证和计费凭据           | 不应写入 TOML  |
| `model`    | 提供商识别的模型 ID         | 不一定等于官方模型名 |

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

```toml theme={null}
model_provider = "my-provider"
model = "<提供商官方模型 ID>"

[model_providers.my-provider]
name = "My Provider"
base_url = "<提供商官方 API base URL>"
env_key = "MY_PROVIDER_API_KEY"
```

### provider ID

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

```toml theme={null}
model_provider = "internal-gateway"

[model_providers.internal-gateway]
name = "Internal Gateway"
```

### base URL

`base_url` 应来自提供商官方 API 文档，不要填：

* 控制台登录页面；
* 包含具体模型的完整请求 URL；
* 只有浏览器能访问的网页地址；
* 未说明路径拼接方式的根域名。

不同客户端可能自动补全路径，也可能要求填写 API 前缀。重复或遗漏 `/v1`、版本号和斜杠，常会造成 404 或 405。

配置前记录但不要保存秘密：

```text theme={null}
官方 base URL：____________________
Codex 当前协议：____________________
最终请求路径：______________________
是否必须 HTTPS：____________________
额外组织/租户头：___________________
```

不要把带临时签名、个人标识或令牌的完整 URL 写入文件或截图。

### API key 和 `env_key`

`env_key` 通常是环境变量的**名称**，不是实际密钥：

```toml theme={null}
env_key = "MY_PROVIDER_API_KEY"
```

不要这样写：

```toml theme={null}
# 错误：明文密钥进入配置
# env_key = "sk-live-real-secret"
```

正确关系是：

```text theme={null}
MY_PROVIDER_API_KEY = 真实密钥
config.toml env_key = 变量名
```

OAuth、组织 ID、额外 header 和其他认证方式是否可用，必须以 Codex 与提供商官方文档核验。

### model

模型 ID 可能区分大小写、版本、区域、部署名或租户前缀。创建配置时记录：

* 官方精确 ID；
* 上下文和输出限制；
* 工具调用、流式和结构化输出支持；
* 账户权限、区域和速率限制；
* 计费单位和下线策略。

## 3. 接入前的边界评估

先回答以下问题：

| 问题      | 需要确认                      |
| ------- | ------------------------- |
| 谁运营服务   | 公司、地区、数据中心和分包商            |
| 数据去哪里   | API 主机、日志、备份和支持渠道         |
| 是否保存请求  | 保存期限、用途、删除方式和训练政策         |
| 谁能用 key | 个人、团队、CI 和供应商人员           |
| 是否自动回退  | 回退模型、区域、价格和能力是否改变         |
| 能否关联网   | 沙箱、网络和审批能否单独控制            |
| 如何停止    | 撤销 key、删除 profile、清理缓存和日志 |

先用低风险数据测试：公开代码、虚构数据、脱敏日志和临时项目。不要直接发送：

* API key、SSH 私钥、云凭据和 cookie；
* `.env`、生产配置、数据库导出和客户数据；
* 未公开源代码、漏洞细节和内部架构；
* 合同、监管或公司政策限制的数据；
* 含个人信息的日志、工单和用户输入。

接入第三方会改变数据处理方、跨境路径、日志归属、服务等级和事件响应责任，不只是改变模型。

## 4. 配置文件和 profile

用户级配置通常位于：

```text theme={null}
~/.codex/config.toml
```

Windows 示例：

```text theme={null}
C:\Users\<用户名>\.codex\config.toml
```

`CODEX_HOME`、项目配置加载规则和优先级可能随版本变化，以本机帮助和官方文档为准。

### 用户级配置

```toml theme={null}
# ~/.codex/config.toml
model_provider = "third-party"
model = "<官方模型 ID>"

[model_providers.third-party]
name = "Third-party Provider"
base_url = "<官方 API base URL>"
env_key = "THIRD_PARTY_API_KEY"
```

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

### profile

profile 适合区分官方服务、企业网关和第三方实验配置：

```text theme={null}
official   已验证的官方服务
internal   企业网关和严格网络策略
experiment 脱敏测试项目中的第三方模型
```

profile 文件命名、加载方式、合并关系和 `--profile` 行为属于动态字段。若本机版本支持，可使用：

```bash theme={null}
codex --profile <profile-name>
```

参考文件骨架：

```toml theme={null}
# ~/.codex/<profile-name>.config.toml
model_provider = "third-party"
model = "<官方模型 ID>"

[model_providers.third-party]
name = "Third-party Provider"
base_url = "<官方 API base URL>"
env_key = "THIRD_PARTY_API_KEY"
```

切换后用 `/status` 或本地可见状态确认实际模型、provider、沙箱和审批。profile 可能改变的不只是模型，还包括网络、日志、工具和权限。

项目级配置只有在项目被信任时才可能加载。涉及服务地址、认证、通知和遥测的机器级字段，可能被项目级配置忽略；禁用列表以官方 Config Reference 为准。不要让陌生仓库替换你的 provider 或端点。

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

当前终端临时设置：

macOS/Linux：

```bash theme={null}
export THIRD_PARTY_API_KEY='<你的密钥>'
codex --profile <profile-name>
```

PowerShell：

```powershell theme={null}
$env:THIRD_PARTY_API_KEY = "<你的密钥>"
codex --profile <profile-name>
```

CMD：

```bat theme={null}
set THIRD_PARTY_API_KEY=<你的密钥>
codex --profile <profile-name>
```

不同 shell、IDE、任务运行器和服务账户的环境不自动共享。检查存在性但不打印值：

```bash theme={null}
if [ -n "$THIRD_PARTY_API_KEY" ]; then
  printf '%s\n' 'API key is set'
else
  printf '%s\n' 'API key is missing'
fi
```

不要使用 `printenv`、`set`，不要把环境输出粘贴到 Issue。命令参数、调试日志、异常堆栈和进程列表也可能暴露 key。

### 轮换和撤销

出现泄露、人员或权限变化、供应商事件或异常账单时：

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

## 6. 能力差异

| 能力    | 验证内容           | 失败影响          |
| ----- | -------------- | ------------- |
| 文本生成  | 简单请求是否稳定返回     | 只适合基础初筛       |
| 长上下文  | 多文件是否截断        | 丢上下文、错改代码     |
| 工具调用  | 合法函数名和 JSON 参数 | 无法完成 agent 任务 |
| 多轮状态  | 能否利用工具结果继续     | 中途偏航          |
| 流式输出  | 事件和结束状态是否正常    | 卡住或残缺         |
| 结构化输出 | 是否遵守 schema    | 解析和重试失败       |
| 推理控制  | 参数是否支持         | 被忽略或报错        |
| 图像输入  | 格式、大小和视觉能力     | 视觉任务不可用       |
| 代码质量  | 编译、测试和补丁质量     | 人工审查成本增加      |
| 安全拒答  | 是否拒绝明显危险请求     | 滥用与合规风险       |

支持矩阵以模型官方资料和实测为准。支持文本字段，不代表支持 Codex 的工具、安全行为和多轮工作流。

在隔离演示项目测试工具调用：

```text theme={null}
请读取当前目录中的 README.md，列出一级标题。
不要修改文件，不要联网，不要读取工作区外内容。
```

检查是否只读取目标文件、调用了正确工具、按需审批、正确使用结果，以及是否出现额外联网、读凭据或改配置。

## 7. 分层连通性验证

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

### 第 0 层：版本和帮助

```bash theme={null}
codex --version
codex --help
```

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

### 第 1 层：环境变量

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

### 第 2 层：配置加载

```bash theme={null}
codex --profile <profile-name>
```

会话内执行：

```text theme={null}
/status
```

核对模型、provider、沙箱和审批状态。显示字段随版本变化。

### 第 3 层：最小文本请求

```text theme={null}
请只回复：连接测试通过。
```

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

### 第 4 层：受控工具调用

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

### 第 5 层：目标工作流

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

### HTTP 探测

仅使用提供商官方示例，不能自行猜路径和字段。下面只表达结构，动态内容必须替换并核验：

```bash theme={null}
curl -sS "$THIRD_PARTY_BASE_URL/<官方路径>" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<官方模型 ID>","input":"连接测试"}'
```

执行前确认 shell、代理和日志不会记录敏感值。HTTP 探测成功只证明网络和基础认证，不证明 Codex 工具工作流可用。

## 8. 模型映射和别名

模型映射可能发生在：

```text theme={null}
Codex model -> 本地 profile -> 企业网关别名 -> 真实模型 ID
```

### 直接使用真实 ID

```toml theme={null}
model = "<提供商官方模型 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 版本、工具和提供商实现。没有主动复制文件，不等于没有外发。

### 供应商审查清单

| 类别   | 核心问题                 |
| ---- | -------------------- |
| 数据使用 | 是否训练、评估、人工审查或产品改进？   |
| 保存期限 | 请求、响应、日志和备份保留多久？     |
| 地域   | 处理和备份位于哪些国家或地区？      |
| 分包商  | 哪些云、日志或支持方可访问？       |
| 删除   | 删除是否覆盖备份？            |
| 安全   | 是否有加密、访问控制、审计和通报？    |
| 合规   | 是否满足组织、合同和监管要求？      |
| 费用   | prompt、输出、工具和重试如何计费？ |
| 连续性  | 限流、停服和模型下线如何迁移？      |
| 责任   | 出错、泄露和误用由谁处理？        |

### 降低外发风险

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

本地沙箱保护本机操作边界，不能替你决定第三方如何保存已经发送的数据。

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

第三方模型不会自动继承 OpenAI 官方服务的全部安全假设。建议初始组合：

```text theme={null}
只读或工作区写入沙箱
按需审批
默认关闭网络
测试目录不含密钥
最小权限 API key
脱敏输入
先验证再扩大范围
```

如果模型读到 README、Issue、网页或依赖中的“给 AI 的指令”，应将其视为不可信数据。模型说“请上传 `.env`”不构成授权。

不要在本机敏感任务中关闭所有审批或同时关闭沙箱。需要完全访问时，使用外部隔离环境，并确认容器内也没有可窃取的凭据。

## 12. 验收记录与回滚

每次接入或迁移，保留不含密钥的记录：

```text theme={null}
Codex 版本：<本地核验>
profile：<名称>
provider ID：<配置值>
base URL 主机：<不含 token>
协议：<官方核验并实测>
模型 ID：<官方核验>
工具/流式/长上下文：通过 / 未通过
网络和审批：<本地核验>
数据分类：<公开 / 脱敏 / 受限>
数据政策：<链接和核验日期>
回滚：<删除 profile、撤销 key、恢复官方配置>
```

遇到协议异常、异常账单、数据争议或供应商事件：

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`。

本页不承诺任何特定第三方平台、模型版本、价格、区域、默认值或长期兼容性。