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

​
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

openclaw gateway --port 18789
# debug/trace được phản chiếu tới stdio
openclaw gateway --port 18789 --verbose
# buộc dừng listener trên cổng đã chọn, sau đó khởi động
openclaw gateway --force
2

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

openclaw gateway status
openclaw status
openclaw logs --follow
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

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

Cài đặtThứ tự giải quyết
Cổng Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Chế độ bindCLI/ghi đè → gateway.bind → loopback

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

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 nóng
restartKhởi động lại khi cần tải lại
hybrid (mặc định)Áp dụng nóng khi an toàn, khởi động lại khi cần

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

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

​
Truy cập từ xa

Ưu tiên: Tailscale/VPN. Dự phòng: SSH tunnel. 
ssh -N -L 18789:127.0.0.1:18789 user@host
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. 
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 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ụ: 
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 thêm: Multiple gateways.

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

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á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

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 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ữ kýVấn đề có thể xảy ra
refusing to bind gateway ... without authKhông bind 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 đặt ở chế độ remote
unauthorized during connectKhông khớp xác thực giữa client và gateway
Để 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:
Last modified on March 22, 2026