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

> Kết nối Codex với TokenLab thông qua OpenCodex bằng định tuyến API theo từng mô hình

## Hãy để agent của tôi thiết lập việc này

Sao chép tác vụ này vào một agent đang chạy trên máy tính của bạn:

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

## Cách thức hoạt động của kết nối

[OpenCodex](https://github.com/lidge-jun/opencodex) là một proxy cục bộ giữa Codex và các API mô hình. Hướng dẫn này sử dụng **OpenCodex 2.73.0** và **Codex CLI 0.149.0**.

Tích hợp Chat Completions của preset TokenLab đã được phát hành và kiểm chứng toàn trình (end-to-end) trong phiên bản 2.72.0. [Phiên bản 2.73.0](https://github.com/lidge-jun/opencodex/releases/tag/v2.73.0) giữ nguyên tích hợp đó và bổ sung định tuyến Responses cũng như Anthropic Messages riêng cho từng mô hình. Các tuyến định tuyến liệt kê dưới đây đã được kiểm tra với TokenLab bằng văn bản truyền theo luồng (streamed text) và các chu kỳ gọi hàm/trả kết quả (function-call/result round trips).

Codex gửi các yêu cầu Responses tới **proxy OpenCodex cục bộ**. Sau đó OpenCodex sẽ gửi yêu cầu của mô hình đã chọn tới **TokenLab**. Một yêu cầu Responses trên kết nối cục bộ không có nghĩa là mô hình đó được gọi thông qua Responses API của TokenLab.

| Các mô hình được chọn trong 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 của preset là `https://api.tokenlab.sh/v1`. Hãy giữ nguyên giá trị này: OpenCodex tự động xây dựng URL Messages hoặc Responses tương ứng. Các mô hình nằm ngoài cấu hình mặc định Responses được liệt kê và định tuyến Claude sẽ sử dụng adapter Chat của preset.

TokenLab hỗ trợ API gốc của Gemini cho các mô hình có khai báo, nhưng **preset TokenLab của OpenCodex 2.73.0 gọi Gemini thông qua Chat Completions**. Không thay đổi toàn bộ provider thành Responses hoặc Gemini; điều đó cũng sẽ làm thay đổi các yêu cầu đối với những mô hình không chấp nhận định dạng đó.

## Cài đặt hoặc cập nhật

Sử dụng Node.js 18 trở lên cho việc cài đặt qua npm:

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

Codex cũng phải được cài đặt. OpenCodex cung cấp [hướng dẫn cài đặt](https://opencodex.me/getting-started/installation/) và [hướng dẫn kết nối Codex](https://opencodex.me/getting-started/quickstart/). Windows gốc và WSL có các cấu hình riêng biệt; hãy chạy thiết lập và Codex trong cùng một môi trường.

## Thêm TokenLab

Tạo một khóa trong [TokenLab API Keys](https://tokenlab.sh/dashboard/api?tab=keys). Đối với thiết lập qua terminal, hãy làm theo [Bắt đầu nhanh](/vi/quickstart) để thiết lập `TOKENLAB_API_KEY` mà không lưu giá trị của nó vào lịch sử lệnh. Khởi động OpenCodex từ terminal đó; một dịch vụ chạy ngầm cần biến môi trường này trong môi trường khởi chạy riêng của nó.

Đối với **bản cài đặt OpenCodex mới**, hãy chạy `ocx init`, chọn TokenLab, rồi nhập khóa trực tiếp trên máy cục bộ hoặc sử dụng tham chiếu biến môi trường nguyên văn `${TOKENLAB_API_KEY}`. Xem lại các tùy chọn kết nối Codex và tự động khởi động (autostart) của trình hướng dẫn trước khi áp dụng.

Đối với **bản cài đặt hiện có**, thêm preset mà không thay thế các provider khác:

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

Dấu ngoặc đơn giúp lưu lại tham chiếu biến môi trường chứ không phải giá trị của khóa. Lệnh này cũng hoạt động trong PowerShell. Nếu `tokenlab` đã tồn tại, hãy chỉnh sửa provider đó trong dashboard thay vì ghi đè bằng `--force`.

Bạn cũng có thể chọn **TokenLab** trong danh sách **Add provider** của dashboard và nhập khóa tại đó. OpenCodex lưu cấu hình của nó tại `$OPENCODEX_HOME/config.json`, thông thường là `~/.opencodex/config.json`.

Khởi động proxy nếu nó chưa chạy, sau đó mở dashboard của nó:

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

Tại trang provider, kiểm tra Base URL và các mô hình đã được phát hiện. Preset này truy vấn `GET /v1/models?category=chat` và giữ lại các mô hình có khả năng `tool-use`. Hình ảnh, video, âm thanh, embeddings và các mô hình đưa ra quyết định (decision models) đều bị loại trừ. Quá trình phát hiện cùng với khóa API sẽ phản ánh quyền truy cập mô hình và delivery policy của khóa đó.

Chạy `ocx sync` để kết nối Codex và làm mới danh mục mô hình, sau đó bắt đầu một phiên Codex mới. Thao tác này sẽ thay đổi kết nối proxy và danh mục của Codex; hãy xem lại các cài đặt provider tùy chỉnh hiện có và sao lưu trước khi đồng bộ. Thao tác này không yêu cầu thay thế tài khoản hoặc chính sách cấp quyền của bạn.

## Chọn mô hình và xác minh yêu cầu

Chọn mục `tokenlab/<model-id>` trong bộ chọn mô hình của Codex, hoặc chọn nó cho một lần khởi chạy CLI:

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

OpenCodex sử dụng `tokenlab/` để chọn provider; ID mô hình gửi tới TokenLab là `gpt-6.1-sol`. Hãy chọn chính xác một ID hiện đang khả dụng từ [Models](https://tokenlab.sh/vi/models).

Để kiểm tra kết nối nhanh, hãy gửi:

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

Yêu cầu này sẽ sử dụng số dư TokenLab của bạn. Kiểm tra phản hồi cùng với mô hình, thời gian và trạng thái tương ứng trong [Requests](https://tokenlab.sh/dashboard/runs?section=requests). Chỉ riêng việc phát hiện provider và khởi động thành công là chưa đủ để xác minh quyền truy cập suy luận (inference access).

Streaming và function calling hoạt động trên các tuyến trong bảng. Đầu vào hình ảnh và các tùy chỉnh thinking phụ thuộc vào mô hình được chọn: hãy kiểm tra các khả năng của mô hình và chỉ sử dụng các mức effort mà OpenCodex cung cấp cho mô hình đó. Các yêu cầu đầu vào hình ảnh và thinking đã được kiểm tra trên các mô hình đại diện cho các tuyến Responses và Messages; đầu vào hình ảnh của Gemini đã được kiểm tra trên tuyến Chat của nó. Một mô hình hỗ trợ thinking không nhất thiết phải hiển thị văn bản thinking hoặc hỗ trợ mọi mức effort.

## Giữ mô hình Responses ở lại Chat Completions

Để sử dụng đường dẫn Chat cho một trong các mô hình Responses được liệt kê, hãy hợp nhất một mục `modelAdapters` vào đối tượng `providers.tokenlab` **hiện có** trong cấu hình của OpenCodex. Ví dụ này giữ `gpt-6-astra` trên Chat cho Codex:

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

Đây là ví dụ về một trường của provider, không phải là nội dung thay thế toàn bộ cấu hình. Hãy giữ lại các ghi đè mô hình, thông tin xác thực và provider khác, sau đó khởi động lại proxy và mở một phiên Codex mới. Chỉ xóa mục mô hình này sẽ khôi phục lại mặc định Responses của nó.

Định tuyến Messages của Claude được liên kết với endpoint TokenLab chuẩn. Ghi đè Chat ở trên chỉ áp dụng cho các cấu hình mặc định của Responses; nó không chuyển Claude sang Chat. Đối với client hỗ trợ Chat gốc, các mô hình Responses được liệt kê đã tự động sử dụng Chat mà không cần ghi đè này. Xem [OpenCodex provider routing](https://opencodex.me/guides/providers/#3-api-key-catalog).

## Delivery policy và các công cụ TokenLab khác

Preset không bắt buộc dùng header `X-TokenLab-Delivery-Policy`. TokenLab sử dụng delivery policy mặc định của API key của bạn. Việc lựa chọn Chat, Responses, hoặc Messages tách biệt với việc chọn delivery policy; xem [TokenLab provider settings](/vi/guides/tokenlab-provider).

Thêm [TokenLab MCP server](/vi/integrations/tokenlab-mcp-server) cho các công cụ API khác, hoặc [TokenLab Skills](/vi/integrations/coding-agent-skill) để xem hướng dẫn tích hợp. Những công cụ này không làm thay đổi provider hoặc định dạng API của mô hình chính.

**JEV Auto trong OpenCodex 2.73.0 sử dụng backend quyết định của TypeSafe.** Tính năng này không cung cấp TokenLab làm backend đó. Việc gọi [System One API](/vi/api-reference/systemone/create-decision) của TokenLab thông qua MCP là một tác vụ riêng biệt; không nhập khóa TokenLab vào trường thông tin xác thực của TypeSafe.

## Khắc phục sự cố và khôi phục thiết lập của bạn

* **Thiếu TokenLab trong bộ chọn:** kiểm tra `ocx --version`; hướng dẫn này dành cho phiên bản 2.73.0. Làm mới danh mục bằng `ocx sync` và bắt đầu một phiên Codex mới.
* **Lỗi 401 hoặc thiếu thông tin xác thực:** kiểm tra xem khóa có đang hoạt động và khả dụng cho tiến trình đang chạy OpenCodex hay không. Biến môi trường trong một terminal khác sẽ không cập nhật cho dịch vụ đang chạy sẵn.
* **Mô hình bị thiếu:** kiểm tra chính xác ID, quyền của khóa và tính khả dụng hiện tại. Các mô hình non-chat và mô hình chat không có khả năng `tool-use` sẽ không được bao gồm trong preset này.
* **Yêu cầu không được hỗ trợ hoặc sai endpoint:** so sánh mô hình đã chọn với bảng định tuyến và kiểm tra các ghi đè adapter đã lưu. Định dạng bắt buộc là `tokenlab.accepted_request_formats` trong [chi tiết mô hình](/vi/api-reference/models/get-model); danh sách mô hình không thể thay thế cho trường chi tiết đó. Claude và Gemini không được gửi tới Responses chỉ vì Codex sử dụng Responses cục bộ.
* **Công cụ hoặc đầu vào hình ảnh bị lỗi:** giữ lại lỗi gốc và Request ID. Kiểm tra khả năng của mô hình và tuyến OpenCodex đang hoạt động trước khi thay đổi cài đặt; không xóa lịch sử hội thoại hoặc kết quả công cụ để ẩn lỗi.

Để dừng định tuyến Codex qua proxy, hãy sử dụng `ocx stop`; OpenCodex sẽ dừng proxy và khôi phục kết nối Codex gốc. Lệnh `ocx restore` sẽ khôi phục kết nối gốc trong khi vẫn duy trì proxy hoạt động cho các client khác. Xem lại [tài liệu tham khảo OpenCodex CLI](https://opencodex.me/reference/cli/) trước khi thay đổi một bản cài đặt được chia sẻ với các client khác.