---
title: "通过 agentgateway 连接模型服务"
summary: "官方主路径是 ~/.codex/agentgateway.config.toml 加 [model_providers.agentgateway]，wire_api = responses，name 必填。本机 base_url 是 http://localhost:4000/v1。"
category: config
level: intermediate
surfaces: [cli, app]
tags: ["model_providers", "agentgateway", "wire_api", "profile"]
canonical: /tips/agentgateway-codex-gateway/
---

# 通过 agentgateway 连接模型服务

官方主路径是 ~/.codex/agentgateway.config.toml 加 [model_providers.agentgateway]，wire_api = responses，name 必填。本机 base_url 是 http://localhost:4000/v1。

agentgateway 官方 Codex 网关：profile 写 [model_providers.agentgateway]，base_url 是 http://localhost:4000/v1，env_key 读 AGENTGATEWAY_API_KEY。

这是换 Codex **使用的模型**，把 Responses 请求经 agentgateway 转到上游 OpenAI，不是添加 MCP 服务。自定义供应商必须 `wire_api = "responses"`，`name` **必填**。官方测过 `codex-cli 0.144.4`。

先起网关。`config.yaml` 里的 `OPENAI_API_KEY` 是**上游**密钥，不是 Codex 那颗客户端钥匙。通配 `*` 接受 Codex 请求里的任意模型名，不必在网关钉死型号：

```yaml
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
  models:
    - name: "*"
      provider: openAI
      params:
        apiKey: "$OPENAI_API_KEY"
```

```bash
agentgateway -f config.yaml
```

官方把供应商写进 **profile 文件**（用户层 `$CODEX_HOME`，不是项目 `.codex`）：

```toml
# ~/.codex/agentgateway.config.toml
model_provider = "agentgateway"

[model_providers.agentgateway]
name = "OpenAI via agentgateway"
base_url = "http://localhost:4000/v1"
wire_api = "responses"
env_key = "AGENTGATEWAY_API_KEY"
```

`base_url` 必须带 `/v1`，因为 Codex 打的是 `/v1/responses`。本机默认 `http://localhost:4000/v1`。Kubernetes Ingress 换成字面量 `http://YOUR_INGRESS_HOST/v1`（TLS 用 `https://`）。**Codex 不会在 `base_url` 里展开环境变量**；无引号 heredoc 是在**写文件时**由 shell 展开。不要把字面量 `$AGENTGATEWAY_BASE_URL` 留在 TOML 里。

`env_key` 是变量**名**。值是网关**虚拟钥 / 客户端钥匙**，不是上游 `OPENAI_API_KEY`。只有网关要求客户端鉴权时才加这行。必须出现在**启动 Codex 的那个进程**里。从已经 `export AGENTGATEWAY_API_KEY` 的终端启动；Dock 打开的桌面不会读你刚改的 zshrc。

鉴权只选一种，**避免重复配置**：`env_key`、`[model_providers.agentgateway.auth]`（组织自备命令返回 bearer token）、`requires_openai_auth = true`（官方本指南不配）。Codex 自定义供应商没有 Claude Desktop 那种任意 OIDC / Entra 字段；要 Entra 令牌得自己写 `auth` 命令去拿。

```bash
codex --profile agentgateway
codex --profile agentgateway "Hello"
```

单次覆盖也可以，但 `-c` 里同样要带 `name` 和 `wire_api = "responses"`。0.134 起不要再写 `[profiles.agentgateway]`。不要写进项目 `.codex/config.toml`：项目文件无法修改 `model_provider` / `model_providers`。

网关日志应看到 `POST /v1/responses` 且 `http.status=200`。Codex 还会探 `/v1/models`；在 agentgateway issue 1462 落地前可能警告找不到模型 metadata，**不挡** `/v1/responses`。

配置说明：

- 不要把这张表当成 `codex mcp add agentregistry`。那是 Solo 注册表 MCP（本机常是 31313），不是换模型。
- 不要用桌面官方 heredoc **整文件覆盖** `~/.codex/config.toml` 当主路径；先走 profile。
- 不要写 `wire_api = "chat"`，也不要省略 `/v1`。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`agentgateway` 是新 ID，可以。
- 不要把 `OPENAI_BASE_URL` 当主路径。
- 不要把 `env_key` 和 `auth` / `requires_openai_auth` 叠在同一张表。
- 不要把 LiteLLM 默认的 4000 端口和该服务网关当成同一进程。表名、配置文件都不是同一套。

改完新开会话。`codex --profile agentgateway` 启动后，发送一条简短请求验证连接。

## 来源

- [agentgateway · Codex (standalone)](https://agentgateway.dev/docs/standalone/latest/integrations/llm/clients/codex/)
- [agentgateway · Codex (Kubernetes)](https://agentgateway.dev/docs/kubernetes/latest/integrations/llm/clients/codex/)
- [agentgateway · OpenAI provider](https://agentgateway.dev/docs/standalone/latest/llm/providers/openai/)