Skip to main content

​
Let my agent set this up

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

​
How the connection works

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 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. 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:
Codex must also be installed. OpenCodex provides installation and Codex connection instructions. Native Windows and WSL have separate configurations; run setup and Codex in the same environment.

​
Add TokenLab

Create a key in TokenLab API Keys. For terminal setup, follow 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:
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:
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:
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. For a small connection check, send:
This request uses your TokenLab balance. Check the reply and its matching model, time, and status in 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:
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.

​
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. Add the TokenLab MCP server for other API tools, or TokenLab Skills 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 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; 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 before changing an installation shared by other clients.