Từ con số 0: nối ZCode với API key riêng của bạn

Vấn đề

ZCode cài xong là dùng được ngay, vì nó đã chọn sẵn một nhà cung cấp tích hợp. Nhưng nếu chìa khóa bạn đang có thuộc về một gateway phục vụ nhiều dòng mô hình, thẻ tích hợp đó không dùng được: địa chỉ, giao thức và danh sách mô hình đều đã cố định trong thẻ.

Cách xử lý là tạo một nhà cung cấp tùy chỉnh. Biểu mẫu có sáu ô, nhưng chỉ bốn ô quyết định kết nối thành công hay không, và điều khó là biết mỗi ô lấy giá trị từ đâu.

Trước khi vào chi tiết, xin nói rõ ba thuật ngữ sẽ dùng suốt bài:

• Gateway: dịch vụ API trung gian mà bạn mua hạn mức mô hình. Nó nhận yêu cầu, chọn mô hình và trả kết quả.
• Token / API key: chuỗi bí mật dùng để chứng minh bạn có quyền gọi gateway. Không phải mật khẩu đăng nhập.
• Endpoint: địa chỉ cụ thể mà yêu cầu được gửi tới. Ở đây, địa chỉ gốc và đường dẫn là hai thứ khác nhau.

Bối cảnh: hai đối tượng khác nhau

Trong phần cài đặt, một nhà cung cấp là gói tham số kết nối cộng với danh sách mô hình. Một cuộc hội thoại chỉ là con trỏ tới một nhà cung cấp trong số đó.

Hai thứ này nằm ở hai màn hình khác nhau và không tự đồng bộ. Đó là lý do nhiều người cấu hình xong, thấy nhà cung cấp hiện trong danh sách bên trái, nhưng cửa sổ chat vẫn dùng nhà cung cấp cũ.

Hiểu được điểm này thì phần còn lại chỉ là thao tác.

Chuẩn bị

Hạng mục	Giá trị dùng trong bài
Hệ điều hành	Windows 11
Ứng dụng	ZCode desktop, giao diện tháng 10/2026
Mô hình ví dụ	glm-5.3
Cần điền	Base URL, định dạng API, API key, ID mô hình

Ứng dụng có bản cho Windows, macOS và Linux trên trang chính thức (https://zcode.z.ai/). Toàn bộ ảnh trong bài được chụp trên bản Windows.

Bước 1: Cài đặt và bỏ qua hai màn hình đầu

Chạy bộ cài, mở ứng dụng từ menu Start. Lần đầu sẽ có hai màn hình.

Màn hình thứ nhất hỏi hướng công việc — mười hai lựa chọn từ phát triển phần mềm đến tài chính. Câu trả lời chỉ ảnh hưởng cách ứng dụng gợi ý, không liên quan đến việc có kết nối được endpoint riêng hay không. Bấm 「跳过」 (bỏ qua) ở góc dưới bên trái.

Màn hình thứ hai yêu cầu kết nối tài khoản: danh sách thả xuống đang trỏ vào dịch vụ tích hợp, bên dưới là ô nhập API key của dịch vụ đó. Đây không phải chỗ dành cho khóa của bạn, nên bấm 「暂时跳过」 (bỏ qua tạm thời).

Cả hai đều là bước giới thiệu, không phải cấu hình. Nhà cung cấp được thêm sau, trong cùng cửa sổ cài đặt.

Bước 2: Lấy API key

ZCode lưu một token của gateway. Trong bảng điều khiển của gateway, tạo token mới, đặt tên dễ nhận ra, rồi sao chép ngay: phần lớn bảng điều khiển chỉ hiển thị đầy đủ một lần.

Hạn mức, thời hạn và quyền trên mô hình nằm ở bảng điều khiển, không nằm trong ứng dụng. Ứng dụng chỉ gắn khóa vào yêu cầu. Cách tính phí thường theo lượng dùng thực tế; số dư và các chương trình hiện hành xem trên trang của bảng điều khiển tại thời điểm bạn kiểm tra.

Ví dụ trong bài dùng Crazyrouter, nhưng cách điền bốn trường là như nhau với mọi gateway tương thích.

Bước 3: Tạo nhà cung cấp tùy chỉnh

Trong phần cài đặt, cột bên trái chia hai nhóm: nhóm cơ bản (常规, 外观, 模型设置 — tức cài đặt mô hình, 浏览器控制 và vài mục khác) và nhóm Agent (bộ nhớ, tác nhân con, plugin, máy chủ MCP, kỹ năng, lệnh, hook).

Mở 「模型设置」, bấm 「新增供应商」 (thêm nhà cung cấp) ở góc trên bên phải. Bảng hiện ra chia hai nửa: phía trên là các thẻ tích hợp, chỉ cần khóa; phía dưới, trong mục 「其他」, là danh sách nhà cung cấp phổ biến, mục đầu tiên là 「创建自定义供应商」 (tạo nhà cung cấp tùy chỉnh).

Khác biệt duy nhất là ai cung cấp tham số kết nối. Thẻ tích hợp cố định địa chỉ và giao thức; nhà cung cấp tùy chỉnh để bạn tự nhập cả hai, cùng danh sách mô hình. Gateway không nằm trong danh sách tích hợp, hoặc endpoint tự dựng, đều đi theo đường này.

Bước 4: Điền bốn trường

Biểu mẫu gồm: tên, công tắc bật/tắt, Base URL, định dạng API, API key, danh sách mô hình.

Tên chỉ là nhãn trong danh sách bên trái. Đặt tên dễ nhận như 「团队网关」 để sau này chọn nhóm trong danh sách mô hình không bị nhầm.

Base URL là địa chỉ gốc của gateway, dừng ở tên miền:

https://api.crazyrouter.com

Không thêm /v1, cũng không thêm /messages. Địa chỉ và giao thức là hai trường riêng; đường dẫn do ô định dạng bên dưới quyết định. Tự nối đường dẫn vào địa chỉ là cách chắc chắn nhất để nhận lỗi 404.

Định dạng API là mục có chứa /v1/messages. Ô này quyết định cả đường dẫn gửi yêu cầu lẫn cách phân tích phản hồi, nên phải khớp với giao thức mà gateway thực sự mở. Chọn sai thường ra 400 hoặc 404, không phải lỗi xác thực. Ngoài ra /v1/messages và /v1/chat/completions là hai cấu trúc dữ liệu khác nhau: địa chỉ đúng cũng không cứu được định dạng sai.

API key là token ở bước 2. Bấm biểu tượng con mắt để kiểm tra: thừa một dấu cách ở đầu hoặc thiếu vài ký tự ở cuối đều ra 401, trông giống hệt khóa sai. Khóa chỉ lưu trong cấu hình máy, đừng dán vào khung chat hay ảnh chụp màn hình.

Danh sách mô hình: bấm 「+ 新增模型」 rồi dán ID. Một dòng là đủ để bắt đầu; các dòng khác dùng chung địa chỉ và khóa. Mỗi dòng có công tắc riêng, mô hình bị tắt sẽ không xuất hiện trong danh sách chọn khi chat.

Trước khi rời trang, kiểm tra công tắc nhà cung cấp ở trên cùng đang bật. Biểu mẫu chưa lưu thì coi như chưa tạo.

Bước 5: Thêm mô hình và kiểm tra trong hội thoại

Không nên gõ ID bằng tay. Mở danh mục mô hình trong bảng điều khiển, gõ glm vào ô tìm kiếm — danh sách lọc ngay, ảnh chụp cho thấy mười kết quả trong 170 mô hình. Mỗi thẻ có liên kết chi tiết và một biểu tượng sao chép ID; dùng biểu tượng đó rồi dán vào biểu mẫu, giữ nguyên chữ hoa chữ thường.

Một nhà cung cấp có thể chứa nhiều mô hình: địa chỉ và khóa quyết định đi tới gateway nào, ID quyết định gọi mô hình nào bên trong. Vì vậy thêm mô hình thứ hai không có nghĩa là nhập lại khóa, cũng không cần tạo nhà cung cấp mới.

Lưu lại, mở hội thoại mới, trong danh sách chọn mô hình chọn nhóm nhà cung cấp trước rồi chọn mô hình, gửi một câu ngắn. Nếu có phản hồi, tên mô hình hiện ở góc dưới bên phải khung nhập, kèm mức độ suy luận.

Có một cái bẫy hay gặp: cấu hình đã đúng, mô hình trả lời bình thường, nhưng yêu cầu vẫn đi qua nhà cung cấp cũ. Hội thoại đang mở không tự chuyển sang nhà cung cấp mới thêm. Phải chuyển nhóm ở thanh chọn mô hình dưới khung nhập; sau đó yêu cầu mới thực sự mang khóa của bạn.

Không thấy mô hình trong danh sách thì kiểm tra ba chỗ theo thứ tự: công tắc nhà cung cấp, công tắc từng dòng mô hình, biểu mẫu đã lưu chưa. Cả ba đều đúng mà vẫn không thấy, thoát khỏi cài đặt rồi vào lại để danh sách tải lại.

Kết quả

Sau khi hoàn tất, mọi yêu cầu từ hội thoại đó đi qua gateway của bạn. Đổi mô hình chỉ là chọn một dòng khác trong danh sách, không phải sửa cấu hình.

Về chi phí, đây là mô hình trả theo lượng dùng: bạn trả cho token tiêu thụ, mức giá tùy mô hình. Chi phí ẩn là thời gian — mỗi lần chọn nhầm nhóm hoặc để khóa hết hạn, bạn mất vài phút mà không có thông báo lỗi nào.

Chọn mô hình

Tên trong họ glm có quy luật: số phiên bản, rồi hậu tố. flash là bản giá thấp, flashx là bản tăng tốc, v thiên về thị giác, ocr chuyên đọc tài liệu, legal cho tình huống pháp lý.

Mô hình	Định vị	Ngữ cảnh / đầu ra	Phù hợp
glm-5.3	Cao cấp nhất	1M / 128K	Sửa nhiều tệp, gỡ lỗi chuỗi dài
glm-5.3-flash	Đa phương thức, giá thấp	1M / 128K	Vừa xem ảnh giao diện vừa sửa mã
glm-5.3-flashx	Bản nhanh, khoảng 200 tokens/s	1M / 128K	Nhiều tác vụ nhỏ, cần phản hồi nhanh
glm-5.3-flashx-legal	Tối ưu cho pháp lý	1M / 128K	Rà soát hợp đồng, tra cứu điều luật
glm-5.2	Thế hệ trước	1M / 128K	Quy trình cũ, cần ổn định
glm-ocr	Đọc tài liệu nhẹ	Ảnh 10MB, PDF 50MB, tối đa 100 trang	Bản scan, hóa đơn, bố cục phức tạp
glm-5v-turbo	Đa phương thức thế hệ đầu	Theo thẻ mô hình	Chỉ cần đọc ảnh, chi phí thấp

Các ID cũ như glm-5.1, glm-5, glm-5-turbo, glm-3-turbo vẫn dùng được nhưng là thế hệ trước; dự án mới nên bắt đầu từ dòng 5.3. Riêng glm-5.3 luôn bật suy luận với ba mức low, high, max — ký tự cạnh tên mô hình trong khung nhập chính là mức này.

Những chỗ dễ sai

• Nhận 404: phần lớn do thêm đường dẫn vào Base URL. Chỉ giữ tên miền.
• Nhận 400 hoặc 404: định dạng không khớp gateway. Kiểm tra /v1/messages, không phải địa chỉ.
• Nhận 401: khóa có dấu cách thừa, bị cắt, hoặc hết hạn.
• Mô hình không xuất hiện: công tắc nhà cung cấp, công tắc dòng mô hình, hoặc biểu mẫu chưa lưu.
• Mô hình chạy nhưng vẫn dùng khóa cũ: chưa chuyển nhóm trong hội thoại.

Tổng kết

Chỉ cần đúng bốn giá trị: địa chỉ dừng ở tên miền, định dạng chứa /v1/messages, khóa lấy từ bảng điều khiển, ID sao chép từ danh mục. Phần còn lại là thao tác giao diện, và một bước không có thông báo lỗi — chuyển nhóm hội thoại — mới là bước quyết định yêu cầu có đi qua khóa của bạn hay không.