Sổ tay vận hành Gateway

Sử dụng trang này cho khởi động ngày đầu và vận hành ngày sau của dịch vụ Gateway.

# Khởi động cục bộ trong 5 phút

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# Mô hình runtime

• Một tiến trình luôn bật cho định tuyến, control plane và kết nối kênh.
• Một cổng ghép kênh duy nhất cho:
  • Điều khiển/RPC WebSocket
  • API HTTP, tương thích OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Control UI và hook
• Chế độ bind mặc định: loopback.
• Xác thực được yêu cầu theo mặc định. Thiết lập dùng bí mật dùng chung sử dụng gateway.auth.token / gateway.auth.password (hoặc OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), và các thiết lập reverse proxy không phải loopback có thể dùng gateway.auth.mode: "trusted-proxy".

# Endpoint tương thích OpenAI

Bề mặt tương thích có đòn bẩy cao nhất của OpenClaw hiện là:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Vì sao tập hợp này quan trọng:

• Hầu hết tích hợp Open WebUI, LobeChat và LibreChat thăm dò /v1/models trước.
• Nhiều pipeline RAG và bộ nhớ kỳ vọng /v1/embeddings.
• Các client gốc agent ngày càng ưu tiên /v1/responses.

Ghi chú lập kế hoạch:

• /v1/models ưu tiên agent: nó trả về openclaw, openclaw/default, và openclaw/<agentId>.
• openclaw/default là bí danh ổn định luôn ánh xạ tới agent mặc định đã cấu hình.
• Dùng x-openclaw-model khi bạn muốn ghi đè provider/model backend; nếu không, thiết lập model và embedding bình thường của agent đã chọn vẫn nắm quyền điều khiển.

Tất cả các endpoint này chạy trên cổng Gateway chính và dùng cùng ranh giới xác thực operator đáng tin cậy như phần còn lại của API HTTP Gateway.

# Thứ tự ưu tiên cổng và bind

Các dịch vụ gateway đã cài đặt ghi lại --port đã phân giải trong siêu dữ liệu supervisor. Sau khi thay đổi gateway.port, chạy openclaw doctor --fix hoặc openclaw gateway install --force để launchd/systemd/schtasks khởi động tiến trình trên cổng mới.

Khởi động Gateway dùng cùng cổng và bind hiệu dụng khi nó gieo origin Control UI cục bộ cho bind không phải loopback. Ví dụ, --bind lan --port 3000 gieo http://localhost:3000 và http://127.0.0.1:3000 trước khi xác thực runtime chạy. Thêm mọi origin trình duyệt từ xa, chẳng hạn URL proxy HTTPS, vào gateway.controlUi.allowedOrigins một cách tường minh.

# Chế độ tải lại nóng

# Bộ lệnh operator

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

gateway status --deep dùng để phát hiện dịch vụ bổ sung (LaunchDaemons/đơn vị hệ thống systemd/schtasks), không phải là phép thăm dò tình trạng RPC sâu hơn.

# Nhiều gateway (cùng máy chủ)

Hầu hết cài đặt nên chạy một gateway trên mỗi máy. Một gateway duy nhất có thể lưu trữ nhiều agent và kênh.

Bạn chỉ cần nhiều gateway khi chủ đích muốn cô lập hoặc có bot cứu hộ.

Các kiểm tra hữu ích:

openclaw gateway status --deep
openclaw gateway probe

Điều cần kỳ vọng:

• gateway status --deep có thể báo cáo Other gateway-like services detected (best effort) và in gợi ý dọn dẹp khi các cài đặt launchd/systemd/schtasks cũ vẫn còn.
• gateway probe có thể cảnh báo về multiple reachable gateways khi nhiều hơn một target phản hồi.
• Nếu đó là chủ đích, hãy cô lập cổng, cấu hình/trạng thái, và thư mục gốc workspace cho từng gateway.

Danh sách kiểm tra cho mỗi phiên bản:

• gateway.port duy nhất
• OPENCLAW_CONFIG_PATH duy nhất
• OPENCLAW_STATE_DIR duy nhất
• agents.defaults.workspace duy nhất

Ví dụ:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Thiết lập chi tiết: /gateway/multiple-gateways.

# Truy cập từ xa

Ưu tiên: Tailscale/VPN. Dự phòng: đường hầm SSH.

ssh -N -L 18789:127.0.0.1:18789 user@host

Sau đó kết nối client cục bộ tới ws://127.0.0.1:18789.

Xem: Gateway từ xa, Xác thực, Tailscale.

# Giám sát và vòng đời dịch vụ

Dùng các lần chạy được giám sát để có độ tin cậy giống môi trường production.

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

# Lối nhanh cho hồ sơ dev

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Mặc định bao gồm trạng thái/cấu hình cô lập và cổng gateway cơ sở 19001.

# Tham chiếu nhanh protocol (góc nhìn operator)

• Khung client đầu tiên phải là connect.
• Gateway trả về ảnh chụp nhanh hello-ok (presence, health, stateVersion, uptimeMs, giới hạn/chính sách).
• hello-ok.features.methods / events là danh sách phát hiện thận trọng, không phải bản xuất được tạo của mọi tuyến helper có thể gọi.
• Yêu cầu: req(method, params) → res(ok/payload|error).
• Các sự kiện phổ biến gồm connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, các sự kiện vòng đời ghép cặp/phê duyệt, và shutdown.

Các lần chạy agent có hai giai đoạn:

1. Ack chấp nhận tức thì (status:"accepted")
2. Phản hồi hoàn tất cuối cùng (status:"ok"|"error"), với các sự kiện agent được stream ở giữa.

Xem tài liệu protocol đầy đủ: Protocol Gateway.

# Kiểm tra vận hành

# Liveness

• Mở WS và gửi connect.
• Kỳ vọng phản hồi hello-ok kèm ảnh chụp nhanh.

# Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

# Khôi phục khoảng trống

Sự kiện không được phát lại. Khi có khoảng trống trình tự, làm mới trạng thái (health, system-presence) trước khi tiếp tục.

# Chữ ký lỗi phổ biến

Để có đầy đủ các chuỗi chẩn đoán, dùng Khắc phục sự cố Gateway.

# Bảo đảm an toàn

• Máy khách giao thức Gateway báo lỗi ngay khi Gateway không khả dụng (không có dự phòng ngầm sang kênh trực tiếp).
• Các khung đầu tiên không hợp lệ/không phải kết nối bị từ chối và đóng.
• Tắt máy nhẹ nhàng phát sự kiện shutdown trước khi đóng ổ cắm.

Liên quan:

• Khắc phục sự cố
• Tiến trình nền
• Cấu hình
• Sức khỏe
• Doctor
• Xác thực

# Liên quan

• Cấu hình
• Khắc phục sự cố Gateway
• Truy cập từ xa
• Quản lý bí mật