3.7 模型服务、网关与网络代理：以 Codex 配置为例

寄快递时，收件地址、转运仓和运输路线是不同的概念。模型调用也要区分：模型服务提供响应，API 网关接收并转发请求，网络代理处理连接路径。它们可能一起出现，但配置方式不能混用。

先分清三个地址

地址类型	做什么	示例含义
模型 API 地址	接收符合接口格式的模型请求	服务商提供的 API 入口
本地网关地址	在本机接收请求并转发到上游	管理工具实际监听的地址
网络代理地址	转发网络连接	所在网络提供的代理端口

不能因为三个地址都写成 http://...，就把它们互相替换。网络代理端口通常不接受模型请求结构；一个兼容聊天接口的网关，也未必支持编码工具需要的全部功能。

什么情况下需要调整配置

已经能使用官方入口完成任务，就可以先保持现有配置。需要连接自托管服务、组织内部网关或多个授权提供方时，再设置自定义服务。

连接超时并不一定需要换服务商。先检查地址、网络、服务状态与请求长度；认证失败则优先检查密钥和账户权限。问题层次不同，处理方法也不同。

CC-Switch 的作用

CC-Switch 官方仓库提供多个编码工具的配置管理功能。它可以帮助管理提供方与相关设置，但不是模型服务本身，也不会自动提供 API 余额或账户权限。

使用前记录原来的配置。添加提供方时，按上游文档填写地址、密钥和模型标识；切换后确认目标工具实际读取的是哪份配置。若启用了本地代理模式，监听端口应以当前设置为准，不能照抄某个固定数字。

配置管理工具与手工编辑同时使用时，要留意谁会覆盖谁。建议先选一种方式完成连接，再检查最终生成的配置，避免两边来回修改造成混乱。

Codex 的自定义提供方示例

下面以 Codex CLI 的用户级 ~/.codex/config.toml 为例。.codex 是目录，不是把全部设置写进去的单个文件。项目级配置、用户级配置及托管设置可能同时存在，具体优先级查官方配置说明。

先核对上游是否支持 Codex 当前使用的接口。本例选择 Responses 接口；只有 Chat Completions 兼容说明，不足以证明可以直接按本例连接。

# 以下地址和模型名称均为占位内容，使用前替换
model = "provider-model-id"
model_provider = "practice_gateway"

[model_providers.practice_gateway]
name = "练习网关"
base_url = "https://gateway.example.com/v1"
env_key = "PRACTICE_MODEL_API_KEY"
wire_api = "responses"

model_provider 对应下面提供方表的名称；env_key 填环境变量名，不填密钥本身。字段定义与兼容说明参见 Codex 高级配置和配置参考。

这份示例没有承诺任何未指定上游可用。真正能否连接，还取决于模型标识、认证方式、流式响应及工具调用兼容性。

让启动进程能够读取密钥

在启动 CLI 的终端中设置对应变量，再启动工具。以下仍是占位值，不能直接用于调用：

macOS / Linux：

export PRACTICE_MODEL_API_KEY="replace-with-your-key"
codex

Windows PowerShell：

$env:PRACTICE_MODEL_API_KEY = "replace-with-your-key"
codex

变量只影响能够继承它的进程。已经运行的桌面应用通常不会自动获得后来在另一个终端设置的变量。配置未生效时，先确认应用的启动方式和实际配置来源。

真实密钥应使用工具或系统支持的凭据管理方式保存。若临时在终端输入，注意命令历史与屏幕共享；不要把真实值写进项目说明或提交到仓库。

也不要假定 OPENAI_BASE_URL 对所有编码工具自动有效。不同客户端识别的变量不同，本节使用自定义提供方字段明确表达配置。

按层次验证连接

1. 读取配置：启动时没有格式解析错误，选择的是预期提供方与模型。
2. 完成短请求：收到真实响应，确认基本认证与协议可用。
3. 验证工具调用：在练习目录读取一个文件，确认调用和结果能往返。
4. 检查失败处理：遇到服务错误时能保留错误信息，而不是把空响应当作成功。
5. 检查用量来源：确认费用记在预期账户上，避免误用另一把密钥。

只完成第二步，不足以证明复杂编码任务可用；第三步失败时，应优先查协议和工具格式，而不是增加提示词长度。

常见错误怎样排查

错误	可能原因	处理方向
Connection refused	服务未监听、地址或端口错误	查看本地网关运行状态与实际端口
Timeout	网络、服务繁忙或响应超时	用短请求区分连接与生成耗时
401	密钥无效或认证方式不匹配	核对当前提供方、变量名与密钥状态
403	服务或模型权限不足	查看账户授权与上游返回说明
404	路径或模型标识错误	核对基础地址、接口与模型列表
429	速率或用量限制	查看是否可重试及等待时间
Certificate verify failed	系统时间、证书链或代理证书问题	修复时间与证书信任，按组织网络要求配置

证书问题应从证书链和网络配置排查，不把关闭证书校验作为常规解决办法。连接恢复后，保留一份不含密钥的配置说明，记录上游、接口类型与验证过的功能。