Skip to main content

​
Runbook dịch vụ Gateway

Cập nhật lần cuối: 2025-12-09

Deep troubleshooting

Chẩn đoán theo triệu chứng trước, kèm theo các chuỗi lệnh chính xác và dấu hiệu log.

Configuration

Hướng dẫn thiết lập theo tác vụ + tài liệu tham chiếu cấu hình đầy đủ.

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

1

Start the Gateway

2

Verify service health

Trạng thái chuẩn: Runtime: running và RPC probe: ok.
3

Validate channel readiness

Cơ chế tải lại cấu hình Gateway theo dõi đường dẫn tệp cấu hình đang hoạt động (được phân giải từ mặc định hồ sơ/trạng thái, hoặc OPENCLAW_CONFIG_PATH khi được thiết lập). Chế độ mặc định là gateway.reload.mode="hybrid".

​
Mô hình runtime

  • Một tiến trình luôn hoạt động để định tuyến, control plane và kết nối kênh.
  • Một cổng được ghép kênh duy nhất cho:
    • WebSocket control/RPC
    • HTTP APIs (tương thích OpenAI, Responses, gọi tools)
    • Control UI và hooks
  • Chế độ bind mặc định: loopback.
  • Yêu cầu xác thực theo mặc định (gateway.auth.token / gateway.auth.password, hoặc OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

​
Profile dev (--dev)

​
Các chế độ hot reload

​
Bộ lệnh dành cho operator

​
Truy cập từ xa

Ưu tiên: Tailscale/VPN. Phương án dự phòng: SSH tunnel.
Cài đặt dịch vụ theo profile:
Nếu cấu hình xác thực gateway được bật, client vẫn phải gửi thông tin xác thực (token/password) ngay cả khi kết nối qua SSH tunnel.
Ví dụ:

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

Sử dụng chế độ chạy có giám sát để đạt độ tin cậy tương tự môi trường production.
Nhãn LaunchAgent là ai.openclaw.gateway (mặc định) hoặc ai.openclaw.<profile> (profile được đặt tên). openclaw doctor kiểm tra và sửa các sai lệch cấu hình dịch vụ.

​
Nhiều gateway trên một máy chủ

Hầu hết các thiết lập chỉ nên chạy một Gateway. Chỉ sử dụng nhiều gateway khi cần cô lập/dự phòng nghiêm ngặt (ví dụ: profile cứu hộ). Danh sách kiểm tra cho mỗi instance:
  • 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ụ:
Xem: Multiple gateways.

​
Quản lý dịch vụ Gateway (CLI)

Mặc định bao gồm state/config được cô lập và cổng gateway cơ sở 19001.

​
Tham khảo nhanh giao thức (góc nhìn vận hành)

  • gateway status thăm dò RPC của Gateway theo mặc định bằng cổng/cấu hình đã resolve của dịch vụ (ghi đè bằng --url).
  • gateway status --deep thêm quét cấp hệ thống (LaunchDaemons/system units).
  • gateway status --no-probe bỏ qua thăm dò RPC (hữu ích khi mạng bị down).
  • gateway status --json ổn định cho script.
Ứng dụng mac đóng gói:
  1. Phản hồi xác nhận ngay lập tức (status:"accepted")
  2. Để dừng sạch, dùng openclaw gateway stop (hoặc launchctl bootout gui/$UID/bot.molt.gateway).
Xem tài liệu giao thức đầy đủ: Gateway Protocol.

​
Kiểm tra vận hành

​
Kiểm tra hoạt động (Liveness)

  • Mở WS và gửi connect.
  • Mong đợi phản hồi hello-ok kèm snapshot.

​
Kiểm tra sẵn sàng (Readiness)

​
Khôi phục khi mất đồng bộ (Gap recovery)

Sự kiện không được phát lại. Khi phát hiện thiếu sequence, làm mới trạng thái (health, system-presence) trước khi tiếp tục.

​
Các dấu hiệu lỗi phổ biến

Để chẩn đoán đầy đủ theo từng bước, xem Gateway Troubleshooting.

​
Windows (WSL2)

  • Các client sử dụng giao thức Gateway sẽ thất bại ngay khi Gateway không khả dụng (không có cơ chế tự động chuyển sang kênh trực tiếp).
  • Các frame đầu tiên không hợp lệ/không phải kết nối sẽ bị từ chối và đóng lại.
  • Quá trình tắt mềm sẽ phát sự kiện shutdown trước khi đóng socket.
Liên quan: