Cấu hình OpenCode

1. OpenCode là gì và bạn cần chuẩn bị gì

OpenCode là một agent lập trình AI mã nguồn mở. Công cụ này có thể đọc repository, sửa mã và thực thi lệnh trong terminal, đồng thời có thể dùng cùng desktop app, giao diện Web và extension IDE.

Trước khi tích hợp OpenCode qua RouteAPI, nên chuẩn bị:

Môi trường terminal hoạt động bình thường
Khóa RouteAPI của bạn
Mô hình khả dụng trong console RouteAPI và phù hợp với tác vụ lập trình
Ưu tiên chọn mô hình hỗ trợ giao thức OpenAI-compatible và gọi công cụ

2. Cài đặt OpenCode

Cài đặt CLI

Nếu bạn dùng macOS / Linux / WSL, cách cài đặt được khuyến nghị chính thức là:

curl -fsSL https://opencode.ai/install | bash

Nếu quen cài toàn cục qua Node.js, bạn cũng có thể dùng:

npm install -g opencode-ai

Nếu bạn dùng môi trường Windows PowerShell native, có thể chạy trực tiếp:

npm install -g opencode-ai

Kiểm tra cài đặt

opencode --version

Nếu hiển thị số phiên bản, OpenCode CLI đã được cài đặt thành công.

3. Cách khuyến nghị: lưu khóa trước, rồi viết cấu hình dự án

Tài liệu chính thức OpenCode khuyến nghị trước tiên lưu thông tin xác thực bằng /connect, sau đó khai báo provider và model trong tệp cấu hình. Với gateway như RouteAPI không nằm trong danh sách tích hợp sẵn, chỉ cần chọn Other.

Lưu khóa RouteAPI trong OpenCode

Trước tiên khởi động OpenCode:

opencode

Sau đó chạy trong phiên:

/connect

Tiếp theo hoàn tất theo thứ tự:

Chọn Other.
Điền provider ID là routeapi.
Dán khóa RouteAPI của bạn.

Thông tin xác thực sẽ được OpenCode tự động ghi vào ~/.local/share/opencode/auth.json cục bộ, thường không cần chỉnh sửa thủ công.

Tạo `opencode.json` ở thư mục gốc dự án

Tài liệu chính thức OpenCode hỗ trợ cả cấu hình toàn cục ~/.config/opencode/opencode.json và opencode.json ở thư mục gốc dự án. Với cộng tác nhóm, thường nên đặt cấu hình không nhạy cảm ở thư mục gốc dự án.

{
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "routeapi": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "RouteAPI",
          "options": {
            "baseURL": "https://www.routeapi.ai/v1"
          },
          "models": {
            "your-routeapi-model-id": {
              "name": "RouteAPI Model"
            }
          }
        }
      },
      "model": "routeapi/your-routeapi-model-id"
}

Trong cấu hình trên:

routeapi: ID duy nhất của provider tùy chỉnh, phải hoàn toàn khớp với provider ID đã điền khi /connect.
npm: /v1/chat/completions dùng @ai-sdk/openai-compatible; /v1/responses dùng @ai-sdk/openai.
options.baseURL: https://www.routeapi.ai/v1
models: tên khóa điền ID mô hình thực sự khả dụng trong console RouteAPI, không điền tên hiển thị.
model: định dạng mô hình mặc định là provider_id/model_id, ở đây là routeapi/your-routeapi-model-id.

4. Nếu không muốn dùng `/connect`: chuyển sang biến môi trường

Nếu bạn quen để khóa đến từ biến môi trường, cũng có thể điền trực tiếp options.apiKey trong opencode.json. Đây là cách viết biến được tài liệu chính thức OpenCode hỗ trợ.

4.1 Đặt biến môi trường

Nếu bạn dùng bash, zsh hoặc sh trên macOS / Linux / WSL:

export ROUTEAPI_KEY="khóa RouteAPI của bạn"

Nếu bạn dùng Windows PowerShell:

$env:ROUTEAPI_KEY="khóa RouteAPI của bạn"

4.2 Tham chiếu biến môi trường trong `opencode.json`

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"routeapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "RouteAPI",
      "options": {
        "baseURL": "https://www.routeapi.ai/v1",
        "apiKey": "{env:ROUTEAPI_KEY}"
      },
      "models": {
        "your-routeapi-model-id": {
          "name": "RouteAPI Model"
        }
      }
}
  },
  "model": "routeapi/your-routeapi-model-id"
}

5. Chọn mô hình và khởi động OpenCode

Sau khi cấu hình xong, có thể chọn mô hình và khởi động như sau:

Khởi động OpenCode:

opencode

Chạy trong phiên:

/models

Chọn mô hình dưới routeapi; nếu bạn đã đặt model trong opencode.json, OpenCode sẽ dùng nó làm mặc định.

Nếu chỉ muốn tạm thời đổi mô hình cho phiên hiện tại, cũng có thể dùng tham số dòng lệnh:

opencode -m routeapi/your-routeapi-model-id

Nếu muốn chỉ định riêng một mô hình rẻ hơn cho tác vụ nhẹ như tạo tiêu đề, bạn cũng có thể bổ sung trong cấu hình:

{
  "small_model": "routeapi/your-small-model-id"
}

6. Xử lý sự cố thường gặp

Chạy opencode auth list để xác nhận thông tin xác thực routeapi đã được lưu cục bộ.
Nếu không thấy provider tùy chỉnh trong /models, trước tiên kiểm tra provider ID khi /connect có hoàn toàn khớp với routeapi trong opencode.json hay không.
Nếu mô hình hiển thị nhưng yêu cầu báo lỗi giao thức, ưu tiên kiểm tra gói npm có chọn đúng không: /v1/chat/completions dùng @ai-sdk/openai-compatible, /v1/responses dùng @ai-sdk/openai.
Nếu trên Windows gặp truy cập tệp chậm, hành vi terminal bất thường hoặc đường dẫn không nhất quán, ưu tiên chuyển sang chạy OpenCode trong WSL.
Nếu muốn so sánh các cách tích hợp client RouteAPI khác, có thể đọc tiếp hướng dẫn cấu hình Codex, hướng dẫn cấu hình Cursor và hướng dẫn cấu hình Claude Code.