Dùng OpenCode với API LLM miễn phí
OpenCode là một agent lập trình mã nguồn mở cho terminal và máy tính để bàn. Nó chấp nhận mọi nhà cung cấp tương thích OpenAI. Hướng dẫn này kết nối OpenCode tới các mô hình miễn phí qua FreeLLMAPI. Một lệnh ghi cấu hình và lưu khóa.
Mã, tên mô hình và nhãn danh mục trực tiếp được hiển thị bằng tiếng Anh.
Bước 1: Cài đặt FreeLLMAPI
FreeLLMAPI là một gateway mã nguồn mở. Nó chạy trên máy tính của bạn trong Docker và gom các gói miễn phí của 45 nhà cung cấp sau một khóa duy nhất.
Cài đặt trên macOS hoặc Linux
curl -fsSL https://freellmapi.co/install.sh | bashMở http://localhost:3001. Thêm ít nhất hai khóa nhà cung cấp miễn phí ở trang Keys. Google AI Studio và Groq mỗi nơi cấp một khóa miễn phí trong vài phút. Sao chép khóa thống nhất của bạn từ cùng trang đó.
Bước 2: Kết nối OpenCode bằng một lệnh
Một lệnh
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key> --dry-run
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key>
opencodeLệnh thực hiện ba việc:
- Nó thêm một provider
freellmapivào~/.config/opencode/opencode.json. Provider liệt kê các mô hình từ danh mục trực tiếp của bạn cùng giới hạn ngữ cảnh của chúng. - Nó đặt
freellmapi/autolàm mô hình mặc định. - Nó lưu khóa vào tệp thông tin xác thực của OpenCode,
~/.local/share/opencode/auth.json. Bạn không cần biến môi trường, dù trong CLI hay trong ứng dụng máy tính.
Lệnh tạo bản sao lưu trước khi ghi. Nó gộp provider mới, nên các provider khác của bạn vẫn giữ nguyên. Nếu XDG_CONFIG_HOME hoặc XDG_DATA_HOME được đặt, lệnh dùng các thư mục đó.
Trước khi bắt đầu một tác vụ dài, hãy đảm bảo gateway có thể phục vụ một yêu cầu ngay bây giờ. Lệnh này chỉ liệt kê các mô hình có khóa dùng được tại thời điểm này:
Kiểm tra mô hình nào đã sẵn sàng
curl "http://localhost:3001/v1/models?execution_status=ready" \
-H "Authorization: Bearer <unified-key>"Mô hình có trạng thái exhausted có khóa, nhưng tất cả đều đã đạt giới hạn ngay bây giờ. Trạng thái này sẽ mất khi thời gian nghỉ kết thúc. Chạy npx freellmapi doctor để đảm bảo yêu cầu của một client tới được gateway. Nhật ký yêu cầu trên bảng điều khiển hiển thị từng lệnh gọi từ OpenCode. Header phản hồi X-Routed-Via cho biết nhà cung cấp và mô hình đã trả lời mỗi yêu cầu. Nếu một yêu cầu được chuyển dự phòng, header X-Fallback-Trail nêu tên từng bước thất bại và lý do.
Thiết lập thủ công: khối provider trong opencode.json
Để thiết lập thủ công, thêm khối này vào ~/.config/opencode/opencode.json, hoặc vào opencode.json trong dự án của bạn. OpenCode dùng @ai-sdk/openai-compatible cho các endpoint /v1/chat/completions.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"model": "freellmapi/auto",
"provider": {
"freellmapi": {
"npm": "@ai-sdk/openai-compatible",
"name": "FreeLLMAPI",
"options": {
"baseURL": "http://localhost:3001/v1"
},
"models": {
"auto": {
"name": "Auto",
"limit": { "context": 128000, "output": 8192 }
}
}
}
}
}Sau đó thêm khóa. Khởi động OpenCode, chạy /connect, chọn provider freellmapi và dán khóa thống nhất của bạn. Provider id trong /connect phải khớp với id trong cấu hình. Chạy /models để chọn mô hình.
limit.contextlà số token đầu vào tối đa của mô hình.limit.outputlà số token tối đa mà nó có thể tạo ra.modelở cấp cao nhất dùng định dạngprovider/model. Nếu không có, OpenCode giữ mô hình mà nó đã dùng trước đó.- Mọi model id bạn muốn dùng phải có trong bản ánh xạ
models. Thêm các id khác từGET /v1/models.
providers. Tài liệu nói rằng định dạng V1 ở trên vẫn được hỗ trợ. Lệnh thiết lập của FreeLLMAPI ghi định dạng V1.Chọn mô hình cho OpenCode
OpenCode là một agent. Nó đọc tệp, sửa chúng và chạy lệnh qua các lệnh gọi công cụ. Mỗi yêu cầu mang theo một system prompt, định nghĩa công cụ và nội dung tệp. Dùng mô hình có gọi công cụ và cửa sổ ngữ cảnh lớn.
| Mô hình | Miễn phí trên | Ngữ cảnh | Giới hạn miễn phí (ưu đãi tốt nhất) | Công cụ | Thị giác |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 yêu cầu/phút 1 req/min per model | Có | Không |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 yêu cầu/phút 40 RPM | Có | Có |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Có | Có |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Có | Không |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Có | Có |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Có | Có |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 yêu cầu/phút 50 yêu cầu/ngày 50 req/day account-wide (1,000 after a $10 purchase) | Có | Có |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 yêu cầu/phút 50 yêu cầu/ngày Shared rate limit | Có | Không |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 yêu cầu/phút 250 yêu cầu/ngày 70,000 token/phút ~6M | Có | Có |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | Có | Có |
Đang hiển thị 12 trong số 109 mô hình miễn phí phù hợp. Xem tất cả mô hình.
Dữ liệu trực tiếp từ danh mục FreeLLMAPI (phiên bản 2026.11.19, đã kiểm tra 2026-11-19). Giới hạn miễn phí thay đổi thường xuyên. Danh mục được kiểm tra mỗi ngày.
Dùng freellmapi/auto để bộ định tuyến chọn mô hình cho mỗi yêu cầu. Thêm auto:smart hoặc auto:fast vào bản ánh xạ models để điều hướng yêu cầu theo trí tuệ hoặc tốc độ. Bạn cũng có thể thêm một profile có tên, ví dụ auto:coding, sau khi tạo nó trên bảng điều khiển.
Giới hạn tốc độ và phiên dài
Một tác vụ agent có thể gửi hàng chục yêu cầu. Một gói miễn phí đơn lẻ sẽ dừng một tác vụ dài rất nhanh. FreeLLMAPI đếm yêu cầu và token của từng khóa. Khi một nhà cung cấp gửi lỗi 429, bộ định tuyến gửi yêu cầu tới mô hình tiếp theo trong chuỗi, và phiên tiếp tục.
- Thêm khóa từ bốn nhà cung cấp trở lên. Nhiều nhà cung cấp hơn cho nhiều yêu cầu hơn mỗi ngày.
- Bật chuyển giao ngữ cảnh bằng
FREELLMAPI_CONTEXT_HANDOFF=on_model_switchtrong.envcủa FreeLLMAPI. Khi mô hình thay đổi, mô hình tiếp theo nhận một ghi chú ngắn rằng nó tiếp tục một tác vụ. - Phiên bám (sticky) giữ một cuộc hội thoại trên một mô hình trong 30 phút. Điều này giữ cho agent nhất quán.
- Bắt đầu một phiên mới cho mỗi tác vụ. Ngữ cảnh nhỏ hơn dùng ít token hơn cho mỗi yêu cầu.
Khắc phục sự cố
| Vấn đề | Nguyên nhân | Cách khắc phục |
|---|---|---|
| "Invalid API key" với khóa hợp lệ | Một apiKey rỗng trong cấu hình ghi đè khóa từ /connect | Xóa apiKey khỏi options, hoặc chạy lại setup-opencode |
| OpenCode không dùng provider mới | model ở cấp cao nhất chưa được đặt | Đặt "model": "freellmapi/auto" |
| Model not found | Model id không có trong bản ánh xạ models của provider | Thêm id vào bản ánh xạ, hoặc chạy lại setup-opencode |
Khóa {env:VAR} rỗng | OpenCode thay một biến chưa đặt bằng chuỗi rỗng | Export biến trong cùng shell, hoặc lưu khóa bằng /connect |
| Gọi công cụ thất bại | Mô hình có gọi công cụ yếu | Chọn một mô hình từ bảng trên |
| "Mọi mô hình bị giới hạn tốc độ sau N lần thử" | Mọi khóa đều đã đạt giới hạn | Thêm khóa từ nhiều nhà cung cấp hơn, hoặc chờ thời gian nghỉ kết thúc |
Câu hỏi thường gặp
Tôi có thể dùng OpenCode miễn phí không?
Có. OpenCode là mã nguồn mở. Kết nối nó tới FreeLLMAPI như một provider tương thích OpenAI. Gateway gửi mỗi yêu cầu tới các gói miễn phí của nhà cung cấp, nên chi phí suy luận là $0.
Làm sao thêm một provider tương thích OpenAI tùy chỉnh vào OpenCode?
Thêm một provider với npm đặt thành @ai-sdk/openai-compatible, options.baseURL và một bản ánh xạ models vào opencode.json. Sau đó chạy /connect để lưu khóa và /models để chọn mô hình.
Mô hình miễn phí nào tốt nhất cho OpenCode?
Dùng mô hình có gọi công cụ và ít nhất 128K ngữ cảnh. Bảng trên trang này cho thấy các mô hình miễn phí mạnh nhất đáp ứng cả hai quy tắc hiện nay. Dùng freellmapi/auto để bộ định tuyến chọn một mô hình.
OpenCode lưu khóa API ở đâu?
Khóa thêm bằng /connect được lưu vào ~/.local/share/opencode/auth.json. Lệnh thiết lập của FreeLLMAPI ghi khóa vào đó, nên cả CLI và ứng dụng máy tính đều tìm thấy nó.
Hướng dẫn liên quan
- Dùng Aider với API LLM miễn phí
- Dùng Codex CLI với mô hình miễn phí
- Cách dùng Claude Code miễn phí
- API model lập trình miễn phí tốt nhất
- Base URL API tương thích OpenAI miễn phí
Nguồn
- OpenCode docs: providers (V1 config) (đã kiểm tra 20 November 2026)
- OpenCode docs: config (đã kiểm tra 20 November 2026)
- OpenCode docs: migrate from V1 (đã kiểm tra 20 November 2026)
- FreeLLMAPI CLI generators (đã kiểm tra 20 November 2026)
- FreeLLMAPI docs: context handoff (đã kiểm tra 20 November 2026)