# OpenClaw

> Cài trợ lý AI OpenClaw từ Kho ứng dụng với API key của LLM, đăng nhập bằng gateway token, duyệt trình duyệt và kết nối Telegram, Zalo hoặc WhatsApp.

Source: https://zopanel.net/vi/docs/app-openclaw  
Updated: 2026-10-09

OpenClaw là gateway trợ lý AI tự host. Ứng dụng nối một mô hình ngôn ngữ lớn (Anthropic, OpenAI, DeepSeek…) với các ứng dụng chat bạn đang dùng như Telegram, Zalo, WhatsApp, kèm Control UI trên web để chat, quản lý phiên, agent và kênh. Dùng OpenClaw khi bạn muốn một trợ lý luôn sẵn sàng, nhắn được từ ứng dụng chat trên điện thoại, với lịch sử hội thoại nằm trên server của mình.

## Yêu cầu

| Mục | Giá trị |
| --- | --- |
| Image | `ghcr.io/openclaw/openclaw:2026.9.8` |
| Giới hạn RAM | 2048 MB, 1 CPU. Hộp thoại cài cảnh báo ứng dụng cần khoảng 2 GB RAM trở lên. |
| Dung lượng trống để cài | khoảng 5,8 GB (image khoảng 3,3 GB) |
| Tên miền | tên miền hoặc subdomain đã trỏ về server, ví dụ `claw.example.com` |
| API key của LLM | ít nhất một trong Anthropic, OpenAI hoặc DeepSeek. Bạn trả phí trực tiếp cho nhà cung cấp. |

Server phải có Docker (**Kho ứng dụng → Cài Docker**). Khách hàng cần gói hosting cho phép ứng dụng Docker và còn trống 2048 MB trong **RAM (MB)** cho ứng dụng; xem [Kho ứng dụng và lưu trữ S3](/vi/docs/apps).

## Cài đặt

1. Trỏ bản ghi A của tên miền về server.
2. Mở **Kho ứng dụng** và bấm **Cài đặt** trên thẻ **OpenClaw**.
3. Điền hộp thoại. Hộp thoại ghi "Nhập ít nhất một API key (bạn tự trả phí cho nhà cung cấp model)."

   | Trường | Nhập gì |
   | --- | --- |
   | **Tên miền** | ví dụ `claw.example.com` |
   | **Chủ sở hữu** | Chỉ quản trị viên thấy: tài khoản hosting sở hữu ứng dụng |
   | **Anthropic API key** | key lấy từ Anthropic Console (bắt đầu bằng `sk-ant-`) |
   | **OpenAI API key** | key lấy từ OpenAI platform |
   | **DeepSeek API key** | key lấy từ DeepSeek platform |
   | **SSL miễn phí (Let's Encrypt)** | Giữ bật |

   Điền một hoặc nhiều key. Lượt cài không có key nào bị từ chối với thông báo `OpenClaw needs at least one API key`. Mỗi giá trị tối đa 512 ký tự, trên một dòng.

4. Bấm **Cài đặt** và theo dõi log tác vụ.

ZoPanel truyền key vào container dưới dạng `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` và `DEEPSEEK_API_KEY`, đồng thời đặt:

| Thiết lập | Giá trị |
| --- | --- |
| `OPENCLAW_GATEWAY_TOKEN` | token ngẫu nhiên 32 ký tự bảo vệ Control UI, hiển thị trong **Thông tin đăng nhập** |
| `gateway.bind`, `gateway.mode` | `lan`, `local`: gateway lắng nghe bên trong container; cổng chỉ publish trên 127.0.0.1 và đi qua nginx |
| `gateway.trustedProxies` | bridge của Docker, để OpenClaw chấp nhận request từ nginx của website |
| `gateway.controlUi.allowedOrigins` | `https://<tên miền>` và `http://<tên miền>` |

Các giá trị `gateway.*` được ghi vào `openclaw.json` mỗi lần ứng dụng khởi động và khi panel khởi động. Nếu bạn sửa chúng, ZoPanel đặt lại và khởi động lại ứng dụng.

Sau khi cài, không sửa được key từ panel. Muốn dùng key khác, hãy thêm nó bên trong OpenClaw (xem mục Chọn model).

## Đăng nhập và duyệt trình duyệt

OpenClaw không có khoá thiết lập: ứng dụng được bảo vệ bằng gateway token và bằng việc duyệt trình duyệt, nên tên miền công khai ngay khi cài xong.

1. Mở **Website**, chọn tên miền và vào tab **Docker**.
2. Trong **Thông tin đăng nhập**, sao chép `OPENCLAW_GATEWAY_TOKEN`. Chỉ người quản lý được website mới thấy.
3. Mở `https://<tên miền>`. Dán token vào **Gateway secret** và bấm **Connect**.
4. OpenClaw yêu cầu duyệt trình duyệt này. Quay lại tab **Docker**: thẻ **Trình duyệt** liệt kê nó ở mục **Đang chờ duyệt**, kèm nền tảng, địa chỉ IP và thời gian.
5. Bấm **Duyệt**. Control UI sẽ mở. Bấm **Từ chối** với yêu cầu bạn không nhận ra.

Mỗi trình duyệt hay thiết bị mới đều phải được duyệt như vậy. Những cái đã duyệt nằm ở mục **Đã duyệt**. Token chỉ được giữ trong tab trình duyệt hiện tại; sau khi duyệt, trình duyệt dùng token thiết bị riêng.

**Quan trọng:** ai có gateway token đều gửi được yêu cầu truy cập, và trình duyệt đã duyệt có thể điều khiển trợ lý và dùng API key của bạn. Hãy giữ bí mật token.

## Chọn model

OpenClaw dùng các nhà cung cấp mà nó tìm thấy key. Kiểm tra hoặc đổi model mặc định trong Control UI tại **Settings → Models**, hoặc bằng lệnh `/model` trong cuộc chat. Hãy đặt hạn mức chi tiêu ở trang quản lý của nhà cung cấp: mọi tin nhắn, tác vụ tự động và kênh đều dùng key của bạn.

Operator terminal trong Control UI mở một shell bên trong container, có sẵn CLI của OpenClaw, ví dụ:

```bash
openclaw models list
openclaw channels status --probe
```

Nếu không thấy model DeepSeek, có thể thiếu plugin của nhà cung cấp này: `openclaw plugins install @openclaw/deepseek-provider`.

## Kết nối kênh chat

Kênh được cấu hình trong **Settings → Channels** (nhóm **Connections**) hoặc bằng CLI trong operator terminal. OpenClaw áp dụng thay đổi kênh mà không cần khởi động lại.

**Telegram**

1. Trong Telegram, nhắn cho **@BotFather**, chạy `/newbot` và sao chép bot token.
2. Thêm token trong **Settings → Channels → Telegram**, hoặc chạy `openclaw channels add --channel telegram --token <bot-token>`.
3. Gửi một tin nhắn bất kỳ cho bot. Mặc định, người gửi lạ nhận được mã ghép đôi (pairing code).
4. Duyệt mã trong operator terminal (mã hết hạn sau một giờ):

   ```bash
   openclaw pairing list telegram
   openclaw pairing approve telegram <CODE>
   ```

**Zalo** (OpenClaw ghi là thử nghiệm): tạo bot tại [bot.zaloplatforms.com](https://bot.zaloplatforms.com), nhập token trong **Settings → Channels**, rồi duyệt mã ghép đôi của tin nhắn đầu tiên theo cách tương tự (`openclaw pairing approve zalo <CODE>`).

**WhatsApp**: OpenClaw liên kết như một thiết bị WhatsApp Web. Bắt đầu đăng nhập từ **Settings → Channels → WhatsApp** và quét mã QR bằng WhatsApp trên điện thoại (**Thiết bị liên kết**).

Telegram mặc định dùng long polling, chỉ mở kết nối ra ngoài, nên chạy được sau ZoPanel mà không cần thiết lập thêm.

## Dữ liệu nằm ở đâu

```text
/var/lib/zopanel-apps/<instance>/state/
```

`<instance>` là tên miền với dấu chấm thay bằng dấu gạch ngang (`claw.example.com` → `claw-example-com`). Thư mục được gắn vào `/home/node/.openclaw`, chứa `openclaw.json`, thông tin đăng nhập của các kênh (bot token, phiên WhatsApp), thiết bị đã ghép đôi, phiên chat, bộ nhớ và workspace của agent. Chỉ root và container đọc được.

## Sao lưu

Sao lưu website của ZoPanel **không** gồm `/var/lib/zopanel-apps`; ứng dụng được sao lưu bằng thẻ **Sao lưu** trong tab **Docker** của website.

Để sao lưu OpenClaw, bấm **Sao lưu ngay** trong thẻ **Sao lưu** ở tab **Docker** của website. Quản trị viên còn đặt được **Lịch** (**Tắt**, **Mỗi ngày** hoặc **Mỗi tuần**; mặc định tắt) và số bản **Giữ lại** (1–60, mặc định 7), rồi bấm **Lưu**. Mỗi bản sao lưu nén `/var/lib/zopanel-apps/<instance>/` thành `/var/backups/zopanel-apps/<instance>/YYYYMMDD-HHMMSS.tar.gz`, trong thư mục chỉ root đọc được và không tính vào dung lượng đĩa của tài khoản. Container được tạm dừng (pause, không phải stop) trong vài giây sao chép, nên bản sao nhất quán. Các bản cũ vượt quá số **Giữ lại** bị xoá, và khi một lần sao lưu theo lịch thất bại, quản trị viên nhận cảnh báo **Sao lưu thất bại**.

Để khôi phục, quản trị viên bấm **Khôi phục** cạnh một bản sao lưu. OpenClaw được dừng và dữ liệu được thay bằng nội dung file nén; dữ liệu hiện tại được giữ riêng tới khi ứng dụng khôi phục khởi động được, và được đặt lại nếu nó không khởi động. Mọi thay đổi sau thời điểm sao lưu sẽ mất. Mỗi bản sao lưu còn có nút xoá (chỉ quản trị viên), và xoá ứng dụng kèm file của nó cũng xoá luôn các bản sao lưu. Khách hàng có thể bấm **Sao lưu ngay** và xem danh sách; việc đặt lịch và khôi phục do nhà cung cấp thực hiện.

Các file nén vẫn ở trên cùng máy chủ. Hãy chép những bản quan trọng ra ngoài (ví dụ bằng `scp` hoặc `rclone` từ `/var/backups/zopanel-apps/<instance>/`) và lưu ở dạng mã hoá, vì chúng chứa API key, bot token và phiên WhatsApp. Để khôi phục trên máy chủ khác, cài OpenClaw với cùng tên miền ở đó, chép file nén vào `/var/backups/zopanel-apps/<instance>/` trên máy chủ mới rồi bấm **Khôi phục** trong thẻ **Sao lưu** của nó. Bản cài mới có gateway token mới, hiển thị trong **Thông tin đăng nhập**.

## Cập nhật

Quản trị viên bấm **Cập nhật bản mới** ở tab **Docker**. ZoPanel kéo image mà phiên bản ZoPanel hiện tại đã ghim, tạo lại container, giữ nguyên state, key và token. Bản OpenClaw mới hơn đến cùng các bản cập nhật ZoPanel. OpenClaw chuyển đổi state khi khởi động, nên hãy sao lưu trước (**Sao lưu ngay**). Khách hàng nhờ nhà cung cấp cập nhật.

## Giới hạn mạng

Container bị chặn khỏi loopback và mạng nội bộ của server, khỏi địa chỉ link-local (gồm cả dịch vụ metadata của cloud) và khỏi các container khác. Trên chính server, container chỉ tới được cổng 80, 443, 25, 465, 587 và DNS. Container không có Docker socket hay thư mục của máy chủ: chính container là sandbox của trợ lý. Với OpenClaw:

- Nhà cung cấp model phải là API công khai. Không dùng được server model cục bộ (Ollama, LM Studio, vLLM) trên cùng server hay trong mạng nội bộ.
- Công cụ duyệt web, lấy dữ liệu từ URL hay chạy lệnh chỉ tới được internet công khai, không tới được database, Redis, panel của server hay máy trong mạng nội bộ của bạn.
- Operator terminal chỉ là shell bên trong container này.

## Xử lý sự cố

| Vấn đề | Cách xử lý |
| --- | --- |
| Thẻ **Trình duyệt** báo `the app is not ready yet; try again in a minute` | OpenClaw vẫn đang khởi động (có thể mất một tới hai phút). Làm mới thẻ. |
| Đã kết nối nhưng thẻ báo "Chưa có trình duyệt nào chờ duyệt" | Kết nối lại trong Control UI, rồi làm mới thẻ **Trình duyệt**. |
| Control UI từ chối token | Sao chép lại từ **Thông tin đăng nhập**, không lẫn khoảng trắng. |
| Control UI từ chối origin | Mở ứng dụng bằng `https://<tên miền>`, không mở bằng địa chỉ IP. |
| Bot không trả lời trên Telegram | Duyệt mã ghép đôi; kiểm tra `openclaw channels status --probe`. Trong nhóm, hãy nhắc tên bot hoặc tắt privacy mode của bot trong BotFather. |
| Lỗi từ model (401, 429, hết tiền) | Kiểm tra key và số dư ở nhà cung cấp. |
| Kết nối tới `localhost` hay IP nội bộ thất bại | Bị chặn có chủ đích; hãy dùng endpoint công khai. |
| `not enough disk space: this app needs about 5.8 GB free…` | Giải phóng dung lượng rồi cài lại. |
| Container khởi động lại khi tải nặng | Đã chạm giới hạn 2048 MB. Giảm số phiên hoặc công cụ chạy cùng lúc. |

Xem **Log ứng dụng** ở tab **Docker** để đọc lỗi từ ứng dụng.

## Xem thêm

- [Từng ứng dụng dùng để làm gì](/vi/docs/app-catalog)
- [Kho ứng dụng và lưu trữ S3](/vi/docs/apps)
- [Open WebUI](/vi/docs/app-open-webui)
- [Flowise](/vi/docs/app-flowise)
- Chính thức: [Tài liệu OpenClaw](https://docs.openclaw.ai), [Control UI](https://docs.openclaw.ai/web/control-ui), [Thiết lập Telegram](https://docs.openclaw.ai/channels/telegram/setup)