---
title: "Codex"
description: "让 Codex CLI 走 pirouter：在 ~/.codex/config.toml 里加一个 provider，base_url 填 https://api.pirouter.ai/v1、wire_api 填 responses，key 从环境变量 PIROUTER_API_KEY 读；只能用接受 Responses 端点的模型。"
canonical: "https://pirouter.ai/zh/docs/integrations/codex"
last-updated: "2026-10-18"
lang: "zh"
source: "content/docs/zh/integrations/codex.mdx"
---

# Codex

让 Codex CLI 走 pirouter：在 ~/.codex/config.toml 里加一个 provider，base_url 填 https://api.pirouter.ai/v1、wire_api 填 responses，key 从环境变量 PIROUTER_API_KEY 读；只能用接受 Responses 端点的模型。

[Codex CLI](https://learn.chatgpt.com/docs/codex/cli) 不需要插件就能走 pirouter：在 `~/.codex/config.toml` 里定义一个指向 pirouter 的 provider，key 从环境变量读。Codex 只用 OpenAI 的 Responses 端点，请求发到 `POST /v1/responses`，所以只能用接受这个端点的模型。

## 前提

- 一个 pirouter API key。还没有的话，按[快速开始](https://pirouter.ai/zh/docs/quickstart.md)创建一个，并存进环境变量。写进 `~/.zshrc` 这类 shell 配置文件，以后每个终端都能读到：

`~/.zshrc`:

```bash
export PIROUTER_API_KEY="sk-pi-..."
```

- Codex CLI。本页在 v0.162.1 上验证。还没安装的话，macOS、Linux 上运行：

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

也可以用 `npm install -g @openai/codex` 或 `brew install --cask codex`，Windows 的安装方式见 [Codex CLI 安装说明](https://learn.chatgpt.com/docs/codex/cli)。

## 配置

把下面这段写进 `~/.codex/config.toml`。文件里已经有内容的话，把前三行放到文件最前面、第一个 `[...]` 表头之前，否则 Codex 会把它们当成上一个表里的键：

`~/.codex/config.toml`:

```toml
model = "openai/gpt-6.1-sol"
model_provider = "pirouter"
web_search = "disabled"

[model_providers.pirouter]
name = "pirouter"
base_url = "https://api.pirouter.ai/v1"
wire_api = "responses"
env_key = "PIROUTER_API_KEY"
```

每一项的作用：

- `model` 写模型全 ID。
- `model_provider` 指向下面定义的 `pirouter`。
- `web_search = "disabled"` 关掉 Codex 自带的网页搜索工具。它默认搜的是 OpenAI 维护的索引，pirouter 不提供这个工具。
- `base_url` 填 `https://api.pirouter.ai/v1`，带 `/v1`，Codex 在后面拼上 `/responses`。
- `wire_api` 填 `responses`，这是 Codex 唯一支持的值。
- `env_key` 写存放 key 的环境变量名，不写 key 本身。Codex 把这个变量的值放在 `Authorization: Bearer` 请求头里发出，网关从这个头读 key。

这段配置只能写在用户目录下的 `~/.codex/config.toml`。项目里的 `.codex/config.toml` 会忽略 `model_provider` 和 `model_providers`。

### 能用哪些模型

Codex 只调用 `POST /v1/responses`，Chat Completions 和 Anthropic 协议它都不用。能用哪些模型，见[模型与协议](https://pirouter.ai/zh/docs/models.md#每个模型接受哪些协议)的协议表：选 OpenAI 一列为「支持」、并提供 Responses 端点的模型。`openai/gpt-6.1-sol` 和 `openai/gpt-5.5` 都实测可用，工具调用也正常。

临时换模型，加 `-m`：

```bash
codex -m openai/gpt-5.5
```

## 验证

在终端里运行：

```bash
codex exec --skip-git-repo-check "Reply with the single word: ok"
```

你应该看到 Codex 最后输出 `ok`。`--skip-git-repo-check` 让它在不是 git 仓库的目录里也能运行。

在控制台的[日志](https://pirouter.ai/zh/docs/guides/logs.md)里能看到这次请求，**端点** 一栏是 `/v1/responses`。

## 排障

### wire\_api = "chat" is no longer supported

Codex 启动时报 `` `wire_api = "chat"` is no longer supported ``：配置来自旧教程。Codex 已经去掉了 Chat Completions，把 `wire_api` 改成 `"responses"`，`base_url` 保持 `https://api.pirouter.ai/v1`。

### 没关网页搜索

没写 `web_search = "disabled"` 时，默认值是 `"cached"`：Codex 给模型加一个网页搜索工具，搜的是 OpenAI 维护的索引。pirouter 不提供这个工具。在配置文件最前面加上 `web_search = "disabled"`。

### 脚本里调用 codex exec 卡住不动

在脚本、CI 或其他程序里调用 `codex exec` 时，标准输入不是终端，Codex 会等着读标准输入，看起来像卡住了。没有内容要传给它时，把标准输入接到 `/dev/null`：

```bash
codex exec --skip-git-repo-check "Reply with the single word: ok" < /dev/null
```

### 422 validation\_failed

返回 `422`，错误码 `validation_failed`，`message` 以 "This model is not served on the endpoint you called." 开头：这个模型不提供 Responses 端点。`message` 后半句列出它提供的端点。换一个协议表里提供 Responses 端点的模型。

### 401 invalid\_api\_key

返回 `401`，错误码 `invalid_api_key`：请求没带上 key，或者带的不是以 `sk-pi-` 开头的 pirouter key。确认启动 Codex 的那个终端里设置了 `PIROUTER_API_KEY`。从桌面启动的 Codex 应用不一定读得到终端里导出的变量。其他鉴权失败见[鉴权与 API key](https://pirouter.ai/zh/docs/authentication.md#鉴权失败时的返回)。

## 目前没有验证的用法

- 非 OpenAI 的模型配 Codex 没有验证过。有的模型虽然提供 Responses 端点，但 Codex 的提示和工具是按 OpenAI 模型写的。
- 把 provider 写进单独的 profile 文件（`~/.codex/pirouter.config.toml`，用 `codex --profile pirouter` 启动）没有验证过。
- 开着网页搜索（`web_search` 为 `"cached"` 或 `"live"`）时请求会怎样，没有验证过。

## 相关链接

- [Codex](https://github.com/openai/codex)（GitHub）
- [Codex CLI 安装说明](https://learn.chatgpt.com/docs/codex/cli)
- [连接网关](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)：Codex 官方的自定义 provider 配置说明
- [配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)：`config.toml` 全部配置项