Gateway

• Theo mặc định, Gateway từ chối khởi động trừ khi gateway.mode=local được đặt trong ~/.openclaw/openclaw.json. Dùng --allow-unconfigured cho các lần chạy ad-hoc/dev.
• openclaw onboard --mode local và openclaw setup được kỳ vọng sẽ ghi gateway.mode=local. Nếu tệp tồn tại nhưng thiếu gateway.mode, hãy coi đó là cấu hình bị hỏng hoặc bị ghi đè và sửa nó thay vì ngầm giả định chế độ cục bộ.
• Nếu tệp tồn tại và thiếu gateway.mode, Gateway coi đó là hư hại cấu hình đáng ngờ và từ chối "đoán local" thay bạn.
• Việc bind vượt ra ngoài loopback mà không có xác thực sẽ bị chặn (hàng rào an toàn).
• SIGUSR1 kích hoạt khởi động lại trong tiến trình khi được ủy quyền (commands.restart được bật theo mặc định; đặt commands.restart: false để chặn khởi động lại thủ công, trong khi áp dụng/cập nhật công cụ/cấu hình Gateway vẫn được phép).
• Các handler SIGINT/SIGTERM dừng tiến trình Gateway, nhưng chúng không khôi phục bất kỳ trạng thái terminal tùy chỉnh nào. Nếu bạn bọc CLI bằng TUI hoặc đầu vào raw-mode, hãy khôi phục terminal trước khi thoát.

• Bản ghi giữ metadata vận hành: tên sự kiện, số lượng, kích thước byte, chỉ số bộ nhớ, trạng thái hàng đợi/phiên, tên kênh/plugin và tóm tắt phiên đã biên tập. Chúng không giữ văn bản chat, nội dung Webhook, đầu ra công cụ, nội dung request hoặc response thô, token, cookie, giá trị bí mật, hostname hoặc id phiên thô. Đặt diagnostics.enabled: false để tắt hoàn toàn bộ ghi.
• Khi Gateway thoát do lỗi nghiêm trọng, timeout khi tắt và lỗi khởi động sau khi restart, OpenClaw ghi cùng snapshot chẩn đoán vào ~/.openclaw/logs/stability/openclaw-stability-*.json khi bộ ghi có sự kiện. Kiểm tra bundle mới nhất bằng openclaw gateway stability --bundle latest; --limit, --type và --since-seq cũng áp dụng cho đầu ra bundle.

• gateway status vẫn khả dụng cho chẩn đoán ngay cả khi cấu hình CLI cục bộ bị thiếu hoặc không hợp lệ.
• gateway status mặc định chứng minh trạng thái dịch vụ, kết nối WebSocket và khả năng xác thực hiển thị tại thời điểm bắt tay. Nó không chứng minh các thao tác đọc/ghi/quản trị.
• Thăm dò chẩn đoán không gây biến đổi đối với xác thực thiết bị lần đầu: chúng tái sử dụng token thiết bị đã lưu trong bộ nhớ đệm khi có, nhưng không tạo danh tính thiết bị CLI mới hoặc bản ghi ghép đôi thiết bị chỉ đọc chỉ để kiểm tra trạng thái.
• gateway status phân giải SecretRefs xác thực đã cấu hình cho xác thực thăm dò khi có thể.
• Nếu một SecretRef xác thực bắt buộc chưa được phân giải trong đường dẫn lệnh này, gateway status --json báo cáo rpc.authWarning khi kết nối/xác thực thăm dò thất bại; hãy truyền rõ ràng --token/--password hoặc phân giải nguồn bí mật trước.
• Nếu thăm dò thành công, cảnh báo auth-ref chưa phân giải sẽ bị ẩn để tránh dương tính giả.
• Dùng --require-rpc trong script và tự động hóa khi một dịch vụ đang lắng nghe là chưa đủ và bạn cũng cần các lệnh gọi RPC phạm vi đọc hoạt động tốt.
• --deep thêm quét nỗ lực tối đa cho các bản cài đặt launchd/systemd/schtasks bổ sung. Khi phát hiện nhiều dịch vụ giống gateway, đầu ra cho người dùng in gợi ý dọn dẹp và cảnh báo rằng hầu hết thiết lập nên chạy một gateway trên mỗi máy.
• --deep cũng báo cáo một lần bàn giao khởi động lại Gateway supervisor gần đây khi tiến trình dịch vụ đã thoát sạch để một supervisor bên ngoài khởi động lại.
• Đầu ra cho người dùng bao gồm đường dẫn log tệp đã phân giải cùng ảnh chụp nhanh đường dẫn/tính hợp lệ của cấu hình CLI so với dịch vụ để giúp chẩn đoán lệch profile hoặc state-dir.

• Trên các bản cài đặt systemd Linux, kiểm tra lệch xác thực dịch vụ đọc cả giá trị Environment= và EnvironmentFile= từ unit (bao gồm %h, đường dẫn có trích dẫn, nhiều tệp và các tệp - tùy chọn).
• Kiểm tra lệch phân giải SecretRefs gateway.auth.token bằng env runtime đã hợp nhất (env lệnh dịch vụ trước, rồi dự phòng về env tiến trình).
• Nếu xác thực token không thực sự hoạt động (đặt rõ gateway.auth.mode là password/none/trusted-proxy, hoặc chưa đặt mode khi mật khẩu có thể thắng và không có ứng viên token nào có thể thắng), kiểm tra token-drift bỏ qua phân giải token cấu hình.

• Reachable: yes nghĩa là ít nhất một mục tiêu đã chấp nhận kết nối WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only báo cáo những gì thăm dò có thể chứng minh về xác thực. Nó tách biệt với khả năng truy cập.
• Read probe: ok nghĩa là các lệnh gọi RPC chi tiết phạm vi đọc (health/status/system-presence/config.get) cũng đã thành công.
• Read probe: limited - missing scope: operator.read nghĩa là kết nối thành công nhưng RPC phạm vi đọc bị giới hạn. Trường hợp này được báo cáo là khả năng truy cập suy giảm, không phải thất bại hoàn toàn.
• Read probe: failed sau Connect: ok nghĩa là Gateway đã chấp nhận kết nối WebSocket, nhưng chẩn đoán đọc tiếp theo đã hết thời gian chờ hoặc thất bại. Đây cũng là khả năng truy cập suy giảm, không phải Gateway không thể truy cập.
• Giống gateway status, thăm dò tái sử dụng xác thực thiết bị đã lưu trong bộ nhớ đệm nhưng không tạo danh tính thiết bị lần đầu hoặc trạng thái ghép đôi.
• Mã thoát khác 0 chỉ khi không có mục tiêu được thăm dò nào có thể truy cập.

Cấp cao nhất:

• ok: ít nhất một mục tiêu có thể truy cập.
• degraded: ít nhất một mục tiêu đã chấp nhận kết nối nhưng không hoàn tất chẩn đoán RPC chi tiết đầy đủ.
• capability: khả năng tốt nhất quan sát được trên các mục tiêu có thể truy cập (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, hoặc unknown).
• primaryTargetId: mục tiêu tốt nhất để xem là mục tiêu thắng đang hoạt động theo thứ tự này: URL rõ ràng, đường hầm SSH, remote đã cấu hình, rồi local loopback.
• warnings[]: các bản ghi cảnh báo nỗ lực tối đa với code, message và targetIds tùy chọn.
• network: gợi ý URL local loopback/tailnet được suy ra từ cấu hình hiện tại và mạng của host.
• discovery.timeoutMs và discovery.count: ngân sách khám phá/số lượng kết quả thực tế dùng cho lượt thăm dò này.

Theo từng mục tiêu (targets[].connect):

• ok: khả năng truy cập sau phân loại kết nối + suy giảm.
• rpcOk: RPC chi tiết đầy đủ thành công.
• scopeLimited: RPC chi tiết thất bại do thiếu phạm vi operator.

Theo từng mục tiêu (targets[].auth):

• role: vai trò xác thực được báo cáo trong hello-ok khi có.
• scopes: các phạm vi được cấp được báo cáo trong hello-ok khi có.
• capability: phân loại khả năng xác thực được hiển thị cho mục tiêu đó.

• ssh_tunnel_failed: thiết lập đường hầm SSH thất bại; lệnh đã dự phòng sang thăm dò trực tiếp.
• multiple_gateways: có thể truy cập nhiều hơn một mục tiêu; điều này bất thường trừ khi bạn cố ý chạy các profile tách biệt, chẳng hạn như bot cứu hộ.
• auth_secretref_unresolved: không thể phân giải SecretRef xác thực đã cấu hình cho một mục tiêu thất bại.
• probe_scope_limited: kết nối WebSocket thành công, nhưng thăm dò đọc bị giới hạn do thiếu operator.read.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Dùng gateway restart để khởi động lại một dịch vụ được quản lý. Không nối gateway stop và gateway start để thay thế thao tác khởi động lại; trên macOS, gateway stop cố ý vô hiệu hóa LaunchAgent trước khi dừng nó.
• gateway restart --safe yêu cầu Gateway đang chạy kiểm tra trước công việc OpenClaw đang hoạt động và trì hoãn khởi động lại cho đến khi việc gửi trả lời, các lần chạy nhúng và các lần chạy tác vụ rút hết. Không thể kết hợp --safe với --force hoặc --wait.
• gateway restart --wait 30s ghi đè ngân sách rút cạn khi khởi động lại đã cấu hình cho lần khởi động lại đó. Số trần là mili giây; các đơn vị như s, m và h được chấp nhận. --wait 0 chờ vô thời hạn.
• gateway restart --force bỏ qua việc rút cạn công việc đang hoạt động và khởi động lại ngay lập tức. Dùng tùy chọn này khi operator đã kiểm tra các tác vụ chặn được liệt kê và muốn gateway hoạt động trở lại ngay.
• Các lệnh vòng đời chấp nhận --json cho script.

• Khi xác thực bằng token yêu cầu token và gateway.auth.token được quản lý bằng SecretRef, gateway install xác thực rằng SecretRef có thể được phân giải nhưng không lưu token đã phân giải vào siêu dữ liệu môi trường dịch vụ.
• Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, quá trình cài đặt sẽ thất bại theo hướng đóng thay vì lưu văn bản thuần dự phòng.
• Với xác thực bằng mật khẩu trên gateway run, ưu tiên OPENCLAW_GATEWAY_PASSWORD, --password-file, hoặc gateway.auth.password dựa trên SecretRef thay vì --password nội tuyến.
• Trong chế độ xác thực suy luận, OPENCLAW_GATEWAY_PASSWORD chỉ có trong shell không nới lỏng yêu cầu token khi cài đặt; hãy dùng cấu hình bền vững (gateway.auth.password hoặc cấu hình env) khi cài đặt một dịch vụ được quản lý.
• Nếu cả gateway.auth.token và gateway.auth.password đều được cấu hình và gateway.auth.mode chưa được đặt, quá trình cài đặt sẽ bị chặn cho đến khi chế độ được đặt rõ ràng.