---
title: "Cấu hình opencode với custom provider tương thích OpenAI"
description: "Thêm BroadNet Inference vào coding agent opencode làm custom provider tương thích OpenAI trong opencode.jsonc, kèm alias model, capabilities và limit."
url: https://broadrouter.com/vi/guides/opencode-custom-provider/
lang: vi
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Được dịch từ tiếng Anh với sự hỗ trợ của AI. [Đọc bản gốc tiếng Anh](https://broadrouter.com/guides/opencode-custom-provider/) (cập nhật ngày 2026-11-16).

# Thêm BroadNet Inference vào opencode làm custom provider

Cập nhật 2026-11-16

Trong opencode.jsonc, thêm mục broadnet dưới providers với package @opencode/ai/providers/openai-compatible, settings.baseURL là https://inference.broadnet.ai/v1 và env là BROADNET\_API\_KEY. Ánh xạ các key model ngắn tới ID BroadNet bằng modelID, như broadnet/glm-5.3, rồi chọn model bằng /models. Cấu hình V1 cũ dùng npm @ai-sdk/openai-compatible và options.baseURL vẫn chạy.

opencode là một coding agent mã nguồn mở chạy trong terminal. Các provider không có trong catalog sẵn có của nó được thêm làm **custom provider** trong `opencode.jsonc`. BroadNet Inference dùng định dạng chat completions của OpenAI, nên nó dùng gói runtime tương thích OpenAI của opencode. Hướng dẫn này làm theo tài liệu opencode hiện tại (V2).

## Thiết lập

1.  **Export key** trong shell dùng để khởi động opencode:

```bash
export BROADNET_API_KEY='your-broadnet-key'
```

2.  **Tạo file cấu hình.** Đặt nó trong dự án với tên `opencode.jsonc`, hoặc ở `~/.config/opencode/opencode.jsonc` để dùng ở mọi nơi.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "broadnet/glm-5.3",
  "providers": {
    "broadnet": {
      "name": "BroadNet Inference",
      "env": ["BROADNET_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://inference.broadnet.ai/v1"
      },
      "models": {
        "glm-5.3": {
          "modelID": "broadnet/glm-5.3",
          "name": "GLM 5.3",
          "capabilities": { "tools": true, "input": ["text"], "output": ["text"] },
          "limit": { "context": 1048576, "output": 16000 }
        },
        "deepseek-v4.1-flash": {
          "modelID": "broadnet/deepseek-v4.1-flash",
          "name": "DeepSeek V4.1 Flash",
          // BroadNet's docs don't list tool calling for this model: test it first
          "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"] },
          "limit": { "context": 1048576, "output": 16000 }
        },
        "qwen3.8-27b": {
          "modelID": "broadnet/qwen3.8-27b",
          "name": "Qwen3.8 27B",
          "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"] },
          "limit": { "context": 262144, "output": 16000 }
        }
      }
    }
  }
}
```

3.  **Khởi động opencode và chọn model** bằng `/models`. Tham chiếu có dạng `broadnet/<key trong map>`, ví dụ `broadnet/glm-5.3`. opencode gửi giá trị `modelID` tới BroadNet.

Các file cấu hình được gộp lại. opencode áp dụng file toàn cục trước, rồi tới các file dự án tìm thấy từ thư mục hiện tại đi ngược lên (file xa nhất trước), rồi tới cấu hình `.opencode/` nếu có, nên file dự án có thể ghi đè provider toàn cục. Cấu hình hệ thống được quản lý tập trung, nếu công ty bạn dùng, sẽ ghi đè cả hai. Hãy giữ key trong biến môi trường, không để trong file, để có thể đưa file cấu hình vào version control.

## Vì sao dùng alias

ID của BroadNet vốn đã chứa dấu gạch chéo (`broadnet/glm-5.3`). Key trong map `models` là thứ opencode hiển thị và cho chọn, còn `modelID` là thứ nó gửi đi. Key ngắn giúp tham chiếu dễ đọc.

Hãy tự đặt `capabilities` và `limit`. Với một model ngoài catalog, opencode giả định có hỗ trợ JSON tool, đầu vào văn bản và hình ảnh, context 200.000 token và 32.000 token đầu ra. Tài liệu của nó gọi đây là giả định dự phòng (fallback), không phải giá trị phát hiện được. Giá trị `output` 16000 ở trên là đề xuất của chúng tôi, không phải giới hạn của BroadNet; nó chừa chỗ cho phần suy luận.

### Cấu hình V1 cũ

opencode V2 vẫn đọc định dạng V1, nên một khối có sẵn như thế này vẫn tiếp tục chạy:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "broadnet": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BroadNet Inference",
      "options": {
        "baseURL": "https://inference.broadnet.ai/v1",
        "apiKey": "{env:BROADNET_API_KEY}"
      },
      "models": {
        "broadnet/glm-5.3": { "name": "GLM 5.3" }
      }
    }
  }
}
```

Trong dạng V2 gốc, `provider` đổi thành `providers`, `npm` đổi thành `package` (`aisdk:@ai-sdk/openai-compatible` nếu bạn muốn giữ gói AI SDK), còn `options.baseURL` và `options.apiKey` chuyển xuống dưới `settings`. [Hướng dẫn chuyển đổi V1 của opencode](https://opencode.ai/docs/migrate-v1/) ánh xạ từng trường.

## Nên chọn model nào

| Tác vụ | Model | Ghi chú |
| --- | --- | --- |
| Lập trình bằng agent có tool | [GLM 5.3](https://broadrouter.com/vi/models/glm-5.3/) | Có ghi hỗ trợ tool và đầu ra có cấu trúc; context 1M |
| Ảnh chụp màn hình, tiếng Ả Rập | [Qwen3.8 27B](https://broadrouter.com/vi/models/qwen3.8-27b/) | Tool và hình ảnh; context 262K |
| Phiên làm việc cả ngày, giá cố định | [DeepSeek V4.1 Flash](https://broadrouter.com/vi/models/deepseek-v4.1-flash/) | Gói không giới hạn; BroadNet không ghi hỗ trợ tool |

opencode dựa vào lời gọi tool. Tài liệu BroadNet không ghi hỗ trợ gọi tool cho DeepSeek V4.1 Flash, nên cấu hình trên đánh dấu điều này là giả định cần thử. Hãy chạy một task thật trên một giờ Meteor ($1) trước khi mua một tháng Full Moon ($60).

## Xử lý sự cố

-   **401.** Key trong `BROADNET_API_KEY` bị sai, hết hạn hoặc hết hạn mức trả theo mức dùng. Hãy chắc chắn biến này được đặt trong tiến trình chạy opencode.
-   **Không tìm thấy model hoặc model bị từ chối.** Chọn key trong map (`broadnet/glm-5.3`), và kiểm tra `modelID` khớp chính xác với ID của BroadNet. Tham chiếu phân biệt chữ hoa chữ thường. Các model trả phí cần nạp tiền; tín dụng $5 chỉ dùng được cho `broadnet/gemma-4-26b-a4b` và hai model Transcribe.
-   **Câu trả lời rỗng.** Hãy tăng `limit.output`. [Vì sao câu trả lời trả về rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/).
-   **429.** Key trả theo mức dùng cho phép 30 request mỗi phút và 4 request đang xử lý. Các lần thử lại cũng được tính. Xem [lỗi và thử lại](https://broadrouter.com/vi/guides/errors-and-retries/).
-   **Subagent trên một gói.** Mỗi [phiên của gói](https://broadrouter.com/vi/guides/unlimited-llm-api-sessions/) xử lý một request tại một thời điểm, nên các subagent song song sẽ xếp hàng, trừ khi mỗi subagent có phiên riêng.

## Thuật ngữ trong hướng dẫn này

[Trả theo mức dùng (pay-as-you-go)](https://broadrouter.com/vi/glossary/pay-as-you-go/)

Trả theo mức dùng (pay-as-you-go) là mô hình giá mà bạn chỉ trả cho những gì đã dùng, đo theo đơn vị như token, request hoặc phút âm thanh, không có gói đăng ký hay cam kết tối thiểu. Hầu hết API LLM tính phí theo cách này, trừ vào số dư trả trước hoặc qua hóa đơn định kỳ.

[Subagent (agent con)](https://broadrouter.com/vi/glossary/subagent/)

Subagent là một agent riêng biệt mà agent chính khởi chạy để xử lý một việc cụ thể. Nó chạy với context window, system prompt và quyền dùng tool riêng, làm xong việc và chỉ trả kết quả hoặc bản tóm tắt cho agent chính, nhờ đó cuộc hội thoại chính luôn gọn.

[Giới hạn tần suất (rate limit)](https://broadrouter.com/vi/glossary/rate-limit/)

Giới hạn tần suất (rate limit) là mức trần mà API đặt ra cho lượng sử dụng của một client trong một khoảng thời gian, như số request mỗi phút hoặc số token mỗi phút. Request vượt giới hạn bị từ chối, thường với HTTP 429 Too Many Requests, cho đến khi mức dùng giảm xuống dưới giới hạn.

[Token](https://broadrouter.com/vi/glossary/token/)

Token là đơn vị văn bản mà model ngôn ngữ đọc và viết: một từ, một phần của từ, một dấu câu hoặc một chuỗi byte do tokenizer của model tạo ra. API LLM đếm, giới hạn và thường tính phí theo token.

[Tool calling (gọi tool, function calling)](https://broadrouter.com/vi/glossary/tool-calling/)

Tool calling, còn gọi là function calling, là tính năng của API LLM trong đó model trả về một yêu cầu có cấu trúc để chạy một hàm do nhà phát triển định nghĩa, kèm đối số JSON. Ứng dụng chạy hàm rồi gửi kết quả lại; model không bao giờ tự chạy code.

[AI coding agent](https://broadrouter.com/vi/glossary/coding-agent/)

AI coding agent là công cụ phần mềm trong đó một model ngôn ngữ làm việc trên codebase theo vòng lặp: đọc file, sửa file, chạy lệnh như test, đọc kết quả và quyết định bước tiếp theo cho tới khi xong task hoặc chạm giới hạn.

[API tương thích OpenAI (OpenAI-compatible API)](https://broadrouter.com/vi/glossary/openai-compatible-api/)

API tương thích OpenAI là một HTTP API nhận cùng định dạng request và phản hồi như OpenAI API, ví dụ POST /v1/chat/completions, nên SDK và công cụ của OpenAI dùng được nó chỉ bằng cách đổi base URL, API key và tên model.

[Chat Completions API](https://broadrouter.com/vi/glossary/chat-completions-api/)

Chat Completions API là endpoint HTTP của OpenAI, POST /v1/chat/completions, nhận tên model và danh sách message có gắn vai trò rồi trả về message tiếp theo của model. Cấu trúc request và response của nó đã trở thành định dạng chung mà các nhà cung cấp và SDK tương thích OpenAI dùng lại.

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

### Vì sao opencode không tìm thấy model BroadNet của tôi?

opencode hiểu tham chiếu model theo dạng provider/key trong map, và ID phân biệt chữ hoa chữ thường. Với cấu hình bên dưới, hãy chọn broadnet/glm-5.3, trong đó glm-5.3 là key trong map. Giá trị modelID chỉ là thứ được gửi tới BroadNet.

### Cấu hình của tôi dùng provider và npm với @ai-sdk/openai-compatible. Như vậy có sai không?

Không. Đó là định dạng V1, và hướng dẫn chuyển đổi của opencode nói định dạng này vẫn được hỗ trợ. Dạng V2 gốc đổi provider thành providers, npm thành package (aisdk:@ai-sdk/openai-compatible) và options.baseURL thành settings.baseURL.

### Vì sao câu trả lời của opencode bị rỗng?

Model đã tiêu hết ngân sách đầu ra cho phần suy luận. Hãy tăng limit.output cho model đó. Trên BroadNet, phần suy luận được tính vào max\_tokens.

## Hướng dẫn liên quan

-   [Dùng Cline với BroadNet Inference (provider OpenAI Compatible)](https://broadrouter.com/vi/guides/cline-openai-compatible/)
-   [Gói LLM API không giới hạn cho agent hoạt động thế nào?](https://broadrouter.com/vi/guides/unlimited-llm-api-sessions/)
-   [Vì sao model suy luận trả về câu trả lời rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/)
-   [Dùng Vercel AI SDK với BroadNet Inference](https://broadrouter.com/vi/guides/vercel-ai-sdk-openai-compatible/)
-   [Mọi công cụ dùng được với BroadNet Inference (tiếng Anh)](https://broadrouter.com/integrations/): SDK, agent lập trình, giao diện chat và công cụ tự động hóa, kèm cấu hình chính xác cho từng công cụ

Hãy thử với khối lượng công việc thực tế của bạn. Tài khoản mới được tặng US$5 tín dụng ban đầu cho Gemma và chuyển giọng nói thành văn bản. DeepSeek, GLM và Qwen3.8 cần nạp tiền.

[Bắt đầu](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-guides-opencode-custom-provider&utm_content=page-cta) ·

**Nguồn**

-   [Tài liệu opencode, Providers (custom provider) (kiểm tra ngày 2026-11-14)](https://opencode.ai/docs/providers/)
-   [Tài liệu opencode, Models (alias, capabilities, limit) (kiểm tra ngày 2026-11-14)](https://opencode.ai/docs/models/)
-   [Tài liệu opencode, vị trí file cấu hình (kiểm tra ngày 2026-11-14)](https://opencode.ai/docs/config/)
-   [Tài liệu opencode, chuyển đổi từ V1 (kiểm tra ngày 2026-11-14)](https://opencode.ai/docs/migrate-v1/)
-   [Tài liệu tham chiếu API BroadNet Inference (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-guides-opencode-custom-provider&utm_content=sources)
