Nexus Composer

Nexus Composer là desktop app cho phép các AI agent đội bạn đang dùng gọi model do OneNexus host — không phải đổi công cụ, cũng không phải tự sửa proxy settings hay model ID.

Codex Desktop, Codex CLI và VS Code là các agent Composer hỗ trợ hiện nay, và chúng tôi đang bổ sung thêm agent. Guide này viết cho Codex vì đó là agent đã có hôm nay, không phải vì Composer chỉ chạy được với Codex.

Composer cho phép bạn chuyển active provider của từng client — không bao giờ gửi cùng lúc tới cả OpenAI Official và OneNexus. Khi chọn OneNexus, local proxy sẽ convert protocol của client rồi forward request.

Composer phải luôn chạy

Khi client đang route qua OneNexus, request đi qua local proxy của Composer. Nếu bạn thoát Composer, các request đó sẽ lỗi. Hãy để Composer chạy, hoặc chuyển client về provider cũ trước.

Bạn cần gì

Yêu cầu	Chi tiết
Pilot access	OneNexus pilot account và tenant đã được duyệt — nếu chưa có, hãy đăng ký pilot access.
Hệ điều hành	macOS 14 trở lên trên Apple Silicon. Windows x64 và Linux (Ubuntu 24.04+) sắp có. Hiện chưa hỗ trợ Mac Intel và Windows on ARM.
Client	Codex Desktop, Codex CLI hoặc VS Code — các agent được hỗ trợ hiện nay. Chúng tôi đang bổ sung thêm.
Nexus API key	Platform API key từ Console. Mở Khóa API (API Keys) → Tạo khóa API (Generate API key), đặt Loại (Type) thành Platform, rồi copy secret khi Console hiển thị.
ChatGPT login	Chỉ cần cho model OpenAI Official trong Codex.
Network	Outbound access tới OneNexus, và tới OpenAI khi dùng OpenAI Official.

Inference key chỉ authorize Served Model Name của các self-hosted model đã chọn, không gọi được hosted model catalog mà Composer sử dụng; replacement dùng chung một Served Model Name đã authorize sẽ dùng chung access. Platform key chính là credential Composer cần — key gọi được mọi model đã publish trong catalog, kể cả model được thêm sau này, và không thể thu hẹp scope. Nếu không chắc, hãy kiểm tra cột Loại (Type) trong Khóa API (API Keys): Platform key sẽ hiển thị Platform.

Composer tự kiểm tra client version tương thích — sau khi cài, mở Settings → About để lấy yêu cầu hiện tại, thay đổi theo từng client release.

Download và cài Composer

Chỉ tải installer từ trang download Nexus Composer chính thức, nơi validate release manifest và mọi installer đang được cung cấp trước khi cho phép download.

Nếu download tạm thời không dùng được, hãy reload trang sau hoặc liên hệ đầu mối onboarding — không tải installer từ mirror không chính thức.

macOS trên Apple Silicon

1. Download file .dmg cho macOS từ trang chính thức.
2. Mở disk image và làm theo hướng dẫn cài đặt bên trong.
3. Mở Nexus Composer từ Applications, rồi eject disk image.

Signing và notarization có thể thay đổi trong giai đoạn pilot. Nếu macOS chặn installer, hãy xác nhận file đến từ trang chính thức, rồi hỏi đầu mối onboarding trước khi bỏ qua cảnh báo.

Mở Composer lần đầu

1. Mở Nexus Composer và đọc first-run notice trước khi đóng.
2. Mở Settings bằng biểu tượng bánh răng và ở lại tab General.

Bạn có thể quản lý route OpenAI Official mà không cần Nexus account. Model do OneNexus host cần Platform key ở phần tiếp theo.

Kết nối Nexus account

Chưa có Platform key?

Tạo trước khi tiếp tục, trong OneNexus Console: Khóa API → Tạo khóa API, đặt Loại thành Platform. Copy secret ngay lúc dialog hiển thị — nó không hiện lại lần nào nữa. Platform quickstart đi qua đúng màn hình này kèm ảnh minh họa.

Chỉ Platform dùng được ở đây. Loại này gọi được mọi catalog model đã publish — đúng thứ Composer route tới; key chỉ scoped tới self-hosted model của bạn không chạm được catalog đó. Đừng thử lần lượt từng secret để đoán: xem cột Loại trong Khóa API.

Trong Settings → General → Nexus Account:

1. Dán Platform key vào Nexus API Key, rồi chọn Connect.
2. Đợi Composer validate và xác nhận status là Connected.
3. Kiểm tra username và tenant đang hiển thị đúng là của bạn. Nếu sai, dừng lại và liên hệ đầu mối onboarding.

Sau khi kết nối thành công, Composer validate key, lưu vào credential store của hệ điều hành, download catalog được quản lý sẵn và chỉ cập nhật những client profile thuộc quyền quản lý của Composer — các Codex settings, MCP configuration, skill và session khác giữ nguyên.

Dùng Replace API Key để kết nối key mới, hoặc Forget key để xóa credential đã lưu.

Connected kèm username và tenant đúng của bạn. Sai một trong hai thì dừng lại ở đây.

Không để lộ API key

Không bao giờ dán Nexus API key vào screenshot, log, support message, Git repository, prompt hay configuration file sửa tay. Nếu key bị lộ, hãy revoke trong console rồi kết nối key mới.

Kiểm tra client installation

Mở Settings → About. Composer detect từng client được hỗ trợ, so sánh version tìm thấy với version cần thiết, đồng thời cảnh báo khi có nhiều installation xung đột.

Nếu thiếu Codex CLI, dùng Install. Nếu Composer tìm thấy nhiều Codex installation, chọn Diagnose installs và xác nhận shell của bạn thực sự chạy executable nào trước khi thay đổi.

Mỗi client được đối chiếu với version Composer cần. Diagnose installs là nút dùng khi Composer thấy nhiều bản Codex.

Trước request đầu tiên

Dữ liệu của bạn không được lưu lại

Prompt và output không được lưu lại, và không được dùng để train hay fine-tune model OneNexus. Xem Pilot & security.

Trong guide này, hãy mở một conversation mới và chỉ dùng test prompt giả lập sau:

Reply with exactly: OneNexus connection is working.

Chọn client

Composer đổi route cho từng client một. Chọn client của bạn.

Codex Desktop

Card mang nhãn Effective route mới là nơi request thực sự đi tới.

Codex Desktop mặc định chạy trên OpenAI Official và giữ nguyên như vậy cho tới khi bạn đổi — Composer hiển thị card đó là Active. OneNexus nằm ngay cạnh kèm nút Select, và chưa có gì thay đổi cho tới khi bạn bấm nút đó.

1. Bấm Select trên card OneNexus để route Codex qua OneNexus. Đợi tới khi card đó hiển thị Active và không kèm warning nào.

2. Thoát Codex Desktop — không phải chỉ đóng cửa sổ — rồi mở lại. Nó giữ route lúc khởi động.

3. Trong conversation mới, mở model picker. Các model OneNexus giờ nằm ngay cạnh model của OpenAI — chọn model bạn cần rồi bắt đầu cuộc chat đầu tiên.

   

   Model OneNexus có tiền tố là tên provider, nên dễ phân biệt với model của OpenAI.

Muốn model từ OpenAI Official vẫn chọn được song song với model OneNexus thì hãy đăng nhập ChatGPT trong Codex Desktop. Composer tự quản lý OneNexus catalog — model nào xuất hiện phụ thuộc vào tenant, availability hiện tại và việc Codex đã restart sau lần catalog thay đổi gần nhất hay chưa.

Không dùng ChatGPT login. Trên card OneNexus, mở settings và bật Use OneNexus without ChatGPT sign-in, rồi restart Codex Desktop. Mode này chỉ publish OneNexus catalog tương thích và có thể ẩn model từ OpenAI Official — tắt option này khi muốn chuyển qua lại giữa hai provider từ model picker.

Codex CLI

Một card dùng chung cho cả hai client Codex — không có route riêng cho CLI.

Codex CLI dùng chung Codex route của Composer, nên card bạn chọn cũng chính là card Codex Desktop dùng.

1. Bấm Select trên card OneNexus để route Codex qua OneNexus. Đợi tới khi card đó hiển thị Active và không kèm warning nào.

2. Thoát mọi Codex CLI process đang chạy, rồi khởi động lại Codex trong terminal mới — process đang chạy vẫn giữ configuration lúc nó khởi động.

3. Xác nhận một model OneNexus đang được chọn, rồi bắt đầu cuộc chat đầu tiên.

   

   Cảnh báo đỏ là bình thường: base URL bị override đó chính là local proxy của Composer. Khác với Codex Desktop, CLI liệt kê model OneNexus không kèm tiền tố provider — chúng là các mục nằm dưới nhóm gpt-.

Hãy restart CLI sau mỗi lần đổi provider, không chỉ lần đầu này.

VS Code

Tab VS Code trong Composer mở ra trang có tiêu đề Visual Studio Code chat.

Route này áp cho Chat agent tích hợp sẵn của VS Code. Mặc định nó chạy trên GitHub Copilot và giữ nguyên như vậy cho tới khi bạn đổi — Composer hiển thị card đó là Active. OneNexus nằm ngay cạnh kèm nút Select, và chưa có gì thay đổi cho tới khi bạn bấm nút đó.

1. Bấm Select trên card OneNexus để route VS Code Chat qua OneNexus. Đợi tới khi card đó hiển thị Active và không kèm warning nào.

2. Mở hoặc reload VS Code để nó nhận model group mới.

3. Trong conversation Chat mới, chọn một model OneNexus rồi bắt đầu cuộc chat đầu tiên.

   

   VS Code ghi tên provider ở bên phải mỗi model. Chỉ model đang dùng nằm ở trên cùng — mở nhóm Other Models để thấy những model còn lại.

Composer thêm chúng vào dưới dạng một model group do nó quản lý, và trong VS Code chúng là text-only — không gửi được ảnh hay file đính kèm.

Usage và proxy

Cuộc chat bạn vừa gửi sẽ xuất hiện trong Settings → Usage Statistics, kèm application, provider và model. Đó là local record của Composer về các AI request nó đã route — chỉ mở Composer thì không tạo record, và cost hiển thị là ước tính chứ không phải invoice. Xem Skill, prompt và MCP để hiểu các field và giới hạn của view này.

Để kiểm tra proxy, mở Settings → Routing, mở rộng Local Routing rồi xác nhận service đang Running. Service chỉ listen trên 127.0.0.1, bound vào loopback interface — dùng Restart ngay tại màn hình đó nếu unhealthy.

Running trên card Local Routing là tín hiệu cần thấy. Không có nó thì client đang route qua OneNexus không có gì để gọi.

Chuyển về provider cũ trước khi thoát

Client vẫn route qua OneNexus sẽ lỗi khi Composer thoát, vì request của nó phụ thuộc vào local proxy.

Với Codex Desktop hoặc Codex CLI:

1. Mở Codex trong Composer rồi chọn OpenAI Official.
2. Đợi route trở thành active.
3. Restart Codex client và verify bằng một OpenAI Official request không chứa dữ liệu nhạy cảm.

Với VS Code, chọn GitHub Copilot trên trang VS Code, rồi reload VS Code. Composer chỉ gỡ đúng model group nó đã thêm; phần model configuration còn lại của VS Code được giữ nguyên.

Đổi provider không xóa session, dù conversation chứa encrypted reasoning state có thể vẫn lỗi khi resume qua backend khác; khi đó hãy quay về provider đã tạo conversation hoặc mở conversation mới. Xem Khắc phục sự cố Composer.

Để Composer chạy background là lựa chọn đơn giản hơn — đóng cửa sổ có thể chỉ minimize app, tùy Settings → General → Window Behavior.

Bước tiếp theo

• Skill, prompt và MCP — quản lý tool dùng lại được của Codex và hiểu local usage statistics.
• Khắc phục sự cố Composer — bắt đầu từ symptom và chuẩn bị thông tin an toàn cho support.
• Protocol conversion — hiểu local proxy gửi gì tới từng upstream provider.
• Platform quickstart — gọi model do OneNexus host trực tiếp từ code của bạn.