Chuyển đến nội dung chính

​
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

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch
2

Verify service health

openclaw gateway status
openclaw status
openclaw logs --follow
Trạng thái chuẩn: Runtime: running và RPC probe: ok.
3

Validate channel readiness

openclaw channels status --probe
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)

Thiết lậpThứ tự phân giải
Cổng Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Chế độ bindCLI/override → gateway.bind → loopback

​
Các chế độ hot reload

gateway.reload.modeHành vi
offKhông tải lại cấu hình
hotChỉ áp dụng các thay đổi an toàn cho hot reload
restartKhởi động lại khi có thay đổi yêu cầu reload
hybrid (mặc định)Hot-apply khi an toàn, khởi động lại khi cần thiết

​
Bộ lệnh dành cho operator

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw logs --follow
openclaw doctor

​
Truy cập từ xa

Ưu tiên: Tailscale/VPN. Phương án dự phòng: SSH tunnel. 
ssh -N -L 18789:127.0.0.1:18789 user@host
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. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
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ụ: 
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
Xem: Multiple gateways.

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
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)

openclaw gateway status
openclaw channels status --probe
openclaw health

​
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

Dấu hiệuVấn đề có thể xảy ra
refusing to bind gateway ... without authBind tới địa chỉ không phải loopback mà không có token/password
another gateway instance is already listening / EADDRINUSEXung đột cổng
Gateway start blocked: set gateway.mode=localCấu hình đã được đặt sang chế độ remote
unauthorized trong quá trình kết nốiKhông khớp xác thực giữa client và gateway
Để 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: