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 tạm thời/phát triển.
• 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 xem đó là cấu hình bị hỏng hoặc bị ghi đè và sửa nó thay vì ngầm giả định chế độ local.
• Nếu tệp tồn tại và thiếu gateway.mode, Gateway xem đó là hư hỏng cấu hình đáng ngờ và từ chối "đoán local" thay bạn.
• Việc bind vượt quá loopback mà không có xác thực sẽ bị chặn (lan can an toàn).
• lan, tailnet, và custom hiện phân giải qua các đường dẫn BYOH chỉ IPv4.
• BYOH chỉ IPv6 hiện chưa được hỗ trợ nguyên bản trên đường dẫn này. Dùng một sidecar hoặc proxy IPv4 nếu chính máy chủ chỉ có IPv6.
• SIGUSR1 kích hoạt khởi động lại trong tiến trình khi được cho phép (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 gateway tool/config apply/update 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ữ siêu dữ liệu 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, id phê duyệt, 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, body webhook, output tool, body 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 lỗi nghiêm trọng, timeout shutdown, và lỗi khởi động sau 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 output bundle.

• gateway status vẫn khả dụng để 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 nhìn thấy 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ị.
• Các phép dò chẩn đoán không gây đột biến đối với xác thực thiết bị lần đầu: chúng dùng lại token thiết bị đã lưu trong bộ nhớ đệm nếu 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 các SecretRef xác thực đã cấu hình cho xác thực phép dò khi có thể.
• Nếu một SecretRef xác thực bắt buộc không đượ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 dò thất bại; truyền rõ ràng --token/--password hoặc phân giải nguồn bí mật trước.
• Nếu phép 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ả.
• Khi bật dò, đầu ra JSON bao gồm gateway.version khi Gateway đang chạy báo cáo nó; --require-rpc có thể dự phòng về tải trọng RPC status.runtimeVersion nếu phép dò bắt tay tiếp theo không cung cấp được siêu dữ liệu phiên bản.
• 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 khỏe mạnh.
• --deep thêm quét nỗ lực tối đa để tìm các 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 đọc 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 chuyển giao khởi động lại supervisor Gateway gần đây khi tiến trình dịch vụ đã thoát sạch để supervisor bên ngoài khởi động lại.
• --deep chạy xác thực cấu hình ở chế độ nhận biết plugin (pluginValidation: "full") và hiển thị cảnh báo manifest plugin đã cấu hình (ví dụ thiếu siêu dữ liệu cấu hình kênh) để các kiểm tra smoke cài đặt và cập nhật bắt được chúng. gateway status mặc định giữ đường dẫn chỉ đọc nhanh bỏ qua xác thực plugin.
• Đầu ra cho người đọc bao gồm đường dẫn nhật ký tệp đã phân giải cùng với ảnh chụp nhanh đường dẫn/tính hợp lệ cấu hình CLI-so-với-dịch vụ để giúp chẩn đoán trôi lệch hồ sơ hoặc thư mục trạng thái.

• Trên các cài đặt Linux systemd, kiểm tra trôi 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ó dấu ngoặc kép, nhiều tệp, và các tệp - tùy chọn).
• Kiểm tra trôi lệch phân giải SecretRef gateway.auth.token bằng môi trường runtime đã hợp nhất (môi trường lệnh dịch vụ trước, sau đó dự phòng về môi trường tiến trình).
• Nếu xác thực token không thực sự hoạt động (gateway.auth.mode rõ ràng là password/none/trusted-proxy, hoặc mode chưa đặt trong đó 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ì phép 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. Điều 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, probe dùng lại 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 chỉ khác 0 khi không có mục tiêu nào được dò 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 đã thấy 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à bên 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[]: 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 dẫn xuất từ cấu hình hiện tại và mạng máy chủ.
• 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 dò này.

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

• ok: khả năng truy cập sau kết nối + phân loạ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 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 về các phép dò trực tiếp.
• multiple_gateways: các danh tính gateway khác biệt có thể truy cập, hoặc OpenClaw không thể chứng minh các mục tiêu có thể truy cập là cùng một gateway. Đường hầm SSH, URL proxy, hoặc URL remote đã cấu hình tới cùng một gateway không kích hoạt cảnh báo này.
• auth_secretref_unresolved: một SecretRef xác thực đã cấu hình không thể phân giải cho mục tiêu thất bại.
• probe_scope_limited: Kết nối WebSocket thành công, nhưng phép 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, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Dùng gateway restart để khởi động lại một dịch vụ được quản lý. Không nối chuỗi gateway stop và gateway start để thay thế thao tác khởi động lại.
• Trên macOS, theo mặc định gateway stop dùng launchctl bootout, thao tác này xóa LaunchAgent khỏi phiên khởi động hiện tại mà không lưu bền trạng thái tắt — tính năng tự khôi phục KeepAlive vẫn hoạt động cho các sự cố về sau và gateway start bật lại sạch sẽ mà không cần launchctl enable thủ công. Truyền --disable để chặn KeepAlive và RunAtLoad một cách bền vững, để Gateway không tái sinh cho đến lần gateway start rõ ràng tiếp theo; dùng tùy chọn này khi một lần dừng thủ công cần tồn tại qua các lần khởi động lại máy hoặc khởi động lại hệ thống.
• gateway restart --safe yêu cầu Gateway đang chạy kiểm tra trước công việc đang hoạt động và lên lịch một lần khởi động lại gộp sau khi công việc đang hoạt động được xả hết. Khởi động lại an toàn mặc định chờ công việc đang hoạt động tối đa theo gateway.reload.deferralTimeoutMs đã cấu hình (mặc định 5 phút); khi ngân sách đó hết, lần khởi động lại sẽ bị bắt buộc. Đặt gateway.reload.deferralTimeoutMs thành 0 để chờ an toàn vô thời hạn và không bao giờ bắt buộc. Không thể kết hợp --safe với --force hoặc --wait.
• gateway restart --wait 30s ghi đè ngân sách xả trước 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 --safe --skip-deferral chạy khởi động lại an toàn có nhận biết OpenClaw nhưng bỏ qua cổng trì hoãn, để Gateway phát ra lệnh khởi động lại ngay cả khi có báo cáo về các tác nhân chặn. Đây là lối thoát cho người vận hành khi các trì hoãn do lượt chạy tác vụ bị kẹt; yêu cầu --safe.
• gateway restart --force bỏ qua bước xả 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 người vận hành đã 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 để viết 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ể phân giải nhưng không lưu bền 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ẽ đóng lỗi thay vì lưu bền 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 các 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 env trong cấu hình) 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 mode được đặt rõ ràng.