diff --git a/English/.gitbook/assets/ai-coding/claude-code-with-glm.png b/English/.gitbook/assets/ai-coding/claude-code-with-glm.png new file mode 100644 index 00000000..59ea10d1 Binary files /dev/null and b/English/.gitbook/assets/ai-coding/claude-code-with-glm.png differ diff --git a/English/.gitbook/assets/ai-coding/codex-ui-chat.png b/English/.gitbook/assets/ai-coding/codex-ui-chat.png new file mode 100644 index 00000000..351bae6d Binary files /dev/null and b/English/.gitbook/assets/ai-coding/codex-ui-chat.png differ diff --git a/English/.gitbook/assets/ai-coding/done-setup-glm-into-codex.png b/English/.gitbook/assets/ai-coding/done-setup-glm-into-codex.png new file mode 100644 index 00000000..1c7371d8 Binary files /dev/null and b/English/.gitbook/assets/ai-coding/done-setup-glm-into-codex.png differ diff --git a/English/.gitbook/assets/ai-coding/find-config-toml-file.png b/English/.gitbook/assets/ai-coding/find-config-toml-file.png new file mode 100644 index 00000000..2c0c32a2 Binary files /dev/null and b/English/.gitbook/assets/ai-coding/find-config-toml-file.png differ diff --git a/English/.gitbook/assets/ai-coding/tip-chat-with-agent.png b/English/.gitbook/assets/ai-coding/tip-chat-with-agent.png new file mode 100644 index 00000000..5d22ee85 Binary files /dev/null and b/English/.gitbook/assets/ai-coding/tip-chat-with-agent.png differ diff --git a/English/.gitbook/assets/ai-coding/tip-run-after-setup-done.png b/English/.gitbook/assets/ai-coding/tip-run-after-setup-done.png new file mode 100644 index 00000000..872eabc2 Binary files /dev/null and b/English/.gitbook/assets/ai-coding/tip-run-after-setup-done.png differ diff --git a/English/.gitbook/assets/ai-coding/tip-run-to-confirm.png b/English/.gitbook/assets/ai-coding/tip-run-to-confirm.png new file mode 100644 index 00000000..e1925433 Binary files /dev/null and b/English/.gitbook/assets/ai-coding/tip-run-to-confirm.png differ diff --git a/English/SUMMARY.md b/English/SUMMARY.md index 547973b0..885b6f9f 100644 --- a/English/SUMMARY.md +++ b/English/SUMMARY.md @@ -717,7 +717,6 @@ * [Security](ai-stack/ai-gateway/security.md) * [Pricing](ai-stack/ai-gateway/pricing.md) * [AI Coding](ai-stack/ai-coding/README.md) - * [Connect Claude Code to GreenNode MaaS](ai-stack/ai-coding/connect-claude-code-to-maas.md) * [Connect OpenAI-compatible Clients to GreenNode MaaS](ai-stack/ai-coding/connect-openai-compatible-to-maas.md) * [Getting Started with AI Coding](ai-stack/ai-coding/getting-started.md) * [Using MCP Servers with AI Coding](ai-stack/ai-coding/mcp-servers.md) diff --git a/English/ai-stack/ai-coding/cli-tools/claude-code.md b/English/ai-stack/ai-coding/cli-tools/claude-code.md index 6afb81b4..13546f77 100644 --- a/English/ai-stack/ai-coding/cli-tools/claude-code.md +++ b/English/ai-stack/ai-coding/cli-tools/claude-code.md @@ -63,6 +63,8 @@ To persist them for your account (run once, then **reopen PowerShell**): {% endtab %} {% endtabs %} +

ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL configured in the shell profile

+ --- ## Step 3 — Run Claude Code with GLM 5.2 @@ -88,6 +90,8 @@ In Claude Code, type `/status` — it's correct when: Then check the **[AI Platform Console](https://aiplatform.console.greennode.ai/)** to see the call logged. +

Claude Code responding successfully with the z-ai/glm-5.2 model via GreenNode MaaS

+ --- ## Troubleshooting @@ -105,7 +109,6 @@ Then check the **[AI Platform Console](https://aiplatform.console.greennode.ai/) | I want to next... | Go to | |------------------------|--------| -| Use the GUI version | [Claude Desktop](../gui-tools/claude-desktop.md) | | Use OpenCode | [OpenCode](opencode.md) | | See the prerequisites | [Getting Started with AI Coding](../getting-started.md) | diff --git a/English/ai-stack/ai-coding/cli-tools/codex-cli.md b/English/ai-stack/ai-coding/cli-tools/codex-cli.md index b083ecff..06255557 100644 --- a/English/ai-stack/ai-coding/cli-tools/codex-cli.md +++ b/English/ai-stack/ai-coding/cli-tools/codex-cli.md @@ -9,7 +9,7 @@ * Prepare your API key, Base URL, and model following [Getting Started with AI Coding](../getting-started.md) * Node.js ≥ 22 installed -> The GLM 5.2 model via Codex uses the **OpenAI standard** — the Base URL includes `/v1`: `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1`. +> The Minimax M2.5 model via Codex uses the **OpenAI standard** — the Base URL includes `/v1`: `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1`. *** @@ -132,6 +132,7 @@ Once done, the Codex CLI routes all requests through GreenNode MaaS using the Mi | I want to next... | Go to | |---|---| +| Use the GUI version | [Codex Desktop](../gui-tools/codex-desktop.md) | | Use OpenCode with MaaS | [Use OpenCode with GreenNode MaaS](opencode.md) | | Connect Claude Code to MaaS | [Connect Claude Code to GreenNode MaaS](claude-code.md) | | View usage and billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | diff --git a/English/ai-stack/ai-coding/connect-claude-code-to-maas.md b/English/ai-stack/ai-coding/connect-claude-code-to-maas.md deleted file mode 100644 index 49b782cc..00000000 --- a/English/ai-stack/ai-coding/connect-claude-code-to-maas.md +++ /dev/null @@ -1,158 +0,0 @@ -# Connect Claude Code to GreenNode MaaS - -> Route Claude Code CLI requests through GreenNode MaaS instead of the Anthropic API directly — all traffic goes through GreenNode infrastructure and is billed via internal credit-tokens. - -*** - -## Prerequisites - -* An active [AI Platform](https://aiplatform.console.greennode.ai/) account -* Claude Code CLI installed - -{% hint style="info" %} -Claude Code uses the **Anthropic API protocol**. The LLM URL is `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` (no `/v1`). -{% endhint %} - -*** - -## Step 1 — Get an API key from AI Platform - -1. Log in to [AI Platform Console](https://aiplatform.console.greennode.ai/) -2. Go to **API Keys** → **Create API Key** -3. Name the key using the format `claude-code-` (5–50 chars, lowercase letters, numbers, and hyphens) -4. Copy the API key — it is shown only once - -{% hint style="warning" %} -A newly created API key has status `pending`. Poll `api-keys get ` until the status is `ACTIVE` before using it. -{% endhint %} - -*** - -## Step 2 — Select a model - -List available Claude models: - -```bash -bash .claude/skills/agentbase/scripts/aip.sh models list --providers anthropic --status ENABLED -``` - -Note the `path` value for the model you want (e.g., `claude-sonnet-4-6`, `claude-opus-4-8`). This value is used in the model mapping environment variables in the next step. - -*** - -## Step 3 — Configure - -Choose one of two options: - -**Option A — Shell profile (system-wide)** - -Add to `~/.zshrc` or `~/.bashrc`: - -```bash -# GreenNode MaaS — Claude Code Integration -export ANTHROPIC_BASE_URL="https://maas-llm-aiplatform-hcm.api.vngcloud.vn" -export ANTHROPIC_AUTH_TOKEN="" -export ANTHROPIC_API_KEY="" # Must be empty — avoids routing to Anthropic directly - -# Model mapping (use the path from Step 2) -export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6" -export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-8" -export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001" -export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6" -``` - -Reload without restarting the terminal: - -```bash -source ~/.zshrc -``` - -

ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL configured in shell profile

- -**Option B — Project settings (per-project)** - -Create `.claude/settings.local.json` at the project root: - -```json -{ - "env": { - "ANTHROPIC_BASE_URL": "https://maas-llm-aiplatform-hcm.api.vngcloud.vn", - "ANTHROPIC_AUTH_TOKEN": "", - "ANTHROPIC_API_KEY": "", - "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6", - "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8", - "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001", - "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6" - } -} -``` - -{% hint style="warning" %} -Claude Code does not read standard `.env` files. Use `settings.local.json` or a shell profile instead. -{% endhint %} - -*** - -## Step 4 — Verify the connection - -Open Claude Code and run: - -``` -/status -``` - -Expected result: - -* Base URL points to `maas-llm-aiplatform-hcm.api.vngcloud.vn` -* Model matches your configuration - -Confirm requests are recorded in [AI Platform Console → Usage](https://aiplatform.console.greennode.ai/). - -*** - -## Environment Variables Reference - -| Variable | Purpose | Example value | -| -------------------------------- | ----------------------------------- | ------------------------------------------------- | -| `ANTHROPIC_BASE_URL` | Redirect API calls to GreenNode | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` | -| `ANTHROPIC_AUTH_TOKEN` | Authentication API key | `` | -| `ANTHROPIC_API_KEY` | Must be empty (avoid conflict) | `""` | -| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model for everyday coding | `claude-sonnet-4-6` | -| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model for complex reasoning | `claude-opus-4-8` | -| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model for fast completions | `claude-haiku-4-5-20251001` | -| `CLAUDE_CODE_SUBAGENT_MODEL` | Model used when spawning sub-agents | `claude-sonnet-4-6` | - -*** - -## Billing & Usage - -* Requests through GreenNode MaaS are billed in credit-tokens (1 credit = 1 VND) -* View real-time usage on [AI Platform Console → Usage](https://aiplatform.console.greennode.ai/) -* **Prepaid:** credits are deducted every 5-minute collection cycle — when credits run out, the model is automatically disabled -* **Postpaid:** usage is recorded as a debt with no quota limit - -*** - -## Troubleshooting - -| Symptom | Cause | Fix | -| --------------------------------- | --------------------------------- | ------------------------------------------------- | -| `401 Unauthorized` | Wrong or inactive API key | Verify the key; create a new one if needed | -| `403 Forbidden` | API key not yet ACTIVE | Poll `api-keys get ` until status = ACTIVE | -| Model not responding | Credits exhausted, model disabled | Add credits in AI Platform Console | -| Requests still going to Anthropic | `ANTHROPIC_API_KEY` is not empty | Set `ANTHROPIC_API_KEY=""` | -| Wrong model used | Incorrect model path | Verify the `path` field with `aip.sh models list` | -| `/status` reports URL error | Base URL has a trailing slash | Remove trailing `/` from `ANTHROPIC_BASE_URL` | - -*** - -## Result - -After completing setup, Claude Code CLI routes all requests through GreenNode MaaS. Usage is recorded in AI Platform Console and billed via internal credit-tokens. - -

Claude Code running successfully through GreenNode MaaS endpoint

- -| I want to... | Go to | -| --------------------------------------- | ------------------------------------------------------------------------------------------- | -| Use an OpenAI-compatible tool with MaaS | [Connect OpenAI-compatible Clients to GreenNode MaaS](connect-openai-compatible-to-maas.md) | -| View usage and billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | diff --git a/English/ai-stack/ai-coding/connect-openai-compatible-to-maas.md b/English/ai-stack/ai-coding/connect-openai-compatible-to-maas.md index d9f2f7c1..0f225299 100644 --- a/English/ai-stack/ai-coding/connect-openai-compatible-to-maas.md +++ b/English/ai-stack/ai-coding/connect-openai-compatible-to-maas.md @@ -156,5 +156,5 @@ After configuration, the tool or SDK calls models through GreenNode MaaS instead | I want to... | Go to | |---|---| -| Use Claude Code with MaaS | [Connect Claude Code to GreenNode MaaS](connect-claude-code-to-maas.md) | +| Use Claude Code with MaaS | [Connect Claude Code to GreenNode MaaS](cli-tools/claude-code.md) | | View usage and billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | diff --git a/English/ai-stack/ai-coding/gui-tools/README.md b/English/ai-stack/ai-coding/gui-tools/README.md new file mode 100644 index 00000000..dcb82d4a --- /dev/null +++ b/English/ai-stack/ai-coding/gui-tools/README.md @@ -0,0 +1,10 @@ +# GUI Tools + +> AI Coding tools with a graphical interface — just fill in the Base URL and API key, no commands needed. Best for **beginners**. + +Before installing, see [Prerequisites](../getting-started.md). + +| Tool | Notes | +|---|---| +| [Codex Desktop](codex-desktop.md) | Configured via the `config.toml` file in Settings | +| Claude Desktop | Currently only allows connecting real **Anthropic** models (`claude-*`) when configuring third-party inference — self-hosted models from other vendors (GLM, etc.) can't be used through this GUI yet. If you need a self-hosted model from another vendor, switch to [Claude Code (CLI)](../cli-tools/claude-code.md). | diff --git a/English/ai-stack/ai-coding/gui-tools/codex-desktop.md b/English/ai-stack/ai-coding/gui-tools/codex-desktop.md new file mode 100644 index 00000000..229086b4 --- /dev/null +++ b/English/ai-stack/ai-coding/gui-tools/codex-desktop.md @@ -0,0 +1,150 @@ +# Connect Codex Desktop to GreenNode MaaS (GLM 5.2) + +> For **beginners** on macOS or Windows. Configure it by editing a `config.toml` file from Settings — you can ask an AI to help draft it, no need to know TOML syntax. Codex Desktop will use GreenNode's self-hosted **GLM 5.2** model. + +{% hint style="info" %} +**First, complete the [Prerequisites](../getting-started.md):** an **ACTIVE** API key, the Base URL, and the GLM 5.2 model **ENABLED**. This page only covers install and configuration. +{% endhint %} + +You'll need these 3 values (from the Prerequisites page): + +| Info | Value | +| -------------------------- | ------------------------------------------------------------------------------- | +| Base URL (OpenAI standard) | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1` (**with** `/v1`) | +| API key | your`vn-...` key | +| Model ID | `z-ai/glm-5.2` | + +{% hint style="info" %} +**GLM 5.2 is just an example model.** GreenNode offers many models — swap in whichever one you want. Each model's Model ID and Base URL are on its [model detail page](https://aiplatform.console.greennode.ai/models). +{% endhint %} + +--- + +## Step 1 — Download and install Codex Desktop + +Go to **[openai.com/index/introducing-the-codex-app](https://openai.com/index/introducing-the-codex-app/)** and download the app for your machine, then install it like a normal app. + +--- + +## Step 2 — Open the app and log in + +Open Codex and log in with your ChatGPT/OpenAI account. + +

Codex home screen after logging in

+ +--- + +## Step 3 — Open the config.toml file + +1. Click your avatar/account name in the bottom-left corner → **Settings**. +2. In the left search box, type **"config.toml"**. +3. Click **Open config.toml** in the top-right of the **Custom config.toml settings** section — the file opens in your machine's default editor. + +

Find and open config.toml in Settings

+ +--- + +## Step 4 — Add the self-hosted model configuration + +Add the following block to the **end** of `config.toml` (keep the existing content above it): + +```toml +[model_providers.vngcloud-glm] +name = "VNGCloud GLM" +base_url = "https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1" +experimental_bearer_token = "vn-...your-key..." +wire_api = "responses" +stream_idle_timeout_ms = 3000000 +request_max_retries = 3 +supports_websockets = false + +[profiles.glm] +model = "z-ai/glm-5.2" +model_provider = "vngcloud-glm" +model_context_window = 200000 +model_auto_compact_token_limit = 200000 +model_reasoning_effort = "medium" +model_reasoning_summary = "auto" +``` + +**Key fields explained:** + +| Field | Purpose | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `model_providers.vngcloud-glm` | A provider name you choose — reused in`model_provider` below | +| `base_url` | The OpenAI-standard Base URL,**with** `/v1` | +| `experimental_bearer_token` | Your API key, pasted directly into the file — Codex Desktop doesn't need an exported env var like the CLI | +| `wire_api` | Keep as`"responses"` — the Responses API standard Codex Desktop uses | +| `stream_idle_timeout_ms` | Max idle time (ms) before the stream is treated as timed out | +| `request_max_retries` | Number of retries on a failed request | +| `supports_websockets` | Keep as `false` — MaaS doesn't support websockets yet | +| `profiles.glm` | A profile name you choose — appears in the app's model picker | +| `model` | The Model ID sent to MaaS | +| `model_provider` | Points back to the provider declared above | +| `model_context_window` | Set manually since MaaS doesn't expose model metadata | +| `model_auto_compact_token_limit` | Token threshold at which Codex auto-compacts the context | +| `model_reasoning_effort` | Default reasoning effort (`low` / `medium` / `high`) | +| `model_reasoning_summary` | Keep as `"auto"` — lets Codex decide whether to summarize its reasoning | + +{% hint style="warning" %} +**Don't copy the environment-variable style config used for Claude Code** (`export ANTHROPIC_BASE_URL=...`, `claude --model ...`) — that syntax is specific to Claude Code CLI and **doesn't** apply to Codex. Codex Desktop reads its config from `config.toml` using `model_providers` / `profiles` as shown above. +{% endhint %} + +{% hint style="info" %} +**Not comfortable with TOML syntax?** Copy the full content of your current `config.toml`, paste it into an AI chat (Codex, ChatGPT, Claude...) along with the 3 values above (Base URL / API key / Model ID), and ask it to write the `[model_providers.*]` and `[profiles.*]` blocks in the correct Codex format, then paste the result back into the file. +{% endhint %} + +--- + +## Step 5 — Save the file and restart Codex + +1. Save `config.toml`. +2. Fully quit and reopen Codex Desktop. + +--- + +## Step 6 — Verify + +1. In the chat panel, click the model picker (bottom-right corner, e.g. **"5.6 Terra Medium"**). +2. Find the profile you just added (e.g. **glm**) in the list — select it. +3. Type a test message, e.g. *"Write a function to add two numbers in Python."* If it responds, you're set. +4. Check the **[AI Platform Console](https://aiplatform.console.greennode.ai/)** to see the call logged. + +

Configuration succeeded — chat responds and the model picker shows "Custom" instead of the default model

+ +{% hint style="warning" %} +**Note on switching between the default model and your self-hosted model:** If you pick a default Codex model directly from the model picker (UI), the app **only overwrites the `model` field** in `config.toml` — it does **not** reset `model_provider` back to the default (`openai`) provider. If you later want to switch back to the self-hosted model, selecting it through the UI can leave `model` and `model_provider` out of sync (pointing at mismatched providers). To be safe, whenever you switch between the default model and your self-hosted model, **edit `model` / `model_provider` directly in `config.toml`** (or ask an AI to edit it for you) instead of just switching through the model picker. +{% endhint %} + +--- + +## Troubleshooting + +| Symptom | Cause | Fix | +| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| New profile doesn't show in the model picker | App wasn't restarted, or the`[profiles.*]` section name is wrong | Fully quit and reopen Codex; recheck the TOML syntax | +| `401` / "Unauthorized" | Wrong or not-yet-ACTIVE API key | Recheck your key; wait for**ACTIVE** status | +| `404` / "Not Found" | Wrong Base URL (missing`/v1`) | Should be exactly`https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1` | +| App errors out / can't read config | Invalid TOML syntax (missing quotes, wrong indentation) | Ask an AI to check the block you added, or compare it against the Step 4 sample | +| No response even with the right model selected | Out of credit, model auto-disabled | Top up credit in the AI Platform Console | +| Switched models via the model picker (UI) and the self-hosted model stopped working | `model` and `model_provider` in `config.toml` are out of sync — the picker only overwrites `model`, not `model_provider` | Reopen`config.toml`, fix `model` / `model_provider` back to a matching pair (see the Step 4 sample), save, and restart Codex | + +--- + +| I want to next... | Go to | +| --------------------- | -------------------------------------------------------------- | +| Use the CLI version | [Codex CLI](../cli-tools/codex-cli.md) | +| See the prerequisites | [Getting Started with AI Coding](../getting-started.md) | +| View usage & billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | + +--- + +## Need help? + +If you've followed the steps and it's still not working, feel free to contact GreenNode Customer Support: + +* Email: [support@greennode.ai](mailto:support@greennode.ai) +* Hotline: 19001549 +* Help center: [helpdesk.greennode.ai](https://helpdesk.greennode.ai) + +Thank you for using GreenNode's services. diff --git a/English/ai-stack/ai-coding/opencode-with-maas-model.md b/English/ai-stack/ai-coding/opencode-with-maas-model.md deleted file mode 100644 index 48105da8..00000000 --- a/English/ai-stack/ai-coding/opencode-with-maas-model.md +++ /dev/null @@ -1,182 +0,0 @@ -# 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.greennode.ai/) 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.greennode.ai/) -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.greennode.ai/). - -| 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.greennode.ai/) | diff --git a/English/ai-stack/ai-coding/use-codex-with-minimax.md b/English/ai-stack/ai-coding/use-codex-with-minimax.md deleted file mode 100644 index 6b38eefe..00000000 --- a/English/ai-stack/ai-coding/use-codex-with-minimax.md +++ /dev/null @@ -1,136 +0,0 @@ -# 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.greennode.ai/) 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.greennode.ai/) -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.greennode.ai/). - -| 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.greennode.ai/) | diff --git a/Vietnamese/.gitbook/assets/ai-coding/claude-code-with-glm.png b/Vietnamese/.gitbook/assets/ai-coding/claude-code-with-glm.png new file mode 100644 index 00000000..59ea10d1 Binary files /dev/null and b/Vietnamese/.gitbook/assets/ai-coding/claude-code-with-glm.png differ diff --git a/Vietnamese/.gitbook/assets/ai-coding/codex-ui-chat.png b/Vietnamese/.gitbook/assets/ai-coding/codex-ui-chat.png new file mode 100644 index 00000000..351bae6d Binary files /dev/null and b/Vietnamese/.gitbook/assets/ai-coding/codex-ui-chat.png differ diff --git a/Vietnamese/.gitbook/assets/ai-coding/done-setup-glm-into-codex.png b/Vietnamese/.gitbook/assets/ai-coding/done-setup-glm-into-codex.png new file mode 100644 index 00000000..1c7371d8 Binary files /dev/null and b/Vietnamese/.gitbook/assets/ai-coding/done-setup-glm-into-codex.png differ diff --git a/Vietnamese/.gitbook/assets/ai-coding/find-config-toml-file.png b/Vietnamese/.gitbook/assets/ai-coding/find-config-toml-file.png new file mode 100644 index 00000000..2c0c32a2 Binary files /dev/null and b/Vietnamese/.gitbook/assets/ai-coding/find-config-toml-file.png differ diff --git a/Vietnamese/.gitbook/assets/ai-coding/tip-chat-with-agent.png b/Vietnamese/.gitbook/assets/ai-coding/tip-chat-with-agent.png new file mode 100644 index 00000000..5d22ee85 Binary files /dev/null and b/Vietnamese/.gitbook/assets/ai-coding/tip-chat-with-agent.png differ diff --git a/Vietnamese/.gitbook/assets/ai-coding/tip-run-after-setup-done.png b/Vietnamese/.gitbook/assets/ai-coding/tip-run-after-setup-done.png new file mode 100644 index 00000000..872eabc2 Binary files /dev/null and b/Vietnamese/.gitbook/assets/ai-coding/tip-run-after-setup-done.png differ diff --git a/Vietnamese/.gitbook/assets/ai-coding/tip-run-to-confirm.png b/Vietnamese/.gitbook/assets/ai-coding/tip-run-to-confirm.png new file mode 100644 index 00000000..e1925433 Binary files /dev/null and b/Vietnamese/.gitbook/assets/ai-coding/tip-run-to-confirm.png differ diff --git a/Vietnamese/SUMMARY.md b/Vietnamese/SUMMARY.md index 9b2a1379..935910c6 100644 --- a/Vietnamese/SUMMARY.md +++ b/Vietnamese/SUMMARY.md @@ -845,7 +845,6 @@ * [Bảo mật](ai-stack/ai-gateway/bao-mat.md) * [Cách tính giá](ai-stack/ai-gateway/cach-tinh-gia.md) * [AI Coding](ai-stack/ai-coding/README.md) - * [Kết nối Claude Code với GreenNode MaaS](ai-stack/ai-coding/ket-noi-claude-code-voi-maas.md) * [Kết nối OpenAI-compatible với GreenNode MaaS](ai-stack/ai-coding/ket-noi-openai-compatible-voi-maas.md) * [Bắt đầu với AI Coding](ai-stack/ai-coding/bat-dau.md) * [Dùng MCP Server với AI Coding](ai-stack/ai-coding/mcp-openrouter.md) diff --git a/Vietnamese/ai-stack/ai-coding/co-giao-dien/README.md b/Vietnamese/ai-stack/ai-coding/co-giao-dien/README.md new file mode 100644 index 00000000..39a8379f --- /dev/null +++ b/Vietnamese/ai-stack/ai-coding/co-giao-dien/README.md @@ -0,0 +1,10 @@ +# Có giao diện (GUI) + +> Công cụ AI Coding có giao diện đồ hoạ — chỉ cần điền Base URL và API key, không phải gõ lệnh. Phù hợp cho **người mới bắt đầu**. + +Trước khi cài, xem [Điều kiện cần](../bat-dau.md). + +| Công cụ | Ghi chú | +|---|---| +| [Codex Desktop](codex-desktop.md) | Cấu hình qua file `config.toml` trong Settings | +| Claude Desktop | Hiện chỉ cho kết nối model **Anthropic thật** (`claude-*`) khi cấu hình third-party inference — model self-host của hãng khác (GLM, v.v.) chưa dùng được qua giao diện này. Cần dùng model self-host hãng khác, chuyển sang [Claude Code (CLI)](../dong-lenh/claude-code.md). | diff --git a/Vietnamese/ai-stack/ai-coding/co-giao-dien/codex-desktop.md b/Vietnamese/ai-stack/ai-coding/co-giao-dien/codex-desktop.md new file mode 100644 index 00000000..64a10222 --- /dev/null +++ b/Vietnamese/ai-stack/ai-coding/co-giao-dien/codex-desktop.md @@ -0,0 +1,150 @@ +# Kết nối Codex Desktop với GreenNode MaaS (GLM 5.2) + +> Dành cho **người mới bắt đầu** dùng macOS hoặc Windows. Cấu hình bằng cách sửa 1 file `config.toml` qua Settings — có thể nhờ AI hỗ trợ soạn, không cần thuộc cú pháp TOML. Codex Desktop sẽ dùng model **GLM 5.2** chạy nội bộ của GreenNode. + +{% hint style="info" %} +**Trước tiên hãy chuẩn bị [Điều kiện cần](../bat-dau.md):** API key (ACTIVE), Base URL, và model GLM 5.2 đã ENABLED. Trang này chỉ hướng dẫn cài và cấu hình. +{% endhint %} + +Bạn sẽ cần 3 giá trị này (lấy ở trang Điều kiện cần): + +| Thông tin | Giá trị | +|-----------|---------| +| Base URL (chuẩn OpenAI) | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1` (**có** `/v1`) | +| API key | key `vn-...` của bạn | +| Model ID | `z-ai/glm-5.2` | + +{% hint style="info" %} +**GLM 5.2 chỉ là model ví dụ.** GreenNode có nhiều model — bạn thay bằng model mình muốn. Model ID và Base URL của từng model đều xem được trong [trang chi tiết model](https://aiplatform.console.greennode.ai/models). +{% endhint %} + +--- + +## Bước 1 — Tải và cài Codex Desktop + +Vào **[openai.com/index/introducing-the-codex-app](https://openai.com/index/introducing-the-codex-app/)** và tải app cho máy của bạn, cài như phần mềm bình thường. + +--- + +## Bước 2 — Mở app và đăng nhập + +Mở Codex, đăng nhập bằng tài khoản ChatGPT/OpenAI của bạn. + +

Màn hình chính Codex sau khi đăng nhập

+ +--- + +## Bước 3 — Mở file config.toml + +1. Bấm avatar/tên tài khoản ở góc dưới bên trái → **Settings**. +2. Ở ô tìm kiếm bên trái, gõ **"config.toml"**. +3. Bấm nút **Open config.toml** ở góc trên bên phải mục **Custom config.toml settings** — file sẽ mở bằng trình soạn thảo mặc định của máy. + +

Tìm và mở config.toml trong Settings

+ +--- + +## Bước 4 — Thêm cấu hình model self-host + +Thêm đoạn sau vào **cuối** file `config.toml` (giữ nguyên nội dung có sẵn phía trên): + +```toml +[model_providers.vngcloud-glm] +name = "VNGCloud GLM" +base_url = "https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1" +experimental_bearer_token = "vn-...key-của-bạn..." +wire_api = "responses" +stream_idle_timeout_ms = 3000000 +request_max_retries = 3 +supports_websockets = false + +[profiles.glm] +model = "z-ai/glm-5.2" +model_provider = "vngcloud-glm" +model_context_window = 200000 +model_auto_compact_token_limit = 200000 +model_reasoning_effort = "medium" +model_reasoning_summary = "auto" +``` + +**Giải thích các field quan trọng:** + +| Field | Mục đích | +|---|---| +| `model_providers.vngcloud-glm` | Tên provider tuỳ bạn đặt — dùng lại ở `model_provider` bên dưới | +| `base_url` | Base URL chuẩn OpenAI, **có** `/v1` | +| `experimental_bearer_token` | API key của bạn, dán trực tiếp vào file — Codex Desktop không cần export biến môi trường như CLI | +| `wire_api` | Để `"responses"` — đúng chuẩn Responses API mà Codex Desktop dùng | +| `stream_idle_timeout_ms` | Thời gian chờ tối đa (ms) trước khi coi stream là timeout | +| `request_max_retries` | Số lần retry lại request khi gọi lỗi | +| `supports_websockets` | Để `false` — MaaS chưa hỗ trợ websocket | +| `profiles.glm` | Tên profile tuỳ bạn đặt — sẽ hiện trong model picker của app | +| `model` | Model ID gửi lên MaaS | +| `model_provider` | Trỏ về provider đã khai báo ở trên | +| `model_context_window` | Khai báo thủ công vì MaaS không expose metadata model | +| `model_auto_compact_token_limit` | Ngưỡng token để Codex tự nén (compact) lại context | +| `model_reasoning_effort` | Mức độ suy luận mặc định (`low` / `medium` / `high`) | +| `model_reasoning_summary` | Để `"auto"` — Codex tự quyết có tóm tắt reasoning hay không | + +{% hint style="warning" %} +**Đừng copy nguyên mẫu cấu hình theo kiểu biến môi trường của Claude Code** (`export ANTHROPIC_BASE_URL=...`, `claude --model ...`) — đó là cú pháp riêng cho Claude Code CLI, **không** áp dụng được cho Codex. Codex Desktop đọc cấu hình qua `config.toml` với `model_providers` / `profiles` như mẫu trên. +{% endhint %} + +{% hint style="info" %} +**Chưa quen cú pháp TOML?** Copy toàn bộ nội dung file `config.toml` hiện tại, dán vào một AI chat (Codex, ChatGPT, Claude...) kèm 3 giá trị Base URL / API key / Model ID ở trên, nhờ AI viết giúp đoạn `[model_providers.*]` và `[profiles.*]` đúng chuẩn Codex rồi dán lại vào file. +{% endhint %} + +--- + +## Bước 5 — Lưu file và khởi động lại Codex + +1. Lưu file `config.toml`. +2. Thoát hẳn và mở lại Codex Desktop. + +--- + +## Bước 6 — Kiểm tra + +1. Ở khung chat, bấm vào ô chọn model (góc dưới bên phải, ví dụ **"5.6 Terra Medium"**). +2. Tìm profile bạn vừa thêm (ví dụ **glm**) trong danh sách — chọn nó. +3. Gõ thử một câu, ví dụ *"Viết hàm cộng hai số bằng Python."* Nếu trả lời được là thành công. +4. Vào **[AI Platform Console](https://aiplatform.console.greennode.ai/)** để thấy lượt gọi được ghi nhận. + +

Cấu hình thành công — chat trả lời được và model picker hiện "Custom" thay vì model mặc định

+ +{% hint style="warning" %} +**Lưu ý khi đổi qua lại giữa model mặc định và model self-host:** Nếu bạn chọn một model mặc định của Codex ngay trong model picker (UI), app **chỉ ghi đè field `model`** trong `config.toml`, **không** tự reset `model_provider` về provider mặc định (`openai`). Nếu sau đó muốn quay lại model self-host, bấm chọn qua UI có thể khiến `model` và `model_provider` bị lệch nhau (không khớp provider). Để chắc chắn, khi cần đổi qua lại giữa model mặc định và model self-host, hãy **sửa trực tiếp `model` / `model_provider` trong `config.toml`** (hoặc nhờ AI sửa giúp) thay vì chỉ bấm switch trong model picker. +{% endhint %} + +--- + +## Xử lý sự cố + +| Hiện tượng | Nguyên nhân | Cách xử lý | +|------------|-------------|------------| +| Không thấy profile mới trong model picker | Chưa restart app, hoặc sai tên section `[profiles.*]` | Thoát hẳn và mở lại Codex; kiểm tra lại cú pháp TOML | +| `401` / "Unauthorized" | API key sai hoặc chưa ACTIVE | Kiểm tra lại key; đợi trạng thái **ACTIVE** | +| `404` / "Not Found" | Base URL sai (thiếu `/v1`) | Đúng phải là `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1` | +| App báo lỗi khi mở / không đọc được config | Sai cú pháp TOML (thiếu dấu `"`, sai indent) | Nhờ AI kiểm tra lại đoạn vừa thêm, hoặc so lại với mẫu ở Bước 4 | +| AI không phản hồi dù đã chọn đúng model | Hết credit nên model bị tắt | Nạp credit tại AI Platform Console | +| Đổi model qua model picker (UI) xong, model self-host không dùng được nữa | `model` và `model_provider` trong `config.toml` bị lệch nhau — picker chỉ ghi đè `model`, không reset `model_provider` | Mở lại `config.toml`, sửa `model` / `model_provider` cho khớp đúng cặp (xem mẫu ở Bước 4), lưu rồi restart Codex | + +--- + +| Tôi muốn tiếp theo... | Đi đến | +|------------------------|--------| +| Dùng bằng dòng lệnh | [Codex CLI](../dong-lenh/codex-cli.md) | +| Xem điều kiện cần | [Bắt đầu với AI Coding](../bat-dau.md) | +| Xem usage & billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | + +--- + +## Cần hỗ trợ? + +Nếu bạn làm theo mà vẫn chưa được, đừng ngại liên hệ bộ phận Hỗ trợ Khách hàng của GreenNode: + +* Email: [support@greennode.ai](mailto:support@greennode.ai) +* Hotline: 19001549 +* Trung tâm hỗ trợ: [helpdesk.greennode.ai](https://helpdesk.greennode.ai) + +Cảm ơn bạn đã sử dụng dịch vụ của GreenNode. diff --git a/Vietnamese/ai-stack/ai-coding/dong-lenh/claude-code.md b/Vietnamese/ai-stack/ai-coding/dong-lenh/claude-code.md index a00d1361..07153e1b 100644 --- a/Vietnamese/ai-stack/ai-coding/dong-lenh/claude-code.md +++ b/Vietnamese/ai-stack/ai-coding/dong-lenh/claude-code.md @@ -63,6 +63,8 @@ $env:ANTHROPIC_AUTH_TOKEN = "--" # thay bằng API key của bạn {% endtab %} {% endtabs %} +

Cấu hình ANTHROPIC_AUTH_TOKEN và ANTHROPIC_BASE_URL trong shell profile

+ --- ## Bước 3 — Chạy Claude Code với GLM 5.2 @@ -88,6 +90,8 @@ Trong Claude Code, gõ `/status` — đúng khi: Sau đó vào **[AI Platform Console](https://aiplatform.console.greennode.ai/)** để thấy lượt gọi được ghi nhận. +

Claude Code chạy thành công với model z-ai/glm-5.2 qua GreenNode MaaS

+ --- ## Xử lý sự cố @@ -105,7 +109,6 @@ Sau đó vào **[AI Platform Console](https://aiplatform.console.greennode.ai/)* | Tôi muốn tiếp theo... | Đi đến | |------------------------|--------| -| Dùng bản có giao diện | [Claude Desktop](../co-giao-dien/claude-desktop.md) | | Dùng OpenCode | [OpenCode](opencode.md) | | Xem điều kiện cần | [Bắt đầu với AI Coding](../bat-dau.md) | diff --git a/Vietnamese/ai-stack/ai-coding/dong-lenh/codex-cli.md b/Vietnamese/ai-stack/ai-coding/dong-lenh/codex-cli.md index 5a329197..29c7edd7 100644 --- a/Vietnamese/ai-stack/ai-coding/dong-lenh/codex-cli.md +++ b/Vietnamese/ai-stack/ai-coding/dong-lenh/codex-cli.md @@ -9,7 +9,7 @@ * Chuẩn bị API key, Base URL và model theo [Bắt đầu với AI Coding](../bat-dau.md) * Node.js ≥ 22 đã cài đặt -> Model GLM 5.2 qua Codex dùng **chuẩn OpenAI** — Base URL có `/v1`: `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1`. +> Model Minimax M2.5 qua Codex dùng **chuẩn OpenAI** — Base URL có `/v1`: `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1`. *** @@ -132,6 +132,7 @@ Sau khi hoàn thành, Codex CLI route toàn bộ request qua GreenNode MaaS vớ | Tôi muốn tiếp theo... | Đi đến | |---|---| +| Dùng bản có giao diện | [Codex Desktop](../co-giao-dien/codex-desktop.md) | | Dùng OpenCode với MaaS | [Dùng OpenCode với GreenNode MaaS](opencode.md) | | Kết nối Claude Code với MaaS | [Kết nối Claude Code với GreenNode MaaS](claude-code.md) | | Xem usage và billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | diff --git "a/Vietnamese/ai-stack/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/ai-coding/h\306\260\341\273\233ng-d\341\272\253n-x\303\240i-codex-v\341\273\233i-minimax.md" deleted file mode 100644 index 6e48c68c..00000000 --- "a/Vietnamese/ai-stack/ai-coding/h\306\260\341\273\233ng-d\341\272\253n-x\303\240i-codex-v\341\273\233i-minimax.md" +++ /dev/null @@ -1,136 +0,0 @@ -# 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.greennode.ai/) -* Đã 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.greennode.ai/) -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.greennode.ai/). - -| 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.greennode.ai/) | diff --git a/Vietnamese/ai-stack/ai-coding/ket-noi-claude-code-voi-maas.md b/Vietnamese/ai-stack/ai-coding/ket-noi-claude-code-voi-maas.md deleted file mode 100644 index a54a74f3..00000000 --- a/Vietnamese/ai-stack/ai-coding/ket-noi-claude-code-voi-maas.md +++ /dev/null @@ -1,158 +0,0 @@ -# Kết nối Claude Code với GreenNode MaaS - -> Hướng dẫn định tuyến Claude Code CLI sang GreenNode MaaS endpoint thay vì Anthropic API trực tiếp — toàn bộ request đi qua hạ tầng GreenNode, 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.greennode.ai/) -* Claude Code CLI đã cài đặt - -{% hint style="info" %} -LLM URL cho Claude Code dùng **Anthropic API protocol**: `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` (không có `/v1`). -{% endhint %} - -*** - -## Bước 1 — Lấy API key từ AI Platform - -1. Đăng nhập [AI Platform Console](https://aiplatform.console.greennode.ai/) -2. Vào **API Keys** → **Create API Key** -3. Đặt tên theo format `claude-code-` (5–50 ký tự, chữ thường + số + gạch ngang) -4. Copy API key vừa tạo - -{% hint style="warning" %} -API key mới tạo ở trạng thái `pending`. Poll `api-keys get ` cho đến khi status = `ACTIVE` mới dùng được. -{% endhint %} - -*** - -## Bước 2 — Chọn model - -Xem danh sách model Claude đang khả dụng: - -```bash -bash .claude/skills/agentbase/scripts/aip.sh models list --providers anthropic --status ENABLED -``` - -Lấy giá trị `path` của model muốn dùng (ví dụ: `claude-sonnet-4-6`, `claude-opus-4-8`). Giá trị này sẽ điền vào biến môi trường model mapping ở bước sau. - -*** - -## Bước 3 — Cấu hình - -Chọn 1 trong 2 cách: - -**Cách A — Shell profile (áp dụng toàn hệ thống)** - -Thêm vào `~/.zshrc` hoặc `~/.bashrc`: - -```bash -# GreenNode MaaS — Claude Code Integration -export ANTHROPIC_BASE_URL="https://maas-llm-aiplatform-hcm.api.vngcloud.vn" -export ANTHROPIC_AUTH_TOKEN="" -export ANTHROPIC_API_KEY="" # Phải để trống — tránh conflict với Anthropic trực tiếp - -# Model mapping (dùng path từ bước 2) -export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6" -export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-8" -export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001" -export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6" -``` - -Áp dụng ngay không cần restart terminal: - -```bash -source ~/.zshrc -``` - -

Cấu hình ANTHROPIC_AUTH_TOKEN và ANTHROPIC_BASE_URL trong shell profile

- -**Cách B — Project settings (chỉ áp dụng cho project cụ thể)** - -Tạo file `.claude/settings.local.json` tại root của project: - -```json -{ - "env": { - "ANTHROPIC_BASE_URL": "https://maas-llm-aiplatform-hcm.api.vngcloud.vn", - "ANTHROPIC_AUTH_TOKEN": "", - "ANTHROPIC_API_KEY": "", - "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6", - "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8", - "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001", - "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6" - } -} -``` - -{% hint style="warning" %} -Claude Code không đọc file `.env` thông thường. Phải dùng `settings.local.json` hoặc shell profile. -{% endhint %} - -*** - -## Bước 4 — Kiểm tra kết nối - -Mở Claude Code và chạy: - -``` -/status -``` - -Kết quả mong đợi: - -* Base URL trỏ đến `maas-llm-aiplatform-hcm.api.vngcloud.vn` -* Model hiển thị đúng với cấu hình - -Xác nhận request được ghi nhận tại [AI Platform Console → Usage](https://aiplatform.console.greennode.ai/). - -*** - -## Bảng biến môi trường - -| Biến | Mục đích | Giá trị mẫu | -| -------------------------------- | --------------------------------- | ------------------------------------------------- | -| `ANTHROPIC_BASE_URL` | Redirect API calls sang GreenNode | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` | -| `ANTHROPIC_AUTH_TOKEN` | API key xác thực | `` | -| `ANTHROPIC_API_KEY` | Phải để trống (tránh conflict) | `""` | -| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model cho coding thông thường | `claude-sonnet-4-6` | -| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model cho reasoning phức tạp | `claude-opus-4-8` | -| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model cho completions nhanh | `claude-haiku-4-5-20251001` | -| `CLAUDE_CODE_SUBAGENT_MODEL` | Model khi spawn sub-agent | `claude-sonnet-4-6` | - -*** - -## Billing & Usage - -* Request đi qua GreenNode MaaS được tính phí bằng credit-token (1 credit = 1 VND) -* Xem usage real-time trên [AI Platform Console → Usage](https://aiplatform.console.greennode.ai/) -* **Prepaid:** credit bị trừ mỗi chu kỳ collect 5 phút — khi hết credit, model bị tắt tự động -* **Postpaid:** usage được ghi nợ, không giới hạn quota - -*** - -## Troubleshooting - -| Triệu chứng | Nguyên nhân | Cách xử lý | -| -------------------------- | ----------------------------------- | ----------------------------------------------- | -| `401 Unauthorized` | API key sai hoặc chưa ACTIVE | Kiểm tra lại key, tạo key mới nếu cần | -| `403 Forbidden` | API key chưa ACTIVE | Poll `api-keys get ` đợi status = ACTIVE | -| Model không phản hồi | Credit hết, model bị tắt | Nạp thêm credit tại AI Platform Console | -| Request đi thẳng Anthropic | `ANTHROPIC_API_KEY` không để trống | Đặt `ANTHROPIC_API_KEY=""` | -| Wrong model được dùng | Model path không đúng | Kiểm tra `path` field bằng `aip.sh models list` | -| `/status` báo lỗi URL | Base URL sai hoặc có trailing slash | Đảm bảo `ANTHROPIC_BASE_URL` không có `/` cuối | - -*** - -## Kết quả - -Sau khi hoàn thành, Claude Code CLI sẽ route toàn bộ request qua GreenNode MaaS. Usage được ghi nhận trên AI Platform Console và tính phí theo credit-token nội bộ. - -

Claude Code chạy thành công qua GreenNode MaaS endpoint

- -| Tôi muốn tiếp theo... | Đi đến | -| ------------------------------------ | ------------------------------------------------------------------------------------- | -| Dùng OpenAI-compatible tool với MaaS | [Kết nối OpenAI-compatible với GreenNode MaaS](ket-noi-openai-compatible-voi-maas.md) | -| Xem usage và billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | diff --git a/Vietnamese/ai-stack/ai-coding/ket-noi-openai-compatible-voi-maas.md b/Vietnamese/ai-stack/ai-coding/ket-noi-openai-compatible-voi-maas.md index ca1a2db6..6428d0c7 100644 --- a/Vietnamese/ai-stack/ai-coding/ket-noi-openai-compatible-voi-maas.md +++ b/Vietnamese/ai-stack/ai-coding/ket-noi-openai-compatible-voi-maas.md @@ -156,5 +156,5 @@ Sau khi cấu hình, tool hoặc SDK sẽ gọi model qua GreenNode MaaS thay v | Tôi muốn tiếp theo... | Đi đến | | ------------------------- | ------------------------------------------------------------------------- | -| Dùng Claude Code với MaaS | [Kết nối Claude Code với GreenNode MaaS](ket-noi-claude-code-voi-maas.md) | +| Dùng Claude Code với MaaS | [Kết nối Claude Code với GreenNode MaaS](dong-lenh/claude-code.md) | | Xem usage và billing | [AI Platform Console](https://aiplatform.console.greennode.ai/) | diff --git a/Vietnamese/ai-stack/ai-coding/opencode-with-maas-model.md b/Vietnamese/ai-stack/ai-coding/opencode-with-maas-model.md deleted file mode 100644 index cd8ef542..00000000 --- a/Vietnamese/ai-stack/ai-coding/opencode-with-maas-model.md +++ /dev/null @@ -1,183 +0,0 @@ -# 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.greennode.ai/) -* Đã 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.greennode.ai/) -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.greennode.ai/). - -| 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.greennode.ai/) |