# Codex

Codex 通过 Responses 接口调用模型。在 config.toml 里加一个指向 NezhaGate 的服务商，就能用 NezhaGate 的 GPT 模型写代码。

> https://nezhagate.com/docs/integrations/codex

按此版本编写：Codex CLI 0.160

## 准备

- 安装 Codex CLI，或在 VS Code、Cursor、Windsurf 里安装 Codex 扩展；再到控制台创建一把 API Key。

- Codex 只使用 OpenAI 的 Responses 接口（`/v1/responses`），NezhaGate 在这个接口上提供 GPT 模型。Claude、Gemini 和国产模型请用对话接口，或者换用 [Claude Code](https://nezhagate.com/docs/integrations/claude-code) 等工具。

可以在 Codex 里使用的模型：

`gpt-5.6-sol` · `gpt-5.6-terra` · `gpt-5.6-luna` · `gpt-5.5` · `gpt-6-astra` · `gpt-6.1-sol` · `gpt-6-sol` · `gpt-6-luna`

## 在 config.toml 里添加服务商

打开 `~/.codex/config.toml`（Windows 是 `%USERPROFILE%\.codex\config.toml`），没有就新建一个，写入：

```
model = "gpt-6.1-sol"
model_provider = "nezhagate"
web_search = "disabled"

[model_providers.nezhagate]
name = "NezhaGate"
base_url = "https://nezhagate.com/v1"
wire_api = "responses"
env_key = "NEZHAGATE_API_KEY"
```

- `model`、`model_provider` 这些顶层设置要写在第一个 `[...]` 段之前，否则 Codex 会把它们当成那个段的内容。

- `web_search = "disabled"`：Codex 自带的联网搜索依赖 OpenAI 托管的工具，经其他服务商调用时不保证可用，建议关闭。

- 服务商只能写在用户目录的 config.toml 里，项目里的 `.codex/config.toml` 设置 `model_provider` 会被忽略。服务商 ID 不能用 `openai`、`ollama`、`lmstudio`，它们是 Codex 保留的。

## 设置 API Key

Codex 从环境变量 `NEZHAGATE_API_KEY` 读取 Key（也就是上面 `env_key` 的值），以 `Authorization: Bearer` 发送，不需要 `codex login`。

```
export NEZHAGATE_API_KEY=YOUR_API_KEY
codex
```

```
setx NEZHAGATE_API_KEY "YOUR_API_KEY"
```

macOS / Linux 要把 `export` 那一行写进 `~/.zshrc` 或 `~/.bashrc` 才能长期生效；Windows 用 `setx` 设置后，要重新打开终端或 VS Code 才能读到。

## 运行与测试

运行下面的命令，回复 `gateway-ok` 就说明接通了：

```
codex exec "Reply with exactly: gateway-ok"
```

- 在 Codex 里输入 `/status`，可以看到当前的模型和服务商。

- 换模型：启动时用 `codex -m gpt-6.1-sol`，或修改 config.toml 里的 `model`。Codex 的 `/model` 菜单只列出它自带的型号，不读取 NezhaGate 的模型列表。

- 再让它做一件需要工具的事（例如列出当前目录的文件），确认工具调用也正常。

## IDE 扩展

VS Code、Cursor、Windsurf 里的 Codex 扩展读取同一个 config.toml：在扩展面板点齿轮 → **Codex Settings** → **Open config.toml**。改完后重启编辑器；如果编辑器不是从终端启动的，要确认它能读到 API Key 的环境变量。

## 常见问题

**Missing environment variable: `NEZHAGATE_API_KEY`**

启动 Codex 的进程读不到这个变量：在同一个终端里设好再运行；IDE 或桌面应用需要重启，Windows 用 `setx` 之后要重新打开。

**`wire_api = "chat"` is no longer supported**

旧版配置：把 `wire_api` 改成 `"responses"`。

**unexpected status 401**

Key 不对：检查是否复制完整、有没有多余的空格，或者这把 Key 已被停用。

**unexpected status 404**

`base_url` 少了 `/v1`，应为 `https://nezhagate.com/v1`；Codex 会自己在后面加上 `/responses`。

**选了 Claude、Gemini 或国产模型后报错**

Codex 只走 `/v1/responses`，NezhaGate 在这个接口上只提供 GPT 模型。请换成上面列出的 GPT 模型。

**stream disconnected before completion**

流在结束前断开了，多半是本机代理或网络中途切断了连接。重试即可；经常出现时检查代理设置。