Chuyển đến nội dung chính
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ắc phục sự cố chuyên sâu

Chẩn đoán theo triệu chứng trước, với các thang lệnh chính xác và dấu hiệu log.

Cấu hình

Hướng dẫn thiết lập theo tác vụ + tài liệu tham chiếu cấu hình đầy đủ.

Quản lý bí mật

Hợp đồng SecretRef, hành vi ảnh chụp nhanh khi chạy, và thao tác di chuyển/tải lại.

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

Quy tắc đích/đường dẫn chính xác của secrets apply và hành vi hồ sơ xác thực chỉ dùng tham chiếu.

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

1

Khởi động Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Xác minh tình trạng dịch vụ

openclaw gateway status
openclaw status
openclaw logs --follow
Đường cơ sở khỏe mạnh: Runtime: running, Connectivity probe: ok, và Capability: ... khớp với điều bạn mong đợi. Dùng openclaw gateway status --require-rpc khi bạn cần bằng chứng RPC phạm vi đọc, không chỉ khả năng truy cập.
3

Xác thực mức sẵn sàng của kênh

openclaw channels status --probe
Với một gateway có thể truy cập, lệnh này chạy các probe kênh trực tiếp theo từng tài khoản và các kiểm tra tùy chọn. Nếu gateway không thể truy cập, CLI sẽ chuyển sang bản tóm tắt kênh chỉ dựa trên cấu hình thay vì đầu ra probe trực tiếp.
Tải lại cấu hình Gateway theo dõi đường dẫn tệp cấu hình đang hoạt động (được phân giải từ mặc định hồ sơ/trạng thái, hoặc OPENCLAW_CONFIG_PATH khi được đặt). Chế độ mặc định là gateway.reload.mode="hybrid". Sau lần tải thành công đầu tiên, tiến trình đang chạy phục vụ ảnh chụp nhanh cấu hình đang hoạt động trong bộ nhớ; lần tải lại thành công sẽ hoán đổi ảnh chụp nhanh đó một cách nguyên tử.

​
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

Thiết lậpThứ tự phân giải
Cổng Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Chế độ bindCLI/ghi đè → gateway.bind → loopback
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

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 khi nóng
restartKhởi động lại khi có thay đổi 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 toán tử

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw 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 --deep
openclaw 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 19001
OPENCLAW_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.
SSH tunnel không bỏ qua xác thực gateway. Với xác thực bí mật dùng chung, client vẫn phải gửi token/password ngay cả qua tunnel. Với các chế độ mang danh tính, yêu cầu vẫn phải thỏa mãn đường dẫn xác thực đó.
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 install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Dùng openclaw gateway restart để khởi động lại. Không nối chuỗi openclaw gateway stop và openclaw gateway start như một cách thay thế cho khởi động lại.Trên macOS, gateway stop mặc định dùng launchctl bootout — thao tác này gỡ LaunchAgent khỏi phiên khởi động hiện tại mà không duy trì trạng thái vô hiệu hóa, nên tự phục hồi KeepAlive vẫn hoạt động sau các lần sập bất ngờ và gateway start bật lại sạch sẽ. Để ngăn tự tái sinh qua các lần khởi động lại một cách bền vững, truyền --disable: openclaw gateway stop --disable.Nhãn LaunchAgent là ai.openclaw.gateway (mặc định) hoặc ai.openclaw.<profile> (hồ sơ có tên). openclaw doctor kiểm tra và sửa lệch cấu hình dịch vụ.

​
Lối tắt hồ sơ dev

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

Chữ kýVấn đề có khả năng xảy ra
refusing to bind gateway ... without authBind không phải local loopback mà không có đường dẫn xác thực gateway hợp lệ
another gateway instance is already listening / EADDRINUSEXung đột cổng
Gateway start blocked: set gateway.mode=localCấu hình được đặt ở chế độ từ xa, hoặc dấu chế độ cục bộ bị thiếu trong cấu hình bị hỏng
unauthorized trong khi kết nốiXác thực không khớp giữa client và gateway
Để 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:

​
Liên quan