--- title: >- Thiết lập provider tùy chỉnh trong OpenCode: Thêm bất kỳ API tương thích OpenAI nào description: >- Thêm Haimaker, Ollama, OpenRouter hoặc bất kỳ API tương thích OpenAI nào vào OpenCode. Bao gồm opencode auth login, cấu hình opencode.json, thiết lập model cục bộ và các lỗi provider thường gặp. date: 2026-04-12T00:00:00.000Z updatedDate: 2026-06-26T00:00:00.000Z location: 'San Francisco, CA – ngày 12 tháng 4 năm 2026' image: /images/opencode-custom-provider-setup-hero.jpg keywords: >- opencode provider tùy chỉnh, opencode thêm provider, opencode model provider, opencode tương thích openai, opencode haimaker, opencode llm provider, opencode thiết lập provider, opencode provider cục bộ faq: - question: Làm thế nào để thêm provider LLM tùy chỉnh vào OpenCode? answer: >- Chạy 'opencode auth login' và chọn Other để lưu credential, sau đó thêm mục provider tương ứng trong opencode.json với npm đặt là '@ai-sdk/openai-compatible', baseURL trỏ tới API của bạn, và các model muốn dùng trong phần 'models'. Khởi động lại OpenCode và dùng /models để chọn. Riêng với Haimaker, lệnh 'npx -y @haimaker/connect --opencode' sẽ tự động ghi credential và khối provider cho bạn. - question: Tại sao provider tùy chỉnh của tôi không hiển thị trong /models? answer: >- Nguyên nhân thường gặp là ID provider không khớp giữa credential và cấu hình, file opencode.json không phải là JSON/JSONC hợp lệ, ID model không khớp với API upstream, hoặc quên khởi động lại OpenCode sau khi sửa cấu hình provider. - question: >- Tôi có thể dùng cùng một API tương thích OpenAI cho nhiều provider trong OpenCode không? answer: >- Có. Mỗi mục trong khối 'provider' là độc lập, nên bạn có thể thêm Haimaker, Ollama, OpenRouter, LM Studio và các gateway nội bộ thành các provider riêng. Hãy đặt ID provider khác nhau để /models dễ đọc. locale: vi-vn translationKey: opencode-custom-provider-setup --- OpenCode hỗ trợ hơn 75 provider LLM thông qua danh sách provider, nhưng provider tùy chỉnh vẫn đóng vai trò quan trọng. Chúng giúp bạn thêm gateway, runtime cục bộ, endpoint inference nội bộ hoặc một model chưa có trong danh sách. Quy trình khá đơn giản: lưu credential, thêm khối provider, khởi động lại OpenCode, sau đó chọn model từ `/models`. > **Chỉ muốn thiết lập Haimaker?** Bỏ qua các bước thủ công — chạy `npx -y @haimaker/connect --opencode` và CLI sẽ tự động ghi khối provider, lưu credential cho bạn (thêm `--project` nếu muốn cấu hình cho riêng dự án). Hướng dẫn dưới đây là phương pháp chung cho *bất kỳ* provider tương thích OpenAI nào — Ollama, LM Studio, gateway nội bộ hoặc bất kỳ dịch vụ nào chưa có trong danh sách. Xem [hướng dẫn connect](/connect) để thực hiện bằng một lệnh duy nhất. ## Khi nào nên dùng provider tùy chỉnh Hãy dùng provider tùy chỉnh khi model hoặc endpoint chưa có sẵn trong danh sách provider mặc định của OpenCode. Một số ví dụ điển hình: - **Haimaker** - một API key cho nhiều dòng model thông qua gateway tương thích OpenAI. - **Ollama** - model cục bộ tại `http://localhost:11434/v1`. - **LM Studio** - model cục bộ tại `http://127.0.0.1:1234/v1`. - **Gateway nội bộ** - các endpoint tương thích OpenAI do công ty tự host. - **Provider mới** - bất kỳ dịch vụ nào có API chat tương thích OpenAI, trước khi danh sách OpenCode theo kịp. Nếu provider đã có sẵn trong OpenCode, hãy ưu tiên dùng phương thức tích hợp. Cấu hình tùy chỉnh hữu ích nhất khi bạn cần base URL riêng, gateway, hoặc một model chưa có trong danh sách mặc định. ## Bước 1: Thêm credential Tài liệu OpenCode hiện tại hướng dẫn dùng `opencode auth login` để quản lý credential. Với provider tương thích OpenAI tùy chỉnh, hãy chọn **Other**, nhập ID provider, sau đó dán API key vào: ```bash opencode auth login ``` Hãy chọn một ID provider ngắn gọn để dùng lại trong phần cấu hình. Ví dụ: ```text haimaker ollama mygateway ``` OpenCode lưu credential ở: ```text ~/.local/share/opencode/auth.json ``` Bạn có thể tự chỉnh sửa file này khi cần, nhưng việc dùng `opencode auth login` sẽ giúp tránh sai sót định dạng key. ## Bước 2: Cấu hình provider Mở hoặc tạo file cấu hình OpenCode. Tùy thuộc vào thiết lập của bạn, đây có thể là `opencode.json` của dự án hoặc file toàn cục trong `~/.config/opencode/`. Thêm khối `provider` với cùng ID provider mà bạn đã dùng khi xác thực. Dưới đây là mẫu sử dụng [haimaker.ai](https://haimaker.ai) làm ví dụ: ```jsonc { "$schema": "https://opencode.ai/config.json", "provider": { "haimaker": { "npm": "@ai-sdk/openai-compatible", "name": "Haimaker", "options": { "baseURL": "https://api.haimaker.ai/v1" }, "models": { "z-ai/glm-4.6": { "name": "GLM 4.6" }, "minimax/minimax-m2.5": { "name": "MiniMax M2.5" }, "qwen/qwen3-coder": { "name": "Qwen3 Coder" } } } } } ``` Ý nghĩa của từng trường: - **`npm`**: adapter SDK. Với bất kỳ API tương thích OpenAI nào, hãy dùng `@ai-sdk/openai-compatible`. OpenCode sẽ tải adapter khi cần. - **`name`**: tên hiển thị trong OpenCode. - **`options.baseURL`**: base URL cho API của provider. Nên kết thúc bằng `/v1` hoặc tiền tố phiên bản tương ứng của provider. - **`models`**: các model bạn muốn dùng trong OpenCode. Các key phải khớp chính xác với giá trị mà API của provider chấp nhận trong trường `model` của request completion. Bạn có thể thêm bao nhiêu provider tùy chỉnh tùy thích, mỗi provider là một mục riêng nằm dưới `provider`. ## Bước 3: Khởi động lại và xác minh OpenCode có thể không nhận các thay đổi về provider cho đến khi được khởi động lại. Hãy thoát hẳn, mở lại, rồi chạy: ```text /models ``` Bạn sẽ thấy tên hiển thị của provider và các model đã cấu hình. Hãy chọn một model và gửi một prompt nhỏ trước khi dùng cho code thực tế. ## Ví dụ đầy đủ: Gateway Haimaker Sử dụng cấu hình này khi bạn muốn một endpoint tương thích OpenAI duy nhất cho nhiều dòng model: ```jsonc { "$schema": "https://opencode.ai/config.json", "provider": { "haimaker": { "npm": "@ai-sdk/openai-compatible", "name": "Haimaker", "options": { "baseURL": "https://api.haimaker.ai/v1" }, "models": { "anthropic/claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" }, "openai/gpt-5.4-mini": { "name": "GPT-5.4 Mini" }, "minimax/minimax-m2.5": { "name": "MiniMax M2.5" }, "qwen/qwen3-coder": { "name": "Qwen3 Coder" } } } } } ``` Lý do cấu hình này hoạt động tốt: OpenCode chỉ thấy một provider, còn Haimaker đảm bảo quyền truy cập tới nhiều dòng model upstream. Điều này giúp cấu hình OpenCode gọn gàng hơn và việc chuyển đổi model cũng ít phiền phức hơn. ## Ví dụ đầy đủ: Provider cục bộ Ollama Ollama cung cấp một endpoint cục bộ tương thích OpenAI tại `http://localhost:11434/v1`: ```jsonc { "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen3-coder:30b": { "name": "Qwen3 Coder 30B" }, "gemma4:e4b": { "name": "Gemma 4 E4B" } } } } } ``` Hãy tải model về trước khi khởi động OpenCode: ```bash ollama pull qwen3-coder:30b ollama pull gemma4:e4b ``` Nếu OpenCode yêu cầu xác thực cho provider cục bộ, hãy chạy `opencode auth login`, chọn **Other**, dùng `ollama` làm ID provider và nhập một key bất kỳ không trống, ví dụ `ollama`. Ollama không xác thực API key cục bộ. ## Các lỗi thường gặp và cách khắc phục #### Provider không hiển thị trong /models Hãy kiểm tra bốn điểm sau: 1. ID provider từ `opencode auth login` khớp với key provider trong cấu hình. 2. File cấu hình là JSON hoặc JSONC hợp lệ. 3. Bạn đã khởi động lại OpenCode sau khi sửa cấu hình provider. 4. Model được liệt kê trong object `models` của provider. #### Xác thực thất bại ở request đầu tiên Credential bị thiếu hoặc gắn sai ID provider. Chạy: ```bash opencode auth list ``` Sau đó xác nhận ID provider khớp chính xác với cấu hình. Đừng kèm theo `Bearer` trong trường key. #### Model hiển thị nhưng request thất bại Rất có thể ID model không đúng với những gì API upstream mong đợi. Provider tùy chỉnh truyền nguyên ID model mà không thay đổi. Nếu cấu hình ghi `qwen/qwen3-coder`, API phải chấp nhận chính xác `qwen/qwen3-coder`. Với Haimaker, hãy kiểm tra key và endpoint: ```bash curl https://api.haimaker.ai/v1/models \ -H "Authorization: Bearer your-haimaker-api-key" ``` Với Ollama, hãy kiểm tra model cục bộ: ```bash ollama list ``` Hãy dùng đúng tên model từ kết quả trả về. #### Tool call thất bại với model cục bộ Model cục bộ nhạy cảm hơn với giới hạn context và cách định dạng tool call. Hãy bắt đầu với một model được đánh giá tốt cho agentic coding, chẳng hạn Qwen3 Coder, và giữ context ở mức vừa phải. Tài liệu OpenCode cũng khuyến nghị tăng `num_ctx` của Ollama khi tool call không hoạt động. #### Provider tích hợp ngừng hoạt động Có thể bạn đã thay đổi nhiều cấu hình hơn dự định. Hãy giữ các provider tùy chỉnh trong object `provider` và tránh xóa các mục provider có sẵn. Khi không chắc chắn, hãy thay đổi cấu hình ở mức nhỏ nhất có thể: thêm một ID provider và một model, khởi động lại, kiểm tra, sau đó mới thêm dần. ## Thiết lập thực tế Với hầu hết người dùng OpenCode, một cấu hình hợp lý là: 1. **Haimaker** cho các model cloud và định tuyến bằng một API key duy nhất. 2. **Ollama** cho công việc riêng tư trên máy cục bộ. 3. **Một model cao cấp dự phòng** cho các phiên debug khó và refactor nhiều file. Cách này mang lại sự riêng tư cục bộ khi cần thiết, model cloud chi phí thấp cho công việc hằng ngày, và một model mạnh hơn khi tác vụ lập trình đòi hỏi nhiều sự tập trung. DÙNG HAIMAKER VỚI OPENCODE --- *Để thiết lập cục bộ, xem [Sử dụng Ollama với OpenCode](/vi-vn/blog/dùng-ollama-với-opencode/). Để xem bảng xếp hạng model cục bộ đầy đủ hơn, xem [Các model Ollama tốt nhất cho coding agent](/vi-vn/blog/các-mô-hình-ollama-tốt-nhất-cho-tác-nhân-lập-trình/).*