OpenClaw đã phát triển nhanh chóng: từ sự hỗn loạn trong việc đặt tên Moltbot thành Clawdbot đến một định danh ổn định và cộng đồng ngày càng chấp nhận rộng rãi. Nếu bạn ở đây, có lẽ bạn muốn một kết quả thực tế: một node OpenClaw đáng tin cậy chạy trên Raspberry Pi mà bạn có thể tin tưởng sử dụng tại nhà hoặc ở biên.

Hướng dẫn này dành cho những nhà phát triển kỹ thuật chuyên sâu. Bạn sẽ thiết lập OpenClaw với:

các phụ thuộc hệ thống có thể tái tạo,
cô lập dịch vụ,
kiểm tra sức khỏe dựa trên tín hiệu "heartbeat" (ưu tiên các kiểm tra đơn giản trước),
gọi mô hình có chọn lọc,
các mẫu sandboxing bảo mật tùy chọn,
và khả năng quan sát cấp độ API.

Trong quá trình thực hiện, tôi sẽ chỉ ra nơi Apidog giúp ích: xác thực các endpoint của OpenClaw, xây dựng các bài kiểm tra hồi quy và tài liệu hóa bề mặt API cục bộ của bạn để nhóm sử dụng.

button

1) Quyết định kiến trúc trước khi cài đặt

Trước khi chạm vào apt, hãy quyết định cách Pi của bạn sẽ chạy các quy trình suy luận.

Tùy chọn A: Pi đóng vai trò điều phối, mô hình được chuyển giao (offload)

Tốt nhất cho Raspberry Pi 4/5 với RAM hạn chế.

OpenClaw chạy điều phối, lập lịch, plugin và tín hiệu heartbeat cục bộ.
Suy luận LLM nặng được định tuyến đến các nhà cung cấp từ xa hoặc một máy chủ mô hình LAN.
Giảm tải nhiệt, thời gian hoạt động tốt hơn.

Tùy chọn B: Pi chỉ dành cho các mô hình cục bộ nhẹ

Tốt cho quyền riêng tư nghiêm ngặt và các tác vụ ngoại tuyến.

Sử dụng các mô hình nhỏ gọn (đã lượng tử hóa, cửa sổ ngữ cảnh nhỏ).
Hạn chế các pipeline nặng và chuỗi dài.
Chấp nhận đánh đổi về độ trễ.

Tùy chọn C: Định tuyến lai

Kiến trúc thực tế nhất.

Ưu tiên các kiểm tra xác định đơn giản trước.
Chỉ chuyển sang gọi mô hình khi cần thiết.
Định tuyến các tác vụ rủi ro thấp cục bộ, các tác vụ phức tạp cao từ xa.

Mẫu "kiểm tra đơn giản trước, chỉ gọi mô hình khi cần" này đã trở thành một chiến lược độ tin cậy cốt lõi của OpenClaw vì nó kiểm soát chi phí, áp lực nhiệt và các đợt tăng độ trễ.

2) Phần cứng và Hệ điều hành cơ bản

Phần cứng đề xuất

Ưu tiên Raspberry Pi 5 (8GB)
Raspberry Pi 4 (4GB+) hoạt động tốt cho các tác vụ nhẹ hơn
NVMe hoặc SSD chất lượng cao thay vì microSD để tăng độ bền
Nguồn điện ổn định và làm mát chủ động

Hệ điều hành

Sử dụng Raspberry Pi OS Lite (64-bit) hoặc Ubuntu Server 24.04 cho ARM64.

Sau đó cập nhật:

bash sudo apt update && sudo apt upgrade -y sudo reboot

Đặt tên máy chủ và đồng bộ hóa thời gian (quan trọng cho nhật ký và thời hạn của token):

bash sudo hostnamectl set-hostname openclaw-pi sudo timedatectl set-ntp true

3) Cài đặt các phụ thuộc thời gian chạy

Các stack OpenClaw thường sử dụng worker Python và/hoặc Node tùy thuộc vào plugin. Cài đặt cả hai để duy trì khả năng tương thích với các module đang phát triển.

sudo apt install -y   git curl wget jq build-essential pkg-config   python3 python3-venv python3-pip   nodejs npm   redis-server sqlite3

Kiểm tra phiên bản:

bash python3 --version node --version npm --version redis-server --version

Tại sao lại dùng Redis + SQLite?

Redis: hàng đợi/tín hiệu trạng thái độ trễ thấp.
SQLite: lưu trữ cục bộ nhẹ cho các thiết lập node đơn.

Đối với thiết lập đa node sau này, hãy di chuyển khả năng lưu trữ sang Postgres.

4) Tạo một người dùng dịch vụ chuyên dụng

Tránh chạy các tác nhân dưới quyền pi hoặc root.

sudo useradd -m -s /bin/bash openclaw sudo usermod -aG sudo openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw

Chuyển đổi người dùng:

bash sudo su - openclaw cd /opt/openclaw

5) Clone và cấu hình OpenClaw

bash git clone https://github.com//.git app cd app

Thay thế bằng đường dẫn kho lưu trữ chính thức hiện tại từ trang dự án OpenClaw.

Tạo môi trường Python:

python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt

Nếu có dịch vụ Node:

npm ci

Sao chép mẫu môi trường:

cp .env.example .env

Cấu hình .env điển hình:

env OPENCLAW_HOST=0.0.0.0 OPENCLAW_PORT=8080 OPENCLAW_LOG_LEVEL=info
STATE_BACKEND=redis REDIS_URL=redis://127.0.0.1:6379 DB_URL=sqlite:////opt/openclaw/app/data/openclaw.db
MODEL_ROUTER=hybrid LOCAL_MODEL_ENABLED=true REMOTE_MODEL_ENABLED=true REMOTE_MODEL_API_KEY=your_key_here
HEARTBEAT_INTERVAL_SEC=15 HEARTBEAT_TIMEOUT_SEC=5 CHEAP_CHECKS_ENABLED=true
SANDBOX_MODE=on SANDBOX_PROVIDER=process

Sử dụng chmod 600 .env để bảo vệ các bí mật.

6) Thêm dịch vụ systemd để tăng độ tin cậy

Tạo tệp /etc/systemd/system/openclaw.service:

ini [Unit] Description=OpenClaw Agent Service After=network-online.target redis.service Wants=network-online.target
[Service] Type=simple User=openclaw WorkingDirectory=/opt/openclaw/app Environment="PYTHONUNBUFFERED=1" ExecStart=/opt/openclaw/app/.venv/bin/python -m openclaw.server Restart=always RestartSec=3 TimeoutStartSec=30 TimeoutStopSec=20

Tăng cường bảo mật cơ bản

NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true ReadWritePaths=/opt/openclaw/app/data /opt/openclaw/app/logs

[Install] WantedBy=multi-user.target

Bật và khởi động:

sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw

Xem nhật ký:

bash journalctl -u openclaw -f

7) Triển khai chiến lược heartbeat (ưu tiên kiểm tra đơn giản trước)

Một bài học cộng đồng thường xuyên: đừng lãng phí token của mô hình để phát hiện các lỗi rõ ràng.

Heartbeat phân lớp được đề xuất

Kiểm tra tiến trình L0: dịch vụ đang hoạt động, cổng mở.
Kiểm tra phụ thuộc L1: Redis/DB có thể truy cập, độ trễ hàng đợi chấp nhận được.
Kiểm tra tác vụ xác định L2: chạy script xác thực tĩnh.
Thăm dò dựa trên mô hình L3: chỉ khi các kiểm tra trước đó đã vượt qua nhưng độ tin cậy thấp.

Ví dụ cấu hình giả:

yaml heartbeat: interval_sec: 15 timeout_sec: 5 stages: - name: process type: tcp target: 127.0.0.1:8080 - name: deps type: internal checks: [redis_ping, db_read] - name: deterministic type: task command: "python scripts/selfcheck.py" - name: model_probe type: llm enabled_on: degraded_only

Mẫu này giảm chi phí và cảnh báo sai, đồng thời bảo vệ thời gian hoạt động trên phần cứng bị hạn chế.

8) Thực thi an toàn với các giới hạn sandbox

Nếu OpenClaw chạy các công cụ (shell, trình duyệt, ghi tệp), hãy cô lập quá trình thực thi.

Mức cơ bản tối thiểu trên Pi:

chạy các công cụ dưới quyền người dùng không đặc quyền,
từ chối ghi vào hệ thống tệp diện rộng,
danh sách trắng các thư mục,
đặt thời gian chờ của tiến trình con và giới hạn bộ nhớ.

Nếu stack của bạn hỗ trợ các sandbox được tăng cường (tương tự như các mô hình sandbox của secure-agent), hãy sử dụng chúng cho các lời gọi công cụ không đáng tin cậy.

Các biện pháp bảo vệ thực tế:

env TOOL_EXEC_TIMEOUT_MS=12000 TOOL_MAX_STDOUT_KB=256 TOOL_ALLOWED_PATHS=/opt/openclaw/app/workdir TOOL_BLOCK_NETWORK_BY_DEFAULT=true

Đối với các công cụ có khả năng mạng, chỉ cho phép danh sách máy chủ được chỉ định rõ ràng.

9) Xác thực API OpenClaw với Apidog

Khi OpenClaw đã hoạt động, hãy xem nó như bất kỳ sản phẩm API nào: định nghĩa các hợp đồng, kiểm tra hành vi và theo dõi các lỗi hồi quy.

Tại sao lại là Apidog ở đây

Bạn có thể sử dụng Apidog để:

nhập hoặc thiết kế đặc tả OpenAPI của OpenClaw,
chạy kiểm thử tự động đối với các endpoint Pi cục bộ,
tạo các xác nhận trực quan cho các payload heartbeat,
giả lập các phụ thuộc downstream để gỡ lỗi ngoại tuyến,
xuất bản tài liệu tương tác cho đồng đội.

Ví dụ kiểm tra endpoint sức khỏe

Giả sử endpoint:

GET /healthz

Phản hồi mong đợi:

{ "status": "ok", "checks": { "redis": "ok", "db": "ok", "queue_lag_ms": 12 } }

Trong Apidog, tạo một kịch bản kiểm thử:

Khẳng định HTTP 200.
Khẳng định status == ok.
Khẳng định checks.queue_lag_ms < 100.
Thêm một môi trường tiêu cực trong đó Redis bị dừng; mong đợi trạng thái suy giảm.

Điều này biến "có vẻ ổn" thành các cổng chất lượng API có thể lặp lại.

10) Tối ưu hóa hiệu suất trên Raspberry Pi

Kiểm soát CPU và nhiệt độ

Giám sát:

bash vcgencmd measure_temp uptime top

Nếu nhiệt độ vượt quá giới hạn duy trì an toàn, độ trễ suy luận sẽ tăng vọt do quá trình điều tiết (throttling).

Áp lực bộ nhớ

Bật zram hoặc swap vừa phải nếu cần, nhưng tránh các tác vụ nặng về swap đối với các luồng thời gian thực.

Hàng đợi và đồng thời

Bắt đầu thận trọng:

env WORKER_CONCURRENCY=1 MAX_INFLIGHT_TASKS=4

Sau đó tăng lên sau khi quan sát độ trễ p95 và tỷ lệ lỗi.

Xoay vòng nhật ký (Log rotation)

Ngăn ngừa mòn thẻ SD/SSD:

bash sudo apt install -y logrotate

Thêm các quy tắc xoay vòng cho /opt/openclaw/app/logs/*.log.

11) Sổ tay khắc phục sự cố

Dịch vụ bị lỗi liên tục mỗi vài giây

Kiểm tra các khóa môi trường không đúng hoặc thiếu khóa API.
Chạy ứng dụng thủ công bên trong venv để xem toàn bộ thông báo lỗi.

bash sudo su - openclaw cd /opt/openclaw/app source .venv/bin/activate python -m openclaw.server

Kết nối Redis bị từ chối

bash sudo systemctl status redis redis-cli ping

Nếu không phải PONG, hãy khắc phục Redis trước khi gỡ lỗi OpenClaw.

Độ trễ cao sau vài phút

Có thể là do điều tiết nhiệt độ (thermal throttling) hoặc áp lực bộ nhớ.

giảm ngữ cảnh mô hình,
giảm đồng thời worker,
chuyển các lệnh gọi nặng sang mô hình từ xa.

Heartbeat vẫn hoạt động nhưng tác vụ thất bại

Các kiểm tra của bạn quá nông. Hãy thêm các thăm dò tác vụ xác định mô phỏng các quy trình làm việc thực tế (đọc tệp, phân tích cú pháp, tóm tắt, mã hóa phản hồi).

12) Danh sách kiểm tra tăng cường bảo mật cho việc sử dụng ở biên gần môi trường sản xuất

Người dùng chuyên dụng (openclaw), không chạy với quyền root
Chính sách khởi động lại systemd và giới hạn tài nguyên
Các bí mật trong .env với quyền hạn nghiêm ngặt
Chấm dứt TLS thông qua reverse proxy (Caddy/Nginx)
Danh sách trắng tường lửa (chỉ LAN/VPN)
Các tầng heartbeat với sự leo thang thăm dò mô hình
Hạn chế sandbox công cụ
Kiểm tra hợp đồng API trong Apidog
Chạy kiểm thử tự động trong CI/CD cho các thay đổi cấu hình

Nếu bạn hợp tác giữa các nhóm backend, QA và frontend, hãy đặt đặc tả API OpenClaw vào một không gian làm việc Apidog được chia sẻ. Bạn sẽ giữ cho các thay đổi schema, kiểm thử, mock và tài liệu được đồng bộ hóa thay vì phân tán trên các công cụ khác nhau.

13) Ví dụ về bản đồ endpoint bạn nên công khai

Giữ bề mặt nhỏ và rõ ràng:

GET /healthz — kiểm tra sức khỏe cơ bản
GET /readyz — sự sẵn sàng của các phụ thuộc
GET /metrics — các chỉ số tương thích Prometheus
POST /v1/tasks — gửi tác vụ
GET /v1/tasks/{id} — kiểm tra trạng thái
POST /v1/chat/completions — endpoint tương thích tùy chọn

Tài liệu hóa những điều này trong OpenAPI. Sau đó, sử dụng quy trình làm việc ưu tiên schema của Apidog để đảm bảo tính nhất quán của phản hồi và tránh làm hỏng các consumer khi các module OpenClaw phát triển.

Kết luận

Chạy OpenClaw trên Raspberry Pi hoàn toàn khả thi khi bạn thiết kế có tính đến các ràng buộc:

điều phối cục bộ, suy luận có chọn lọc,
sử dụng các lớp heartbeat với các kiểm tra đơn giản trước,
thực thi công cụ trong sandbox,
coi tác nhân cục bộ của bạn như một dịch vụ API thực sự với kiểm thử và tài liệu.

Sự kết hợp đó mang lại cho bạn một node có giá cả phải chăng, riêng tư và đủ ổn định cho tự động hóa hàng ngày.

Nếu bạn muốn một bước tiếp theo rõ ràng, hãy nhập các endpoint OpenClaw của bạn vào Apidog và tạo ba bài kiểm thử tự động ngay hôm nay: healthz, readyz và một quy trình tác vụ đầu cuối. Bạn sẽ phát hiện sớm các lỗi hồi quy và giữ cho triển khai Pi của bạn đáng tin cậy khi stack tác nhân của bạn phát triển.

button