diff --git a/English/.gitbook/assets/Agentbase-image/use-codex-with-minimax.png b/English/.gitbook/assets/Agentbase-image/use-codex-with-minimax.png new file mode 100644 index 00000000..cdfb63d7 Binary files /dev/null and b/English/.gitbook/assets/Agentbase-image/use-codex-with-minimax.png differ diff --git a/English/.gitbook/assets/Agentbase-image/using-opencode-with-maas.png b/English/.gitbook/assets/Agentbase-image/using-opencode-with-maas.png new file mode 100644 index 00000000..9b84c859 Binary files /dev/null and b/English/.gitbook/assets/Agentbase-image/using-opencode-with-maas.png differ diff --git a/English/SUMMARY.md b/English/SUMMARY.md index 1ad29af9..18c6bf56 100644 --- a/English/SUMMARY.md +++ b/English/SUMMARY.md @@ -740,6 +740,8 @@ * [AI Coding](ai-stack/agent-base/ai-coding/README.md) * [Connect Claude Code to GreenNode MaaS](ai-stack/agent-base/ai-coding/connect-claude-code-to-maas.md) * [Connect OpenAI-compatible Clients to GreenNode MaaS](ai-stack/agent-base/ai-coding/connect-openai-compatible-to-maas.md) + * [Use Codex with Minimax via GreenNode MaaS](ai-stack/agent-base/ai-coding/use-codex-with-minimax.md) + * [Use OpenCode with GreenNode MaaS](ai-stack/agent-base/ai-coding/opencode-with-maas-model.md) * [MCP Governance](ai-stack/agent-base/mcp-governance/README.md) * [MCP Gateway](ai-stack/agent-base/mcp-governance/mcp-gateway/README.md) * [Manage MCP Gateway](ai-stack/agent-base/mcp-governance/mcp-gateway/manage-mcp-gateway.md) diff --git a/English/ai-stack/agent-base/ai-coding/opencode-with-maas-model.md b/English/ai-stack/agent-base/ai-coding/opencode-with-maas-model.md new file mode 100644 index 00000000..63e1b922 --- /dev/null +++ b/English/ai-stack/agent-base/ai-coding/opencode-with-maas-model.md @@ -0,0 +1,183 @@ +# Use OpenCode with GreenNode MaaS + +> Configure [OpenCode](https://opencode.ai) — a TUI coding assistant — to call models through GreenNode MaaS via the `@ai-sdk/openai-compatible` provider, billed via internal credit-tokens. + +--- + +## Prerequisites + +- An active [AI Platform](https://aiplatform.console.vngcloud.vn/) account +- API key (`vn-...` token) with status **ACTIVE** +- Node.js installed + +--- + +## Step 1 — Install OpenCode + +```bash +npm install -g opencode-ai +``` + +Or via Homebrew (macOS): + +```bash +brew install opencode +``` + +--- + +## Step 2 — Get an API key from AI Platform + +1. Log in to [AI Platform Console](https://aiplatform.console.vngcloud.vn/) +2. Go to **API Keys** → **Create API Key** +3. Name the key (5–50 chars, lowercase letters, numbers, and hyphens) +4. Copy the API key (`vn-...`) + +{% hint style="warning" %} +A newly created API key has status `pending`. Wait until the status is `ACTIVE` before using it. +{% endhint %} + +--- + +## Step 3 — Create the `opencode.json` config file + +Create `opencode.json` at the project root: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "model": "MAAS-chat/openai/gpt-oss-120b", + "provider": { + "MAAS-chat": { + "npm": "@ai-sdk/openai-compatible", + "name": "MAAS chat", + "options": { + "baseURL": "https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1", + "apiKey": "{env:MAAS_API_KEY}" + }, + "models": { + "openai/gpt-oss-120b": { + "name": "openai/gpt-oss-120b" + } + } + } + } +} +``` + +**Field reference:** + +| Field | Purpose | +|---|---| +| `$schema` | Enables editor autocomplete and validation | +| `model` | Default model — format is `/` | +| `provider.MAAS-chat` | Provider key — the part before `/` in `model` must match exactly | +| `npm` | Adapter package — `@ai-sdk/openai-compatible` works for any OpenAI-style endpoint | +| `options.baseURL` | MaaS endpoint, including the `/v1` suffix | +| `options.apiKey` | MaaS token — use `{env:MAAS_API_KEY}` instead of a hardcoded value | +| `models` | Models to expose from this provider | + +{% hint style="warning" %} +Common mistake: setting `"model"` to a value that does not match a registered provider key. OpenCode resolves `model` by splitting on the first `/` and looking up the provider. If it doesn't match a `provider.*` entry, the model fails to load. Always use `MAAS-chat/openai/gpt-oss-120b`. +{% endhint %} + +--- + +## Step 4 — Provide the API key + +Because the config uses `{env:MAAS_API_KEY}`, the key is never stored in the file — OpenCode reads it from the environment variable at runtime. Two options: + +**Option A — Export the environment variable (recommended)** + +Export the key in your shell, then launch OpenCode in the same session: + +```bash +export MAAS_API_KEY="vn-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +opencode +``` + +To set it automatically on every terminal open, add it to `~/.zshrc` or `~/.bashrc`: + +```bash +echo 'export MAAS_API_KEY="vn-xxxx..."' >> ~/.zshrc +source ~/.zshrc +``` + +Or set it inline for a single run: + +```bash +MAAS_API_KEY="vn-xxxx..." opencode +``` + +**Option B — Use a gitignored `.env` file in the project** + +Create a `.env` file (add to `.gitignore`): + +```bash +export MAAS_API_KEY="vn-xxxx..." +``` + +Source it before launching OpenCode: + +```bash +source .env && opencode +``` + +{% hint style="warning" %} +Do not hardcode the API key directly in `opencode.json` if the file is committed to git. If a key has already been committed, rotate it immediately in the MAAS Console — once pushed, it must be treated as compromised. +{% endhint %} + +--- + +## Step 5 — Run OpenCode and select the model + +1. Navigate to the project directory and run: + + ```bash + opencode + ``` + + OpenCode starts with `MAAS-chat/openai/gpt-oss-120b` as the active model. + +2. Switch models at runtime with the `/models` command, then pick **MAAS chat → openai/gpt-oss-120b** from the list. + +

OpenCode running with openai/gpt-oss-120b via GreenNode MaaS

+ +--- + +## Adding more MaaS models + +To expose additional models from the same MaaS endpoint, add entries under `models`: + +```json +"models": { + "openai/gpt-oss-120b": { "name": "openai/gpt-oss-120b" }, + "openai/gpt-oss-20b": { "name": "openai/gpt-oss-20b" } +} +``` + +Then select them via `/models`, or update the top-level `model` field to `MAAS-chat/`. + +--- + +## Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| `provider not found` / model won't load | `model` value doesn't match a provider key | Use `MAAS-chat/openai/gpt-oss-120b` | +| `401 Unauthorized` | Missing, expired, or inactive API key | Re-export `MAAS_API_KEY`; rotate the token in MAAS Console | +| `404` on requests | Wrong base URL or missing `/v1` | Confirm `baseURL` ends with `/v1` | +| Connection timeout | Endpoint unreachable from your network | Check VPN / connectivity to `*.api.vngcloud.vn` | +| Model returns errors but auth is fine | Incorrect model ID | Use the exact ID MaaS publishes (`openai/gpt-oss-120b`) | + +--- + +## Result + +After completing setup, OpenCode routes all requests through GreenNode MaaS. Usage is recorded on [AI Platform Console → Usage](https://aiplatform.console.vngcloud.vn/). + +| I want to... | Go to | +|---|---| +| Use Codex with Minimax via MaaS | [Use Codex with Minimax via GreenNode MaaS](use-codex-with-minimax.md) | +| Connect Claude Code to MaaS | [Connect Claude Code to GreenNode MaaS](connect-claude-code-to-maas.md) | +| View usage and billing | [AI Platform Console](https://aiplatform.console.vngcloud.vn/) | diff --git a/English/ai-stack/agent-base/ai-coding/use-codex-with-minimax.md b/English/ai-stack/agent-base/ai-coding/use-codex-with-minimax.md new file mode 100644 index 00000000..177f45d9 --- /dev/null +++ b/English/ai-stack/agent-base/ai-coding/use-codex-with-minimax.md @@ -0,0 +1,136 @@ +# Use Codex with Minimax via GreenNode MaaS + +> Configure [OpenAI Codex CLI](https://github.com/openai/codex) to call Minimax models through GreenNode MaaS — using the Responses API via a custom `maas` provider defined in `codex.toml`. + +--- + +## Prerequisites + +- An active [AI Platform](https://aiplatform.console.vngcloud.vn/) account +- API key (`vn-...` token) with status **ACTIVE** +- Node.js ≥ 22 installed + +--- + +## Step 1 — Install Codex CLI + +```bash +npm install -g @openai/codex +``` + +Verify the installation: + +```bash +codex --version +``` + +--- + +## Step 2 — Get an API key from AI Platform + +1. Log in to [AI Platform Console](https://aiplatform.console.vngcloud.vn/) +2. Go to **API Keys** → **Create API Key** +3. Name the key (5–50 chars, lowercase letters, numbers, and hyphens) +4. Copy the API key (`vn-...`) + +{% hint style="warning" %} +A newly created API key has status `pending`. Wait until the status is `ACTIVE` before using it. +{% endhint %} + +--- + +## Step 3 — Configure `codex.toml` + +Create or edit `~/.codex/config.toml` (system-wide) or `codex.toml` at the project root (project-scoped): + +```toml +# API key — export before running Codex +# export MAAS_API_KEY="vn-...your-gateway-token..." + +model_provider = "maas" +model = "minimax/minimax-m2.5" + +# Required because MAAS does not expose model metadata — prevents incorrect context truncation +model_context_window = 204800 +model_max_output_tokens = 16400 + +# MAAS backend is stateless — Codex must resend the full conversation every turn +disable_response_storage = true + +[model_providers.maas] +name = "MAAS AI Gateway" + +# base_url WITHOUT trailing /responses — Codex appends it (→ .../v1/responses) +base_url = "https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1" +env_key = "MAAS_API_KEY" +wire_api = "responses" +request_max_retries = 3 +``` + +**Field reference:** + +| Field | Purpose | +|---|---| +| `model_provider` | Key of the provider defined in `[model_providers.*]` | +| `model` | Model ID sent to MaaS | +| `model_context_window` | Declared manually because MaaS does not expose model metadata | +| `disable_response_storage` | Required for stateless backends — resends full conversation each turn | +| `base_url` | MaaS endpoint with `/v1` — Codex appends `/responses` automatically | +| `env_key` | Name of the environment variable holding the API key | +| `wire_api` | Protocol used — `responses` maps to the OpenAI Responses API | + +--- + +## Step 4 — Set the API key and run Codex + +Export the API key in your shell: + +```bash +export MAAS_API_KEY="vn-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +``` + +To set it automatically on every terminal open, add it to `~/.zshrc` or `~/.bashrc`: + +```bash +echo 'export MAAS_API_KEY="vn-xxxx..."' >> ~/.zshrc +source ~/.zshrc +``` + +Navigate to the project directory and run Codex: + +```bash +codex +``` + +Codex displays the active provider and model in the session header: + +``` +model: minimax/minimax-m2.5 /model to change +directory: ~/your-project +``` + +

Codex running with minimax/minimax-m2.5 via GreenNode MaaS

+ +--- + +## Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| `401 Unauthorized` | Wrong, missing, or inactive API key | Re-export `MAAS_API_KEY`; check key status in AI Platform Console | +| `404` on requests | Wrong `base_url` or missing `/v1` | Ensure `base_url` ends with `/v1` (no `/responses`) | +| Context truncated incorrectly | Model metadata not declared | Verify `model_context_window` and `model_max_output_tokens` in config | +| Previous context lost each turn | `disable_response_storage` not set | Add `disable_response_storage = true` to config | +| Connection timeout | Endpoint unreachable | Check VPN / connectivity to `*.api.vngcloud.vn` | + +--- + +## Result + +After completing setup, Codex CLI routes all requests through GreenNode MaaS using the Minimax model. Usage is recorded on [AI Platform Console → Usage](https://aiplatform.console.vngcloud.vn/). + +| I want to... | Go to | +|---|---| +| Use OpenCode with MaaS | [Use OpenCode with GreenNode MaaS](opencode-with-maas-model.md) | +| Connect Claude Code to MaaS | [Connect Claude Code to GreenNode MaaS](connect-claude-code-to-maas.md) | +| View usage and billing | [AI Platform Console](https://aiplatform.console.vngcloud.vn/) | diff --git a/Vietnamese/.gitbook/assets/Agentbase-image/use-codex-with-minimax.png b/Vietnamese/.gitbook/assets/Agentbase-image/use-codex-with-minimax.png new file mode 100644 index 00000000..cdfb63d7 Binary files /dev/null and b/Vietnamese/.gitbook/assets/Agentbase-image/use-codex-with-minimax.png differ diff --git a/Vietnamese/.gitbook/assets/Agentbase-image/using-opencode-with-maas.png b/Vietnamese/.gitbook/assets/Agentbase-image/using-opencode-with-maas.png new file mode 100644 index 00000000..9b84c859 Binary files /dev/null and b/Vietnamese/.gitbook/assets/Agentbase-image/using-opencode-with-maas.png differ diff --git a/Vietnamese/SUMMARY.md b/Vietnamese/SUMMARY.md index 89c7b12e..df3de88c 100644 --- a/Vietnamese/SUMMARY.md +++ b/Vietnamese/SUMMARY.md @@ -868,6 +868,8 @@ * [AI Coding](ai-stack/agent-base/ai-coding/README.md) * [Kết nối Claude Code với GreenNode MaaS](ai-stack/agent-base/ai-coding/ket-noi-claude-code-voi-maas.md) * [Kết nối OpenAI-compatible với GreenNode MaaS](ai-stack/agent-base/ai-coding/ket-noi-openai-compatible-voi-maas.md) + * [Dùng Codex với Minimax qua GreenNode MaaS](ai-stack/agent-base/ai-coding/hướng-dẫn-xài-codex-với-minimax.md) + * [Dùng OpenCode với GreenNode MaaS](ai-stack/agent-base/ai-coding/opencode-with-maas-model.md) * [MCP Governance](ai-stack/agent-base/mcp-governance/README.md) * [MCP Gateway](ai-stack/agent-base/mcp-governance/mcp-gateway/README.md) * [Quản lý MCP Gateway](ai-stack/agent-base/mcp-governance/mcp-gateway/quan-ly-mcp-gateway.md) diff --git "a/Vietnamese/ai-stack/agent-base/ai-coding/h\306\260\341\273\233ng-d\341\272\253n-x\303\240i-codex-v\341\273\233i-minimax.md" "b/Vietnamese/ai-stack/agent-base/ai-coding/h\306\260\341\273\233ng-d\341\272\253n-x\303\240i-codex-v\341\273\233i-minimax.md" new file mode 100644 index 00000000..e68f95d5 --- /dev/null +++ "b/Vietnamese/ai-stack/agent-base/ai-coding/h\306\260\341\273\233ng-d\341\272\253n-x\303\240i-codex-v\341\273\233i-minimax.md" @@ -0,0 +1,136 @@ +# Dùng Codex với Minimax qua GreenNode MaaS + +> Hướng dẫn cấu hình [OpenAI Codex CLI](https://github.com/openai/codex) để gọi model Minimax qua GreenNode MaaS — sử dụng Responses API thông qua custom provider `maas` định nghĩa trong `codex.toml`. + +*** + +## Điều kiện cần (Prerequisites) + +* Đã có tài khoản [AI Platform](https://aiplatform.console.vngcloud.vn/) +* Đã tạo API key (token `vn-...`) với status **ACTIVE** +* Node.js ≥ 22 đã cài đặt + +*** + +## Bước 1 — Cài đặt Codex CLI + +```bash +npm install -g @openai/codex +``` + +Xác nhận cài thành công: + +```bash +codex --version +``` + +*** + +## Bước 2 — Lấy API key từ AI Platform + +1. Đăng nhập [AI Platform Console](https://aiplatform.console.vngcloud.vn/) +2. Vào **API Keys** → **Create API Key** +3. Đặt tên key (5–50 ký tự, chữ thường + số + gạch ngang) +4. Copy API key (`vn-...`) vừa tạo + +{% hint style="warning" %} +API key mới tạo ở trạng thái `pending`. Đợi đến khi status = `ACTIVE` mới dùng được. +{% endhint %} + +*** + +## Bước 3 — Cấu hình `codex.toml` + +Tạo hoặc chỉnh sửa file `~/.codex/config.toml` (cấu hình toàn hệ thống) hoặc `codex.toml` tại thư mục gốc project (chỉ áp dụng cho project đó): + +```toml +# API key — export trước khi chạy Codex +# export MAAS_API_KEY="vn-...your-gateway-token..." + +model_provider = "maas" +model = "minimax/minimax-m2.5" + +# Cần thiết vì MAAS không trả metadata model — tránh context bị cắt sai +model_context_window = 204800 +model_max_output_tokens = 16400 + +# MAAS backend là stateless — Codex phải gửi lại toàn bộ conversation mỗi turn +disable_response_storage = true + +[model_providers.maas] +name = "MAAS AI Gateway" + +# base_url KHÔNG có trailing /responses — Codex tự append (→ .../v1/responses) +base_url = "https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1" +env_key = "MAAS_API_KEY" +wire_api = "responses" +request_max_retries = 3 +``` + +**Giải thích các field quan trọng:** + +| Field | Mục đích | +|---|---| +| `model_provider` | Key của provider trong `[model_providers.*]` | +| `model` | Model ID gửi lên MaaS | +| `model_context_window` | Khai báo thủ công vì MaaS không expose metadata model | +| `disable_response_storage` | Bắt buộc cho backend stateless — gửi lại full conversation mỗi turn | +| `base_url` | MaaS endpoint có `/v1` — Codex tự thêm `/responses` phía sau | +| `env_key` | Tên biến môi trường chứa API key | +| `wire_api` | Protocol sử dụng — `responses` tương ứng OpenAI Responses API | + +*** + +## Bước 4 — Set API key và chạy Codex + +Export API key trong shell: + +```bash +export MAAS_API_KEY="vn-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +``` + +Để tự động mỗi lần mở terminal, thêm vào `~/.zshrc` hoặc `~/.bashrc`: + +```bash +echo 'export MAAS_API_KEY="vn-xxxx..."' >> ~/.zshrc +source ~/.zshrc +``` + +Chạy Codex trong thư mục project: + +```bash +codex +``` + +Codex sẽ hiển thị provider và model đang dùng tại header session: + +``` +model: minimax/minimax-m2.5 /model to change +directory: ~/your-project +``` + +

Codex chạy với model minimax/minimax-m2.5 qua GreenNode MaaS

+ +*** + +## Troubleshooting + +| Triệu chứng | Nguyên nhân | Cách xử lý | +|---|---|---| +| `401 Unauthorized` | API key sai, thiếu, hoặc chưa ACTIVE | Re-export `MAAS_API_KEY`; kiểm tra status key tại AI Platform Console | +| `404` khi gửi request | `base_url` sai hoặc thiếu `/v1` | Đảm bảo `base_url` kết thúc bằng `/v1` (không có `/responses`) | +| Context bị cắt sai | Model metadata không được khai báo | Kiểm tra `model_context_window` và `model_max_output_tokens` trong config | +| Mỗi turn mất context cũ | `disable_response_storage` chưa được set | Thêm `disable_response_storage = true` vào config | +| Connection timeout | Endpoint không truy cập được | Kiểm tra VPN / kết nối đến `*.api.vngcloud.vn` | + +*** + +## Kết quả + +Sau khi hoàn thành, Codex CLI route toàn bộ request qua GreenNode MaaS với model Minimax. Usage được ghi nhận trên [AI Platform Console → Usage](https://aiplatform.console.vngcloud.vn/). + +| Tôi muốn tiếp theo... | Đi đến | +| ------------------------------ | ------------------------------------------------------------------------------------- | +| Dùng OpenCode với MaaS | [Dùng OpenCode với GreenNode MaaS](opencode-with-maas-model.md) | +| Kết nối Claude Code với MaaS | [Kết nối Claude Code với GreenNode MaaS](ket-noi-claude-code-voi-maas.md) | +| Xem usage và billing | [AI Platform Console](https://aiplatform.console.vngcloud.vn/) | diff --git a/Vietnamese/ai-stack/agent-base/ai-coding/opencode-with-maas-model.md b/Vietnamese/ai-stack/agent-base/ai-coding/opencode-with-maas-model.md new file mode 100644 index 00000000..7575a192 --- /dev/null +++ b/Vietnamese/ai-stack/agent-base/ai-coding/opencode-with-maas-model.md @@ -0,0 +1,183 @@ +# Dùng OpenCode với GreenNode MaaS + +> Hướng dẫn cấu hình [OpenCode](https://opencode.ai) — TUI coding assistant — để gọi model qua GreenNode MaaS thông qua provider `@ai-sdk/openai-compatible`, thanh toán bằng credit-token nội bộ. + +*** + +## Điều kiện cần (Prerequisites) + +* Đã có tài khoản [AI Platform](https://aiplatform.console.vngcloud.vn/) +* Đã tạo API key (token `vn-...`) với status **ACTIVE** +* Node.js đã cài đặt + +*** + +## Bước 1 — Cài đặt OpenCode + +```bash +npm install -g opencode-ai +``` + +Hoặc qua Homebrew (macOS): + +```bash +brew install opencode +``` + +*** + +## Bước 2 — Lấy API key từ AI Platform + +1. Đăng nhập [AI Platform Console](https://aiplatform.console.vngcloud.vn/) +2. Vào **API Keys** → **Create API Key** +3. Đặt tên key (5–50 ký tự, chữ thường + số + gạch ngang) +4. Copy API key (`vn-...`) vừa tạo + +{% hint style="warning" %} +API key mới tạo ở trạng thái `pending`. Đợi đến khi status = `ACTIVE` mới dùng được. +{% endhint %} + +*** + +## Bước 3 — Tạo file cấu hình `opencode.json` + +Tạo file `opencode.json` tại thư mục gốc của project: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "model": "MAAS-chat/openai/gpt-oss-120b", + "provider": { + "MAAS-chat": { + "npm": "@ai-sdk/openai-compatible", + "name": "MAAS chat", + "options": { + "baseURL": "https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1", + "apiKey": "{env:MAAS_API_KEY}" + }, + "models": { + "openai/gpt-oss-120b": { + "name": "openai/gpt-oss-120b" + } + } + } + } +} +``` + +**Giải thích các field:** + +| Field | Mục đích | +|---|---| +| `$schema` | Bật autocomplete/validation trong editor | +| `model` | Model mặc định — format `/` | +| `provider.MAAS-chat` | Provider key — phần trước `/` trong `model` phải khớp chính xác | +| `npm` | Adapter package — `@ai-sdk/openai-compatible` dùng được cho mọi endpoint OpenAI-style | +| `options.baseURL` | MaaS endpoint, có `/v1` ở cuối | +| `options.apiKey` | Token MaaS — dùng `{env:MAAS_API_KEY}` thay vì hardcode | +| `models` | Danh sách model expose từ provider này | + +{% hint style="warning" %} +Lỗi phổ biến: đặt `"model"` thành tên không khớp với provider key đã đăng ký. OpenCode tách theo `/` đầu tiên để tìm provider — nếu không khớp, model không load được. Luôn dùng `MAAS-chat/openai/gpt-oss-120b`. +{% endhint %} + +*** + +## Bước 4 — Cung cấp API key + +Vì config dùng `{env:MAAS_API_KEY}`, key không nằm trong file mà được đọc từ biến môi trường lúc runtime. Có hai cách: + +**Cách A — Export biến môi trường (khuyến nghị)** + +Export key trong shell rồi chạy OpenCode trong cùng session: + +```bash +export MAAS_API_KEY="vn-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +opencode +``` + +Để tự động mỗi lần mở terminal, thêm vào `~/.zshrc` hoặc `~/.bashrc`: + +```bash +echo 'export MAAS_API_KEY="vn-xxxx..."' >> ~/.zshrc +source ~/.zshrc +``` + +Hoặc set inline cho một lần chạy duy nhất: + +```bash +MAAS_API_KEY="vn-xxxx..." opencode +``` + +**Cách B — Dùng file `.env` gitignored trong project** + +Tạo file `.env` (thêm vào `.gitignore`): + +```bash +export MAAS_API_KEY="vn-xxxx..." +``` + +Chạy OpenCode bằng cách load `.env` trước: + +```bash +source .env && opencode +``` + +{% hint style="warning" %} +Không hardcode API key trực tiếp vào `opencode.json` nếu file đó được commit. Nếu key đã bị commit, rotate ngay tại MAAS Console vì key đó phải coi là đã bị lộ. +{% endhint %} + +*** + +## Bước 5 — Chạy OpenCode và chọn model + +1. Di chuyển đến thư mục project và chạy: + + ```bash + opencode + ``` + + OpenCode khởi động với `MAAS-chat/openai/gpt-oss-120b` là model mặc định. + +2. Đổi model trong phiên bằng lệnh `/models`, sau đó chọn **MAAS chat → openai/gpt-oss-120b** từ danh sách. + +

OpenCode chạy với model openai/gpt-oss-120b qua GreenNode MaaS

+ +*** + +## Thêm model MaaS khác + +Để expose thêm model từ cùng endpoint MaaS, thêm entry vào `models`: + +```json +"models": { + "openai/gpt-oss-120b": { "name": "openai/gpt-oss-120b" }, + "openai/gpt-oss-20b": { "name": "openai/gpt-oss-20b" } +} +``` + +Sau đó chọn qua `/models`, hoặc đổi `model` ở cấp top-level thành `MAAS-chat/` mới. + +*** + +## Troubleshooting + +| Triệu chứng | Nguyên nhân | Cách xử lý | +|---|---|---| +| `provider not found` / model không load | Giá trị `model` không khớp provider key | Dùng `MAAS-chat/openai/gpt-oss-120b` | +| `401 Unauthorized` | API key sai, hết hạn, hoặc chưa ACTIVE | Re-export `MAAS_API_KEY`; rotate token tại MAAS Console | +| `404` khi gửi request | Base URL sai hoặc thiếu `/v1` | Kiểm tra `baseURL` kết thúc bằng `/v1` | +| Connection timeout | Endpoint không truy cập được từ network hiện tại | Kiểm tra VPN / kết nối đến `*.api.vngcloud.vn` | +| Model trả lỗi nhưng auth đúng | Sai model ID | Dùng đúng ID mà MaaS publish (`openai/gpt-oss-120b`) | + +*** + +## Kết quả + +Sau khi hoàn thành, OpenCode route toàn bộ request qua GreenNode MaaS. Usage được ghi nhận trên [AI Platform Console → Usage](https://aiplatform.console.vngcloud.vn/). + +| Tôi muốn tiếp theo... | Đi đến | +| ------------------------------- | ----------------------------------------------------------------------------------- | +| Dùng Codex với Minimax qua MaaS | [Dùng Codex với Minimax qua GreenNode MaaS](hướng-dẫn-xài-codex-với-minimax.md) | +| Kết nối Claude Code với MaaS | [Kết nối Claude Code với GreenNode MaaS](ket-noi-claude-code-voi-maas.md) | +| Xem usage và billing | [AI Platform Console](https://aiplatform.console.vngcloud.vn/) |