Skip to main content

​
Hướng dẫn Gateway

Sử dụng trang này cho việc khởi động ngày đầu tiên và vận hành ngày thứ hai của dịch vụ Gateway.

Khắc phục sự cố chuyên sâu

Chẩn đoán theo triệu chứng với các lệnh và chữ ký log chính xác.

Cấu hình

Hướng dẫn thiết lập theo nhiệm vụ + tham khảo cấu hình đầy đủ.

Quản lý bí mật

Hợp đồng SecretRef, hành vi snapshot runtime, và các thao tác di chuyển/tải lại.

Hợp đồng kế hoạch bí mật

Quy tắc mục tiêu/đường dẫn secrets apply chính xác và hành vi auth-profile chỉ tham chiếu.

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

1

Khởi động Gateway

2

Kiểm tra sức khỏe dịch vụ

Trạng thái khỏe mạnh: Runtime: running và RPC probe: ok.
3

Xác nhận kênh sẵn sàng

Tải lại cấu hình Gateway theo dõi đường dẫn file cấu hình đang hoạt động (được giải quyết từ mặc định profile/state, 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 quá trình luôn hoạt động cho việc định tuyến, mặt phẳng điều khiển và kết nối kênh.
  • Một cổng đa kênh cho:
    • WebSocket điều khiển/RPC
    • HTTP APIs (tương thích OpenAI, Responses, công cụ gọi)
    • Giao diện điều khiển và hooks
  • Chế độ bind mặc định: loopback.
  • Yêu cầu xác thực mặc định (gateway.auth.token / gateway.auth.password, hoặc OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

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

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

​
Bộ lệnh cho người vận hành

​
Truy cập từ xa

Ưu tiên: Tailscale/VPN. Dự phòng: SSH tunnel.
Sau đó kết nối client tới ws://127.0.0.1:18789 cục bộ.
Nếu cấu hình xác thực gateway, client vẫn phải gửi xác thực (token/password) ngay cả khi qua SSH tunnels.
Xem thêm: Remote Gateway, Authentication, Tailscale.

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

Sử dụng chạy giám sát để đạt độ tin cậy như sản xuất.
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 chữa cấu hình dịch vụ bị lệch.

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

Hầu hết các thiết lập nên chạy một Gateway. Chỉ sử dụng nhiều khi cần cách ly/độ dự phòng nghiêm ngặt (ví dụ một 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 thêm: Multiple gateways.

​
Đường dẫn nhanh cho profile phát triển

Mặc định bao gồm trạng thái/cấu hình cách ly và cổng gateway cơ bản 19001.

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

  • Khung đầu tiên của client phải là connect.
  • Gateway trả về snapshot hello-ok (presence, health, stateVersion, uptimeMs, giới hạn/chính sách).
  • Yêu cầu: req(method, params) → res(ok/payload|error).
  • Sự kiện phổ biến: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
Chạy agent gồm hai giai đoạn:
  1. Xác nhận chấp nhận ngay lập tức (status:"accepted")
  2. Phản hồi hoàn thành cuối cùng (status:"ok"|"error"), với các sự kiện agent được truyền giữa.
Xem tài liệu giao thức đầy đủ: Gateway Protocol.

​
Kiểm tra hoạt động

​
Tính sống

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

​
Tính sẵn sàng

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

Sự kiện không được phát lại. Khi có khoảng trống trong chuỗi, 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

Để chẩn đoán đầy đủ, sử dụng Gateway Troubleshooting.

​
Đảm bảo an toàn

  • Client giao thức Gateway thất bại nhanh khi Gateway không khả dụng (không có fallback kênh trực tiếp ngầm định).
  • Các khung đầu tiên không hợp lệ/không phải connect bị từ chối và đóng.
  • Tắt máy nhẹ nhàng phát ra sự kiện shutdown trước khi đóng socket.
Liên quan:
Lần sửa đổi cuối 22 tháng 3, 2026