Sổ tay vận hành Gateway

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

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

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

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Mô hình thời gian chạy

• Một tiến trình luôn bật cho định tuyến, mặt phẳng điều khiển, 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
  • HTTP APIs, tương thích OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Giao diện điều khiển và hook
• Chế độ bind mặc định: loopback.
• Mặc định yêu cầu xác thực. Thiết lập shared-secret dùng gateway.auth.token / gateway.auth.password (hoặc OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), và 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 này quan trọng:

• Hầu hết tích hợp Open WebUI, LobeChat, và LibreChat dò /v1/models trước.
• Nhiều pipeline RAG và bộ nhớ mong đợi /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à alias ổ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 thông thường của agent được chọn vẫn giữ quyền kiểm soát.

Tất 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 Gateway HTTP API.

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

Dịch vụ gateway đã cài đặt ghi lại --port đã phân giải trong metadata của supervisor. Sau khi thay đổi gateway.port, hãy 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 các origin Giao diện điều khiển 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 quá trình xác thực thời gian chạy diễn ra. Thêm rõ ràng mọi origin trình duyệt từ xa, chẳng hạn URL proxy HTTPS, vào gateway.controlUi.allowedOrigins.

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

Bộ lệnh operator

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

Nhiều gateway (cùng host)

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 cố ý muốn cô lập hoặc có một bot cứu hộ.

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

openclaw gateway status --deepopenclaw gateway probe

Điều cần mong đợi:

• 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 trả lời.
• Nếu điều đó là cố ý, 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.

Checklist 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 19001OPENCLAW_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: SSH tunnel.

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 production.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

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

Đường dẫn nhanh cho profile dev

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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 giao thức (góc nhìn operator)

• Frame đầu tiên của client 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 khám phá thận trọng, không phải bản dump được tạo của mọi helper route có thể gọi.
• Yêu cầu: req(method, params) → res(ok/payload|error).
• Sự kiện phổ biến bao gồm connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, các sự kiện vòng đời pairing/approval, và shutdown.

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

1. Ack chấp nhận ngay lập tức (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 giao thức đầy đủ: Giao thức Gateway.

Kiểm tra vận hành

Liveness

• Mở WS và gửi connect.
• Mong đợi phản hồi hello-ok có ảnh chụp nhanh.

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw 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ự, hãy làm mới trạng thái (health, system-presence) trước khi tiếp tục.

Dấu hiệu lỗi thường gặp

Để xem đầy đủ các bước chẩn đoán, hãy dùng Khắc phục sự cố Gateway.

Đả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 ngầm định 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.
• Tắt một cách êm thấm phát sự kiện shutdown trước khi đóng socket.

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