> ## 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}
Read https://docs.tokenlab.sh/zh-Hant/integrations/opencodex and help me connect OpenCodex to TokenLab.
Check my installed OpenCodex and Codex versions, active configuration, and running proxy first.
Preserve existing accounts, providers, models, and permissions. Back up files before changing them.
Have me enter the API key locally; never ask for, print, or paste it in chat.
Use the TokenLab preset and the selected model's documented API format.
Check configuration loading first. Explain the cost before running a small real request.
Match the reply with its TokenLab request record.
```

## 連線運作方式

[OpenCodex](https://github.com/lidge-jun/opencodex) 是位於 Codex 與模型 API 之間的本機 Proxy。本指南使用 **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 會將 Responses 請求傳送至**本機 OpenCodex Proxy**。接著 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**。請勿將整個 Provider 變更為 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 金鑰](https://tokenlab.sh/dashboard/api?tab=keys)中建立金鑰。終端機設定方面，請依照[快速入門](/zh-Hant/quickstart)設定 `TOKENLAB_API_KEY`，以避免將其值留在指令歷程記錄中。請從該終端機啟動 OpenCodex；背景服務則需要在其專屬的啟動環境中取得該變數。

若是**全新安裝 OpenCodex**，請執行 `ocx init`，選取 TokenLab，並於本機輸入金鑰或使用字面環境變數參照 `${TOKENLAB_API_KEY}`。在套用設定前，請先檢閱精靈中的 Codex 連線與自動啟動選項。

若是**現有安裝**，可以在不取代其他 Provider 的情況下新增此預設組態：

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

單引號會儲存環境變數的參照，而非金鑰本身的值。此指令亦適用於 PowerShell。若 `tokenlab` 已存在，請在儀表板中編輯該 Provider，而非使用 `--force` 進行覆寫。

您也可以在儀表板的 **Add provider** 清單中選擇 **TokenLab** 並在該處輸入金鑰。OpenCodex 會將其組態儲存於 `$OPENCODEX_HOME/config.json`，通常為 `~/.opencodex/config.json`。

若 Proxy 尚未執行，請啟動它，然後開啟其儀表板：

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

在 Provider 頁面中，檢查 Base URL 與探索到的模型。該預設組態會透過 `GET /v1/models?category=chat` 探索模型，並保留具有 `tool-use` 功能的模型。圖片、影片、音訊、Embeddings 及 Decision 模型均已排除。使用金鑰進行探索會反映該金鑰的模型權限與交付原則。

執行 `ocx sync` 以連線 Codex 並重新整理其模型目錄，接著啟動新的 Codex 工作階段。這將會變更 Codex 的 Proxy 連線與目錄；在同步之前，請檢閱現有的自訂 Provider 設定並保留備份。這不需要替換您的帳號或權限原則。

## 選取模型並驗證請求

在 Codex 的模型選取器中選擇 `tokenlab/<model-id>` 項目，或在單次 CLI 啟動時指定：

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

OpenCodex 使用 `tokenlab/` 來選擇 Provider；傳送給 TokenLab 的模型 ID 則是 `gpt-6.1-sol`。請從[模型](https://tokenlab.sh/zh-TW/models)中選擇目前可用的確切 ID。

若要進行小規模連線檢查，請傳送：

```text theme={null}
Reply only with TOKENLAB_CONNECTION_OK. Do not use tools or modify files.
```

此請求將會取用您的 TokenLab 餘額。請在[請求](https://tokenlab.sh/dashboard/runs?section=requests)中查看回覆以及其對應的模型、時間與狀態。僅憑 Provider 探索與成功啟動並不能驗證推論存取權限。

表格中所列的路由皆支援串流與函式呼叫。圖片輸入與思考控制取決於所選模型：請檢查其功能，並僅使用 OpenCodex 針對該模型提供的 effort 選項。已在 Responses 與 Messages 路由的代表性模型上檢查了圖片輸入與思考請求；Gemini 圖片輸入則在其 Chat 路由上進行了檢查。支援思考的模型不一定會公開思考文字或支援所有 effort 等級。

## 將 Responses 模型保留在 Chat Completions

若要針對列出的其中一個 Responses 模型使用 Chat 路徑，請在 OpenCodex 組態中將 `modelAdapters` 項目合併至**現有的** `providers.tokenlab` 物件中。此範例為 Codex 將 `gpt-6-astra` 保留在 Chat：

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

這是一個 Provider 欄位範例，而非完整組態的替代品。請保留其他模型覆寫、憑證以及 Provider，接著重新啟動 Proxy 並開啟新的 Codex 工作階段。僅移除此模型項目即可恢復其 Responses 預設值。

Claude 的 Messages 路由繫結至 TokenLab 的標準端點。上述的 Chat 覆寫僅適用於 Responses 預設值；它不會將 Claude 切換至 Chat。對於原生支援 Chat 的客戶端，列出的 Responses 模型無需此覆寫即可直接使用 Chat。請參閱 [OpenCodex Provider 路由](https://opencodex.me/guides/providers/#3-api-key-catalog)。

## 交付原則與其他 TokenLab 工具

該預設組態不會強制加入 `X-TokenLab-Delivery-Policy` 標頭。TokenLab 會使用您 API 金鑰的預設交付原則。選擇 Chat、Responses 或 Messages 與選擇交付原則是分開的；請參閱 [TokenLab Provider 設定](/zh-Hant/guides/tokenlab-provider)。

新增 [TokenLab MCP 伺服器](/zh-Hant/integrations/tokenlab-mcp-server)以使用其他 API 工具，或參閱 [TokenLab Skills](/zh-Hant/integrations/coding-agent-skill) 取得整合指示。這些都不會變更主模型的 Provider 或 API 格式。

\*\*OpenCodex 2.73.0 中的 JEV Auto 使用 TypeSafe 的決策後端。\*\*它並未提供 TokenLab 作為該後端。透過 MCP 呼叫 TokenLab 的 [System One API](/zh-Hant/api-reference/systemone/create-decision) 是一項獨立的操作；請勿將 TokenLab 金鑰填入 TypeSafe 的憑證欄位中。

## 疑難排解與還原設定

* \*\*選取器中遺漏 TokenLab：\*\*檢查 `ocx --version`；本指南適用於 2.73.0。使用 `ocx sync` 重新整理目錄並啟動新的 Codex 工作階段。
* \*\*401 或遺失憑證：\*\*確認金鑰處於有效狀態，且執行 OpenCodex 的程序可以存取該金鑰。在另一個終端機設定環境變數並不會更新已在執行的服務。
* \*\*遺漏模型：\*\*檢查確切的 ID、您金鑰的權限以及目前的可用性。非 Chat 模型以及不具備 `tool-use` 的 Chat 模型未包含在此預設組態中。
* \*\*不支援的請求或錯誤的端點：\*\*比對所選模型與路由表，並檢查已儲存的配接器覆寫設定。所需的格式為[模型詳細資料](/zh-Hant/api-reference/models/get-model)中的 `tokenlab.accepted_request_formats`；模型清單無法取代該詳細資料欄位。不得僅因 Codex 在本機使用 Responses，就將 Claude 與 Gemini 傳送至 Responses。
* \*\*工具或圖片輸入失敗：\*\*保留原始錯誤訊息與 Request ID。在變更設定之前，請先檢查模型的功能與作用中的 OpenCodex 路由；請勿為了掩蓋錯誤而刪除對話歷程記錄或工具執行結果。

若要停止透過 Proxy 路由 Codex，請使用 `ocx stop`；OpenCodex 將會停止 Proxy 並還原原生 Codex 連線。`ocx restore` 則會在維持 Proxy 運作以供其他客戶端使用的同時，還原原生連線。在變更與其他客戶端共用的安裝環境前，請先檢閱 [OpenCodex CLI 參考文件](https://opencodex.me/reference/cli/)。