Cài đặt OpenCode và cấu hình OmniProxy

OpenCode là trợ lý lập trình mã nguồn mở, có thể viết mã trong terminal, IDE hoặc ứng dụng máy tính. Công cụ này không lưu mã nguồn và ngữ cảnh của bạn, nên phù hợp với các dự án chú trọng quyền riêng tư. Chế độ build dùng để sửa đổi dự án, còn plan mặc định chỉ đọc, phù hợp để tìm hiểu mã nguồn chưa quen thuộc và lập kế hoạch chỉnh sửa trước. Bạn có thể lựa chọn dịch vụ mô hình theo nhu cầu.

Chuẩn bị trước khi cài đặt

Script cài đặt là cách đơn giản nhất. Bạn cần một terminal hiện đại, tức chương trình terminal có thể chạy lệnh và thao tác với tệp dự án, chẳng hạn như WezTerm, Alacritty, Ghostty hoặc Kitty. Trên Windows, nên ưu tiên WSL. Đây là công cụ dùng để chạy môi trường Linux trong Windows, với hiệu năng và tính năng đầy đủ hơn.

Dễ nhất

Tập lệnh cài đặt

curl opencode.ai/install
Dùng trực tiếp trên macOS Linux
Khuyến nghị WSL trên Windows

macOS Linux

Homebrew tap

anomalyco/tap/opencode
Được cập nhật thường xuyên hơn formula
Arch cũng có gói phần mềm

Windows gốc

Trình quản lý gói

choco hoặc scoop
Hoặc cài đặt toàn cục bằng npm
Cũng có thể tải từ Releases

Hãy dùng script cài đặt trước. Nếu đã quen với trình quản lý gói, bạn có thể dùng các lệnh khác được liệt kê.

Đồng thời, hãy chuẩn bị ID mô hình trong danh sách mô hình hiện tại. ID mô hình là tên mà dịch vụ dùng để xác định chính xác một mô hình cụ thể.

Cài đặt và khởi chạy lần đầu

Lệnh cài đặt dễ dùng nhất là:

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

Bạn cũng có thể dùng các phương thức cài đặt sau:

Node.js: npm install -g opencode-ai. Bun, pnpm và Yarn cũng có các lệnh cài đặt toàn cục tương ứng; xem trang giới thiệu ở cuối bài.
Homebrew trên macOS và Linux: brew install anomalyco/tap/opencode. Hãy dùng tap này vì nó được cập nhật thường xuyên hơn brew install opencode do nhóm Homebrew duy trì.
Arch Linux: dùng sudo pacman -S opencode cho bản ổn định; với phiên bản mới hơn, có thể dùng gói AUR opencode-bin.
Windows: dùng choco install opencode hoặc scoop install opencode; bạn cũng có thể dùng npm install -g opencode-ai. Ngoài ra, có thể tải tệp nhị phân từ Releases. Việc hỗ trợ cài đặt bằng Bun trên Windows vẫn đang được phát triển.

Đi tới thư mục dự án rồi khởi chạy OpenCode:

cd /path/to/project
opencode

Trong lần sử dụng đầu tiên, bạn có thể chạy /init. Lệnh này sẽ phân tích dự án và tạo AGENTS.md trong thư mục gốc của dự án. Bạn có thể commit tệp này vào Git để lưu lại phần hướng dẫn cho dự án.

Lấy thông số kết nối từ OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: sao chép từ danh sách mô hình hiện tại của OmniProxy

baseURL là địa chỉ dịch vụ, API Key là thông tin xác thực truy cập và Model ID là tên đầy đủ của mô hình.

Khi sử dụng /v1/chat/completions, gói npm phải là @ai-sdk/openai-compatible. Chat Completions ở đây là một loại giao diện yêu cầu trò chuyện. Chỉ chuyển sang @ai-sdk/openai khi mô hình sử dụng /v1/responses. Nếu OmniProxy được dùng qua đường dẫn Chat Completions, hãy giữ nguyên gói tương thích.

Hãy sao chép toàn bộ ID mô hình từ danh sách hiện tại của OmniProxy, bao gồm cả dấu gạch chéo. Hai ID dùng để đối chiếu vào ngày 2026-10-09 là claude-sonnet-5-5 và gpt-6-luna. gpt-6-luna hỗ trợ Chat Completions; trong Chat Completions, gọi hàm chỉ được hỗ trợ khi reasoning_effort là none. Không sao chép các ID không có trong danh sách.

Điền cấu hình công cụ

Có thể hiểu Provider là một nhóm cấu hình mà OpenCode dùng để kết nối với dịch vụ mô hình. Trong tài liệu Provider, các dịch vụ tương thích OpenAI không có trong danh sách /connect được xem là Provider tùy chỉnh. Dịch vụ tương thích OpenAI là dịch vụ sử dụng cùng định dạng yêu cầu và có thể được gọi bằng cùng một loại ứng dụng khách.

Trong OpenCode, chạy /connect rồi cuộn đến Other.
Nhập một Provider ID. Phần bên dưới sử dụng omniproxy. ID này nên dễ nhớ vì bạn phải dùng cùng một ID trong tệp cấu hình.
Nhập API Key của OmniProxy. Bước này chỉ lưu thông tin xác thực; địa chỉ và mô hình vẫn phải được ghi vào opencode.json. Thông tin xác thực được lưu tại ~/.local/share/opencode/auth.json.
Tạo hoặc chỉnh sửa opencode.json trong thư mục dự án:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

Chạy /models; Provider tùy chỉnh và các mô hình sẽ xuất hiện trong danh sách.

ID trong /connect phải trùng với khóa trong opencode.json. Không ghi khóa thật vào tệp này. Nếu không dùng /connect, bạn cũng có thể sử dụng cú pháp biến môi trường trong options.apiKey, chẳng hạn như {env:VARIABLE_NAME}. Trong thử nghiệm ngày 2026-10-09 với OpenCode 1.18.34, khóa được ghi trực tiếp vào options.apiKey của dự án mà không dùng /connect, và kết nối vẫn hoạt động. Nếu gateway không xác minh khóa, mục này có thể là một chuỗi ký tự giữ chỗ chỉ dùng trên máy cục bộ. Các khóa trong models phải sử dụng ID đầy đủ từ danh sách.

Khóa

/connect

Chọn Other ở cuối
Tự đặt Provider ID
Được lưu trong auth.json

Dự án

opencode.json

Khóa provider phải cùng tên
npm dùng gói tương thích
baseURL kết thúc bằng /v1

Chọn dùng

/models

Mô hình xuất hiện trong danh sách
Chọn một mô hình rồi đặt câu hỏi
ID phải theo danh sách của gateway

Khóa và địa chỉ được lưu ở hai nơi khác nhau. Provider ID tại cả hai nơi phải giống nhau.

Xác minh bằng một tác vụ thực tế

Trước tiên, hãy chạy một tác vụ thực tế trong thư mục dự án. Định dạng tham chiếu mô hình là Provider ID/ID mô hình; phải giữ nguyên dấu gạch chéo trong ID mô hình:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Hãy giải thích một tệp do bạn chỉ định đang làm gì, không sửa đổi tệp."

--auto cho phép lần chạy này sử dụng các công cụ như đọc tệp. Trong thử nghiệm ngày 2026-10-09 với OpenCode 1.18.34, công cụ đã đọc được nội dung của tệp được chỉ định. Lần đầu mất khoảng hai phút.

Để sử dụng ở chế độ tương tác, hãy chạy opencode, sau đó dùng /models để chọn mô hình. Bạn có thể dùng @ để tìm kiếm tệp. Dùng opencode auth list để xác nhận thông tin xác thực đã được lưu qua /connect, sau đó kiểm tra nguồn và ID mô hình trong nhật ký lệnh gọi của OmniProxy.

Khởi động

opencode khởi chạy được

Trước tiên cd đến dự án
auth list hiển thị được ID
Tệp cấu hình nằm trong dự án

Tác vụ

Nó đã đọc mã

Hỏi về một tệp cụ thể
Xem phần giải thích của nó
Nếu không đúng thì dùng /undo

Nhật ký

Có thể thấy trên gateway

Nguồn là OpenCode
ID mô hình khớp
Không commit khóa

Sau khi lưu tệp cấu hình, bạn vẫn cần thực hiện một yêu cầu thực tế trong dự án.

Lỗi thường gặp

Không có OmniProxy trong /models: kiểm tra xem ID trong /connect có trùng với khóa trong opencode.json hay không, npm có phải là @ai-sdk/openai-compatible hay không và baseURL có kết thúc bằng /v1 hay không.
Không thấy thông tin xác thực: chạy opencode auth list. Các Provider như Bedrock sử dụng biến môi trường sẽ không xuất hiện ở đây; Provider tùy chỉnh được thiết lập qua /connect phải xuất hiện.
Tính năng trên Windows không đầy đủ: chuyển sang dùng script cài đặt trong WSL.
ID mô hình không hợp lệ: sao chép lại từ danh sách hiện tại của OmniProxy và sửa khóa trong models.
Yêu cầu được gửi đến sai giao diện: với Chat Completions, hãy giữ nguyên @ai-sdk/openai-compatible. Không đổi gói chỉ để dùng giao diện Responses, trừ khi mô hình đó trên OmniProxy thực sự sử dụng /v1/responses.

Tài liệu tham khảo chính thức

Về cài đặt, xem Giới thiệu OpenCode. Về Provider tùy chỉnh, xem Providers. Các ID mô hình dùng trong ví dụ có tại Tổng quan về mô hình Claude và GPT-6 Luna.

Thay thế mọi chỗ giữ chỗ bằng giá trị từ cấu hình OmniProxy của riêng bạn. Không bao giờ công bố khóa thật.

Kết quả được lưu hoặc mã HTTP 200 đơn lẻ không chứng minh khả năng tương thích đầy đủ của Agent. Hãy kiểm tra nguồn và mô hình trong bản ghi lệnh gọi của OmniProxy.

Nguồn chính thức · OpenCode ↗