# opencodex: dùng mọi LLM với Codex và Claude Code — hướng dẫn cài đặt

> opencodex là gateway chạy cục bộ, giúp Codex, Claude Code, Claude Desktop và nhiều công cụ khác dùng được Claude, Gemini, Grok, DeepSeek, Ollama cùng nhiều LLM khác. Cài bằng npm khá đơn giản; bạn cần Node 18 trở lên, sau đó cấu hình nhà cung cấp trong dashboard trên máy.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-09 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/opencodex-dung-moi-llm-voi-codex-claude-code

opencodex là một gateway cục bộ giúp các công cụ lập trình AI dùng được nhiều nhà cung cấp mô hình khác nhau. Thay vì bị cố định vào một model hoặc một dịch vụ, bạn có thể kết nối Codex, Claude Code, Claude Desktop, Grok Build và nhiều công cụ khác qua một điểm trung gian trên máy của mình.

Điểm đáng giá nhất là opencodex giữ lại giao diện và quy trình quen thuộc của công cụ bạn đang dùng, nhưng cho phép đổi provider, đổi model, tạo model kết hợp có cơ chế dự phòng hoặc chia tải. Repo viết bằng TypeScript, có CLI tên `ocx`, dashboard web và bản desktop beta.

Công cụ này phù hợp với lập trình viên, đội kỹ thuật, nhân viên văn phòng muốn thử nhiều mô hình và người vận hành nhiều tài khoản AI. Người mới có thể bắt đầu bằng bản npm. Người cần triển khai nội bộ có thể dùng Docker Compose, còn người muốn tính năng mới nhất có thể cài từ nhánh `dev`.

```repo
- repo | lidge-jun/opencodex
- kind | CLI
- desc | Gateway cục bộ kết nối Codex, Claude Code và nhiều công cụ lập trình với hơn 40 nhà cung cấp LLM.
- stars | 18k
- lang | TypeScript
- license | MIT
```

## opencodex làm được gì

### Kết nối nhiều công cụ AI qua một gateway

opencodex nhận các giao thức OpenAI Responses, Chat Completions và Anthropic Messages, rồi chuyển đổi yêu cầu sang định dạng mà provider đích hỗ trợ. Nhờ vậy, bạn có thể dùng Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama và các provider khác trong cùng quy trình.

Bạn không phải thay đổi toàn bộ cách làm việc mỗi khi đổi model. Codex vẫn chạy bằng lệnh `codex`, Claude Code vẫn dùng CLI `claude`, còn việc chọn provider và model được quản lý ở dashboard.

### Hỗ trợ hơn 40 provider và endpoint tương thích OpenAI

Dashboard có hơn 40 provider tích hợp sẵn. Ngoài ra, bạn có thể thêm một endpoint tương thích OpenAI bất kỳ nếu provider đó không có trong danh sách dựng sẵn.

Điều này hữu ích khi công ty dùng gateway riêng, nhóm kỹ thuật có proxy nội bộ hoặc bạn chạy model cục bộ qua Ollama.

### Tạo combo có dự phòng hoặc chia tải

Combo cho phép gom nhiều provider thành một model ảo. Bạn có thể cấu hình failover để chuyển sang provider khác khi provider chính gặp lỗi, hoặc dùng weighted round-robin để phân phối yêu cầu theo tỷ trọng.

Với nhóm dùng AI hằng ngày, tính năng này giúp giảm gián đoạn khi một tài khoản hết hạn mức hoặc một dịch vụ tạm thời không phản hồi.

### Chạy sub-agent trên model tùy chọn

opencodex hỗ trợ đưa các model đã định tuyến vào danh sách chọn sub-agent của Codex. Bạn có thể kiểm soát bề mặt v1/v2 và thiết lập chuỗi fallback.

Cách này phù hợp khi muốn model mạnh xử lý nhiệm vụ chính, còn model rẻ hoặc nhanh hơn xử lý việc phụ như viết test, tìm file hoặc tóm tắt lỗi.

### Đăng nhập OAuth hoặc dùng API key

README nêu các lựa chọn gồm OAuth cho xAI, Anthropic và Kimi, chuyển tiếp `codex login`, dán API key hoặc dùng tham chiếu dạng `${ENV_VAR}`.

Dashboard cũng hiển thị trạng thái OAuth và provider. Bạn có thể quản lý tài khoản, model và lựa chọn provider tại một nơi.

### Hỗ trợ web search và hình ảnh qua sidecar

Các model không phải OpenAI có thể nhận web search và khả năng hiểu hình ảnh thông qua sidecar dùng đăng nhập ChatGPT, khi client, model và provider hỗ trợ.

Tính năng này giúp mở rộng khả năng của model mà không cần đổi công cụ lập trình đang dùng.

### Có dashboard và log yêu cầu trực tiếp

Dashboard chạy trên `http://localhost:10100` theo mặc định. Tại đây bạn xem provider, trạng thái OAuth, model đang chọn và log yêu cầu trực tiếp, gồm cả số token cache.

Khi cần kiểm tra model nào đang được gọi hoặc một yêu cầu có đi qua gateway hay chưa, log này là nơi nên xem đầu tiên.

### Tự khôi phục cấu hình Codex khi dừng

Lệnh `ocx stop` khôi phục Codex về cấu hình ban đầu. Đây là điểm hữu ích khi bạn chỉ muốn thử gateway trong một khoảng thời gian mà không muốn để lại cấu hình proxy lâu dài.

README cũng mô tả các bộ nhớ dài hạn của tiến trình đều có giới hạn hoặc cơ chế dọn dẹp. Mức ngân sách bộ nhớ ứng dụng mặc định được nêu là 256 MiB, ngoại trừ kho replay điều khiển native được ghim.

## Cần chuẩn bị gì

- Máy macOS arm64 hoặc x64, Linux x64 hoặc arm64, hoặc Windows x64. README đánh dấu cả ba nền tảng là được hỗ trợ đầy đủ.
- Node.js 18 trở lên nếu cài CLI bằng npm. Bun được đóng gói tự động khi cài npm, nên không cần cài Bun riêng và Windows không cần WSL.
- npm để cài gói `@bitkyc08/opencodex`.
- Tài khoản hoặc API key của provider bạn muốn dùng. README cũng hỗ trợ OAuth cho một số provider, tham chiếu biến môi trường hoặc chuyển tiếp đăng nhập Codex.
- Công cụ client tương ứng nếu muốn kết nối Codex, Claude Code, Claude Desktop, Grok Build hoặc công cụ khác. Ví dụ, Claude Code cần CLI `claude` được cài sẵn.
- Nếu dùng Docker Compose: Git và Docker Compose cho bản clone cục bộ. Cách dùng remote Git context cần Docker Compose và BuildKit giữ metadata Git.
- Nếu dùng bản desktop beta: không cần Node hoặc Bun. Windows cần bản x64, macOS cần macOS 13 trở lên, Linux dùng gói x86_64 được cung cấp.

README không nói rằng mọi provider đều miễn phí. Chi phí, hạn mức và điều kiện sử dụng phụ thuộc tài khoản hoặc dịch vụ bạn thêm vào.

## Cài đặt từng bước

```steps
- Cài CLI | Cài gói npm toàn cục và runtime Bun đi kèm
- Khởi động gateway | Chạy proxy và dashboard trên localhost
- Mở dashboard | Thêm provider, tài khoản và model
- Kết nối công cụ | Bật Codex hoặc chạy lệnh tích hợp cho client
- Kiểm tra trạng thái | Dùng status, doctor, health hoặc gọi endpoint kiểm tra
```

### Cài CLI bằng npm

Mở Terminal trên macOS hoặc Linux, hoặc PowerShell trên Windows. Chạy lệnh sau:

```bash
npm install -g --allow-scripts=bun @bitkyc08/opencodex
```

Lệnh này cài CLI `ocx` trên toàn hệ thống. Tùy chọn `--allow-scripts=bun` cho phép cài runtime Bun được đóng gói cùng gói npm. README yêu cầu Node 18 trở lên.

Nếu npm chặn script cài runtime đi kèm, README hướng dẫn xem tài liệu cài đặt của dự án để xử lý trường hợp đó. Không tự đổi tên gói hoặc bỏ tùy chọn này nếu chưa biết nguyên nhân, vì runtime Bun được dùng bên trong opencodex.

### Khởi động proxy và dashboard

Sau khi cài xong, chạy:

```bash
ocx start
```

Lệnh này khởi động proxy và dashboard ở cổng `10100`. Mở trình duyệt đến địa chỉ sau:

```text
http://localhost:10100
```

Bạn cũng có thể chạy gateway ở chế độ nền:

```bash
ocx service
```

Nếu terminal đang chạy `ocx start`, hãy để tiến trình hoạt động trong khi cấu hình dashboard. Nếu đóng terminal, hãy dùng `ocx service` để chạy nền.

### Thêm provider và model trong dashboard

Trong dashboard, thêm provider từ danh sách có sẵn hoặc thêm endpoint tương thích OpenAI. Sau đó chọn model và quản lý tài khoản theo hướng dẫn hiển thị.

README không cung cấp tên biến môi trường hoặc biểu mẫu API key cụ thể cho từng provider trong phần nội dung được cung cấp. Vì vậy, hãy điền key đúng vào phần cấu hình của provider trên dashboard, không tự đặt thêm tên biến hoặc đường dẫn.

Có thể mở lại dashboard bất cứ lúc nào bằng:

```bash
ocx gui
```

Nếu muốn dùng OAuth, chọn provider có hỗ trợ OAuth và hoàn thành luồng đăng nhập. README nêu OAuth cho xAI, Anthropic và Kimi.

### Khởi tạo kết nối với Codex

Để thiết lập tương tác với Codex, chạy:

```bash
ocx init
```

Lệnh này là thiết lập tương tác, ghi cấu hình vào `~/.opencodex/config.json` và kết nối Codex với gateway. Lệnh không tự khởi động proxy. Bạn có thể chạy `ocx start` trước hoặc sau `ocx init`, nhưng các lệnh không tương tác như thêm provider hoặc combo cần proxy đang hoạt động.

README cũng nói `ocx init` sẽ hiện lời nhắc Codex để bạn chấp nhận cấu hình. Đọc kỹ lời nhắc trước khi xác nhận.

Sau đó, trên trang **Connect** của dashboard, bật công tắc Codex. Khi hoàn tất, dùng Codex như bình thường.

### Kết nối Claude Code

Bạn cần cài CLI `claude` trước. Khi đã có CLI, chạy:

```bash
ocx claude
```

Lệnh này khởi động proxy nếu cần rồi mở Claude Code thông qua gateway. Đây là cách đơn giản để Claude Code dùng provider và model đã cấu hình trong opencodex.

### Kết nối Claude Desktop

Chạy:

```bash
ocx claude desktop
```

Ở lần cài mới, lệnh thiết lập gateway profile cho toàn bộ ứng dụng. Nếu đã có cấu hình chính chủ, cấu hình đó được giữ lại. Muốn chuyển rõ ràng sang gateway, chạy:

```bash
ocx claude desktop apply --gateway
```

Sau khi đổi cấu hình, thoát hoàn toàn Claude Desktop rồi mở lại. Chỉ đóng cửa sổ có thể chưa đủ để ứng dụng nạp profile mới.

### Kết nối tool khác

Với công cụ có tích hợp được quản lý, dùng dashboard **Connect** hoặc chạy:

```bash
ocx integration client enable --client <id>
```

Nếu công cụ không có tích hợp dựng sẵn, đặt base URL OpenAI-compatible là:

```text
http://localhost:10100/v1
```

Nếu công cụ dùng Anthropic API, đặt base URL là:

```text
http://localhost:10100
```

README không cung cấp danh sách `<id>` cụ thể trong phần được gửi. Hãy dùng đúng ID mà trang hỗ trợ client hoặc dashboard hiển thị.

### Cài bằng Docker Compose

Nếu muốn chạy gateway trong container, clone repo rồi chạy các lệnh sau:

```bash
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
docker compose build
openssl rand -hex 32 | docker compose run --rm -T hub bun run docker/bootstrap-token.ts
docker compose up -d
curl --fail --silent http://127.0.0.1:10100/healthz
curl --fail --silent http://127.0.0.1:10100/readyz
```

`git clone` tải mã nguồn về máy, còn `cd opencodex` đưa terminal vào đúng thư mục. `docker compose build` tạo image. Lệnh `openssl` tạo token ngẫu nhiên rồi truyền qua stdin cho bước khởi tạo token. Token và dữ liệu thay đổi được lưu trong volume tên `ocx-state`.

Mặc định Docker chỉ bind trên `127.0.0.1:10100`. Nếu mở cho mạng LAN hoặc Tailscale, README yêu cầu đặt rõ `OPENCODEX_BIND_ADDRESS`, giới hạn bằng firewall và dùng frontend có TLS cùng xác thực. Không nên dùng `0.0.0.0` nếu chưa hiểu rủi ro vì giá trị này mở trên mọi interface của máy.

### Cài từ mã nguồn nhánh dev

Trên macOS hoặc Linux:

```bash
curl -fsSL https://bun.sh/install | bash
git clone -b dev https://github.com/lidge-jun/opencodex.git
cd opencodex && ~/.bun/bin/bun install
~/.bun/bin/bun run build:gui
~/.bun/bin/bun run src/cli/index.ts start
```

Trên Windows PowerShell:

```powershell
irm bun.sh/install.ps1 | iex
git clone -b dev https://github.com/lidge-jun/opencodex.git
cd opencodex; bun install
bun run build:gui
bun run src/cli/index.ts start
```

Cách này dùng nhánh `dev`, nơi có các thay đổi chưa chắc đã có trong gói npm. Chỉ nên dùng khi bạn cần bản mới nhất hoặc muốn phát triển từ mã nguồn.

## Kiểm tra đã chạy được chưa

Cách dễ nhất là mở `http://localhost:10100`. Nếu dashboard hiện ra, proxy đã khởi động và đang lắng nghe trên cổng mặc định.

Với bản Docker Compose, hai lệnh sau phải chạy thành công và không trả lỗi:

```bash
curl --fail --silent http://127.0.0.1:10100/healthz
curl --fail --silent http://127.0.0.1:10100/readyz
```

Bạn cũng có thể kiểm tra trạng thái bằng các lệnh:

```bash
ocx status
ocx doctor
ocx health
```

README mô tả các lệnh này dùng để báo cáo trạng thái đang chạy. Sau khi thêm provider, hãy xem provider và model xuất hiện trong dashboard, rồi chạy thử một yêu cầu nhỏ bằng client đã kết nối.

Ví dụ với Codex:

```bash
codex -m "anthropic/claude-opus-5" "Explain this stack trace"
```

Nếu yêu cầu trả về kết quả và log dashboard ghi nhận request, đường kết nối từ Codex qua opencodex đến provider đã hoạt động.

## Dùng vào việc thật

### Lập trình viên cần đổi model theo loại công việc

Một dev có thể chọn model Anthropic để phân tích stack trace:

```bash
codex -m "anthropic/claude-opus-5" "Explain this stack trace"
```

Khi viết test cho file xác thực, dùng model Google:

```bash
codex -m "google/gemini-3-pro" "Write unit tests for auth.ts"
```

Khi muốn thử model chạy cục bộ qua Ollama:

```bash
codex -m "ollama/llama3" "Refactor this function"
```

Kết quả là cùng một cách gọi `codex`, nhưng model được chọn theo nhiệm vụ. Bạn không cần đổi công cụ chỉ vì muốn thử provider khác.

### Nhóm kỹ thuật cần giảm gián đoạn khi provider lỗi

Một trưởng nhóm có thể tạo combo gồm provider chính và provider dự phòng trong dashboard. Khi provider chính lỗi hoặc hết hạn mức, combo chuyển sang provider tiếp theo theo cấu hình failover.

Với nhóm có nhiều tài khoản, weighted round-robin giúp phân phối yêu cầu theo tỷ trọng. Kết quả thực tế là quy trình làm việc ít bị dừng hơn, nhưng chất lượng và chi phí vẫn phụ thuộc những model nằm trong combo.

### Nhân viên văn phòng muốn dùng một công cụ với nhiều tài khoản AI

Một nhân viên có thể cấu hình các tài khoản provider trong dashboard, sau đó dùng công cụ client quen thuộc qua base URL OpenAI-compatible:

```text
http://localhost:10100/v1
```

Dashboard cho phép xem model, trạng thái OAuth và log yêu cầu. Khi cần kiểm tra một câu hỏi đã được gửi đến provider nào, người dùng có thể xem request log thay vì dò nhiều ứng dụng riêng lẻ.

### Người phát triển cần chạy gateway nội bộ bằng Docker

Một devops có thể clone repo, build Compose và khởi tạo token qua stdin:

```bash
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
docker compose build
openssl rand -hex 32 | docker compose run --rm -T hub bun run docker/bootstrap-token.ts
docker compose up -d
```

Sau đó kiểm tra readiness bằng endpoint `readyz`. Dữ liệu trạng thái nằm trong volume `ocx-state`, còn cấu hình bind mặc định chỉ mở trên localhost. Nếu cần truy cập từ máy khác, phải dùng địa chỉ bind rõ ràng, firewall và lớp TLS có xác thực.


> Một gateway giúp bạn đổi “bộ não” phía sau mà vẫn giữ nguyên cách làm việc phía trước.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### `ocx` không được nhận diện sau khi cài

Thường là npm đã cài gói nhưng thư mục binary toàn cục chưa có trong PATH của terminal. Hãy đóng và mở lại terminal, kiểm tra Node và npm, rồi chạy lại lệnh cài đặt. Không tự tải một file binary khác nếu chưa xác định đúng cách cài của hệ điều hành.

### Bun runtime không được cài vì npm chặn script

Gói npm cần script để cài runtime Bun đi kèm. Hãy kiểm tra chính sách script của npm và xem hướng dẫn cài đặt trong repo hoặc tài liệu dự án cho trường hợp npm đã chặn script. Windows không cần WSL và không cần cài Bun riêng khi cài npm thành công.

### Dashboard không mở được ở cổng 10100

Có thể proxy chưa chạy, cổng đã bị tiến trình khác chiếm hoặc bạn đã đóng terminal sau khi chạy `ocx start`. Chạy lại `ocx start`, thử `ocx service`, rồi kiểm tra bằng `ocx status` hoặc `ocx health`.

Nếu dùng Docker, kiểm tra container đã chạy bằng `docker compose up -d` và gọi lại `/healthz`. Không đổi sang cổng hoặc địa chỉ khác nếu chưa cấu hình theo hướng dẫn của repo.

### Codex hoặc Claude Code không dùng model đã chọn

Với Codex, hãy bật công tắc trên trang **Connect** và cân nhắc chạy `ocx init` để nối cấu hình. Với Claude Code, cần chạy `ocx claude` thay vì mở CLI độc lập nếu muốn đi qua gateway.

Nếu vừa đổi provider, hãy kiểm tra provider và model trong dashboard. Với Grok Build, README yêu cầu khởi động lại proxy hoặc chạy `ocx ensure` khi Codex autostart được bật để làm mới danh sách model.

### Docker bị lộ ra mạng ngoài

Mặc định Compose bind trên `127.0.0.1`, nhưng việc đặt `OPENCODEX_BIND_ADDRESS` có thể mở gateway ra LAN hoặc toàn bộ interface. Chỉ mở khi cần, giới hạn bằng firewall và đặt frontend TLS có xác thực. Token không nên đặt trong image, file Compose, biến môi trường hoặc tham số shell.

## Có nên dùng không

opencodex đáng dùng nếu bạn đang sử dụng Codex, Claude Code hoặc nhiều công cụ lập trình AI và muốn thử nhiều model mà không thay đổi toàn bộ quy trình. Dashboard, hơn 40 provider, combo failover, hỗ trợ OAuth, log trực tiếp và khả năng kết nối endpoint tương thích OpenAI là những điểm mạnh rõ ràng.

Bản npm phù hợp với người mới vì chỉ cần Node 18 trở lên và vài lệnh CLI. Docker Compose phù hợp với môi trường cần chạy ổn định hoặc tách gateway khỏi máy làm việc. Bản desktop beta thuận tiện cho người không muốn cài Node, nhưng vẫn nên xem xét trạng thái beta và yêu cầu riêng của từng nền tảng.

Giới hạn chính là opencodex không thay thế tài khoản hoặc chi phí của provider. Chất lượng, tốc độ, hạn mức và quyền riêng tư vẫn phụ thuộc model cùng dịch vụ bạn cấu hình. README cũng không cung cấp chi tiết giá cho từng provider trong phần này.

Nếu bạn chỉ dùng một model, không cần đổi công cụ và muốn cấu hình ít nhất có thể, dùng trực tiếp CLI hoặc API chính thức có thể đơn giản hơn. Nếu cần nhiều model, fallback, tích hợp nhiều client hoặc muốn quản lý tập trung, opencodex là lựa chọn hợp lý. Repo dùng giấy phép MIT, nhưng bạn vẫn nên kiểm tra điều khoản riêng của từng provider trước khi đưa dữ liệu công việc nhạy cảm vào hệ thống.

## Câu hỏi thường gặp

### opencodex có miễn phí không?

Repo dùng giấy phép MIT. Tuy nhiên README không nói opencodex miễn phí ở mọi khía cạnh, và chi phí gọi model phụ thuộc tài khoản hoặc provider bạn cấu hình.

### Có cần GPU để chạy opencodex không?

README không yêu cầu GPU cho gateway. Bạn có thể kết nối provider đám mây hoặc Ollama, nhưng tài liệu được cung cấp không nêu yêu cầu phần cứng cụ thể cho việc chạy model cục bộ.

### Windows có chạy được không?

Có. Windows x64 được đánh dấu hỗ trợ đầy đủ, CLI cần Node 18 trở lên, không cần WSL và Bun được đóng gói khi cài từ npm. Dự án cũng có bản desktop MSI x64.

### Dữ liệu có an toàn không?

Gateway mặc định chạy trên localhost và Docker Compose mặc định bind trên `127.0.0.1:10100`. Khi mở ra mạng khác, README yêu cầu firewall, TLS có xác thực và quản lý token an toàn; dữ liệu gửi đến provider vẫn phụ thuộc chính sách của provider đó.

### Có cần cài Bun riêng không?

Không khi cài CLI bằng npm, vì runtime Bun được đóng gói và cài tự động. Nếu cài từ mã nguồn, README hướng dẫn cài Bun riêng bằng script tương ứng với macOS, Linux hoặc Windows.

### Có dùng được với Claude Code và Codex cùng lúc không?

Có. opencodex có lệnh kết nối riêng cho Claude Code, hỗ trợ `ocx init` và công tắc Codex trong dashboard. Hai công cụ có thể dùng các provider hoặc model được cấu hình qua cùng gateway.

### Khác gì so với việc gọi trực tiếp API của một provider?

opencodex thêm một lớp gateway để nhiều client dùng nhiều provider qua cùng quy trình. Nó hỗ trợ đổi model, combo failover, weighted round-robin, log và dashboard; nếu bạn chỉ dùng một API thì gọi trực tiếp có thể đơn giản hơn.
