# Codex CLI 集成

> 在 ~/.codex/config.toml 里加一个自定义 model_provider,让 OpenAI Codex CLI 走本平台的 /v1/responses

来源：https://qd.zsopc.com/docs/integrations/codex-cli

> [Codex CLI](https://github.com/openai/codex) 是 OpenAI 的命令行编程助手,通过 Responses API 调模型。本页按 Codex CLI 0.169.0(2026-11-13 发布)与官方[配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)核对。

## 准备 API Key

在 [qd.zsopc.com/dashboard/keys](https://qd.zsopc.com/dashboard/keys) 创建 API Key,导出成环境变量(建议写进 `~/.zshrc` / `~/.bashrc`):

```bash
export PLATFORM_API_KEY="sk-gpushare-xxx"
```

## 配置

编辑 `~/.codex/config.toml`(设了 `CODEX_HOME` 时在 `$CODEX_HOME/config.toml`):

```toml
model_provider = "xiaozhan"
model = "gpt-6.1-sol"

[model_providers.xiaozhan]
name = "小战AIhub"
base_url = "https://qd.zsopc.com/v1"   # Codex 自己补 /responses
env_key = "PLATFORM_API_KEY"            # 从这个环境变量读 Key
wire_api = "responses"
```

然后直接运行 `codex`。不需要 `codex login`:自定义 provider 用 `env_key` 指定的环境变量作为 Key。

要点:

- **`base_url` 要带 `/v1`**:Codex 把它与 `/responses` 拼起来,最终请求 `https://qd.zsopc.com/v1/responses`。
- **`wire_api` 只能写 `responses`**:这是现在唯一支持的值,也是默认值;旧版本的 `"chat"` 已移除,写了会报错。
- **provider 配置只能放用户级 `~/.codex/config.toml`**:项目目录里的 `.codex/config.toml` 会忽略 `model_provider` 与 `model_providers`。
- provider id 不能用 `openai`、`ollama`、`lmstudio` 等内置保留名。

## 选模型

Codex 只走 `/v1/responses`,所以 `model` 要选支持 OpenAI Responses 协议的模型。Codex 的提示词按 GPT 模型调过,推荐:

| 用途 | 模型 |
|---|---|
| 默认 / 复杂任务 | `gpt-6.1-sol`、`gpt-5.6-sol` |
| 日常、省钱 | `gpt-6-luna`、`gpt-6.1-terra` |

`claude-opus-4-8`、`claude-sonnet-4-6` 等少数非 GPT 模型也有 Responses 通道,支持情况见 [兼容矩阵](../reference/compatibility-matrix.md) 的 OpenAI Responses 一列;没有通道的模型会返回 503 `no_channel_available`。

Codex 内置目录里没有的模型 ID 会按通用参数运行(启动时可能提示)。需要时可在顶层加 `model_context_window = <窗口大小>` 或 `model_reasoning_effort = "high"`。

## 可选:WebSocket 传输

本平台在同一路径(`GET /v1/responses`)上提供 Responses API 的 WebSocket 传输。在 provider 里加一行:

```toml
supports_websockets = true
```

Codex 就会改用 WebSocket,长会话每轮只上传新增的内容,不再重发全部历史。

## 多套配置(profile)

Codex 0.134.0 起,profile 是单独的文件:把上面的顶层键写进 `~/.codex/<名字>.config.toml`,用 `codex --profile <名字>` 加载,它叠加在 `config.toml` 之上。

> Codex 也能接 MCP 服务器,本平台的出图、视频、音乐工具见 [MCP 媒体工具](./mcp.md)。

## 常见问题

| 现象 | 排查 |
|---|---|
| 401 `invalid_api_key` | 启动 `codex` 的终端里 `echo $PLATFORM_API_KEY` 是否有值;Key 是否复制完整(共 76 字符) |
| 404 | `base_url` 是否以 `/v1` 结尾 |
| 配置不生效 | provider 写在了项目级 `.codex/config.toml`;挪到 `~/.codex/config.toml` |
| 503 `no_channel_available` | 该模型没有 Responses 通道,换上表里的模型 |
| 402 `quota_exceeded` | 余额不足。所有 Key 共享同一账户余额,到 [充值页](https://qd.zsopc.com/dashboard/billing) 充值 |

错误码完整说明见 [错误码](../reference/errors.md)。长任务的超时与保活见 [流式响应](../guides/streaming.md#长请求与超时)。

## 其他客户端

- [Claude Code](./claude-code.md) — Anthropic 的命令行编程助手
- [Gemini CLI](./gemini-cli.md) — Google 的命令行编程助手
- [Cline](./cline.md) — VS Code 编程插件
