Codex
Codex 支持在配置文件中定义自定义模型服务提供方。当 Codex 需要将 Responses API 请求发送到 AISIX 而非直接调用模型服务提供方时，请使用自定义服务提供方。
本指南将 Codex 指向 AISIX 代理 API 根路径，并使用 AISIX 调用方 API Key 认证。Codex 的自定义模型值应填写 AISIX 模型别名。
前置条件
开始前，请准备以下内容：
- 已安装 Codex，且可以读取
~/.codex/config.toml。 - 一个代理监听器可用的运行中 AISIX 网关。
- 一个 AISIX 调用方 API Key。
- 一个调用方 API Key 可访问且支持 Responses API 的模型别名。
如果你的组织已经部署 AISIX，请向管理团队获取网关 URL、模型别名和调用方 API Key。否则，请按照开源 AISIX 网关快速上手或 AISIX Cloud 快速上手完成部署，也可以联系 API7申请 Hybrid Cloud 访问权限。
配置 Codex
在运行 Codex 的环境中设置调用方 API Key：
# 请替换为实际值
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
在 ~/.codex/config.toml 中添加 AISIX 模型服务提供方：
~/.codex/config.toml
model = "gpt-4o-prod" # 使用 AISIX 模型别名，而不是上游服务提供方模型 ID。
model_provider = "aisix"
[model_providers.aisix]
name = "AISIX AI Gateway"
# 包含 /v1，末尾不带斜杠
# 本地快速入门使用 http://127.0.0.1:3000/v1
base_url = "YOUR_AISIX_GATEWAY_URL/v1"
env_key = "AISIX_API_KEY" # 从环境变量读取 AISIX 调用方 API Key。
wire_api = "responses"
验证集成
在已设置 AISIX_API_KEY 的 Shell 中启动 Codex：
codex
提出一个需要模型响应的简短问题。
请求成功后，请确认以下结果：
- Codex 输出模型响应。
- AISIX 为所选模型别名记录一条成功的
POST /v1/responses请求。
AISIX 会验证调用方 API Key、检查模型访问权限、解析模型别名、应用策略，并将请求分发到别名背后的上游服务提供方。
在其他服务提供方上使用 Codex
当模型别名背后的服务提供方 Key 不提供 Responses API 时（例如 Anthropic 的 Key），AISIX 会把每个 Codex 请求转换为 Chat Completions，再把回答转换回来。这条路径上有几处行为与 Codex 直接相关：
- Codex 的
namespace工具（例如multi_agent_v1）会以展平后的函数工具提供给模型，模型的调用会以原来的名称和 namespace 返回给 Codex。参见工具参数。 - Codex 在历史中回放的推理内容会以
reasoning_content发给 OpenAI 兼容上游，因此多轮会话中的输入 Token 数会增加。参见回放的对话历史。 - 某一轮在流中途失败时，AISIX 会以
response.failed事件结束该流，因此 Codex 会显示错误消息。被输出安全护栏拦下的轮次以invalid_prompt失败，Codex 不会重试。参见桥接路径上的流失败。 web_search等托管工具在这条路径上会被丢弃。
排查 Codex 请求
如果 Codex 无法连接 AISIX，请检查以下内容：
| 现象 | 检查项 |
|---|---|
| 认证失 败 | 确认 AISIX_API_KEY 已在运行 Codex 的同一 Shell 或环境中设置。 |
| 找不到模型 | 确认 config.toml 中的 model 是调用方 API Key 可见的 AISIX 模型别名。 |
| Responses 请求失败 | 确认所选模型别名可用于 AISIX Responses API。某些服务提供方支持的别名并不支持全部 OpenAI Responses 特性。 |
| 模型返回推理内容后，下一轮在 OpenAI 兼容上游上失败 | 上游可能拒绝 AISIX 加在回放 assistant 消息上的 reasoning_content 字段。参见回放的对话历史。 |
| 请求绕过 AISIX | 确认生效的 Codex 配置层中包含 model_provider = "aisix"。 |
有关端点行为和服务提供方边界，请参阅 Responses API。
后续步骤
- Responses API：查看 AISIX 如何处理 Responses API 请求。
- 指标与用量事件：查看网关指标和每次尝试的用量事件。
- API Key 与模型限流：为编码 Agent 流量添加调用方或模型限流。