---
title: "通过 Portkey 连接模型服务"
summary: "用户 config 写 [model_providers.portkey]，base_url 是 https://api.portkey.ai/v1，env_key = PORTKEY_API_KEY，wire_api = responses。再用 ~/.codex/portkey.config.toml 和 --profile portkey。"
category: config
level: intermediate
surfaces: [cli, app]
tags: ["model_providers", "Portkey", "wire_api", "profile", "PORTKEY_API_KEY"]
canonical: /tips/portkey-codex-gateway/
---

# 通过 Portkey 连接模型服务

用户 config 写 [model_providers.portkey]，base_url 是 https://api.portkey.ai/v1，env_key = PORTKEY_API_KEY，wire_api = responses。再用 ~/.codex/portkey.config.toml 和 --profile portkey。

Portkey 官方 Codex 网关：用户层 [model_providers.portkey]，base_url 是 https://api.portkey.ai/v1，env_key 读 PORTKEY_API_KEY。这是换 Codex **使用的模型**，不是添加 MCP 服务，也不是插件。模型 slug 走 Portkey Model Catalog，形状是 `@provider-slug/model`，例如 `@openai-prod/gpt-4o`，不是 Vercel 的 `厂商/型号`，也不是 Hugging Face router 后缀。

供应商表放**用户** `~/.codex/config.toml`。不要一上来把顶层 `model_provider = "portkey"` 写成整机默认，除非你就是要把**所有**会话都改走网关：

```toml
# ~/.codex/config.toml
[model_providers.portkey]
name = "Portkey"
base_url = "https://api.portkey.ai/v1"
env_key = "PORTKEY_API_KEY"
wire_api = "responses"
```

`env_key` 是变量**名**。密钥必须出现在**启动 Codex 的那个进程**里。从已经 `export PORTKEY_API_KEY` 的终端启动；Dock 打开的桌面不会读你刚改的 zshrc。不要把 `pk-` 字面量写进 TOML，也不要写进 `http_headers`。

Portkey 官方页把省略 `wire_api` 写成 Chat Completions（`chat`）。Codex 自定义供应商要走工具调用和推理时，用 `responses`。只在你明确只要 Chat Completions 时才写成 `chat`。Wizard 的 `--codex-wire-api chat|responses` 也是改这一项。

更稳妥是独立 profile，不要再写 `[profiles.portkey]`（0.134 起会被拒绝）：

```toml
# ~/.codex/portkey.config.toml
model_provider = "portkey"
model = "@openai-prod/gpt-4o"
```

```bash
codex --profile portkey
codex --profile portkey -m "@openai-prod/gpt-4o"
```

`npx portkey` / `npx portkey setup` 是向导，**可以**改 Claude / Cursor，并把 MCP、技能一并写进配置。只要网关时加 `--skip-mcp --skip-skills`，Codex 协议用 `--codex-wire-api responses`。它可能把 `model_provider = "portkey"` 写成默认，也可能写到项目 `.codex/config.toml`。项目文件**无法修改** `model_provider` / `model_providers` / `otel`；Portkey 文档那句「仓库 `.codex` 能覆盖供应商」按 OpenAI 现行规则是错的。手写用户层表 + profile 才是主路径。

向导写的 `[mcp_servers.*]`（头里带 Portkey API key）是另一条线，不要和这张网关供应商表混用。

配置说明：

- 不要写进项目 `.codex/config.toml`。项目文件无法修改供应商。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`portkey` 是新 ID，可以。
- 不要把密钥写进 TOML。
- 不要用 `openai_base_url` 顶替这张表；那是改内置 `openai` 供应商。

改完新开会话。`codex --profile portkey` 启动后，发送一条简短请求验证连接。401 先看进程里有没有 `PORTKEY_API_KEY`；模型 404 再对照 Model Catalog 改 `model`。用量看 Portkey Dashboard。

## 来源

- [Portkey · OpenAI Codex](https://portkey.ai/docs/integrations/libraries/codex)
- [Portkey-AI/cli](https://github.com/Portkey-AI/cli)
- [OpenAI · Advanced configuration](https://learn.chatgpt.com/docs/config-file/config-advanced)