Trang chủ / Hướng dẫn / Dùng OpenCode với API LLM miễn phí

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 | bash

Mở 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>
opencode

Lệnh thực hiện ba việc:

  • Nó thêm một provider freellmapi và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/auto là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.context là số token đầu vào tối đa của mô hình. limit.output là số token tối đa mà nó có thể tạo ra.
  • model ở cấp cao nhất dùng định dạng provider/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.
Lưu ý về phiên bản cấu hình: tài liệu OpenCode hiện mô tả định dạng cấu hình V2 với khóa 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í cho OpenCode: gọi công cụ và 128K+ ngữ cảnh
Mô hìnhMiễn phí trênNgữ cảnhGiới hạn miễn phí (ưu đãi tốt nhất)Công cụThị giác
GLM 5.3UnoRouter1M1 yêu cầu/phút
1 req/min per model
CóKhông
GLM 5.3 FlashNVIDIA NIM, UnoRouter1M40 yêu cầu/phút
40 RPM
CóCó
Gemini 3.8 FlashGoogle AI Studio1MRecurring provider quotaCóCó
Qwen3.8 Flash NextAMD Radeon Cloud262KRecurring daily account allowanceCóKhông
Qwen3.8 FlashElectronHub1M$0.25/week shared recurring creditCóCó
Gemini 3.7 FlashGoogle AI Studio1M10 yêu cầu/phút
20 yêu cầu/ngày
250,000 token/phút
~3M
CóCó
GPT-5.6 LunaElectronHub1M$0.25/week shared recurring creditCóCó
Dots3 Note PreviewKilo Gateway, OpenRouter512K20 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 FlashAMD Radeon Cloud, BazaarLink, ElectronHub1M10 yêu cầu/phút
50 yêu cầu/ngày
Shared rate limit
CóKhông
Qwen3.8 27BElectronHub, Groq, OVH AI Endpoints262K30 yêu cầu/phút
250 yêu cầu/ngày
70,000 token/phút
~6M
CóCó
Gemini 3.6 FlashGoogle AI Studio1M10 yêu cầu/phút
20 yêu cầu/ngày
250,000 token/phút
~3M
CóCó
Qwen 3.8 27BCloudflare Workers AI262KShared 10k neurons/dayCó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_switch trong .env củ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ânCá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ừ /connectXóa apiKey khỏi options, hoặc chạy lại setup-opencode
OpenCode không dùng provider mớimodel ở cấp cao nhất chưa được đặtĐặt "model": "freellmapi/auto"
Model not foundModel id không có trong bản ánh xạ models của providerThêm id vào bản ánh xạ, hoặc chạy lại setup-opencode
Khóa {env:VAR} rỗngOpenCode thay một biến chưa đặt bằng chuỗi rỗngExport biến trong cùng shell, hoặc lưu khóa bằng /connect
Gọi công cụ thất bạiMô hình có gọi công cụ yếuChọ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ạnThêm khóa từ nhiều nhà cung cấp hơn, hoặc chờ thời gian nghỉ kết thúc
Dùng tất cả các mô hình này qua một khóa duy nhất. FreeLLMAPI là bộ định tuyến mã nguồn mở, tự lưu trữ. Nó đặt tất cả các gói miễn phí này sau một endpoint duy nhất tương thích OpenAI, và tự chuyển sang nhà cung cấp khác khi một nhà cung cấp bị giới hạn tốc độ. Xem danh mục hoặc bắt đầu.

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

Nguồn

Tất cả hướng dẫn · Xem tất cả mô hình miễn phí