Sổ tay vận hành Gateway

Dùng trang này cho khởi động ngày đầu và vận hành ngày thứ hai 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 runtime

• 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
  • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Các tuyến HTTP của Plugin, chẳng hạn như /api/v1/admin/rpc tùy chọn
  • Control UI và hook
• Chế độ bind mặc định: loopback.
• Theo mặc định cần xác thực. Các thiết lập bí mật dùng chung sử dụng gateway.auth.token / gateway.auth.password (hoặc OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), và các thiết lập reverse proxy không phải loopback có thể dùng gateway.auth.mode: "trusted-proxy".

Điểm cuối 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 hợp này quan trọng:

• Hầu hết tích hợp Open WebUI, LobeChat và LibreChat probe /v1/models trước.
• Nhiều pipeline RAG và bộ nhớ kỳ vọng /v1/embeddings.
• Các client gốc cho tác tử ngày càng ưu tiên /v1/responses.

Ghi chú lập kế hoạch:

• /v1/models ưu tiên tác tử: nó trả về openclaw, openclaw/default và openclaw/<agentId>.
• openclaw/default là bí danh ổn định luôn ánh xạ đến tác tử 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, mô hình bình thường và thiết lập embedding của tác tử đã chọn vẫn giữ quyền kiểm soát.

Tất cả các mục này chạy trên cổng Gateway chính và dùng cùng ranh giới xác thực toán tử đáng tin cậy như phần còn lại của API HTTP Gateway.

RPC HTTP quản trị (POST /api/v1/admin/rpc) là một tuyến Plugin riêng, mặc định tắt, dành cho công cụ host không thể dùng RPC WebSocket. Xem RPC HTTP quản trị.

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

Các dịch vụ gateway đã cài đặt ghi lại --port đã phân giải trong siêu dữ liệu supervisor. Sau khi đổi gateway.port, 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 Control UI 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 bước xác thực runtime chạy. 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 cho toán tử

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ùng để khám phá thêm dịch vụ (LaunchDaemons/đơn vị hệ thống systemd/schtasks), không phải probe tình trạng RPC sâu hơn.

Nhiều gateway (cùng host)

Hầu hết bản cài đặt nên chạy một gateway trên mỗi máy. Một gateway duy nhất có thể host nhiều tác tử và kênh.

Bạn chỉ cần nhiều gateway khi chủ ý 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 kỳ vọng:

• 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 bản cài đặt launchd/systemd/schtasks cũ vẫn còn.
• gateway probe có thể cảnh báo về multiple reachable gateway identities khi các gateway riêng biệt phản hồi, hoặc khi OpenClaw không thể chứng minh các đích có thể truy cập là cùng một gateway. Một SSH tunnel, URL proxy hoặc URL từ xa đã cấu hình đến cùng gateway là một gateway với nhiều transport, ngay cả khi cổng transport khác nhau.
• Nếu đó là chủ ý, hãy cô lập cổng, cấu hình/trạng thái và gốc workspace cho từng gateway.

Danh sách kiểm tra cho từng phiên bản:

• 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ộ đến 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 gần như 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 143OOMPolicy=continueKillMode=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

Lối tắt hồ sơ 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 toán tử)

• Khung client đầu tiên 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 sinh ra của mọi tuyến helper có thể gọi.
• Yêu cầu: req(method, params) → res(ok/payload|error).
• Các sự kiện phổ biến gồm connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, sự kiện vòng đời ghép đôi/phê duyệt, và shutdown.

Lần chạy tác tử có hai giai đoạn:

1. Ack được chấp nhận ngay (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.
• Kỳ vọng phản hồi hello-ok với ảnh chụp nhanh.

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

Phục hồi khoảng trống

Sự kiện không được phát lại. Khi có khoảng trống chuỗi, 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 thang chẩn đoán, hãy dùng Khắc phục sự cố Gateway.

Bảo đảm 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 về 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 bị từ chối và đóng.
• Tắt duyên dáng 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