Sổ tay vận hành Gateway

Dùng trang này để khởi động ngày đầu tiên và vận hành từ ngày thứ hai trở đi cho dịch vụ Gateway.

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

openclaw gateway --port 18789# phản chiếu debug/trace sang stdioopenclaw gateway --port 18789 --verbose# buộc dừng trình lắng nghe trên cổng đã chọn, rồi khởi độngopenclaw 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 để định tuyến, vận hành 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 qua WebSocket
  • Các 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
  • Giao diện điều khiển và các hook
• Chế độ liên kết mặc định: loopback. Bên trong môi trường container được phát hiện, giá trị mặc định hiệu dụng là auto (phân giải thành 0.0.0.0 để chuyển tiếp cổng), trừ khi Tailscale serve/funnel đang hoạt động; trường hợp đó luôn buộc dùng loopback.
• Xác thực được yêu cầu theo mặc định. 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), còn các thiết lập proxy ngược không phải loopback có thể sử dụng gateway.auth.mode: "trusted-proxy".

Điểm cuối tương thích với OpenAI

Bề mặt tương thích có tác động lớn nhất của OpenClaw:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Lý do tập hợp này quan trọng:

• Hầu hết tích hợp Open WebUI, LobeChat và LibreChat thăm dò /v1/models trước.
• Nhiều quy trình RAG và bộ nhớ yêu cầu /v1/embeddings.
• Các ứng dụng khách dành riêng cho tác nhân ngày càng ưu tiên /v1/responses.

/v1/models ưu tiên tác nhân: điểm cuối này trả về openclaw, openclaw/default và openclaw/<agentId> cho mọi tác nhân đã cấu hình. openclaw/default là bí danh ổn định luôn ánh xạ đến tác nhân mặc định đã cấu hình. Gửi x-openclaw-model khi bạn muốn ghi đè nhà cung cấp/mô hình phía máy chủ; nếu không, thiết lập mô hình và embedding thông thường của tác nhân đã chọn vẫn nắm quyền kiểm soát.

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

RPC quản trị qua HTTP (POST /api/v1/admin/rpc) là một tuyến Plugin riêng biệt, mặc định tắt, dành cho công cụ trên máy chủ không thể sử dụng RPC qua WebSocket. Xem RPC quản trị qua HTTP.

Thứ tự ưu tiên cổng và liên kết

Các dịch vụ Gateway đã cài đặt ghi lại --port đã phân giải trong siêu dữ liệu của trình giám sát. 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.

Quá trình khởi động Gateway sử dụng cùng cổng và liên kết hiệu dụng khi tạo sẵn các nguồn gốc Giao diện điều khiển cục bộ cho các liên kết không phải loopback. Ví dụ, --bind lan --port 3000 tạo sẵn http://localhost:3000 và http://127.0.0.1:3000 trước khi chạy xác thực thời gian chạy. Thêm rõ ràng mọi nguồn gốc trình duyệt từ xa, chẳng hạn như URL proxy HTTPS, vào gateway.controlUi.allowedOrigins.

Các chế độ tải lại nóng

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

openclaw gateway statusopenclaw gateway status --deep   # thêm thao tác quét dịch vụ ở cấp hệ thốngopenclaw 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 để thăm dò tình trạng RPC chuyên sâu hơn.

Nhiều Gateway (cùng máy chủ)

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ể lưu trữ nhiều tác nhân và kênh. Bạn chỉ cần nhiều Gateway khi chủ đích muốn cô lập hoặc cần bot cứu hộ.

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

openclaw gateway status --deepopenclaw gateway probe

Kết quả dự kiến:

• 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 tồn tại.
• 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. Đường hầm SSH, URL proxy hoặc URL từ xa đã cấu hình đến cùng một Gateway vẫn là một Gateway với nhiều phương thức truyền tải, ngay cả khi các cổng truyền tải khác nhau.
• Nếu đây là chủ đích, hãy cô lập các cổng, cấu hình/trạng thái và thư mục gốc không gian làm việc theo 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. Phương án dự phòng: đường hầm SSH.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Sau đó kết nối các ứng dụng khách cục bộ vớ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 để đạt độ tin cậy tương tự môi trường sản xuất.

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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=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 cấu hình không hợp lệ thoát với mã 78. Các đơn vị systemd trên Linux sử dụng RestartPreventExitStatus=78 để ngừng khởi chạy lại cho đến khi cấu hình được sửa. launchd và Windows Task Scheduler không có quy tắc dừng tương đương theo mã thoát, vì vậy Gateway cũng lưu lịch sử khởi động không sạch diễn ra nhanh và ngăn tự động khởi động tài khoản kênh/nhà cung cấp sau nhiều lần khởi động thất bại. Trong chế độ an toàn đó, mặt phẳng điều khiển vẫn khởi động để kiểm tra và sửa chữa, việc tải nóng cấu hình và secrets.reload từ chối tự động khởi động lại kênh, còn yêu cầu rõ ràng channels.start của người vận hành có thể ghi đè việc ngăn chặn.

Đường dẫn nhanh cho hồ sơ phát triển

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

Các giá trị 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 người vận hành)

• Khung dữ liệu đầu tiên của máy khách phải là connect.
• Gateway trả về một khung hello-ok với snapshot (presence, health, stateVersion, uptimeMs) cùng các giới hạn policy (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events là danh sách khám phá có tính thận trọng, không phải bản kết xuất được tạo tự động của mọi tuyến trợ giúp 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, sự kiện tùy chọn session.approval, sessions.changed, presence, tick, health, heartbeat, các sự kiện vòng đời ghép nối/phê duyệt và shutdown.

Các lượt chạy của tác nhân có 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 tất cuối cùng (status:"ok"|"error"), với các sự kiện agent được truyền phát ở giữa.

Xem tài liệu giao thức đầy đủ: Giao thức Gateway.

Kiểm tra vận hành

Khả năng hoạt động

• Mở WS và gửi connect.
• Chờ phản hồi hello-ok kèm ảnh chụp trạng thái.

Mức độ sẵn sàng

openclaw gateway statusopenclaw channels status --probeopenclaw health

Khôi phục khi có khoảng trống

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

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

Bảo đảm an toàn

• Các máy khách giao thức Gateway dừng ngay khi Gateway không khả dụng (không có cơ chế ngầm định dự phòng trực tiếp sang kênh).
• Các khung đầu tiên không hợp lệ/không phải khung kết nối sẽ bị từ chối và đóng.
• Khi tắt đúng quy trình, sự kiện shutdown được phát trước khi đóng socket.

Liên quan

• Cấu hình
• Khắc phục sự cố Gateway
• Tiến trình nền
• Tình trạng hệ thống
• Doctor
• Xác thực
• Truy cập từ xa
• Quản lý thông tin bí mật