OpenClaw dùng API key: thêm nhà cung cấp OpenAI-compatible và nối với Zalo

OpenClaw là gì?

OpenClaw là trợ lý AI mã nguồn mở chạy trên máy của bạn hoặc trên một máy chủ. Phần lõi là Gateway, tiến trình chạy nền nhận tin nhắn từ các kênh chat như Zalo, Telegram, Discord, Slack hay WhatsApp, gọi model để trả lời và dùng công cụ: đọc file, duyệt web, chạy lệnh, chạy tác vụ theo lịch.

OpenClaw không kèm model. Bạn nối nó với một nhà cung cấp, bằng tài khoản thuê bao mà OpenClaw hỗ trợ đăng nhập hoặc bằng API key tính theo token. Bài này đi theo cách thứ hai, với một endpoint OpenAI-compatible.

Cần chuẩn bị gì?

Trước khi cài, chuẩn bị sẵn:

• Node.js 24.16 trở lên hoặc 26.1 trở lên; bộ cài chính thức tự cài Node nếu máy chưa có.
• macOS, Linux hoặc Windows.
• API key và base URL của nhà cung cấp. Với STEYG Code, base URL là https://steyg.one/api/v1.
• Model id muốn dùng, lấy từ GET /v1/models bằng chính key đó.

Cài OpenClaw

Bộ cài chính thức dò hệ điều hành, cài Node nếu thiếu, cài OpenClaw rồi mở bước thiết lập. Ai tự quản lý Node có thể cài bằng npm rồi chạy openclaw onboard --install-daemon để cài Gateway thành dịch vụ chạy nền. Trên Windows, chạy iwr -useb https://openclaw.ai/install.ps1 | iex trong PowerShell hoặc dùng ứng dụng Windows Hub. Kiểm tra bằng openclaw --version, openclaw doctor và openclaw gateway status.

# macOS, Linux, WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Hoặc npm (npm 11.16 trở lên)
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

Thêm nhà cung cấp bằng openclaw onboard

Cách nhanh là trả lời các câu hỏi của openclaw onboard. OpenClaw gửi một request thật tới model bạn chọn và chỉ lưu cấu hình khi request đó thành công, nên sai base URL hay key lộ ra ngay ở bước này thay vì lúc đang chat.

1. Chạy openclaw onboard và đọc thông báo bảo mật: trợ lý có quyền rộng trên máy chạy nó.
2. Ở bước chọn nhà cung cấp, chọn nhà cung cấp tuỳ chỉnh (Custom provider) cho endpoint OpenAI-compatible; không thấy ngay thì mở nhóm More… để tìm.
3. Nhập base URL https://steyg.one/api/v1, chọn kiểu tương thích OpenAI và dán API key.
4. Nhập model id lấy từ GET /v1/models thay vì để OpenClaw tự dò: khi tự dò, OpenClaw lưu mọi model đọc được và lấy model đầu danh sách làm mặc định.
5. Chờ request thử thành công. OpenClaw lưu cấu hình, khởi động Gateway và mở bảng điều khiển.

Hoặc khai báo trong openclaw.json

Ai muốn quản lý cấu hình bằng file có thể khai nhà cung cấp trong ~/.openclaw/openclaw.json. File này đọc được JSON5, nên JSON thường như mẫu dưới cũng hợp lệ.

Không ghi key vào file cấu hình. Thêm dòng STEYG_CODE_API_KEY= kèm key vào ~/.openclaw/.env, file mà tài liệu OpenClaw khuyên dùng cho API key của nhà cung cấp và Gateway chạy nền cũng đọc được; mẫu dưới tham chiếu biến đó thay vì chép key. Thay MODEL_ID bằng id lấy từ GET /v1/models; muốn nhiều model thì thêm nhiều mục trong models.

Sửa xong, chạy openclaw gateway restart rồi openclaw models status để xem model đang dùng. Đổi model sau này bằng openclaw models set steyg/MODEL_ID.

{
  "models": {
    "mode": "merge",
    "providers": {
      "steyg": {
        "baseUrl": "https://steyg.one/api/v1",
        "apiKey": "${STEYG_CODE_API_KEY}",
        "api": "openai-completions",
        "models": [{ "id": "MODEL_ID", "name": "MODEL_ID" }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "steyg/MODEL_ID" }
    }
  }
}

Nối OpenClaw với Zalo

OpenClaw có sẵn kênh Zalo, hiện ở giai đoạn thử nghiệm, dành cho bot tạo trên Zalo Bot Platform (bot.zaloplatforms.com); Zalo Official Account là sản phẩm khác và không thuộc phạm vi kênh này. Tạo bot, lấy token dạng số_id:chuỗi_bí_mật, đặt vào biến ZALO_BOT_TOKEN trong ~/.openclaw/.env hoặc vào mục channels.zalo của file cấu hình.

Mặc định, người lạ nhắn bot chỉ nhận một mã ghép đôi và tin nhắn bị bỏ qua cho tới khi bạn duyệt; mã hết hạn sau 1 giờ. Trong nhóm chat, bot chỉ trả lời khi được nhắc tên.

# Kiểm tra token và trạng thái kênh
openclaw channels status --probe

# Xem và duyệt người nhắn lần đầu
openclaw pairing list zalo
openclaw pairing approve zalo <MÃ>

Chi phí token khi chạy OpenClaw

Mỗi tin nhắn tới trợ lý là một hoặc nhiều request tới model, và mỗi request mang theo ngữ cảnh của phiên: lời dặn hệ thống, mô tả công cụ, lịch sử chat. Tác vụ theo lịch (automations) chạy cả khi bạn không nhắn gì, nên cũng tốn token đều đặn.

• Dùng model đơn giá thấp cho tác vụ theo lịch và việc lặt vặt; để model tầng cao cho việc khó.
• Giới hạn khung giờ chạy của tác vụ theo lịch, tắt tác vụ không còn cần bằng openclaw automations disable.
• Bật vừa đủ kênh và agent: tài liệu OpenClaw lưu ý nhiều agent là nhiều lượt gọi model chạy song song.
• Xem token và chi phí từng request trong usage của dashboard sau vài ngày chạy thật, rồi mới chọn model mặc định.

Đặt ngân sách cho key của trợ lý

Trợ lý chạy nền gọi model cả khi bạn không ngồi trước máy, nên key của nó cần trần chi tiêu rõ ràng. Với STEYG Code, ngân sách trả trước tiêu hết thì request dừng, không bao giờ bị tính quá số tiền đã trả; tài khoản mới có hạn mức dùng thử 10.000đ trong 7 ngày, không cần thẻ.

Tạo key riêng cho OpenClaw thay vì dùng chung key của coding agent, để usage tách bạch và thu hồi được riêng khi cần. Đơn giá từng model có ở bài bảng giá API theo token.

Bảo mật khi cho trợ lý quyền trên máy

OpenClaw làm được gì thì ai điều khiển được nó cũng làm được nấy. Vài nguyên tắc:

• Chạy OpenClaw bằng tài khoản thường trên máy hoặc máy chủ riêng, không chạy bằng tài khoản quản trị.
• Giữ chế độ ghép đôi hoặc danh sách cho phép (allowFrom) cho tin nhắn riêng, không mở bot cho mọi người.
• Tin nhắn, trang web và file trợ lý đọc có thể chứa lệnh ẩn nhằm điều khiển model; đừng cấp công cụ hay quyền mà bạn không muốn người lạ dùng.
• Thu hồi key ngay khi nghi lộ và tạo key mới; key nằm trong ~/.openclaw/.env nên đừng sao lưu file đó lên nơi công khai.

Lỗi hay gặp

Phần lớn lỗi khi nối OpenClaw với một nhà cung cấp tuỳ chỉnh rơi vào vài trường hợp:

• 401: key sai, đã thu hồi, hoặc Gateway chạy nền không thấy STEYG_CODE_API_KEY; đặt biến trong ~/.openclaw/.env rồi chạy openclaw gateway restart.
• Model không có trong danh mục: MODEL_ID gõ sai; đối chiếu với GET /v1/models.
• 404 kèm trang HTML: baseUrl thiếu /v1 ở cuối.
• Lệnh openclaw không tìm thấy sau khi cài bằng npm: thư mục bin toàn cục của npm chưa nằm trong PATH.
• Sửa file cấu hình mà không thấy thay đổi: chạy openclaw doctor để kiểm tra cấu hình rồi khởi động lại Gateway.

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