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

# OpenCodex

> 通过 OpenCodex 将 Codex 接入 TokenLab，按模型使用对应 API 格式

## 交给我的 Agent 做

把这段任务交给电脑上已经可用的 Agent：

```text theme={null}
阅读 https://docs.tokenlab.sh/zh/integrations/opencodex，帮我将 OpenCodex 接入 TokenLab。
先检查已安装的 OpenCodex、Codex 版本、实际配置和正在运行的代理。
保留已有账户、提供商、模型和权限，修改文件前先备份。
让我在本机输入 API Key，不要在聊天里索取、打印或粘贴密钥。
使用 TokenLab 预设及所选模型的文档所述 API 格式。
先检查配置能否加载，执行小型真实请求前说明费用。
核对回复与 TokenLab 中对应的请求记录。
```

## 连接方式

[OpenCodex](https://github.com/lidge-jun/opencodex) 是 Codex 与模型 API 之间的本地代理。本指南使用 **OpenCodex 2.73.0** 和 **Codex CLI 0.149.0**。

TokenLab 预设的 Chat Completions 接入已在 2.72.0 发布并完成端到端验证。[2.73.0](https://github.com/lidge-jun/opencodex/releases/tag/v2.73.0) 保留该接入，并增加按模型选择 Responses 和 Anthropic Messages 的路由。下表所列路径均已通过 TokenLab 真实请求验证流式文本及函数调用、结果回传。

Codex 向**本地 OpenCodex 代理**发送 Responses 请求，OpenCodex 再通过所选模型对应的接口调用 **TokenLab**。本地连接使用 Responses，不代表模型一定通过 TokenLab 的 Responses API 调用。

| 在 Codex 中选择的模型 | OpenCodex → TokenLab |
| - | - |
| `gpt-6-astra`、`gpt-6.1-sol`、`gpt-6-sol`、`gpt-6-luna`、`grok-4.7`、`deepseek-v4.1-flash`、`deepseek-v4-pro`、`kimi-k3`、`glm-5.3` | Responses：`POST /v1/responses` |
| `claude-opus-5`、`claude-opus-5-5`、`claude-sonnet-5`、`claude-sonnet-5-5`、`claude-fable-5`、`claude-fable-5-1` | Anthropic Messages：`POST /v1/messages` |
| `gemini-3.8-flash` | Chat Completions：`POST /v1/chat/completions` |

预设的 Base URL 为 `https://api.tokenlab.sh/v1`。保留这个地址，OpenCodex 会自行构造相应的 Messages 或 Responses URL。未列入 Responses 默认路由和 Claude 路由的模型使用预设的 Chat 适配器。

TokenLab 为声明支持 Gemini 原生 API 的模型提供该接口，但 **OpenCodex 2.73.0 的 TokenLab 预设通过 Chat Completions 调用 Gemini**。不要把整个提供商改成 Responses 或 Gemini，否则其他不接受该格式的模型也会被切换。

## 安装或更新

npm 安装需要 Node.js 18 或更新版本：

```bash theme={null}
npm install -g @bitkyc08/opencodex@2.73.0
ocx --version
codex --version
```

还需安装 Codex。OpenCodex 提供[安装说明](https://opencodex.me/getting-started/installation/)和 [Codex 连接步骤](https://opencodex.me/getting-started/quickstart/)。原生 Windows 与 WSL 使用不同的配置，请在同一环境中完成设置并运行 Codex。

## 添加 TokenLab

在 [TokenLab API Keys](https://tokenlab.sh/dashboard/api?tab=keys) 创建密钥。终端设置请按[快速开始](/zh/quickstart)设置 `TOKENLAB_API_KEY`，避免把密钥值写入命令历史。从同一终端启动 OpenCodex；后台服务需要在自身的启动环境中获得该变量。

**首次安装 OpenCodex** 时，运行 `ocx init`，选择 TokenLab，在本机输入密钥或使用字面量环境变量引用 `${TOKENLAB_API_KEY}`。应用前检查向导中的 Codex 连接与自动启动选项。

**已有 OpenCodex 配置** 时，添加预设并保留其他提供商：

```bash theme={null}
ocx provider add tokenlab --api-key '${TOKENLAB_API_KEY}'
```

单引号保存的是环境变量引用，不是密钥值；此命令也适用于 PowerShell。如果 `tokenlab` 已存在，请在 Dashboard 中编辑该提供商，不要用 `--force` 覆盖。

也可以在 Dashboard 的 **Add provider** 列表选择 **TokenLab**，在本机表单输入密钥。OpenCodex 的配置位于 `$OPENCODEX_HOME/config.json`，通常为 `~/.opencodex/config.json`。

代理尚未运行时先启动，再打开 Dashboard：

```bash theme={null}
ocx start
ocx status
ocx gui
```

在提供商页面核对 Base URL 与发现的模型。预设通过 `GET /v1/models?category=chat` 获取模型，只保留具备 `tool-use` 能力的聊天模型；图像、视频、音频、嵌入与决策模型不在此列表中。带密钥的模型发现结果受该密钥的模型权限和交付策略约束。

运行 `ocx sync` 连接 Codex 并刷新模型目录，然后新建 Codex 会话。这会改变 Codex 的代理连接与目录；同步前检查已有自定义提供商设置并保留备份，无需替换账户或权限策略。

## 选择模型并验证请求

在 Codex 的模型选择器中选择 `tokenlab/<model-id>`，或为本次 CLI 启动指定模型：

```bash theme={null}
codex -m "tokenlab/gpt-6.1-sol"
```

OpenCodex 使用 `tokenlab/` 选择提供商，发送给 TokenLab 的模型 ID 是 `gpt-6.1-sol`。请从[模型页](https://tokenlab.sh/zh/models)选择当前可用的完整 ID。

发送一条小型连接检查请求：

```text theme={null}
只回复 TOKENLAB_CONNECTION_OK，不要使用工具或修改文件。
```

这条请求会使用 TokenLab 余额。核对回复，以及[请求记录](https://tokenlab.sh/dashboard/runs?section=requests)中对应的模型、时间和状态。成功发现模型或启动代理不能单独证明推理权限有效。

表中路径支持流式输出与函数调用。图片输入和思考控制取决于所选模型：检查模型能力，并仅使用 OpenCodex 为该模型提供的思考强度选项。Responses 和 Messages 路径已抽样验证图片输入及思考请求，Gemini 的图片输入已通过 Chat 路径验证。支持思考的模型不一定返回思考文本，也不一定支持所有强度。

## 让 Responses 模型使用 Chat Completions

如果需要让表中某个 Responses 模型使用 Chat，在 OpenCodex 配置**已有的** `providers.tokenlab` 对象中合并一条 `modelAdapters` 设置。下面示例让 Codex 中的 `gpt-6-astra` 使用 Chat：

```json theme={null}
{
  "modelAdapters": {
    "gpt-6-astra": "openai-chat"
  }
}
```

这是提供商字段示例，不是完整配置的替代文件。保留其他模型覆盖设置、凭据和提供商，修改后重启代理并新建 Codex 会话。只删除该模型条目，即可恢复它的 Responses 默认路由。

Claude 的 Messages 路由绑定于标准 TokenLab 端点。上面的 Chat 覆盖适用于 Responses 默认模型，不能将 Claude 切到 Chat。使用 Chat 原生客户端时，表中的 Responses 模型本就走 Chat，无需添加此覆盖。参见 [OpenCodex 提供商路由说明](https://opencodex.me/guides/providers/#3-api-key-catalog)。

## 交付策略与其他 TokenLab 工具

预设不强制发送 `X-TokenLab-Delivery-Policy`，TokenLab 使用 API Key 的默认交付策略。选择 Chat、Responses 或 Messages，与选择交付策略是两项独立设置，参见 [TokenLab 提供商设置](/zh/guides/tokenlab-provider)。

需要其他 API 工具时，添加 [TokenLab MCP 服务器](/zh/integrations/tokenlab-mcp-server)；需要集成说明时，添加 [TokenLab Skills](/zh/integrations/coding-agent-skill)。它们不会改变主模型的提供商或 API 格式。

**OpenCodex 2.73.0 的 JEV Auto 使用 TypeSafe 决策后端，不能选择 TokenLab 作为该后端。** 通过 MCP 调用 TokenLab 的 [System One API](/zh/api-reference/systemone/create-decision)是另一项操作，请勿把 TokenLab 密钥填入 TypeSafe 凭据字段。

## 排障与恢复原设置

* **模型选择器中没有 TokenLab：** 检查 `ocx --version`，本指南适用于 2.73.0。运行 `ocx sync` 刷新目录并新建 Codex 会话。
* **401 或缺少凭据：** 检查密钥是否有效，以及运行 OpenCodex 的进程能否读取密钥。在其他终端设置环境变量，不会更新已启动的服务。
* **缺少模型：** 检查完整 ID、密钥权限与当前可用状态。非聊天模型及没有 `tool-use` 的聊天模型不在此预设目录中。
* **不支持的请求或端点错误：** 对照路由表检查所选模型及已保存的适配器覆盖设置。所需格式以[模型详情](/zh/api-reference/models/get-model)中的 `tokenlab.accepted_request_formats` 为准，模型列表不能替代该详情字段。不能因为 Codex 在本地使用 Responses，就把 Claude 和 Gemini 发到 Responses。
* **工具或图片输入失败：** 保留原始错误与 请求 ID，先核对模型能力及实际 OpenCodex 路径，再修改设置；不要靠删除历史或工具结果掩盖错误。

需要让 Codex 停止经过代理时，运行 `ocx stop`，OpenCodex 会停止代理并恢复 Codex 的原生连接。`ocx restore` 在保留代理供其他客户端使用的同时恢复原生连接。修改供多个客户端共用的安装前，请阅读 [OpenCodex CLI 参考](https://opencodex.me/reference/cli/)。