Gateway

• โดยค่าเริ่มต้น Gateway จะปฏิเสธการเริ่มทำงาน เว้นแต่จะตั้งค่า gateway.mode=local ไว้ใน ~/.openclaw/openclaw.json ใช้ --allow-unconfigured สำหรับการรันเฉพาะกิจ/การพัฒนา
• openclaw onboard --mode local และ openclaw setup ควรเขียนค่า gateway.mode=local หากไฟล์มีอยู่แต่ไม่มี gateway.mode ให้ถือว่าเป็นการกำหนดค่าที่เสียหรือถูกเขียนทับ และซ่อมแซมแทนการถือว่าเป็นโหมด local โดยนัย
• หากไฟล์มีอยู่และไม่มี gateway.mode Gateway จะถือว่าเป็นความเสียหายของการกำหนดค่าที่น่าสงสัย และปฏิเสธที่จะ "เดา local" ให้คุณ
• การ bind ออกนอก loopback โดยไม่มี auth จะถูกบล็อก (มาตรการป้องกันความปลอดภัย)
• SIGUSR1 จะทริกเกอร์การรีสตาร์ทภายในกระบวนการเมื่อได้รับอนุญาต (commands.restart เปิดใช้งานตามค่าเริ่มต้น; ตั้งค่า commands.restart: false เพื่อบล็อกการรีสตาร์ทด้วยตนเอง ขณะที่การ apply/update เครื่องมือ/การกำหนดค่า Gateway ยังอนุญาตอยู่)
• handler ของ SIGINT/SIGTERM จะหยุดกระบวนการ Gateway แต่จะไม่กู้คืนสถานะเทอร์มินัลแบบกำหนดเองใด ๆ หากคุณครอบ CLI ด้วย TUI หรืออินพุต raw-mode ให้กู้คืนเทอร์มินัลก่อนออก

• records เก็บ metadata ด้านปฏิบัติการ: ชื่อเหตุการณ์, จำนวน, ขนาด byte, ค่าหน่วยความจำ, สถานะคิว/เซสชัน, ชื่อช่องทาง/Plugin, และสรุปเซสชันที่ redact แล้ว โดยไม่เก็บข้อความแชท, body ของ Webhook, เอาต์พุตของเครื่องมือ, body คำขอหรือคำตอบดิบ, token, cookie, ค่าลับ, hostname, หรือ session id ดิบ ตั้งค่า diagnostics.enabled: false เพื่อปิด recorder ทั้งหมด
• เมื่อ Gateway ออกแบบ fatal, shutdown timeout, และ restart startup failure, OpenClaw จะเขียน snapshot diagnostics เดียวกันไปที่ ~/.openclaw/logs/stability/openclaw-stability-*.json เมื่อ recorder มีเหตุการณ์ ตรวจสอบ bundle ใหม่ที่สุดด้วย openclaw gateway stability --bundle latest; --limit, --type, และ --since-seq ใช้กับเอาต์พุต bundle ด้วย

• gateway status ยังคงใช้ได้สำหรับการวินิจฉัย แม้เมื่อ config ของ CLI ภายในเครื่องหายไปหรือไม่ถูกต้อง
• gateway status ค่าเริ่มต้นพิสูจน์สถานะ service, การเชื่อมต่อ WebSocket และความสามารถด้าน auth ที่เห็นได้ในช่วง handshake โดยไม่ได้พิสูจน์การดำเนินการ read/write/admin
• Diagnostic probe ไม่เปลี่ยนแปลงข้อมูลสำหรับ auth ของอุปกรณ์ครั้งแรก: จะใช้ device token ที่ cache ไว้เดิมเมื่อมีอยู่ แต่จะไม่สร้างตัวตนอุปกรณ์ CLI ใหม่หรือระเบียนการจับคู่อุปกรณ์แบบ read-only ใหม่เพียงเพื่อตรวจสอบสถานะ
• gateway status จะ resolve auth SecretRefs ที่กำหนดค่าไว้สำหรับ probe auth เมื่อทำได้
• หาก auth SecretRef ที่จำเป็นยัง resolve ไม่ได้ในเส้นทางคำสั่งนี้ gateway status --json จะรายงาน rpc.authWarning เมื่อ probe connectivity/auth ล้มเหลว; ส่ง --token/--password อย่างชัดเจน หรือ resolve แหล่ง secret ก่อน
• หาก probe สำเร็จ คำเตือน auth-ref ที่ยัง resolve ไม่ได้จะถูกซ่อนเพื่อหลีกเลี่ยง false positive
• ใช้ --require-rpc ในสคริปต์และ automation เมื่อ service ที่กำลัง listen อยู่ยังไม่เพียงพอ และคุณต้องการให้การเรียก RPC แบบ read-scope มีสถานะดีด้วย
• --deep เพิ่มการสแกนแบบ best-effort สำหรับการติดตั้ง launchd/systemd/schtasks เพิ่มเติม เมื่อพบ service ที่คล้าย Gateway หลายรายการ เอาต์พุตสำหรับมนุษย์จะพิมพ์คำแนะนำการล้างข้อมูลและเตือนว่าการตั้งค่าส่วนใหญ่ควรรัน Gateway หนึ่งรายการต่อเครื่อง
• --deep ยังรายงานการส่งต่อการ restart ล่าสุดของ Gateway supervisor เมื่อ process ของ service ออกอย่างสะอาดเพื่อให้ supervisor ภายนอก restart
• --deep รันการตรวจสอบ config ในโหมดที่รับรู้ Plugin (pluginValidation: "full") และแสดงคำเตือน manifest ของ Plugin ที่กำหนดค่าไว้ (เช่น metadata ของ channel config ที่หายไป) เพื่อให้ smoke check สำหรับการติดตั้งและอัปเดตตรวจจับได้ gateway status ค่าเริ่มต้นยังคงใช้เส้นทาง read-only ที่รวดเร็วซึ่งข้ามการตรวจสอบ Plugin
• เอาต์พุตสำหรับมนุษย์รวม path ของ log file ที่ resolve แล้ว พร้อม snapshot ของ path/ความถูกต้องของ config ระหว่าง CLI กับ service เพื่อช่วยวินิจฉัย profile หรือ state-dir drift

• บนการติดตั้ง Linux systemd การตรวจ auth drift ของ service จะอ่านค่าทั้ง Environment= และ EnvironmentFile= จาก unit (รวมถึง %h, path ที่ quote ไว้, ไฟล์หลายไฟล์ และไฟล์ optional ที่ขึ้นต้นด้วย -)
• การตรวจ drift จะ resolve gateway.auth.token SecretRefs โดยใช้ runtime env ที่ merge แล้ว (env ของคำสั่ง service ก่อน จากนั้น fallback เป็น process env)
• หาก token auth ไม่ได้ active อย่างมีผลจริง (gateway.auth.mode แบบชัดเจนเป็น password/none/trusted-proxy หรือไม่ได้ตั้ง mode โดยที่ password อาจชนะได้และไม่มี token candidate ใดชนะได้) การตรวจ token-drift จะข้ามการ resolve config token

• Reachable: yes หมายถึงมีเป้าหมายอย่างน้อยหนึ่งรายการที่ยอมรับการเชื่อมต่อ WebSocket
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only รายงานสิ่งที่ probe พิสูจน์ได้เกี่ยวกับ auth ซึ่งแยกจาก reachability
• Read probe: ok หมายถึงการเรียก RPC รายละเอียดแบบ read-scope (health/status/system-presence/config.get) สำเร็จด้วย
• Read probe: limited - missing scope: operator.read หมายถึงเชื่อมต่อสำเร็จ แต่ RPC แบบ read-scope ถูกจำกัด รายงานเป็น reachability แบบ degraded ไม่ใช่ความล้มเหลวทั้งหมด
• Read probe: failed หลัง Connect: ok หมายถึง Gateway ยอมรับการเชื่อมต่อ WebSocket แล้ว แต่การวินิจฉัย read ที่ตามมาหมดเวลาหรือล้มเหลว ซึ่งเป็น reachability แบบ degraded เช่นกัน ไม่ใช่ Gateway ที่เข้าถึงไม่ได้
• เช่นเดียวกับ gateway status probe จะใช้ auth ของอุปกรณ์ที่ cache ไว้เดิม แต่จะไม่สร้างตัวตนอุปกรณ์หรือสถานะการจับคู่ครั้งแรก
• Exit code จะไม่ใช่ศูนย์เฉพาะเมื่อไม่มีเป้าหมายที่ probe แล้วเข้าถึงได้

ระดับบนสุด:

• ok: มีเป้าหมายอย่างน้อยหนึ่งรายการที่เข้าถึงได้
• degraded: มีเป้าหมายอย่างน้อยหนึ่งรายการที่ยอมรับการเชื่อมต่อ แต่ไม่ได้ทำการวินิจฉัย RPC รายละเอียดอย่างครบถ้วน
• capability: ความสามารถที่ดีที่สุดที่พบในเป้าหมายที่เข้าถึงได้ (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope หรือ unknown)
• primaryTargetId: เป้าหมายที่ดีที่สุดให้ถือเป็นผู้ชนะที่ active ตามลำดับนี้: URL ที่ระบุชัดเจน, SSH tunnel, remote ที่กำหนดค่าไว้, จากนั้น local loopback
• warnings[]: ระเบียนคำเตือนแบบ best-effort ที่มี code, message และ targetIds แบบ optional
• network: hint URL ของ local loopback/tailnet ที่ได้จาก config ปัจจุบันและระบบเครือข่ายของ host
• discovery.timeoutMs และ discovery.count: budget/result count ของ discovery จริงที่ใช้สำหรับรอบ probe นี้

ต่อเป้าหมาย (targets[].connect):

• ok: reachability หลัง connect + การจัดประเภท degraded
• rpcOk: RPC รายละเอียดเต็มสำเร็จ
• scopeLimited: RPC รายละเอียดล้มเหลวเนื่องจากขาด operator scope

ต่อเป้าหมาย (targets[].auth):

• role: บทบาท auth ที่รายงานใน hello-ok เมื่อมี
• scopes: scope ที่ได้รับซึ่งรายงานใน hello-ok เมื่อมี
• capability: การจัดประเภทความสามารถ auth ที่แสดงสำหรับเป้าหมายนั้น

• ssh_tunnel_failed: การตั้งค่า SSH tunnel ล้มเหลว; คำสั่ง fallback ไปใช้ direct probe
• multiple_gateways: มีเป้าหมายมากกว่าหนึ่งรายการที่เข้าถึงได้; เป็นกรณีไม่ปกติ เว้นแต่คุณตั้งใจรัน profile ที่แยกกัน เช่น bot สำหรับกู้คืน
• auth_secretref_unresolved: auth SecretRef ที่กำหนดค่าไว้ไม่สามารถ resolve ได้สำหรับเป้าหมายที่ล้มเหลว
• probe_scope_limited: การเชื่อมต่อ WebSocket สำเร็จ แต่ read probe ถูกจำกัดเนื่องจากขาด 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

• ใช้ gateway restart เพื่อรีสตาร์ตบริการที่จัดการอยู่ อย่าต่อคำสั่ง gateway stop และ gateway start เพื่อใช้แทนการรีสตาร์ต
• บน macOS, gateway stop ใช้ launchctl bootout เป็นค่าเริ่มต้น ซึ่งลบ LaunchAgent ออกจากเซสชันการบูตปัจจุบันโดยไม่คงการปิดใช้งานไว้ — การกู้คืนอัตโนมัติของ KeepAlive ยังคงเปิดใช้งานสำหรับการขัดข้องในอนาคต และ gateway start เปิดใช้งานใหม่ได้อย่างสะอาดโดยไม่ต้องสั่ง launchctl enable ด้วยตนเอง ส่ง --disable เพื่อระงับ KeepAlive และ RunAtLoad แบบถาวร เพื่อไม่ให้ gateway เริ่มทำงานใหม่จนกว่าจะสั่ง gateway start อย่างชัดเจนครั้งถัดไป ใช้ตัวเลือกนี้เมื่อการหยุดด้วยตนเองควรคงอยู่หลังการรีบูตหรือการรีสตาร์ตระบบ
• gateway restart --safe ขอให้ Gateway ที่กำลังทำงานอยู่ตรวจล่วงหน้างาน OpenClaw ที่ยังทำงานอยู่ และเลื่อนการรีสตาร์ตจนกว่าการส่งคำตอบ การรันแบบฝัง และการรันงานจะระบายหมด --safe ใช้ร่วมกับ --force หรือ --wait ไม่ได้
• gateway restart --wait 30s เขียนทับงบเวลาระบายงานก่อนรีสตาร์ตที่กำหนดค่าไว้สำหรับการรีสตาร์ตครั้งนั้น ตัวเลขล้วนเป็นมิลลิวินาที ยอมรับหน่วยอย่าง s, m และ h ได้ --wait 0 จะรอไม่มีกำหนด
• gateway restart --safe --skip-deferral รันการรีสตาร์ตอย่างปลอดภัยที่รับรู้งาน OpenClaw แต่ข้ามด่านการเลื่อนเวลา เพื่อให้ Gateway ส่งสัญญาณรีสตาร์ตทันทีแม้มีรายงานตัวบล็อกอยู่ เป็นทางออกฉุกเฉินสำหรับผู้ปฏิบัติงานเมื่อการเลื่อนเวลาจากงานที่ค้างอยู่หยุดชะงัก ต้องใช้ --safe
• gateway restart --force ข้ามการระบายงานที่ยังทำงานอยู่และรีสตาร์ตทันที ใช้เมื่่อผู้ปฏิบัติงานตรวจสอบตัวบล็อกงานที่แสดงไว้แล้วและต้องการให้ gateway กลับมาทันที
• คำสั่งวงจรชีวิตรองรับ --json สำหรับการเขียนสคริปต์

• เมื่อ token auth ต้องใช้โทเค็นและ gateway.auth.token จัดการโดย SecretRef, gateway install จะตรวจสอบว่า SecretRef แก้ค่าได้ แต่จะไม่คงโทเค็นที่แก้ค่าแล้วไว้ในข้อมูลเมตาสภาพแวดล้อมของบริการ
• หาก token auth ต้องใช้โทเค็นและ SecretRef ของโทเค็นที่กำหนดค่าไว้แก้ค่าไม่ได้ การติดตั้งจะล้มเหลวแบบปิดแทนที่จะคง fallback plaintext ไว้
• สำหรับ password auth บน gateway run ควรใช้ OPENCLAW_GATEWAY_PASSWORD, --password-file หรือ gateway.auth.password ที่มี SecretRef รองรับ แทน --password แบบอินไลน์
• ในโหมด auth ที่อนุมานได้ OPENCLAW_GATEWAY_PASSWORD ที่มีเฉพาะใน shell จะไม่ผ่อนปรนข้อกำหนดโทเค็นสำหรับการติดตั้ง ใช้การกำหนดค่าที่คงทน (gateway.auth.password หรือ config env) เมื่อติดตั้งบริการที่จัดการอยู่
• หากกำหนดค่าทั้ง gateway.auth.token และ gateway.auth.password และไม่ได้ตั้งค่า gateway.auth.mode การติดตั้งจะถูกบล็อกจนกว่าจะตั้งค่าโหมดอย่างชัดเจน