---
title: "通过 Helicone 连接模型服务"
summary: "用户层 [model_providers.helicone]，base_url 是 https://ai-gateway.helicone.ai/v1，wire_api = responses。env_key 读 HELICONE_API_KEY，不要再写 wire_api = chat。"
category: config
level: intermediate
surfaces: [cli, app, ide]
tags: ["model_providers", "Helicone", "wire_api", "profile"]
canonical: /tips/helicone-codex-gateway/
---

# 通过 Helicone 连接模型服务

用户层 [model_providers.helicone]，base_url 是 https://ai-gateway.helicone.ai/v1，wire_api = responses。env_key 读 HELICONE_API_KEY，不要再写 wire_api = chat。

Helicone 官方 Codex 网关：profile 写 [model_providers.helicone]，base_url 是 https://ai-gateway.helicone.ai/v1，密钥用 env_key 不要 wire_api = chat。

这是换 Codex **使用的模型**，流量打到 Helicone AI Gateway，不是添加 MCP 服务。官方 Codex 页给了 `[model_providers.helicone]` 和 `env_key = "HELICONE_API_KEY"`，但把 `wire_api = "chat"` 写进示例——现行 Codex 会不受支持的配置。只留 `responses`。不要和 `experimental_bearer_token` / `requires_openai_auth` / `[model_providers.*.auth]` 叠在同一张供应商表。

`base_url` 就是 `https://ai-gateway.helicone.ai/v1`。**Codex 不会在 `base_url` 里展开环境变量**。不要写 `openai_base_url`。不要把密钥嵌进 `https://gateway.helicone.ai/YOUR_HELICONE_API_KEY/v1/`——那是经典代理的旁路，不是 AI Gateway。也不要把经典代理的 `Helicone-Auth` 头当成这张表的主路径；AI Gateway 用 `env_key` 发 Bearer。

官方把路径写成 `$CODEX_HOME/.codex/config.toml`。`$CODEX_HOME` 默认就是 `~/.codex`，文件是 `$CODEX_HOME/config.toml`，不要再套一层 `.codex`。供应商表放**用户**层。项目 `.codex/config.toml` 无法修改 `model_provider` / `model_providers`。

不要把顶层 `model_provider = "helicone"` 一上来写进用户 config，除非你就是要把**所有**会话都改走网关。官方手册示例就是全局默认。更稳妥是独立 profile（0.134 起不要再写 `[profiles.helicone]`）：

```toml
# ~/.codex/config.toml
[model_providers.helicone]
name = "Helicone"
base_url = "https://ai-gateway.helicone.ai/v1"
env_key = "HELICONE_API_KEY"
wire_api = "responses"
```

```toml
# ~/.codex/helicone.config.toml
model_provider = "helicone"
model = "gpt-5"
```

```bash
export HELICONE_API_KEY=YOUR_HELICONE_API_KEY
codex --profile helicone
codex --profile helicone -m gpt-5
```

`env_key` 是变量**名**。密钥必须在**启动 Codex 的那个进程**里。网关 POST 要用带写权限的密钥（文档写写权限以 `pk-` 开头）；MCP 查请求那条才是读权限 `sk-`。欧盟密钥带 `eu-` 前缀，仍打 `https://ai-gateway.helicone.ai/v1`，不要改成 `eu.helicone.ai`。

官方 SDK 节自己说：Codex SDK 指定不了 wire API，默认就走 Responses，而且网关对 Responses **有限模型**可用。Responses 页写明目前是 OpenAI 和 Anthropic。CLI 不要抄 `wire_api = "chat"` 去迁就 Chat Completions 目录里的其它厂商。模型 slug 用网关认识的短名，例如 `gpt-5`、`claude-sonnet-4-20250514`。文档未说明 WebSocket 支持。

这**不是** `codex mcp add helicone -- npx @helicone/mcp@latest`。MCP 查账号里的请求；这张表换模型流量。

配置说明：

- 不要再写 `[profiles.helicone]` 或 `wire_api = "chat"`。
- 不要把密钥写进 `http_headers` 或 `base_url`。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`helicone` 是新 ID，可以。
- 不要写进项目 `.codex/config.toml`。
- 不要把这张表当成 MCP。
- 不要把 `$CODEX_HOME/.codex/config.toml` 再套一层目录。

改完新开会话。`codex --profile helicone` 启动后，发送一条简短请求验证连接。401 先看进程里有没有写权限密钥；连得上但工具/推理失败，先换 Responses 页列出的 OpenAI / Anthropic 模型。

## 来源

- [Helicone · OpenAI Codex](https://docs.helicone.ai/gateway/integrations/codex)
- [Helicone · Responses API](https://docs.helicone.ai/gateway/concepts/responses-api)
- [Helicone · Auth](https://docs.helicone.ai/helicone-headers/helicone-auth)