vngcloud · greennode-vdb · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/English/ai-stack/ai-coding/README.md b/English/ai-stack/ai-coding/README.md
@@ -1,59 +1,71 @@
 # AI Coding
 
-AI Coding lets you connect popular AI coding tools — Claude Code, OpenAI SDK, IDE extensions — directly to GreenNode MaaS, using cloud models without managing API keys from external providers.
+AI Coding lets you connect popular AI coding tools — Claude Code, OpenAI SDK, IDE extensions — directly to models operated by GreenNode, using cloud models without managing API keys from external providers.
 
 ***
 
 ## Architecture
 
-Requests from your tool are redirected to the GreenNode MaaS endpoint. MaaS exposes two protocols in parallel to support all existing clients:
+Requests from your tool are redirected to a GreenNode endpoint. The endpoint exposes two protocols in parallel to support all existing clients:
 
-<figure><img src="../../.gitbook/assets/ai_coding_flow (1).png" alt=""><figcaption><p>Both API protocols connect to a single MaaS endpoint sharing the same Model Pool</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/ai_coding_flow (1).png" alt=""><figcaption><p>Both API protocols connect to a single endpoint sharing the same Model Pool</p></figcaption></figure>
 
-A single AI Platform API key works for both protocols.
+A single key works for both protocols — but the **key must match the host of the service type that issued it**.
 
-{% hint style="warning" %}
-The LLM URL differs by protocol — see the table below. Using the wrong URL causes 404 errors or malformed request parsing.
-{% endhint %}
+***
+
+## Two service types — settle this before configuring anything
+
+| Service type | Pricing model | Key used to call | Base URL host |
+|---|---|---|---|
+| **PAYG** | Pay per token actually used | API Key from **API Keys** | `maas-llm-aiplatform-hcm.api.vngcloud.vn` |
+| **Token Plan** | Prepaid 30-day package with a fixed token quota | subscription-key from Plan Detail → **Subscription keys** tab | `tokenplan.api.greennode.ai` |
 
 ***
 
-## Protocol and LLM URL
+## Base URL by service type and client standard
+
+| Service type | **Anthropic**-standard clients<br>(Claude Code, Anthropic SDK) | **OpenAI**-standard clients<br>(OpenAI SDK, LiteLLM, Cursor, Continue.dev, Codex, OpenCode) |
+|---|---|---|
+| **PAYG** | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1` |
+| **Token Plan** | `https://tokenplan.api.greennode.ai` | `https://tokenplan.api.greennode.ai/v1` |
 
-| Client                                    | Protocol               | LLM URL                                              |
-| ----------------------------------------- | ---------------------- | ---------------------------------------------------- |
-| Claude Code, Anthropic SDK                | Anthropic Messages API | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn`    |
-| OpenAI SDK, LiteLLM, Cursor, Continue.dev | OpenAI-compatible      | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1` |
+{% hint style="warning" %}
+Picking the wrong cell in this table is the most common failure: the wrong **`/v1` suffix** gives `404 Not Found`; the wrong **host for your key type** gives `401 Unauthorized` even while the key is still valid. Every tool guide has separate tabs per service type — pick your tab and copy it as-is.
+{% endhint %}
 
 ***
 
 ## Supported Tools
 
 ### Claude Code
 
-Claude Code CLI supports overriding `ANTHROPIC_BASE_URL` — pointing to GreenNode MaaS instead of Anthropic directly. All sessions, tool calls, and sub-agents route through the GreenNode endpoint, with usage visible in AI Platform Console.
+Claude Code CLI supports overriding `ANTHROPIC_BASE_URL` — pointing to a GreenNode endpoint instead of Anthropic directly. All sessions, tool calls, and sub-agents route through the GreenNode endpoint, with usage visible in AI Platform Console.
 
 ### OpenAI-compatible clients
 
-Any tool that allows setting a custom `base_url` in OpenAI SDK format works out of the box — OpenAI Python/Node.js SDK, LiteLLM, Cursor, Continue.dev, and other IDE extensions. Change the base URL and API key; no logic changes needed.
+Any tool that allows setting a custom `base_url` in OpenAI SDK format works out of the box — OpenAI Python/Node.js SDK, LiteLLM, Cursor, Continue.dev, and other IDE extensions. Change the base URL and key; no logic changes needed.
 
 ***
 
 ## Billing
 
-* **Credit-token:** 1 credit = 1 VND
-* **Prepaid:** credits deducted every 5-minute collection cycle — model automatically disabled when credits run out
-* **Postpaid:** usage recorded as debt with no quota limit
-* View real-time usage at [AI Platform Console → Usage](https://aiplatform.console.vngcloud.vn/)
+| | PAYG | Token Plan |
+|---|---|---|
+| Pricing | Credit-token, 1 credit = 1 VND | Fixed prepaid 30-day package |
+| Quota | **Prepaid:** credits deducted every 5-minute collection cycle; model auto-disabled when credits run out. **Postpaid:** usage recorded as debt with no quota limit | Fixed token/request quota per model, shared across all subscription-keys in the plan |
+| Where to track | [AI Platform Console](https://aiplatform.console.greennode.ai/) → **Usage** and **Cost** | [AI Platform Console](https://aiplatform.console.greennode.ai/) → **Usage** only |
 
 ***
 
 ## Getting Started
 
-| I want to...                                     | Go to                                                          |
-| ------------------------------------------------ | -------------------------------------------------------------- |
-| Prepare an API key, Base URL, and choose a model | [Getting Started with AI Coding](getting-started.md)           |
-| Use a GUI tool                                   | Coming soon                                                    |
-| Use a CLI tool                                   | [CLI Tools group](cli-tools/)                                  |
-| Attach an MCP server to an agent                 | [Using MCP Servers with AI Coding](mcp-servers.md)             |
-| Get an API key                                   | [AI Platform Console](https://aiplatform.console.vngcloud.vn/) |
+| I want to... | Go to |
+|---|---|
+| Prepare a key and Base URL, and choose a model | [Getting Started with AI Coding](getting-started.md) |
+| Use a GUI tool | [GUI Tools group](gui-tools/README.md) |
+| Use a CLI tool | [CLI Tools group](cli-tools/README.md) |
+| Configure an SDK / IDE extension on the OpenAI standard | [Connect OpenAI-compatible Tools to GreenNode MaaS](connect-openai-compatible-to-maas.md) |
+| Attach an MCP server to an agent | [Using MCP Servers with AI Coding](mcp-servers.md) |
+| Buy and use a Token Plan package | [Token Plan](../token-plan/README.md) |
+| Get a PAYG API key | [AI Platform Console](https://aiplatform.console.greennode.ai/) |
diff --git a/English/ai-stack/ai-coding/cli-tools/README.md b/English/ai-stack/ai-coding/cli-tools/README.md
@@ -4,6 +4,10 @@
 
 Before installing, see [Prerequisites](../getting-started.md).
 
+{% hint style="warning" %}
+Every page below has **separate tabs for PAYG and Token Plan** in its configuration section. Settle your service type first (go by where you got your key), then copy only from that tab — a key and Base URL from different service types return `401 Unauthorized`.
+{% endhint %}
+
 * [Claude Code](claude-code.md)
 * [Codex CLI](codex-cli.md)
 * [OpenCode](opencode.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
@@ -3,18 +3,26 @@
 > For terminal users (macOS / Linux / WSL / Windows). The Claude Code CLI will use GreenNode's **GLM 5.2** model via MaaS instead of calling Anthropic directly.
 
 {% hint style="info" %}
-**First, complete the [Prerequisites](../getting-started.md):** an **ACTIVE** API key, the Base URL, and the GLM 5.2 model **ENABLED**.
+**First, complete the [Prerequisites](../getting-started.md):** an **ACTIVE** key, the Base URL for your service type, and the model **ENABLED**.
 {% endhint %}
 
-| Info | Value |
-|-----------|---------|
-| Base URL | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` (Anthropic standard, **no** `/v1`) |
-| Base URL (Token Plan / package key) | `https://tokenplan.api.greennode.ai` (**no** `/v1`) — see [Token Plan](../../token-plan/README.md) |
-| API key | your key |
-| Model ID | `z-ai/glm-5.2` |
+---
+
+## Pick your configuration by service type
+
+Claude Code uses the **Anthropic standard** → the Base URL has **no** `/v1` on either service type. Only the host and the key type differ:
+
+| Service type | Base URL | Key | Model ID |
+|---|---|---|---|
+| **PAYG** | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` | API Key from the [API Keys page](https://aiplatform.console.greennode.ai/keys) | `z-ai/glm-5.2` |
+| **Token Plan** | `https://tokenplan.api.greennode.ai` | subscription-key from Plan Detail → **Subscription keys** tab | Model code on the **Models** tab (e.g. `glm-5.2`) |
+
+{% hint style="warning" %}
+**Your key and Base URL must belong to the same service type.** A PAYG API Key sent to the `tokenplan…` host (or the reverse) returns `401 Unauthorized` even while the key is still valid. You can't tell the key types apart by looking at them — go by where you got the key. See [section 2 of the Prerequisites page](../getting-started.md).
+{% endhint %}
 
 {% 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 the [model detail page](https://aiplatform.console.greennode.ai/models).
+**GLM 5.2 is just an example model.** GreenNode offers many models — swap in whichever one you want. On PAYG, find the Model ID on the [model detail page](https://aiplatform.console.greennode.ai/models); on Token Plan, check your plan's **Models** tab.
 {% endhint %}
 
 ---
@@ -29,15 +37,15 @@ npm install -g @anthropic-ai/claude-code
 
 ## Step 2 — Declare the Base URL & API key
 
-Pick the right section for your OS.
+Pick the tab matching your **service type** and **OS**, then copy it as-is — only replace the key value.
 
 {% tabs %}
-{% tab title="macOS / Linux / WSL (bash or zsh)" %}
+{% tab title="PAYG — macOS / Linux / WSL" %}
 Set them temporarily for the current session:
 
 ```bash
 export ANTHROPIC_BASE_URL="https://maas-llm-aiplatform-hcm.api.vngcloud.vn"
-export ANTHROPIC_AUTH_TOKEN="--"   # replace with your API key
+export ANTHROPIC_AUTH_TOKEN="<your-PAYG-API-key>"
 ```
 
 To have this happen automatically every time you open a terminal, add the two lines above to the end of `~/.zshrc` (macOS) or `~/.bashrc` (Linux/WSL), then reload:
@@ -47,19 +55,50 @@ source ~/.zshrc      # or: source ~/.bashrc
 ```
 {% endtab %}
 
-{% tab title="Windows PowerShell" %}
+{% tab title="PAYG — Windows PowerShell" %}
 Set them temporarily for the current PowerShell window:
 
 ```powershell
 $env:ANTHROPIC_BASE_URL = "https://maas-llm-aiplatform-hcm.api.vngcloud.vn"
-$env:ANTHROPIC_AUTH_TOKEN = "--"   # replace with your API key
+$env:ANTHROPIC_AUTH_TOKEN = "<your-PAYG-API-key>"
 ```
 
 To persist them for your account (run once, then **reopen PowerShell**):
 
 ```powershell
 [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://maas-llm-aiplatform-hcm.api.vngcloud.vn", "User")
-[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "--", "User")
+[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "<your-PAYG-API-key>", "User")
+```
+{% endtab %}
+
+{% tab title="Token Plan — macOS / Linux / WSL" %}
+Set them temporarily for the current session:
+
+```bash
+export ANTHROPIC_BASE_URL="https://tokenplan.api.greennode.ai"
+export ANTHROPIC_AUTH_TOKEN="<your-subscription-key>"
+```
+
+To have this happen automatically every time you open a terminal, add the two lines above to the end of `~/.zshrc` (macOS) or `~/.bashrc` (Linux/WSL), then reload:
+
+```bash
+source ~/.zshrc      # or: source ~/.bashrc
+```
+{% endtab %}
+
+{% tab title="Token Plan — Windows PowerShell" %}
+Set them temporarily for the current PowerShell window:
+
+```powershell
+$env:ANTHROPIC_BASE_URL = "https://tokenplan.api.greennode.ai"
+$env:ANTHROPIC_AUTH_TOKEN = "<your-subscription-key>"
+```
+
+To persist them for your account (run once, then **reopen PowerShell**):
+
+```powershell
+[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://tokenplan.api.greennode.ai", "User")
+[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "<your-subscription-key>", "User")
 ```
 {% endtab %}
 {% endtabs %}
@@ -68,26 +107,40 @@ To persist them for your account (run once, then **reopen PowerShell**):
 
 ---
 
-## Step 3 — Run Claude Code with GLM 5.2
+## Step 3 — Run Claude Code
 
-In your project directory, run:
+In your project directory, run the command for your service type:
 
+{% tabs %}
+{% tab title="PAYG" %}
 ```bash
 claude --model z-ai/glm-5.2
 ```
+{% endtab %}
+
+{% tab title="Token Plan" %}
+```bash
+claude --model glm-5.2
+```
+
+Replace `glm-5.2` with the exact **Model code** shown on your plan's **Models** tab.
+{% endtab %}
+{% endtabs %}
 
 {% hint style="info" %}
-The `--model z-ai/glm-5.2` flag sets the model for the current session. Inside Claude Code you can also switch models with the `/model` command.
+The `--model` flag sets the model for the current session. Inside Claude Code you can also switch models with the `/model` command.
 {% endhint %}
 
 ---
 
 ## Step 4 — Verify
 
-In Claude Code, type `/status` — it's correct when:
+In Claude Code, type `/status` and compare:
 
-* The Base URL points to `maas-llm-aiplatform-hcm.api.vngcloud.vn`
-* The model is `z-ai/glm-5.2`
+| Check | PAYG | Token Plan |
+|---|---|---|
+| Base URL points to | `maas-llm-aiplatform-hcm.api.vngcloud.vn` | `tokenplan.api.greennode.ai` |
+| Model | `z-ai/glm-5.2` | Your plan's Model code (e.g. `glm-5.2`) |
 
 Then check the **[AI Platform Console](https://aiplatform.console.greennode.ai/)** to see the call logged.
 
@@ -99,19 +152,23 @@ Then check the **[AI Platform Console](https://aiplatform.console.greennode.ai/)
 
 | Symptom | Cause | Fix |
 |------------|-------------|------------|
-| `401` / "Unauthorized" | Wrong or not-yet-ACTIVE API key | Check `ANTHROPIC_AUTH_TOKEN`; wait for the key to become **ACTIVE** |
-| `404` / "Not Found" | Wrong Base URL (extra `/v1` or trailing `/`) | Should be exactly `https://maas-llm-aiplatform-hcm.api.vngcloud.vn` |
+| `401` / "Unauthorized" | Wrong or not-yet-ACTIVE key | Check `ANTHROPIC_AUTH_TOKEN`; wait for the key to become **ACTIVE** |
+| `401` while the key is still valid | **Key and Base URL belong to different service types** — e.g. a PAYG API Key sent to the `tokenplan…` host | Re-check the table at the top of this page: a key from the **API Keys** page → the `maas-llm-…` host; a key from the **Subscription keys** tab → the `tokenplan…` host |
+| `403 Forbidden` (Token Plan) | Model isn't included in the plan | Only call models listed on the plan's **Models** tab |
+| `402 Payment Required` (Token Plan) | Plan has expired or was deleted | Buy the plan again or enable **Auto-renew** |
+| `404` / "Not Found" | Wrong Base URL (extra `/v1` or trailing `/`) | Claude Code is Anthropic-standard — the Base URL has **no** `/v1` |
 | Requests go straight to Anthropic | Old `ANTHROPIC_API_KEY` variable still set | Run `unset ANTHROPIC_API_KEY` (macOS/Linux) or remove that variable on Windows |
-| Wrong model is used | Missing `--model` flag | Run `claude --model z-ai/glm-5.2` or use `/model` to switch |
-| AI doesn't respond | Out of credit, model auto-disabled | Top up credit in the AI Platform Console |
-| Connection timeout | Can't reach MaaS over the network | Check VPN / network access to `*.api.vngcloud.vn` |
+| Wrong model is used | Missing `--model` flag, or a Model ID from the other service type | Run `claude --model <model-id-for-your-service-type>` or use `/model` to switch |
+| AI doesn't respond | PAYG out of credit, or Token Plan out of token quota | PAYG: top up credit. Token Plan: wait for the next cycle, buy another plan, or temporarily switch to a PAYG API Key |
+| Connection timeout | Can't reach the endpoint over the network | Check VPN / network access to `*.api.vngcloud.vn` (PAYG) or `tokenplan.api.greennode.ai` (Token Plan) |
 
 ---
 
 | I want to next... | Go to |
 |------------------------|--------|
 | Use OpenCode | [OpenCode](opencode.md) |
 | See the prerequisites | [Getting Started with AI Coding](../getting-started.md) |
+| Learn about Token Plan packages | [Token Plan](../../token-plan/README.md) |
 
 ---