OpenClaw

OpenClaw là trợ lý AI mã nguồn mở chạy trên thiết bị cá nhân. Gateway quản lý tập trung mô hình, phiên, công cụ và kênh nhắn tin; cung cấp TUI trong terminal và Control UI trong trình duyệt. Sau khi thêm AGTCloud làm Custom Provider, OpenClaw gọi các mô hình mà API Key hiện tại có thể dùng qua điểm vào tương thích OpenAI Chat Completions.

Hướng dẫn này chỉ trình bày cài đặt cục bộ, kết nối mô hình, khởi chạy Gateway và kiểm tra cơ bản. Kênh nhắn tin, Gateway từ xa, tiện ích ClawHub, Skills, MCP, tác vụ định kỳ và đa tác tử không được trình bày trên trang này.

Chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn đã:

• Chuẩn bị thiết bị macOS, Linux, WSL2 hoặc Windows được OpenClaw hỗ trợ;
• Tạo AGTCloud API Key trên trang API Keys;
• Sao chép ID mô hình mà Key hiện tại nhìn thấy và hỗ trợ Chat Completions từ danh mục mô hình;
• Chuẩn bị thư mục thử nghiệm không chứa thông tin xác thực của môi trường production hoặc mã nguồn nhạy cảm.

MODEL_ID là giá trị giữ chỗ cần thay thế. Để thử gọi công cụ, chọn mô hình mà API Key hiện tại nhìn thấy và được xác nhận hỗ trợ gọi công cụ.

Cài đặt OpenClaw

Trình cài đặt chính thức OpenClaw có thể chuẩn bị môi trường Node.js được hỗ trợ khi cần. Nếu tự quản lý Node.js, bạn cũng có thể cài bằng npm.

curl -fsSL https://openclaw.ai/install.sh | bash

Sau khi cài đặt, kiểm tra phiên bản và môi trường chạy:

openclaw --version
openclaw doctor

Nếu trình cài đặt tự mở trình hướng dẫn, bạn có thể thoát bước cấu hình mô hình trước, hoàn tất AGTCloud Provider bên dưới rồi chạy openclaw onboard --install-daemon. Cách này giúp trình hướng dẫn giữ cấu hình mô hình mặc định đã kiểm tra.

Lưu API Key an toàn

OpenClaw đọc ~/.openclaw/.env làm tệp dự phòng biến môi trường toàn cục. Tạo tệp trước, rồi ghi AGTCloud API Key:

~/.openclaw/.env

Nội dung tệp:

AGTCLOUD_API_KEY=your-api-key

Tệp chứa thông tin xác thực thật; không đưa vào kho mã, tải lên dịch vụ lưu trữ hoặc gửi kèm thông tin khắc phục sự cố.

Thêm AGTCloud Custom Provider

OpenClaw lưu Custom Provider trong models.providers. Hướng dẫn này dùng lệnh cấu hình tăng dần để hợp nhất Provider agtcloud, không ghi đè openclaw.json hiện có.

openclaw config set models.providers.agtcloud \
  '{"baseUrl":"https://api.agtcloud.cn/v1","apiKey":"${AGTCLOUD_API_KEY}","api":"openai-completions","auth":"api-key","authHeader":true,"models":[{"id":"MODEL_ID","name":"MODEL_ID","input":["text"]}]}' \
  --strict-json \
  --merge

Các trường chính trong cấu hình:

Hướng dẫn chỉ khai báo đầu vào văn bản cho mô hình, không điền độ dài ngữ cảnh, giới hạn đầu ra, giá, suy luận hoặc khả năng hình ảnh chưa được xác nhận. Sau khi biết khả năng thực tế, bổ sung siêu dữ liệu theo tài liệu trường mô hình chính thức của OpenClaw.

Đặt mô hình và kiểm tra cấu hình

Đặt mô hình vừa đăng ký làm mặc định:

openclaw models set agtcloud/MODEL_ID

Lần lượt kiểm tra tệp cấu hình, mô hình Provider và mô hình mặc định hiện tại:

openclaw config validate
openclaw models list --provider agtcloud
openclaw models status

Nếu config validate báo trường không hợp lệ, sửa cấu hình trước, không tiếp tục khởi chạy Gateway. Nếu danh sách không có agtcloud/MODEL_ID, kiểm tra mô hình đã được thêm vào models.providers.agtcloud.models chưa.

Khi cần kiểm tra kết nối thực tế, có thể chạy:

openclaw models status --probe

Hoàn tất hướng dẫn cục bộ và khởi chạy Gateway

Sau khi cấu hình Provider đạt, chạy trình hướng dẫn cục bộ và cài daemon Gateway:

openclaw onboard --install-daemon

Nếu trình hướng dẫn hỏi cấu hình mô hình, chọn giữ cấu hình hiện có; có thể bỏ qua kênh nhắn tin, Web Search, Skills và phần mở rộng khác. Trong lần đầu, nên giữ Gateway chỉ lắng nghe trên máy cục bộ và giữ xác thực truy cập.

Sau khi hoàn tất, khởi động lại và kiểm tra Gateway:

openclaw gateway restart
openclaw gateway status

Nếu Gateway không khởi động, chạy openclaw config validate và openclaw doctor trước; không dùng cách lắng nghe mạng công khai hoặc tắt xác thực để tạm vượt qua lỗi.

Khởi chạy và kiểm tra kết nối

Mở Control UI hoặc TUI trong terminal

Dùng Control UI trong trình duyệt:

openclaw dashboard

Hoặc kết nối Gateway cục bộ trong terminal:

openclaw tui

Kiểm tra trả lời văn bản cơ bản

Nhập nội dung sau trong lần đầu:

Chỉ trả lời: Kết nối AGTCloud thành công. Không gọi bất kỳ công cụ nào.

Nếu trả về đúng văn bản, Gateway, AGTCloud Provider, API Key và ID mô hình đã kết nối cơ bản.

Tùy chọn: kiểm tra khả năng công cụ chỉ đọc

Sau khi hội thoại thông thường ổn định, nhập trong dự án thử nghiệm an toàn:

Hãy đọc README.md và tóm tắt mục đích dự án thành ba ý. Không sửa bất kỳ tệp nào hoặc chạy lệnh khác.

Kiểm tra từng thao tác OpenClaw đề xuất, chỉ cấp quyền cần để đọc tệp đích. Hội thoại thành công nhưng bước này thất bại thường cho thấy mô hình đích hoặc điểm vào tương thích hiện tại chưa hỗ trợ đầy đủ cấu trúc gọi công cụ cần thiết.

Thêm hoặc chuyển mô hình

Tham chiếu mô hình OpenClaw có dạng provider/model, nên mô hình AGTCloud được viết là:

agtcloud/MODEL_ID

Custom Provider không đảm bảo tự đọc toàn bộ kết quả AGTCloud /v1/models. Khi cần thêm mô hình, hợp nhất đối tượng mô hình mới vào models.providers.agtcloud.models, rồi dùng lệnh sau để chuyển:

openclaw models set agtcloud/MODEL_ID
openclaw gateway restart

Sau khi đổi tên mô hình, xác nhận API Key hiện tại nhìn thấy mô hình và mô hình hỗ trợ giao thức tương ứng; nếu không, có thể báo mô hình không tồn tại hoặc không được phép dùng.

Câu hỏi thường gặp

Nếu chưa xác định được vấn đề, ghi lại phiên bản OpenClaw, thời gian yêu cầu, API Base URL, Provider, ID mô hình, trạng thái HTTP và lỗi đã loại thông tin nhạy cảm, rồi xem Lỗi và khắc phục sự cố. Không gửi .env, bản sao lưu cấu hình đầy đủ hoặc API Key.

Khuyến nghị bảo mật

• OpenClaw được thiết kế cho một người vận hành đáng tin cậy, không đưa Gateway thiếu bảo vệ ra mạng công khai;
• Chỉ dùng thư mục cách ly trong lần đầu và xem xét từng quyền tệp, lệnh, mạng và công cụ;
• Không lưu API Key trong kho mã, ảnh chụp màn hình, bản xuất phiên, nhật ký hoặc cấu hình dùng chung;
• Trước khi thêm kênh nhắn tin, người dùng khác hoặc tác vụ tự động, đọc tài liệu bảo mật và sandbox chính thức của OpenClaw.

Bước tiếp theo

• API Key và xác thực
• Chat Completions API Reference
• Lỗi và khắc phục sự cố
• Tài liệu OpenClaw chính thức