[docs] AgentBase OpenClaw — pair only after Active, enter Bot Token at deploy — VI + EN

English/ai-stack/agent-base/agent-runtime/openclaw/deploy-and-manage-openclaw.md

@@ -12,7 +12,7 @@ For an overview of concepts, architecture, and deployment options, see [OpenClaw
 
 You can access the Agent Marketplace in two ways:
 
-* **Option 1**: Go to the GreenNode homepage at [https://dashboard.console.greennode.ai/](https://dashboard.console.greennode.ai/). From the main dashboard, navigate to **AI Stack** and select **Agentbase** → **Agent Marketplace**.
+* **Option 1**: Go to the GreenNode homepage at [https://dashboard.console.greennode.ai/](https://dashboard.console.greennode.ai/). From the main dashboard, navigate to **AI Stack** and select **Agentbase** → **Agent Marketplace**.
 * **Option 2**: Go directly to [https://aiplatform.console.greennode.ai/agent-marketplace](https://aiplatform.console.greennode.ai/agent-marketplace).
 
 <figure><img src="../../../../.gitbook/assets/Screenshot 2026-04-03 154428.png" alt=""><figcaption></figcaption></figure>
@@ -51,7 +51,7 @@ When selecting **BYOK**, provide the following additional details:
 | Field             | Description                                  | Notes                                                                  |
 | ----------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
 | **OpenClaw Name** | Instance identifier                          | Auto-filled as `openclaw/{username}`, cannot be changed after creation |
-| **Flavor**        | Compute resource configuration (vCPU × RAM) | Default: `2×4`. Options include `4×8`, `8×16`...                    |
+| **Flavor**        | Compute resource configuration (vCPU × RAM) | Default: `2×4`. Options include `4×8`, `8×16`... |
 
 **Section 3 — Channel Configuration (Optional)**
 
@@ -61,7 +61,11 @@ Connect OpenClaw to a messaging platform so you can chat right after deployment.
 | -------------------- | ------------------ | -------------------------------------------------------- |
 | **Channel Provider** | Messaging platform | Supported: Telegram, Zalo                                |
 | **Mode**             | Connection mode    | Pairing (default) or Allow List                          |
-| **Bot Token**        | Channel bot token  | Optional. Can be configured later at Settings → Config |
+| **Bot Token**        | Channel bot token  | Not enforced by the form, but **fill it in here** — see the note below |
+
+{% hint style="warning" %}
+**Enter the Bot Token at this step.** The deploy form does not require a Bot Token, but if you leave it empty, adding the token after the instance is created means asking the agent inside OpenClaw to update the channel configuration itself — which is hard to do and easy to get wrong. Get your bot token first via [Get Bot Token and Pairing](get-bot-token-and-pairing.md), then paste it here so the channel connects as soon as the deploy finishes.
+{% endhint %}
 
 Once all fields are filled, click **"Start Setup"** to begin provisioning.
 
@@ -78,13 +82,17 @@ Once provisioning is complete, the Deploy Success screen shows your instance det
 | Field                    | Description                                                  |
 | ------------------------ | ------------------------------------------------------------ |
 | **Instance Name**        | The name of your created instance (e.g. `openclaw/username`) |
-| **Status**               | 🟢 Active                                                  |
+| **Status**               | 🟢 Active |
 | **Gateway Token**        | Token used to log in to the OpenClaw web admin               |
 | **OpenClaw Gateway URL** | Link to your OpenClaw web admin                              |
 | **Created At**           | Timestamp                                                    |
 
 Click **"Open OpenClaw"** to access your OpenClaw Gateway Dashboard and start using it immediately.
 
+{% hint style="warning" %}
+**Only start pairing once the status is 🟢 Active.** If you send `/start` to your Telegram/Zalo bot while the instance is still `Creating`, the bot returns no pairing code — and that message is not reprocessed once the instance becomes Active. Wait for Active, then follow [Get Bot Token and Pairing](get-bot-token-and-pairing.md).
+{% endhint %}
+
 ***
 
 ## Manage OpenClaw Instances
@@ -115,7 +123,7 @@ After stopping, the instance status changes to **Stopped** and its URL is no lon
 
 1. In My Agents, filter by **Stopped** status to find the instance.
 2. Click **"Restart"** on the instance.
-3. The instance transitions through **Starting → Active**.
+3. The instance transitions through **Starting → Active**.
 
 After restarting, the URL becomes accessible again.
 

English/ai-stack/agent-base/agent-runtime/openclaw/get-bot-token-and-pairing.md

@@ -3,6 +3,14 @@
 > This guide covers how to get a bot token and complete pairing to connect a chat channel with OpenClaw on AgentBase.
 > If you haven't deployed OpenClaw yet, see: [Deploy & Manage OpenClaw](deploy-and-manage-openclaw.md).
 
+{% hint style="warning" %}
+**Get your bot token before you deploy.** The **Bot Token** field in the **Channel Configuration** step is optional, but you should fill it in there. If you leave it empty and only add the token after the instance exists, you have to ask the agent inside OpenClaw to update the channel configuration itself — which is hard to do and easy to get wrong. Do **Part 1** (Telegram) or **Part 3** (Zalo) first, then paste the token into the deploy form.
+{% endhint %}
+
+{% hint style="warning" %}
+**Only pair once the instance is Active.** Pairing requires a running OpenClaw instance. Open **My Agents** and confirm the status is 🟢 **Active** before sending `/start` to your bot.
+{% endhint %}
+
 ## Part 1 — Get a Bot Token from Telegram
 
 ### Step 1: Create a new bot on BotFather
@@ -20,7 +28,7 @@ After creation, BotFather returns a message containing a token in this format:
 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
 ```
 
-Copy this token and store it somewhere safe — you will need it when configuring the Telegram channel in AgentBase.
+Copy this token and store it somewhere safe — you will paste it into the **Bot Token** field in the **Channel Configuration** step when you [deploy OpenClaw](deploy-and-manage-openclaw.md).
 
 > **Note:** The token is a secret — do not share it publicly.
 
@@ -30,6 +38,8 @@ Copy this token and store it somewhere safe — you will need it when configurin
 
 ### Step 1: Get the Pairing Code
 
+Confirm your OpenClaw instance is 🟢 **Active** in **My Agents** before doing this step.
+
 1. Open Telegram and find the bot you just created (e.g. `@my_openclaw_bot`).
 2. Tap **Start** or send `/start`.
 3. The bot replies with a **pairing code**, for example:
@@ -76,31 +86,40 @@ Zalo tokens follow the format `numeric_id:secret`, for example:
 1234567890123456789:abcXYZexampleTokenSecretKey123
 ```
 
-Copy the **full token** (including everything after the `:`).
+Copy the **full token** (including everything after the `:`) and paste it into the **Bot Token** field in the **Channel Configuration** step when you [deploy OpenClaw](deploy-and-manage-openclaw.md).
 
 > **Note:** Zalo tokens are longer than Telegram tokens — make sure you copy the complete `:secret` part.
 
 ---
 
 ## Part 4 — Pair your Zalo account with OpenClaw
 
-### Step 1: Get the Pairing Code
+### Step 1: Confirm the OpenClaw instance is Active
+
+Open **My Agents** and check that the instance status is 🟢 **Active**.
+
+{% hint style="warning" %}
+**Do not send `/start` while the instance is still `Creating`.** The Zalo bot can only generate a pairing code once the OpenClaw instance is running. If you message `/start` while the instance is still being created, the bot returns **no pairing code at all** — and that message is not reprocessed once the instance becomes Active. Wait until the status is **Active**, then send `/start`.
+{% endhint %}
+
+### Step 2: Get the Pairing Code
 
 1. Open Zalo and send a message to the bot you just created.
 2. Send `/start` or `Hello`.
 3. The bot replies with an 8-character **pairing code** (e.g. `EXMP1234`). The code is valid for **1 hour**.
 
-### Step 2: Approve Pairing in OpenClaw Gateway
+### Step 3: Approve Pairing in OpenClaw Gateway
 
 Go to **OpenClaw Gateway Dashboard** → find the chat box and enter:
 
 ```
 openclaw pairing approve zalo <pairing_code>
 ```
 
-Replace `<pairing_code>` with the code from Step 1.
+Replace `<pairing_code>` with the code from Step 2.
 
 ### Result
 
 - Pairing successful → the bot starts receiving and replying to your messages on Zalo.
 - If the code expires → send `/start` again on Zalo to get a new code.
+- If the bot returns **no code at all** → the instance isn't Active yet, or the channel has no Bot Token. Check the instance status in **My Agents** and the channel configuration at **Settings → Config**, then send `/start` again.

English/ai-stack/agent-base/agent-runtime/openclaw/limitations-and-notes.md

@@ -27,4 +27,15 @@ If a BYOK API key expires or is revoked after deployment, the instance will no l
 
 ***
 
+## Channel connection notes
+
+| Situation | Why it matters | What to do |
+| --- | --- | --- |
+| **Bot Token left empty at deploy** | The deploy form doesn't require a Bot Token, but adding one after the instance is created means asking the agent to update the channel configuration itself — hard to do and easy to get wrong | Get the bot token first, then enter it in the **Channel Configuration** step while deploying |
+| **Sending `/start` while the instance is `Creating`** | The bot can only generate a pairing code once the instance is running; send too early and the bot returns **no code at all**, and that message is not reprocessed once the instance becomes Active | Wait for 🟢 **Active** in **My Agents**, then send `/start` |
+
+Details: [Get Bot Token and Pairing](get-bot-token-and-pairing.md).
+
+***
+
 If you encounter any difficulties, please contact the GreenNode team for support.

English/ai-stack/agent-base/agent-runtime/openclaw/openclaw-1-click.md

@@ -74,6 +74,10 @@ OpenClaw supports connecting to messaging platforms so you can chat with your AI
 
 Channels can be configured during the deploy step or later at **Settings → Config** in the OpenClaw Gateway.
 
+{% hint style="warning" %}
+**Enter the Bot Token during deploy.** The Bot Token field in the Channel Configuration step is optional, but if you leave it empty, adding the token after the instance is created means asking the agent to update the channel configuration itself — which is hard to do and easy to get wrong. Prepare the token first via [Get Bot Token and Pairing](get-bot-token-and-pairing.md).
+{% endhint %}
+
 ***
 
 ## FAQ
@@ -92,6 +96,8 @@ Instance data is preserved after an auto-shutdown. Simply Restart from My Agents
 
 ### 4. Can I integrate Telegram or Zalo?
 
-**Yes.** You can configure the integration during the deploy step or later at **Settings → Config** in the OpenClaw Gateway. Both Telegram and Zalo are supported.
+**Yes.** Both Telegram and Zalo are supported. You can configure the integration during the deploy step or later at **Settings → Config** in the OpenClaw Gateway — but enter the **Bot Token** during deploy, because adding a token after the instance exists has to go through the agent and is considerably harder.
+
+After deploying, only start pairing (sending `/start` from Telegram/Zalo) once the instance is 🟢 **Active** — sending it while the instance is still `Creating` returns no pairing code.
 
 For current limitations and important technical notes, see [Limitations & Notes](limitations-and-notes.md).

Vietnamese/ai-stack/agent-base/agent-runtime/openclaw/gioi-han-va-luu-y.md

@@ -27,4 +27,15 @@ Nếu API key BYOK hết hạn hoặc bị thu hồi sau khi deploy, instance s
 
 ***
 
+## Lưu ý khi kết nối Channel
+
+| Tình huống | Vì sao cần lưu ý | Nên làm |
+| --- | --- | --- |
+| **Bot Token để trống khi deploy** | Form deploy không bắt buộc nhập Bot Token, nhưng thêm token sau khi instance đã tạo phải nhờ agent tự cập nhật cấu hình channel — khó thực hiện và dễ sai | Lấy bot token trước, rồi nhập ngay tại bước **Cấu hình Channel** khi deploy |
+| **Gửi `/start` khi instance còn `Creating`** | Bot chỉ sinh được pairing code khi instance đã chạy; gửi sớm thì bot **không trả về code nào**, và tin nhắn đó không được xử lý lại khi instance Active | Đợi trạng thái 🟢 **Active** tại **My Agents**, sau đó mới gửi `/start` |
+
+Chi tiết: [Lấy Bot Token và Pairing](lay-bot-token-va-pairing.md).
+
+***
+
 Nếu gặp bất kỳ khó khăn nào trong quá trình sử dụng, vui lòng liên hệ đội ngũ GreenNode để được hỗ trợ.

Vietnamese/ai-stack/agent-base/agent-runtime/openclaw/lay-bot-token-va-pairing.md

@@ -2,6 +2,14 @@
 
 > Tài liệu này hướng dẫn lấy bot token và pairing để kết nối kênh chat với OpenClaw trên AgentBase. Nếu bạn chưa triển khai OpenClaw, xem trước: [Triển khai và Quản lý OpenClaw](trien-khai-openclaw-1-click.md).
 
+{% hint style="warning" %}
+**Lấy bot token trước khi deploy.** Trường **Bot Token** ở bước **Cấu hình Channel** lúc deploy không bắt buộc, nhưng bạn nên điền ngay tại đó. Nếu để trống rồi deploy xong mới muốn thêm, bạn phải nhờ agent trong OpenClaw tự cập nhật cấu hình channel — việc này khó thực hiện và dễ sai. Hãy làm **Phần 1** (Telegram) hoặc **Phần 3** (Zalo) trước, rồi dán token vào form deploy.
+{% endhint %}
+
+{% hint style="warning" %}
+**Chỉ pairing khi instance đã Active.** Pairing yêu cầu OpenClaw instance đang chạy. Mở **My Agents** và xác nhận trạng thái là 🟢 **Active** trước khi gửi `/start` cho bot.
+{% endhint %}
+
 ## Phần 1 — Lấy Bot Token từ Telegram
 
 ### Bước 1: Tạo bot mới trên BotFather
@@ -21,7 +29,7 @@ Sau khi tạo xong, BotFather trả về tin nhắn chứa token có dạng:
 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
 ```
 
-Sao chép token này và lưu vào nơi an toàn — bạn sẽ cần dùng khi cấu hình kênh Telegram trong AgentBase.
+Sao chép token này và lưu vào nơi an toàn — bạn sẽ dán nó vào trường **Bot Token** ở bước **Cấu hình Channel** khi [deploy OpenClaw](trien-khai-openclaw-1-click.md).
 
 > **Lưu ý:** Token là thông tin bí mật, không chia sẻ công khai.
 
@@ -33,6 +41,8 @@ Sao chép token này và lưu vào nơi an toàn — bạn sẽ cần dùng khi
 
 <figure><img src="../../../../.gitbook/assets/paring.png" alt=""><figcaption></figcaption></figure>
 
+Xác nhận OpenClaw instance đang ở trạng thái 🟢 **Active** tại **My Agents** trước khi làm bước này.
+
 1. Mở Telegram, tìm bot bạn vừa tạo (ví dụ: `@my_openclaw_bot`).
 2. Nhấn **Start** hoặc gửi `/start`.
 3. Bot phản hồi một **pairing code**, ví dụ:
@@ -83,7 +93,7 @@ Token Zalo có dạng `numeric_id:secret`, ví dụ:
 1234567890123456789:abcXYZexampleTokenSecretKey123
 ```
 
-Sao chép **toàn bộ** token (bao gồm cả phần sau dấu `:`) và lưu vào nơi an toàn.
+Sao chép **toàn bộ** token (bao gồm cả phần sau dấu `:`) và dán vào trường **Bot Token** ở bước **Cấu hình Channel** khi [deploy OpenClaw](trien-khai-openclaw-1-click.md).
 
 <figure><img src="../../../../.gitbook/assets/bot token.jpg" alt=""><figcaption></figcaption></figure>
 
@@ -93,25 +103,34 @@ Sao chép **toàn bộ** token (bao gồm cả phần sau dấu `:`) và lưu v
 
 ## Phần 4 — Pairing tài khoản Zalo với OpenClaw
 
-### Bước 1: Lấy Pairing Code
+### Bước 1: Xác nhận OpenClaw instance đã Active
+
+Mở **My Agents** và kiểm tra instance đang ở trạng thái 🟢 **Active**.
+
+{% hint style="warning" %}
+**Đừng gửi `/start` khi instance còn đang `Creating`.** Bot Zalo chỉ sinh được pairing code khi OpenClaw instance đã chạy. Nếu bạn nhắn `/start` lúc instance còn đang khởi tạo, bot **không trả về pairing code nào** — và tin nhắn đó cũng không được xử lý lại khi instance chuyển sang Active. Đợi tới khi trạng thái là **Active** rồi mới gửi `/start`.
+{% endhint %}
+
+### Bước 2: Lấy Pairing Code
 
 1. Mở Zalo, tìm và nhắn tin cho bot vừa tạo.
 2. Gửi `/start` hoặc `Xin chào`.
 3. Bot phản hồi một **pairing code** (8 ký tự), ví dụ: `EXMP1234`. Code có hiệu lực trong **1 giờ**.
 
 <figure><img src="../../../../.gitbook/assets/chat paring.png" alt=""><figcaption></figcaption></figure>
 
-### Bước 2: Approve Pairing trong OpenClaw Gateway
+### Bước 3: Approve Pairing trong OpenClaw Gateway
 
 Truy cập **OpenClaw Gateway Dashboard** → tìm ô chat, sau đó nhập:
 
 ```
 openclaw pairing approve zalo <pairing_code>
 ```
 
-Thay `<pairing_code>` bằng code nhận được ở Bước 1.
+Thay `<pairing_code>` bằng code nhận được ở Bước 2.
 
 ### Kết quả
 
 * Pairing thành công → bot bắt đầu nhận và trả lời tin nhắn của bạn trên Zalo.
 * Nếu code hết hạn → nhắn `/start` lại trên Zalo để lấy code mới.
+* Nếu bot **không trả về code nào** → instance chưa Active, hoặc channel chưa có Bot Token. Kiểm tra trạng thái instance tại **My Agents** và cấu hình channel tại **Settings → Config**, rồi gửi lại `/start`.

Vietnamese/ai-stack/agent-base/agent-runtime/openclaw/openclaw-1-click.md

@@ -74,6 +74,10 @@ OpenClaw hỗ trợ kết nối với các nền tảng nhắn tin để bạn c
 
 Channel có thể được cấu hình ngay trong bước deploy hoặc sau đó tại **Settings → Config** trong OpenClaw Gateway.
 
+{% hint style="warning" %}
+**Nên nhập Bot Token ngay khi deploy.** Trường Bot Token ở bước Cấu hình Channel không bắt buộc, nhưng nếu để trống thì sau khi tạo instance bạn phải nhờ agent tự cập nhật cấu hình channel — việc này khó thực hiện và dễ sai. Chuẩn bị token trước theo [Lấy Bot Token và Pairing](lay-bot-token-va-pairing.md).
+{% endhint %}
+
 ***
 
 ## FAQ
@@ -92,6 +96,8 @@ Dữ liệu của instance được giữ lại sau auto-shutdown. Bạn Restart
 
 ### 4. Tôi có thể tích hợp Telegram hoặc Zalo không?
 
-**Có.** Bạn có thể cấu hình ngay trong bước deploy hoặc sau đó tại **Settings → Config** trong OpenClaw Gateway. Hiện hỗ trợ Telegram và Zalo.
+**Có.** Hiện hỗ trợ Telegram và Zalo. Bạn có thể cấu hình ngay trong bước deploy hoặc sau đó tại **Settings → Config** trong OpenClaw Gateway — nhưng nên nhập **Bot Token** ngay khi deploy, vì thêm token sau khi instance đã tạo phải thực hiện qua agent và khó hơn nhiều.
+
+Sau khi deploy, chỉ bắt đầu pairing (`/start` phía Telegram/Zalo) khi instance đã ở trạng thái 🟢 **Active** — gửi lúc còn `Creating` sẽ không nhận được pairing code.
 
 Xem thêm giới hạn và lưu ý kỹ thuật tại [Giới hạn và Lưu ý](gioi-han-va-luu-y.md).