# Codex CLI 接入

使用 OpenAI Codex CLI 的 Responses 通路连接 GFW，配置自定义模型提供商和 API Key。

## 接入前准备 [#接入前准备]

请先按 [Codex 官方文档](https://developers.openai.com/codex)安装并确认 `codex` CLI 可运行，然后在 GFW 控制台 **使用 → API 密钥** 创建 Key。Codex 当前自定义提供商通路使用 OpenAI Responses API，因此地址应指向：

```text
https://api.gfw.net/v1
```

可用模型必须来自 GFW 当前目录。下面以 `qwen3.7-max` 为例。

## 配置 Responses 提供商 [#配置-responses-提供商]


**提示**

当前 G 网的 Responses 兼容层尚未实现完整 `function_call` / `function_call_output` 循环。本配置用于验证地址与基础文本响应；Codex 的文件操作、命令执行和多轮 Agent 任务尚不能据此确认可用。详见 [Responses API](/docs/responses)。请使用当前 Codex 版本支持的 `responses` 配置。


Codex 的用户级配置通常位于 `~/.codex/config.toml`；如果设置了 `CODEX_HOME`，则位于 `$CODEX_HOME/config.toml`。在该文件中加入一个自定义提供商，并明确使用 `responses`：

```toml
model = "qwen3.7-max"
model_provider = "gfw"

[model_providers.gfw]
name = "GFW"
base_url = "https://api.gfw.net/v1"
env_key = "GFW_API_KEY"
wire_api = "responses"
```

`wire_api = "responses"` 选择 Codex 当前支持的协议。`env_key` 是保存 API Key 的环境变量名称，不应将密钥明文写进 TOML。连接成功后仍需遵循上面的工具兼容限制。

## 设置 API Key 并运行 [#设置-api-key-并运行]

在启动 Codex 的同一环境中设置占位变量：

```bash
export GFW_API_KEY='your-api-key'
codex
```

如果你使用独立配置目录，可以这样运行：

```bash
export GFW_API_KEY='your-api-key'
CODEX_HOME="$HOME/.codex-gfw" codex
```

相应地，把上面的配置保存为 `$HOME/.codex-gfw/config.toml`。不要在项目仓库中提交 Key 或包含 Key 的配置文件。

## 验证 Responses 端点 [#验证-responses-端点]

如果 Codex 启动时报提供商或协议错误，可先绕过 CLI，直接验证 GFW 的 Responses 路由。以下返回体是**响应结构示意**，不是固定实测内容。

```bash
curl -sS https://api.gfw.net/v1/responses \
  -H "Authorization: Bearer ${GFW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "input": "只回复：连接正常"
  }'
```

GFW 会把 Responses 请求转换到内部兼容通路，再返回 Responses 风格数据。流式请求使用同一路由并设置 `stream`，最终用量和费用仍以控制台实际记录为准。

## 故障排查 [#故障排查]

- **`wire_api` 错误**：确认配置值与当前 Codex 版本匹配；本页的 `responses` 只用于地址和基础文本验证，不要仅凭此页判断仍可用的 `chat` 配置必须退役。
- **找不到 Key**：检查 `env_key` 与导出的变量名称完全一致，并确认启动进程继承了该环境变量。
- **模型不存在**：改用模型目录里的 `model_code`，不要填供应商上游模型标识。
- **地址错误**：Codex 的 `base_url` 需要包含 `/v1`，否则会请求到控制台根路径。
- **权限或余额错误**：检查 API Key 状态、模型用户组访问、元余额和 Key 限额。


**提示**

Codex 的配置键名和 CLI 参数会随官方版本演进。遇到配置解析差异时，以当前版本的 `codex --help` 和官方配置参考为准；GFW 侧要求仍是 `/v1/responses`、Bearer API Key 和有效的 GFW `model_code`。


## 相关链接 [#相关链接]

- [Codex 配置参考](https://developers.openai.com/codex/config-reference)
- [Codex 高级配置](https://developers.openai.com/codex/config-advanced)
- [认证](/docs/authentication)
- [Responses API](/docs/responses)
- [模型](/models)