> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetoken.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> 通过 Responses API 将 Codex CLI 连接到 VibeToken。

Codex 可以通过 [Responses API](/zh/api-reference/responses) 将 VibeToken
作为自定义模型服务商。本指南使用 `qwen/qwen3.5-397b-a17b` 和普通的
个人 [API 密钥](/zh/essentials/keys)。此端点不支持管理密钥或组织密钥。

## 安装 Codex

安装或更新 CLI，然后检查版本：

```bash theme={null}
npm install -g @openai/codex
codex --version
```

以下配置和模型目录使用 Codex CLI `0.162.1` 验证。
较旧版本可能不接受相同的目录字段。

## 下载模型目录

Codex 使用专用的模型元数据格式。OpenAI 兼容的 `/v1/models`
响应不能直接作为 Codex 模型目录。

将 [Codex 模型目录](/codex-models.json) 下载到
`~/.codex/vibetoken-models.json`：

```bash theme={null}
mkdir -p ~/.codex
curl -fsSL https://docs.vibetoken.cn/codex-models.json \
  -o ~/.codex/vibetoken-models.json
```

此目录启用 shell 工具和原生 `apply_patch` 调用。
此 Qwen 配置禁用内置网页搜索和推理强度控制。
上游提供推理文本时会返回，但目录不承诺 Qwen 支持可配置的推理强度。

## 配置服务商

编辑前备份现有的 `~/.codex/config.toml`。
将以下设置合并到该文件，保留你的 MCP 服务和项目配置。
`model`、`model_provider`、`model_catalog_json` 和 `web_search`
必须放在顶层，即任何 `[table]` 标题之前。
如果同名设置已存在，请修改原设置，不要重复添加。

```toml theme={null}
model = "qwen/qwen3.5-397b-a17b"
model_provider = "vibetoken"
model_catalog_json = "~/.codex/vibetoken-models.json"
web_search = "disabled"

[model_providers.vibetoken]
name = "VibeToken"
base_url = "https://vibetoken.cn/v1"
env_key = "VIBETOKEN_API_KEY"
wire_api = "responses"
supports_websockets = false
request_max_retries = 0
stream_max_retries = 0
```

自动 HTTP 和流重试均已禁用。
此 Qwen 配置不要添加 `model_reasoning_effort`，也不要启用 WebSocket。

## 运行 Codex

在启动 Codex 的终端中导出 VibeToken 签发的密钥：

```bash theme={null}
export VIBETOKEN_API_KEY="your-api-key"
cd /path/to/your/project
codex
```

也可以进行非交互检查：

```bash theme={null}
codex exec "读取这个项目并总结入口文件，不要修改文件。"
```

Codex IDE 扩展可以使用相同的用户级服务商配置。
请让 IDE 进程能够读取 API 密钥环境变量，并在修改配置后重启 IDE。
本指南的本地验证覆盖 CLI，不包括桌面客户端或 IDE 扩展。

## 已支持的能力

* 函数工具（含 namespace 分组）、上游 `strict` 工具约束及原生 `apply_patch`。上游发送增量片段时，
  文本、推理、函数参数和补丁输入均实时转发，输出项 ID 保持稳定。
* 通过 `text.format` 指定结构化输出（`text`、`json_object`、`json_schema`），
  支持工具结果中的图片及上游提供的 token 概率。仍受服务商限制，不自动重试。
  这两个路由的 Qwen 3.5 397B 支持 `json_object`，不支持 `json_schema`。
* 明文推理回放和按模型、路由选择的推理强度。覆盖 DeepSeek V4 变体、带日期的
  Ark 变体及部分 PPIO Kimi/GLM 模型。`none` 仅在上游支持时关闭思考；本指南
  的 Qwen 配置保持上游默认行为不变。
* 上游返回的原生加密推理和摘要元数据会被保留。回放要求模型路由显式声明兼容
  能力；未声明兼容的历史返回 HTTP 400。密文必须回传给兼容的上游，网关不会
  跨服务商转换或解密密文，也不会生成伪造的隐藏推理状态。
* 保留上游真实终止原因及推理 token 数。达到输出上限或内容过滤时返回
  `response.incomplete`。verbosity 仅在模型参数明确声明时转发。

## 当前限制

* 其他自定义工具、托管工具、不支持的推理/verbosity 控制，以及未声明兼容的
  原生推理回放返回 HTTP 400。
* 上游不发送增量流时仍可能返回缓冲输出。部分模型不能关闭思考或配置推理摘要。
* 不支持服务端历史、`previous_response_id`、WebSocket 或
  `/v1/responses/compact`。每轮应发送完整历史；长会话和自动压缩需要
  单独验证。
* 不支持内置网页搜索或其他 OpenAI 托管工具。

## 常见问题

| 现象 | 检查方式 |
| - | - |
| Codex 仍在使用 OpenAI | 将 `model_provider` 放在用户配置顶层，不要放在服务商表内。 |
| `missing field models` 或未知模型警告 | 将 `model_catalog_json` 指向下载的 Codex 目录，不要使用 `/v1/models` 的响应。 |
| 目录解析错误 | 更新 Codex 并重新下载目录；本指南验证的版本为 `0.162.1`。 |
| HTTP 401 或 403 | 使用目标实例的普通个人 API 密钥，并在启动进程中导出它。 |
| HTTP 402 | 充值或减少上下文和输出上限；编码会话按对话用量计费。 |
| 找不到模型 | 查询目标实例的 [Models API](/zh/api-reference/models)，使用准确的活动模型 ID。 |
| 没有原生 patch 工具 | 下载最新目录；`apply_patch_tool_type` 必须为 `"freeform"`。 |
| 不支持推理强度 | 此 Qwen 目录不要覆盖推理强度；请使用上游支持强度控制的模型。 |

服务商配置字段详见
[Codex 官方配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.