> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tich-hop/coding/opencode.md). # OpenCode ## Hướng dẫn tích hợp OpenCode Hướng dẫn này trình bày cách kết nối [OpenCode](https://opencode.ai) với API tương thích OpenAI của AVIS. ### OpenCode là gì OpenCode là agent lập trình AI mã nguồn mở, có giao diện terminal (TUI), ứng dụng desktop (macOS/Windows/Linux) và tiện ích mở rộng IDE. Công cụ hỗ trợ nhiều nhà cung cấp mô hình thông qua các adapter AI SDK có thể mở rộng. Vì AVIS chưa có trong danh sách nhà cung cấp tích hợp sẵn của OpenCode, bạn cần đăng ký AVIS làm **nhà cung cấp tùy chỉnh** trỏ đến giao diện tương thích OpenAI. ### 1) Cài đặt OpenCode ```bash # Install script curl -fsSL https://opencode.ai/install | bash # npm npm install -g opencode-ai # Homebrew brew install anomalyco/tap/opencode ``` ### 2) Lấy AVIS API key Đăng nhập tại [avis.net](https://avis.net), mở **Settings → API Keys** và tạo key. Xem thêm phần Xác thực. ### 3) Cấu hình AVIS làm nhà cung cấp tùy chỉnh Đặt key trong shell để `opencode.json` có thể tham chiếu tới mà không cần ghi trực tiếp giá trị gốc: ```bash export AVIS_API_KEY="" ``` Chỉnh sửa tệp cấu hình — `opencode.json` cấp dự án ở thư mục gốc của dự án, hoặc `~/.config/opencode/opencode.json` dùng chung: ```json { "$schema": "https://opencode.ai/config.json", "provider": { "avis": { "npm": "@ai-sdk/openai-compatible", "name": "AVIS", "options": { "baseURL": "https://api.avis.net/api/openai/v1", "apiKey": "{env:AVIS_API_KEY}" }, "models": { "claude-sonnet-5": { "name": "Claude Sonnet 5", "limit": { "context": 200000, "output": 64000 } }, "claude-opus-5": { "name": "Claude Opus 5", "limit": { "context": 200000, "output": 128000 } }, "gpt-5.5": { "name": "GPT-5.5" } } } }, "model": "avis/claude-sonnet-5" } ``` Ghi chú: * `npm: "@ai-sdk/openai-compatible"` là adapter AI SDK cho endpoint tương thích OpenAI chung — đây là adapter cần dùng cho AVIS. * Các key trong `models` phải là **id phẳng chính xác** mà danh mục tương thích OpenAI của AVIS trả về (không có tiền tố `anthropic/`/`openai/`) — ví dụ `claude-sonnet-5`, không phải `anthropic/claude-sonnet-5`. Xác nhận với danh mục trực tiếp: ```bash curl https://api.avis.net/api/openai/v1/models \ -H "x-api-key: $AVIS_API_KEY" | jq '.data[].id' ``` * `"model": "avis/"` đặt mô hình mặc định — tiền tố ở đây là key của khối nhà cung cấp (`avis`), không phải một phần của id trong danh mục AVIS. * `{env:AVIS_API_KEY}` được phân giải từ môi trường khi chạy; OpenCode không cần `AVIS_API_KEY` cho việc gì khác, đó chỉ là cái tên bạn đã chọn trong lệnh `export` ở §3. ### 4) Chạy OpenCode ```bash cd your-project opencode ``` Trong phiên làm việc, liệt kê các mô hình đã cấu hình để xác nhận `avis` xuất hiện: ``` /models ``` Chạy một lần (không tương tác), hữu ích để kiểm tra nhanh hoặc viết script: ```bash opencode run "Reply with exactly one word: pong" --model avis/claude-haiku-4-5 ``` ### 5) Khắc phục sự cố * Nhà cung cấp `avis` không xuất hiện trong `/models` * Thay đổi cấu hình trong `opencode.json` cần khởi động lại `opencode` — thoát ra và chạy lại. * Kiểm tra tính hợp lệ của chính tệp JSON (lỗi cú pháp sẽ âm thầm loại bỏ toàn bộ khối `provider` ở một số phiên bản) — chạy qua bất kỳ công cụ kiểm tra JSON nào/`jq . opencode.json`. * `401 Unauthorized` * `AVIS_API_KEY` chưa được export trong shell mà `opencode` được khởi chạy — `{env:AVIS_API_KEY}` sẽ thành rỗng nếu biến không được đặt ở đó. * AVIS key không hợp lệ hoặc đã bị thu hồi — kiểm tra trực tiếp: `curl -H "x-api-key: $AVIS_API_KEY" https://api.avis.net/api/openai/v1/models`. * `404` / không tìm thấy mô hình / slug mô hình bị từ chối * Id trong `models` không khớp chính xác với danh mục của AVIS (phân biệt hoa thường, không tiền tố) — kiểm tra lại với `GET /api/openai/v1/models` (§3). * `403` với key hợp lệ * Số dư tài khoản đã hết — xem phần Lỗi. * Dùng sai adapter npm * `@ai-sdk/openai-compatible` dành cho lệnh gọi kiểu `/chat/completions`. Nếu bạn muốn dùng đường dẫn kiểu `/responses`, hãy dùng `@ai-sdk/openai` với cùng `baseURL`/`apiKey` — nhưng với AVIS, `@ai-sdk/openai-compatible` trỏ tới `/api/openai/v1` đã hỗ trợ mọi mô hình trong danh mục bất kể thương hiệu (bao gồm cả Anthropic, Gemini, v.v.), nên thông thường không cần chuyển đổi. ### 6) Danh sách kiểm tra tối thiểu từ đầu đến cuối 1. Đã tạo AVIS API key (§2) và export thành `AVIS_API_KEY` trong shell. 2. `opencode.json` có khối nhà cung cấp `avis` với `npm`, `baseURL`, `apiKey` và ít nhất một mục trong `models` khớp với id thực trong danh mục AVIS (§3). 3. Đã khởi động lại `opencode` sau mỗi lần sửa cấu hình. 4. `/models` trong phiên làm việc liệt kê các mô hình của nhà cung cấp `avis`. 5. Một tin nhắn gửi qua OpenCode trả về kết quả từ mô hình, với `avis/` là mô hình đang dùng. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tich-hop/coding/opencode.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.