Hướng dẫn dùng OpenCode với KizunaX Coding Plan và model minimax-m2.5

Nếu bạn thích kiểu làm việc với AI ngay trong terminal, OpenCode là một cái tên rất đáng thử. Nó cho cảm giác khá đúng chất của một coding agent hiện đại: có thể đọc codebase, lên plan, sửa code, hoàn tác thay đổi, chia sẻ session, và quan trọng nhất là không ép bạn phải rời khỏi workflow quen thuộc.

Điều thú vị là OpenCode không chỉ dùng được với những provider mặc định. Nếu bạn đang có Coding Plan của KizunaX, bạn hoàn toàn có thể nối KizunaX vào OpenCode để dùng như một backend coding riêng. Và vì API coding của KizunaX đang đi theo kiểu Anthropic-like API, cách mình thấy hợp lý nhất là khai báo hẳn một custom provider dùng @ai-sdk/anthropic.

Trong bài này, mình sẽ đi thẳng vào thứ mà phần lớn mọi người cần nhất: setup sao cho chạy được thật, ổn định, và đủ gọn để bạn có thể copy cấu hình rồi dùng luôn. Ngoài phần hướng dẫn, mình cũng sẽ điểm qua một chút về cách tận dụng Plan mode của OpenCode để khai thác Coding Plan của KizunaX với model minimax-m2.5.

Vì sao lại ghép OpenCode với KizunaX?

OpenCode mạnh ở trải nghiệm làm việc: terminal-first, workflow rõ ràng, có Plan mode và Build mode, khá hợp với anh em dev thích kiểm soát quá trình thay vì chỉ quăng prompt rồi chờ kết quả.

KizunaX thì ở đây đóng vai trò backend model. Với phần coding API, KizunaX hiện expose theo kiểu Anthropic messages API, đồng thời trả về sẵn các model coding như:

• MiniMax-M2.7-highspeed
• MiniMax-M2.5-highspeed

Trong bài này, mình chọn MiniMax-M2.5-highspeed và map nó thành alias minimax-m2.5 trong OpenCode để dễ dùng hơn.

Nói ngắn gọn, combo này hợp ở chỗ:

1. Bạn vẫn giữ được UX và workflow rất ngon của OpenCode.
2. Bạn có thể trỏ model chạy thực tế sang KizunaX.
3. Bạn tận dụng được Coding Plan của KizunaX ngay trong môi trường làm việc quen thuộc.

Điểm quan trọng nhất trước khi setup

Đây là chỗ dễ cấu hình sai nhất.

Trong docs của OpenCode có phần custom provider, nhưng ví dụ phổ biến nhất thường xoay quanh OpenAI-compatible API. Trong khi API coding mà KizunaX đang cung cấp ở đây là Anthropic-like API, với các endpoint kiểu:

• GET /v1/models
• POST /v1/messages

Vì vậy, cách mình khuyên dùng không phải là cố nhét KizunaX vào custom provider kiểu OpenAI-compatible. Thay vào đó, mình sẽ tách KizunaX thành một provider riêng, nhưng dùng adapter Anthropic:

1. Tạo custom provider, ví dụ tên là kizunax.
2. Gán npm là @ai-sdk/anthropic.
3. Trỏ baseURL sang endpoint coding của KizunaX.
4. Khai báo model custom để alias minimax-m2.5 trỏ đúng vào MiniMax-M2.5-highspeed.

Điểm mình thích ở cách này là config rõ ràng hơn hẳn. Nhìn vào là biết bạn đang dùng một provider custom tên kizunax, chứ không phải override lại toàn bộ provider anthropic mặc định.

Bạn cần chuẩn bị gì?

Rất đơn giản, chỉ cần 3 thứ:

1. API key của KizunaX.
2. Máy đã cài Node.js, hoặc dùng Homebrew nếu bạn ở macOS.
3. Một project bất kỳ để test OpenCode.

Mình cũng khuyên bạn nên dùng biến môi trường cho API key, thay vì hard-code trực tiếp vào config. Làm vậy an toàn hơn, và cũng tiện nếu sau này bạn muốn chia sẻ file cấu hình hoặc commit nó vào repo.

Bước 1: Cài OpenCode

Theo docs chính thức, bạn có thể cài OpenCode bằng nhiều cách. Cách nhanh nhất là dùng script:

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

Nếu bạn quen dùng npm:

npm install -g opencode-ai

Nếu đang ở macOS và thích brew hơn:

brew install anomalyco/tap/opencode

Sau khi cài xong, kiểm tra lại phiên bản:

opencode --version

Bước 2: Thêm API key của KizunaX vào môi trường

Trước tiên, export API key:

export KIZUNAX_API_KEY="kx_your_real_key_here"

Nếu bạn dùng zsh, có thể thêm luôn vào ~/.zshrc:

export KIZUNAX_API_KEY="kx_your_real_key_here"

Sau đó nạp lại shell:

source ~/.zshrc

Nếu muốn kiểm tra key có hoạt động trước khi cấu hình OpenCode, bạn có thể gọi thẳng endpoint models của KizunaX:

curl -X GET "https://kizunax.io/api/coding/anthropic/v1/models" \
  -H "x-api-key: $KIZUNAX_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Nếu mọi thứ ổn, bạn sẽ nhận lại danh sách model coding. Đây là một bước nhỏ nhưng đáng làm, vì nó giúp bạn tách biệt lỗi API key với lỗi cấu hình OpenCode.

Bước 3: Cấu hình OpenCode để dùng KizunaX

Bạn có thể đặt config ở 1 trong 2 nơi:

1. ~/.config/opencode/opencode.json nếu muốn dùng cho nhiều project.
2. opencode.json ở root repo nếu chỉ muốn dùng cho một project cụ thể.

Nếu bạn xác định sẽ dùng KizunaX thường xuyên, mình nghĩ nên để ở global config cho gọn.

Dưới đây là cấu hình mình khuyên dùng:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "kizunax/minimax-m2.5",
  "small_model": "kizunax/minimax-m2.5",
  "provider": {
    "kizunax": {
      "npm": "@ai-sdk/anthropic",
      "name": "KizunaX Coding",
      "options": {
        "apiKey": "{env:KIZUNAX_API_KEY}",
        "baseURL": "https://kizunax.io/api/coding/anthropic/v1",
        "timeout": 600000
      },
      "models": {
        "minimax-m2.5": {
          "id": "MiniMax-M2.5-highspeed",
          "name": "MiniMax M2.5 High-Speed (KizunaX Coding Plan)",
          "limit": {
            "context": 131072,
            "output": 16384
          }
        }
      }
    }
  }
}

Nhìn qua thì file này khá ngắn, nhưng có vài dòng rất đáng chú ý.

model

• Đây là model mặc định mà OpenCode sẽ dùng.
• Ở đây mình đặt là kizunax/minimax-m2.5.

small_model

• Mình để cùng một model để tránh việc OpenCode tự rẽ sang một model nhỏ hơn ở provider khác mà bạn chưa cấu hình.
• Đây là một chi tiết nhỏ nhưng thực tế khá hữu ích.

provider.kizunax.npm

• Dòng này nói với OpenCode rằng provider custom kizunax sẽ dùng adapter @ai-sdk/anthropic.
• Đây chính là mấu chốt để làm việc đúng với API Anthropic-like của KizunaX.

provider.kizunax.name

• Chỉ là tên hiển thị trong UI, nhưng nên đặt rõ ràng để sau này nhìn danh sách provider dễ phân biệt hơn.

apiKey: "{env:KIZUNAX_API_KEY}"

• Dòng này yêu cầu bạn phải set biến môi trường KIZUNAX_API_KEY trước khi chạy OpenCode.
• OpenCode sẽ đọc API key từ env thay vì lưu key trực tiếp trong file config.

baseURL

• Đây là dòng quan trọng nhất trong toàn bộ setup.
• OpenCode sẽ dùng adapter Anthropic, nhưng request thực tế sẽ được gửi sang endpoint coding của KizunaX.

id

• minimax-m2.5 là alias bạn dùng trong OpenCode.
• MiniMax-M2.5-highspeed mới là model ID thực tế phía KizunaX.

limit.context và limit.output

• Các giá trị này được lấy theo thông tin model mà endpoint models của KizunaX trả về.

Bước 4: Mở OpenCode và kiểm tra model

Sau khi có config, đi vào project mà bạn muốn làm việc:

cd /path/to/your/project
opencode

Trong giao diện TUI, chạy:

/models

Nếu cấu hình đúng, bạn sẽ thấy model minimax-m2.5 dưới provider kizunax, với tên hiển thị kiểu như:

MiniMax M2.5 High-Speed (KizunaX Coding Plan)

Nếu đây là lần đầu bạn dùng OpenCode cho repo đó, nên chạy thêm:

/init

Lệnh này sẽ giúp OpenCode phân tích project và tạo file AGENTS.md. Nếu bạn dùng OpenCode thường xuyên trong repo này, đây là file rất đáng giữ lại vì nó giúp các session sau hiểu codebase tốt hơn.

Dùng KizunaX Coding Plan trong Plan mode của OpenCode

Đây là phần mình nghĩ thú vị nhất sau setup.

OpenCode có hai kiểu làm việc rất rõ:

1. Build mode: cho nó sửa code trực tiếp.
2. Plan mode: cho nó nghĩ trước, lên hướng làm, chia bước, chưa đụng vào code ngay.

Nếu bạn muốn tận dụng Coding Plan của KizunaX, Plan mode chính là nơi hợp lý để bắt đầu.

Trong TUI, nhấn Tab để chuyển sang Plan mode. Lúc này, thay vì yêu cầu implement ngay, bạn có thể đưa các prompt kiểu:

Hãy lập kế hoạch refactor module auth theo từng bước. Ưu tiên giảm technical debt, tránh sửa API public, và liệt kê các file cần đổi.

Hoặc:

Hãy đề xuất kế hoạch thêm social login cho project này. Chia nhỏ theo migration, backend, frontend, test và rollout.

Điểm hay là bạn vẫn đang dùng giao diện, toolchain và workflow của OpenCode, nhưng model đứng sau phần lập kế hoạch và coding lại là KizunaX thông qua provider custom kizunax và model minimax-m2.5.

Khi thấy plan đã ổn, nhấn Tab một lần nữa để quay về Build mode, rồi yêu cầu nó bắt đầu implement.

Nếu bạn thích workflow “plan trước, code sau”

Bạn có thể đặt OpenCode mặc định dùng Plan mode bằng cách thêm vào config:

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

Bạn có thể gộp luôn khóa này vào file config chính.

Cá nhân mình thấy thiết lập này khá hợp với những ai dùng AI như một technical copilot hơn là một “máy code tự động”. Nó khiến workflow chậm lại một nhịp, nhưng đổi lại bạn kiểm soát được scope, rủi ro và hướng triển khai tốt hơn.

Workflow mình thấy hợp nhất cho combo này

Nếu chỉ cần một cách dùng đơn giản mà hiệu quả, mình sẽ đi theo flow này:

1. Vào repo và chạy opencode.
2. Chuyển sang Plan mode bằng Tab.
3. Mô tả bài toán đủ rõ để AI lập kế hoạch.
4. Review scope, risk và các file sẽ bị ảnh hưởng.
5. Quay lại Build mode.
6. Cho OpenCode bắt đầu sửa code.
7. Review diff, chạy test, rồi mới commit.

Flow này đặc biệt hợp cho những task mà bạn không muốn AI nhảy vào sửa quá sớm. Nó giữ cho quá trình làm việc có nhịp hơn, và cũng tận dụng đúng tinh thần của Coding Plan.

Một test nhanh mình đã thử

Để kiểm tra cảm giác dùng thực tế chứ không chỉ dừng ở phần setup, mình đã thử một bài test nhanh với KizunaX ngay trong OpenCode: yêu cầu nó build một game Snake bằng HTML, CSS và JavaScript thuần.

Prompt mình dùng là:

Build a complete Snake game using plain HTML5, CSS, and JavaScript in a single self-contained project.

Requirements:

* Use an HTML5 canvas for rendering.
* Do not use external libraries or frameworks.
* Keep the code clean, modular, and easy to modify.
* The snake must move smoothly on a grid.
* Include keyboard controls with arrow keys and WASD.
* Prevent the snake from reversing directly into itself.
* Add food spawning at valid positions only.
* Increase the score when food is eaten.
* Make the snake grow after eating food.
* End the game when the snake hits the wall or itself.
* Show a clear Game Over state with the final score.
* Include a restart feature without reloading the page.
* Display the current score during gameplay.
* Add a simple start screen with instructions.
* Make the layout responsive and centered on the page.
* Use a clean visual style with good contrast.

Implementation details:

* Separate logic into clear parts such as game state, input handling, update loop, collision detection, rendering, and UI state.
* Use `requestAnimationFrame` for the main loop.
* Keep movement timing consistent and independent from rendering.
* Use constants for grid size, speed, colors, and canvas dimensions.
* Write code that is beginner-friendly and well commented.

Deliverables:

* `index.html`
* `style.css`
* `script.js`

Also:

* Explain the folder structure briefly.
* Include short setup instructions.
* After generating the code, review it for obvious bugs and fix them before presenting the final result.

Trong lúc chạy, có thể thấy model chia việc khá rõ: tạo index.html, sau đó đến style.css, rồi script.js, và vẫn giữ được checklist review bug trước khi trả kết quả.

Sau khoảng 3 phút chạy, output mình nhận được là một bản Snake game HTML khá sạch, giao diện ổn, bố cục rõ ràng, và đúng kiểu một project nhỏ có thể mở lên chạy ngay.

Đây không phải benchmark chính thức hay bài test quá nặng, nhưng nó cho mình một cảm giác khá rõ: với những task kiểu tạo mini project, prototype giao diện, hoặc dựng một demo có logic vừa phải, combo OpenCode + KizunaX đủ nhanh để dùng hàng ngày.

Điểm mình thích ở test này là model không chỉ nhả ra một file HTML duy nhất cho xong chuyện, mà vẫn bám theo đúng deliverables index.html, style.css, script.js, đồng thời giữ được flow làm việc khá có tổ chức.

Một vài lỗi thường gặp

Không thấy model trong /models

Hãy kiểm tra lại mấy điểm cơ bản:

1. File config có đúng tên và đúng vị trí chưa.
2. model có đang để kizunax/minimax-m2.5 không.
3. Model custom có nằm trong provider.kizunax.models không.

Nếu cần, bạn có thể dùng:

opencode debug config

để xem OpenCode đang đọc config cuối cùng như thế nào.

Bị 401 hoặc 403

Trường hợp này thường là do:

1. KIZUNAX_API_KEY chưa được export.
2. API key sai hoặc đã hết hiệu lực.
3. Bạn vừa sửa ~/.zshrc nhưng chưa nạp lại shell.

Bị 404 hoặc request fail ngay từ đầu

Hãy nhìn lại baseURL. Với setup trong bài này, nó phải đúng là:

https://kizunax.io/api/coding/anthropic/v1

Thiếu /v1 là đủ để request đi sai endpoint.

OpenCode mở lên nhưng các task nhỏ lại dính model khác

Đó là lý do mình set cả small_model thành kizunax/minimax-m2.5.

Nếu bạn bỏ dòng này đi, OpenCode có thể thử chọn một model nhỏ hơn ở provider khác, và lúc đó bạn lại tưởng là KizunaX đang lỗi trong khi vấn đề thực ra nằm ở fallback model.

Kết lại

Nếu bạn đang muốn dùng OpenCode với một backend riêng cho coding, KizunaX là một lựa chọn rất dễ ghép trong trường hợp API của họ đã expose theo kiểu Anthropic-like. Cách làm gọn nhất là:

1. Cài OpenCode.
2. Export KIZUNAX_API_KEY.
3. Tạo provider custom kizunax dùng @ai-sdk/anthropic và baseURL trỏ sang KizunaX.
4. Map minimax-m2.5 sang MiniMax-M2.5-highspeed.
5. Mở OpenCode, vào Plan mode, rồi bắt đầu workflow plan -> build.

Điểm mình thích ở cách setup này là nó không quá cầu kỳ mà lại khá sạch về mặt cấu hình. Bạn vẫn có được trải nghiệm terminal-first rất tốt của OpenCode, nhưng model thực thi phía sau lại là KizunaX thông qua một provider custom riêng. Nếu bạn đang có sẵn Coding Plan của KizunaX, đây là một cách tích hợp khá mượt để đưa nó vào đúng workflow code hằng ngày.

Tham khảo

• OpenCode docs: https://opencode.ai/docs
• OpenCode config docs: https://opencode.ai/docs/config/
• OpenCode providers docs: https://opencode.ai/docs/providers/
• OpenCode models docs: https://opencode.ai/docs/models/
• KizunaX: https://kizunax.io/