> ## 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

> Connect Codex to TokenLab through OpenCodex with model-specific API routing

## Let my agent set this up

Copy this task to an agent already running on your computer:

```text theme={null}
Read https://docs.tokenlab.sh/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.
```

## How the connection works

[OpenCodex](https://github.com/lidge-jun/opencodex) is a local proxy between Codex and model APIs. This guide uses **OpenCodex 2.73.0** and **Codex CLI 0.149.0**.

The TokenLab preset's Chat Completions integration was released and verified end to end in 2.72.0. [Version 2.73.0](https://github.com/lidge-jun/opencodex/releases/tag/v2.73.0) keeps that integration and adds model-specific Responses and Anthropic Messages routing. The routes listed below have been checked against TokenLab with streamed text and function-call/result round trips.

Codex sends Responses requests to the **local OpenCodex proxy**. OpenCodex then sends the selected model's request to **TokenLab**. A Responses request on the local connection does not mean that the model is called through TokenLab's Responses API.

| Models selected in 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` |

The preset's Base URL is `https://api.tokenlab.sh/v1`. Keep it unchanged: OpenCodex builds the matching Messages or Responses URL itself. Models outside the listed Responses defaults and Claude routing use the preset's Chat adapter.

TokenLab supports Gemini's native API for models that declare it, but **the OpenCodex 2.73.0 TokenLab preset calls Gemini through Chat Completions**. Do not change the entire provider to Responses or Gemini; that would also change requests for models that do not accept that format.

## Install or update

Use Node.js 18 or later for the npm installation:

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

Codex must also be installed. OpenCodex provides [installation](https://opencodex.me/getting-started/installation/) and [Codex connection instructions](https://opencodex.me/getting-started/quickstart/). Native Windows and WSL have separate configurations; run setup and Codex in the same environment.

## Add TokenLab

Create a key in [TokenLab API Keys](https://tokenlab.sh/dashboard/api?tab=keys). For terminal setup, follow [Quickstart](/quickstart) to set `TOKENLAB_API_KEY` without putting its value in command history. Start OpenCodex from that terminal; a background service needs the variable in its own launch environment.

For a **fresh OpenCodex installation**, run `ocx init`, select TokenLab, and enter the key locally or use the literal environment reference `${TOKENLAB_API_KEY}`. Review the wizard's Codex connection and autostart choices before applying them.

For an **existing installation**, add the preset without replacing other providers:

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

The single quotes save an environment-variable reference, not the key's value. This command also works in PowerShell. If `tokenlab` already exists, edit that provider in the dashboard instead of overwriting it with `--force`.

You can also choose **TokenLab** in the dashboard's **Add provider** list and enter the key there. OpenCodex saves its configuration under `$OPENCODEX_HOME/config.json`, normally `~/.opencodex/config.json`.

Start the proxy if it is not already running, then open its dashboard:

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

In the provider page, check the Base URL and discovered models. The preset discovers `GET /v1/models?category=chat` and keeps models with `tool-use` capability. Images, video, audio, embeddings, and decision models are excluded. Discovery with a key reflects that key's model permissions and delivery policy.

Run `ocx sync` to connect Codex and refresh its model catalog, then start a new Codex session. This changes Codex's proxy connection and catalog; review existing custom-provider settings and keep a backup before syncing. It does not require replacing your account or permission policy.

## Select a model and verify a request

Choose the `tokenlab/<model-id>` entry in Codex's model picker, or select it for one CLI launch:

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

OpenCodex uses `tokenlab/` to select the provider; the model ID sent to TokenLab is `gpt-6.1-sol`. Choose an exact currently available ID from [Models](https://tokenlab.sh/en/models).

For a small connection check, send:

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

This request uses your TokenLab balance. Check the reply and its matching model, time, and status in [Requests](https://tokenlab.sh/dashboard/runs?section=requests). Provider discovery and successful startup alone do not verify inference access.

Streaming and function calling work on the routes in the table. Image input and thinking controls depend on the selected model: check its capabilities, and use only the effort choices OpenCodex offers for that model. Image input and thinking requests were checked on representative models for the Responses and Messages routes; Gemini image input was checked on its Chat route. A model that supports thinking does not necessarily expose thinking text or support every effort level.

## Keep a Responses model on Chat Completions

To use the Chat path for one of the listed Responses models, merge a `modelAdapters` entry into the **existing** `providers.tokenlab` object in OpenCodex's configuration. This example keeps `gpt-6-astra` on Chat for Codex:

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

This is a provider-field example, not a replacement for the full configuration. Preserve other model overrides, credentials, and providers, then restart the proxy and open a new Codex session. Removing only this model entry restores its Responses default.

Claude's Messages routing is tied to the canonical TokenLab endpoint. The Chat override above applies to the Responses defaults; it does not switch Claude to Chat. For a Chat-native client, the listed Responses models already use Chat without this override. See [OpenCodex provider routing](https://opencodex.me/guides/providers/#3-api-key-catalog).

## Delivery policy and other TokenLab tools

The preset does not force an `X-TokenLab-Delivery-Policy` header. TokenLab uses your API key's delivery-policy default. Choosing Chat, Responses, or Messages is separate from choosing a delivery policy; see [TokenLab provider settings](/guides/tokenlab-provider).

Add the [TokenLab MCP server](/integrations/tokenlab-mcp-server) for other API tools, or [TokenLab Skills](/integrations/coding-agent-skill) for integration instructions. These do not change the main model's provider or API format.

**JEV Auto in OpenCodex 2.73.0 uses TypeSafe's decision backend.** It does not offer TokenLab as that backend. Calling TokenLab's [System One API](/api-reference/systemone/create-decision) through MCP is a separate operation; do not put a TokenLab key in the TypeSafe credential field.

## Troubleshooting and restoring your setup

* **TokenLab is missing from the picker:** check `ocx --version`; this guide targets 2.73.0. Refresh the catalog with `ocx sync` and start a new Codex session.
* **401 or missing credentials:** check the key is active and available to the process running OpenCodex. An environment variable in a different terminal does not update an already running service.
* **Model is missing:** check the exact ID, your key's permissions, and current availability. Non-chat models and chat models without `tool-use` are not included in this preset.
* **Unsupported request or wrong endpoint:** compare the selected model with the routing table and inspect saved adapter overrides. The required format is `tokenlab.accepted_request_formats` in [model details](/api-reference/models/get-model); the model list is not a substitute for that detail field. Claude and Gemini must not be sent to Responses merely because Codex uses Responses locally.
* **Tools or image input fail:** keep the original error and Request ID. Check the model's capabilities and the active OpenCodex route before changing settings; do not remove conversation history or tool results to hide an error.

To stop routing Codex through the proxy, use `ocx stop`; OpenCodex stops the proxy and restores the native Codex connection. `ocx restore` restores the native connection while keeping the proxy running for other clients. Review the [OpenCodex CLI reference](https://opencodex.me/reference/cli/) before changing an installation shared by other clients.