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.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Deep troubleshooting
Chẩn đoán theo triệu chứng trước, với các chuỗi lệnh chính xác và dấu hiệu nhật ký.
Configuration
Hướng dẫn thiết lập theo tác vụ + tài liệu tham chiếu cấu hình đầy đủ.
Secrets management
Hợp đồng SecretRef, hành vi ảnh chụp nhanh lúc chạy, và thao tác di chuyển/tải lại.
Secrets plan contract
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
Verify service health
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 được.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ớ; 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 lúc 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
- API HTTP, tương thích OpenAI (
/v1/models,/v1/embeddings,/v1/chat/completions,/v1/responses,/tools/invoke) - UI điều khiển và hook
- Chế độ bind mặc định:
loopback. - Xác thực được yêu cầu theo mặc định. Thiết lập bí mật dùng chung sử dụng
gateway.auth.token/gateway.auth.password(hoặcOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD), và thiết lập reverse-proxy không phải loopback có thể dùnggateway.auth.mode: "trusted-proxy".
Endpoint tương thích OpenAI
Bề mặt tương thích có tác động cao nhất của OpenClaw hiện là:GET /v1/modelsGET /v1/models/{id}POST /v1/embeddingsPOST /v1/chat/completionsPOST /v1/responses
- Hầu hết tích hợp Open WebUI, LobeChat, và LibreChat dò
/v1/modelstrước. - Nhiều pipeline RAG và bộ nhớ kỳ vọng
/v1/embeddings. - Các client gốc tác nhân ngày càng ưu tiên
/v1/responses.
/v1/modelsưu tiên tác nhân: nó trả vềopenclaw,openclaw/default, vàopenclaw/<agentId>.openclaw/defaultlà bí danh ổn định luôn ánh xạ tới tác nhân mặc định đã cấu hình.- Dùng
x-openclaw-modelkhi bạn muốn ghi đè nhà cung cấp/mô hình backend; nếu không, mô hình và thiết lập embedding thông thường của tác nhân đã chọn vẫn nắm quyền kiểm soát.
Thứ tự ưu tiên cổng và bind
| Thiết lập | Thứ tự phân giải |
|---|---|
| Cổng Gateway | --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 |
| Chế độ bind | CLI/ghi đè → gateway.bind → loopback |
--port đã phân giải trong metadata của 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 lực 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 xác thực
lúc 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
gateway.reload.mode | Hành vi |
|---|---|
off | Không tải lại cấu hình |
hot | Chỉ áp dụng các thay đổi an toàn khi nóng |
restart | Khởi động lại khi có thay đổi yêu cầu 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ử
gateway status --deep dành cho khám phá dịch vụ bổ sung (LaunchDaemons/systemd system
units/schtasks), không phải phép dò sức khỏe RPC sâu hơn.
Nhiều gateway (cùng máy chủ)
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 tác nhân và kênh. Bạn chỉ cần nhiều gateway khi chủ ý muốn cô lập hoặc có bot cứu hộ. Các kiểm tra hữu ích:gateway status --deepcó thể báo cáoOther 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 probecó thể cảnh báo vềmultiple reachable gatewayskhi có hơn một đích trả lời.- 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.
gateway.portduy nhấtOPENCLAW_CONFIG_PATHduy nhấtOPENCLAW_STATE_DIRduy nhấtagents.defaults.workspaceduy nhất
Endpoint não thời gian thực VoiceClaw
OpenClaw cung cấp endpoint WebSocket thời gian thực tương thích VoiceClaw tại/voiceclaw/realtime. Dùng endpoint này khi client desktop VoiceClaw cần nói chuyện
trực tiếp với não OpenClaw thời gian thực thay vì đi qua một tiến trình chuyển tiếp
riêng.
Endpoint này dùng Gemini Live cho âm thanh thời gian thực và gọi OpenClaw như
não bằng cách cung cấp công cụ OpenClaw trực tiếp cho Gemini Live. Lệnh gọi công cụ trả về kết quả
working ngay lập tức để giữ lượt thoại phản hồi nhanh, sau đó OpenClaw
thực thi công cụ thực tế bất đồng bộ và chèn kết quả trở lại phiên
trực tiếp. Đặt GEMINI_API_KEY trong môi trường tiến trình gateway. Nếu
xác thực gateway được bật, client desktop gửi token hoặc mật khẩu gateway
trong thông điệp session.config đầu tiên.
Truy cập não thời gian thực chạy các lệnh tác nhân OpenClaw được chủ sở hữu ủy quyền. Giới hạn
gateway.auth.mode: "none" cho các instance thử nghiệm chỉ loopback. Kết nối
não thời gian thực không cục bộ yêu cầu xác thực gateway.
Đối với gateway thử nghiệm cô lập, chạy một instance riêng với cổng, cấu hình,
và trạng thái riêng:
Truy cập từ xa
Ưu tiên: Tailscale/VPN. Dự phòng: SSH tunnel.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 chạy có giám sát để có độ tin cậy giống sản xuất.- macOS (launchd)
- Linux (systemd user)
- Windows (native)
- Linux (system service)
openclaw gateway restart để khởi động lại. Không nối chuỗi openclaw gateway stop và openclaw gateway start; trên macOS, gateway stop cố ý vô hiệu hóa LaunchAgent trước khi dừng nó.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 chữa trôi lệch cấu hình dịch vụ.Đường tắt hồ sơ dev
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/eventslà danh sách khám phá thận trọng, không phải bản kết xuất được tạo của mọi tuyến helper 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, sự kiện vòng đời ghép nối/phê duyệt, vàshutdown.
- Xác nhận đã chấp nhận ngay lập tức (
status:"accepted") - Phản hồi hoàn tất cuối cùng (
status:"ok"|"error"), với các sự kiệnagentđược stream ở giữa.
Kiểm tra vận hành
Tính sống còn
- Mở WS và gửi
connect. - Chờ phản hồi
hello-okkèm ảnh chụp trạng thái.
Trạng thái sẵn sàng
Khôi phục khi thiếu trình tự
Sự kiện không được phát lại. Khi có khoảng thiếu trong chuỗi, 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
| Dấu hiệu | Vấn đề có khả năng xảy ra |
|---|---|
refusing to bind gateway ... without auth | Liên kết không phải loopback mà không có đường dẫn xác thực Gateway hợp lệ |
another gateway instance is already listening / EADDRINUSE | Xung đột cổng |
Gateway start blocked: set gateway.mode=local | Cấu hình đặt ở chế độ từ xa, hoặc dấu chế độ cục bộ bị thiếu trong cấu hình hỏng |
unauthorized trong khi kết nối | Xác thực giữa client và Gateway không khớp |
Bảo đảm an toàn
- Các client giao thức Gateway thất bại nhanh khi Gateway không khả dụng (không có cơ chế dự phòng ngầm về kênh trực tiếp).
- Các khung đầu tiên không hợp lệ/không phải connect bị từ chối và đóng.
- Tắt nhẹ nhàng sẽ phát sự kiện
shutdowntrước khi đóng socket.
Liên quan: