跳到主要内容
版本：1.10.0

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 Enterprise 快速上手完成部署，也可以联系 API7申请 AISIX 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 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​

Codex 依赖流式函数调用来执行工具，因此别名必须使用能在原生或转换流中返回函数调用的上游。转换后的流会把 Claude 的工具调用作为函数调用返回，无论经由 anthropic 适配器，还是来自 Vertex AI 上的 Claude。

当模型别名背后的服务提供方 Key 不提供 Responses API 时（例如 Anthropic 的 Key），AISIX 会把每个 Codex 请求转换为 Chat Completions，再把回答转换回来。这条路径上有几处行为与 Codex 直接相关：

  • 在支持函数调用的转换流中，Codex 的 namespace 工具（例如 multi_agent_v1）会以展平后的函数工具提供给模型，模型的调用会以原来的名称和 namespace 返回给 Codex。在 Responses Lite 模式下，Codex 通过一个 additional_tools 输入 item 发送工具，其中包括 functions namespace 下的 exec，桥接路径会像顶层工具一样转发它们。参见工具参数。除 OpenAI、Azure OpenAI 和 BYO 密钥外，Lite 模式请求在所有服务提供方密钥上都走桥接，即使密钥声明了原生 Responses 协议面（例如 DeepSeek 目录密钥），见 Lite 模式的工具请求。
  • 当 Codex 的模型元数据开启 tool search 时，Codex 会延迟加载它的 MCP 工具，并在客户端自己执行 tool_search。桥接路径会把搜索工具、搜索历史和搜索加载的工具带给模型，模型对 tool_search 或已加载 MCP 工具的调用会以 Codex 能够分派的 item 返回。参见工具参数。
  • 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 字段。参见回放的对话历史。
滚动升级期间或网关回滚之后，后续轮次以 400 失败该对话由一个会把上下文保持在多目标模型目标上的网关版本打过标记，而这一轮到达了较旧的版本。请开启新对话。参见升级与回滚。
请求绕过 AISIX确认生效的 Codex 配置层中包含 model_provider = "aisix"。

有关端点行为和服务提供方边界，请参阅 Responses API。

后续步骤​

  • Responses API：查看 AISIX 如何处理 Responses API 请求。
  • 语义路由：按主题路由每个会话。Codex 会发送网关能读取的会话 ID，因此会话固定无需额外配置即可让会话保持在同一路由上。
  • 指标与用量事件：查看网关指标和每次尝试的用量事件。
  • API Key 与模型限流：为编码 Agent 流量添加调用方或模型限流。