Cài GoClaw trực tiếp lên Ubuntu từ đầu, không Docker, ai cũng làm được

Hướng dẫn cài GoClaw bare metal trên Ubuntu 24.04+ từ con số không: Go, PostgreSQL + pgvector, build binary, setup wizard, chạy dashboard. Không cần Docker, không cần biết trước gì cả.

Hế nô anh em.

Cuối tuần rồi nên tôi ngồi viết cái bài này, hi vọng giúp được anh em nào đang muốn cài GoClaw mà cứ loay hoay không biết bắt đầu từ đâu.

GoClaw là một AI agent gateway viết bằng Go, open-source, cho phép chạy AI agent kết nối với Telegram, Discord, WhatsApp và nhiều kênh khác. Anh em tham khảo thêm ở repo gốc hoặc docs.

Bài này tôi sẽ hướng dẫn cài thẳng lên máy Ubuntu, không Docker, không cần biết gì trước. Máy mới toanh cũng làm được.

Lưu ý trước: cần Ubuntu 24.04+ vì Ubuntu 22.04 trở xuống ship PostgreSQL 14, mà GoClaw yêu cầu 15+. Nếu đang dùng 22.04 thì nâng lên trước nhé.

Bước 1: Cập nhật hệ thống

Máy mới thì bước đầu tiên bao giờ cũng là update cho lành:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl wget build-essential

Bước 2: Cài Go 1.26+

Đừng cài Go bằng apt install golang, package đó thường bị outdated và sẽ gây lỗi "module requires Go >= 1.26" về sau. Cài từ tarball chính thức cho chắc:

cd /tmp
wget https://go.dev/dl/go1.26.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.26.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
go version

Nếu thấy go version go1.26.0 linux/amd64 là ổn rồi.

Bước 3: Cài PostgreSQL 17 + pgvector

GoClaw cần PostgreSQL 15+ với extension pgvector để làm vector similarity search cho memory và skills. Ubuntu 24.04 mặc định có PostgreSQL 17 nên cứ cài thẳng:

sudo apt install -y postgresql postgresql-common
# Kiểm tra version đang dùng
pg_config --version
# Cài pgvector (thay 17 nếu version của anh em khác)
sudo apt install -y postgresql-17-pgvector
# Tạo database và bật extension
sudo -u postgres createdb goclaw
sudo -u postgres psql -d goclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
# Verify
sudo -u postgres psql -d goclaw -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';"

Nếu thấy vector | 0.x.x là pgvector đã cài đúng rồi.

Giờ tạo user riêng cho GoClaw cho đỡ phải chạy bằng user postgres:

sudo -u postgres psql -c "CREATE USER goclaw WITH PASSWORD 'goclaw';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE goclaw TO goclaw;"
sudo -u postgres psql -d goclaw -c "GRANT ALL ON SCHEMA public TO goclaw;"

Bước 4: Cài Node.js + pnpm (cho dashboard)

Dashboard của GoClaw là một app React riêng, cần Node.js để chạy:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g pnpm
node --version   # v22.x.x
pnpm --version

Bước 5: Clone repo và build

git clone https://github.com/nextlevelbuilder/goclaw.git
cd goclaw
go build -o goclaw .
./goclaw version

Binary được compile thành một file duy nhất khoảng 25MB, không cần cài thêm gì nữa. Khởi động dưới 1 giây, chạy trên VPS $5 cũng được.

Bước 6: Chạy setup wizard

Trước khi chạy wizard, set biến môi trường để wizard biết kết nối vào database nào:

export GOCLAW_POSTGRES_DSN='postgres://goclaw:goclaw@localhost:5432/goclaw?sslmode=disable'
./goclaw onboard

Wizard sẽ hỏi từng bước:

Thông tin kết nối database (nhấn Enter nếu đã set DSN ở trên)
Test kết nối tự động
Tạo toàn bộ tables (tự động)
Sinh GOCLAW_GATEWAY_TOKEN và GOCLAW_ENCRYPTION_KEY
Ghi hết vào file .env.local

Sau khi wizard xong, lưu lại gateway token để dùng đăng nhập dashboard:

cat .env.local | grep GOCLAW_GATEWAY_TOKEN

Bước 7: Khởi động gateway

source .env.local && ./goclaw

Kiểm tra gateway đang chạy:

curl http://localhost:18790/health
# Expected: {"status":"ok"}

Nếu muốn chạy ngầm mà không mất khi đóng terminal, dùng tmux:

sudo apt install -y tmux
tmux new -s goclaw
source .env.local && ./goclaw
# Ctrl+B rồi D để detach, gateway vẫn chạy ngầm

Bước 8: Cài và chạy web dashboard

Dashboard của GoClaw là một service frontend riêng, chạy độc lập với gateway. Có 2 cách tùy mục đích sử dụng.

Cách 1: Dev mode (để test nhanh, không bền vững)

cd ~/goclaw/ui/web
cp .env.example .env
pnpm install
pnpm dev

Dashboard lên tại http://localhost:5173. Cách này sẽ mất khi đóng terminal.

Cách 2: Build production + serve (khuyến nghị)

Build ra static files rồi serve bằng serve, phù hợp chạy lâu dài trên server:

# Cài serve globally
npm install -g serve
# Build production
cd ~/goclaw/ui/web
cp .env.example .env
pnpm install
pnpm build
# Chạy trên port 3000
serve -s dist -l 3000

Dùng tmux để giữ process chạy ngầm:

tmux new -s goclaw-ui
serve -s dist -l 3000
# Ctrl+B rồi D để detach

Cách 3: Systemd service (production, tự restart khi reboot)

sudo nano /etc/systemd/system/goclaw-ui.service

Nội dung file, nhớ thay YOUR_USERNAME:

[Unit]
Description=GoClaw Web Dashboard
After=network.target
[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME/goclaw/ui/web
Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/usr/bin/node /usr/bin/serve -s dist -l 3000
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable goclaw-ui
sudo systemctl start goclaw-ui
sudo systemctl status goclaw-ui

Sau khi service lên, mở trình duyệt vào http://localhost:3000, đăng nhập với:

User ID: system
Gateway Token: lấy từ cat .env.local | grep GOCLAW_GATEWAY_TOKEN

Lần đầu đăng nhập sẽ có Setup Wizard hướng dẫn thêm LLM provider (Anthropic, OpenAI, Groq, DeepSeek,...), tạo agent đầu tiên và kết nối kênh nhắn tin nếu muốn.

(Tùy chọn) Cài làm systemd service

Nếu muốn gateway tự khởi động khi máy reboot, tạo systemd service:

sudo nano /etc/systemd/system/goclaw.service

Nội dung file, nhớ thay YOUR_USERNAME bằng tên user thực:

[Unit]
Description=GoClaw Gateway
After=network.target postgresql.service
[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME/goclaw
EnvironmentFile=/home/YOUR_USERNAME/goclaw/.env.local
ExecStart=/home/YOUR_USERNAME/goclaw/goclaw
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target

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

Cập nhật sau này

cd goclaw
git pull
go build -o goclaw .
# Nếu dùng systemd
sudo systemctl restart goclaw
# GoClaw tự chạy database migration khi khởi động lại

Một số lỗi hay gặp

Tổng hợp mấy cái lỗi tôi từng thấy khi cài, phòng khi anh em gặp:

go: module requires Go >= 1.26: cài Go sai cách, chạy lại bước 2 bằng tarball
pgvector extension not found: chạy lại sudo apt install postgresql-17-pgvector rồi CREATE EXTENSION vector;
encryption key not set: chạy lại ./goclaw onboard
connection refused port 5432: PostgreSQL chưa chạy, sudo systemctl status postgresql để kiểm tra
pnpm: command not found: chạy lại npm install -g pnpm

Tổng cộng từ máy mới đến lúc có gateway chạy tầm 20-30 phút nếu đường truyền ổn. Phần lớn thời gian là chờ apt và go build.

Anh em cài xong có gì thắc mắc cứ comment bên dưới hoặc vào GitHub repo của GoClaw hỏi trực tiếp nhé. Chúc các bạn cài suôn sẻ :v

8 min read

Mar 27, 2026

By Xuân Dũng Hồ