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 จะถูกบล็อก (ขอบเขตป้องกันด้านความปลอดภัย)
• lan, tailnet และ custom ปัจจุบัน resolve ผ่านเส้นทาง BYOH ที่เป็น IPv4 เท่านั้น
• BYOH แบบ IPv6-only ยังไม่รองรับโดยตรงบนเส้นทางนี้ในปัจจุบัน ใช้ sidecar หรือพร็อกซี IPv4 หากโฮสต์เองเป็น IPv6-only
• SIGUSR1 ทริกเกอร์การรีสตาร์ทภายในกระบวนการเมื่อได้รับอนุญาต (commands.restart เปิดใช้งานโดยค่าเริ่มต้น; ตั้งค่า commands.restart: false เพื่อบล็อกการรีสตาร์ทด้วยตนเอง ขณะที่ gateway tool/config apply/update ยังคงได้รับอนุญาต)
• ตัวจัดการ SIGINT/SIGTERM จะหยุดกระบวนการ gateway แต่จะไม่คืนค่าสถานะเทอร์มินัลแบบกำหนดเองใด ๆ หากคุณครอบ CLI ด้วย TUI หรืออินพุต raw-mode ให้คืนค่าเทอร์มินัลก่อนออก

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

• gateway status ยังคงพร้อมใช้งานสำหรับการวินิจฉัย แม้เมื่อคอนฟิก CLI ภายในเครื่องหายไปหรือไม่ถูกต้อง
• gateway status เริ่มต้นพิสูจน์สถานะบริการ การเชื่อมต่อ WebSocket และความสามารถการยืนยันตัวตนที่เห็นได้ในเวลาจับมือ ไม่ได้พิสูจน์การดำเนินการอ่าน/เขียน/ผู้ดูแล
• การตรวจสอบเพื่อวินิจฉัยไม่เปลี่ยนแปลงข้อมูลสำหรับการยืนยันตัวตนอุปกรณ์ครั้งแรก: จะใช้โทเค็นอุปกรณ์ที่แคชไว้แล้วเมื่อมีอยู่ แต่จะไม่สร้างตัวตนอุปกรณ์ CLI ใหม่หรือระเบียนการจับคู่อุปกรณ์แบบอ่านอย่างเดียวเพียงเพื่อเช็กสถานะ
• gateway status จะแก้ SecretRefs การยืนยันตัวตนที่กำหนดค่าไว้สำหรับการยืนยันตัวตนของการตรวจสอบเมื่อเป็นไปได้
• หาก SecretRef การยืนยันตัวตนที่จำเป็นไม่ถูกแก้ในพาธคำสั่งนี้ gateway status --json จะรายงาน rpc.authWarning เมื่อการเชื่อมต่อ/การยืนยันตัวตนของการตรวจสอบล้มเหลว ให้ส่ง --token/--password อย่างชัดเจนหรือแก้แหล่งที่มาของความลับก่อน
• หากการตรวจสอบสำเร็จ คำเตือน auth-ref ที่ยังไม่ถูกแก้จะถูกระงับเพื่อหลีกเลี่ยงผลบวกเท็จ
• เมื่อเปิดใช้การตรวจสอบ เอาต์พุต JSON จะรวม gateway.version เมื่อ Gateway ที่กำลังทำงานรายงานค่าไว้; --require-rpc สามารถถอยกลับไปใช้ payload RPC status.runtimeVersion ได้หากการตรวจสอบการจับมือติดตามผลไม่สามารถให้เมทาดาทาเวอร์ชันได้
• ใช้ --require-rpc ในสคริปต์และระบบอัตโนมัติเมื่อบริการที่กำลังฟังอยู่ยังไม่พอ และคุณต้องการให้การเรียก RPC ขอบเขตการอ่านมีสถานภาพดีด้วย
• --deep เพิ่มการสแกนแบบพยายามเต็มที่สำหรับการติดตั้ง launchd/systemd/schtasks เพิ่มเติม เมื่อพบบริการที่คล้าย gateway หลายรายการ เอาต์พุตสำหรับมนุษย์จะพิมพ์คำแนะนำการล้างข้อมูลและเตือนว่าการตั้งค่าส่วนใหญ่ควรรันหนึ่ง gateway ต่อเครื่อง
• --deep ยังรายงานการส่งต่อการรีสตาร์ตของตัวกำกับดูแล Gateway ล่าสุดเมื่อโพรเซสบริการออกอย่างสะอาดสำหรับการรีสตาร์ตของตัวกำกับดูแลภายนอก
• --deep รันการตรวจสอบคอนฟิกในโหมดที่รับรู้ plugin (pluginValidation: "full") และแสดงคำเตือนแมนิเฟสต์ plugin ที่กำหนดค่าไว้ (เช่น เมทาดาทาคอนฟิกช่องทางหายไป) เพื่อให้การตรวจ smoke ของการติดตั้งและอัปเดตตรวจพบได้ gateway status เริ่มต้นคงพาธอ่านอย่างเดียวที่เร็วไว้ซึ่งข้ามการตรวจสอบ plugin
• เอาต์พุตสำหรับมนุษย์รวมพาธบันทึกไฟล์ที่แก้ได้ พร้อมสแนปช็อตพาธ/ความถูกต้องของคอนฟิก CLI-เทียบกับ-บริการ เพื่อช่วยวินิจฉัยการเบี่ยงเบนของโปรไฟล์หรือ state-dir

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

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

ระดับบนสุด:

• ok: มีอย่างน้อยหนึ่งเป้าหมายที่เข้าถึงได้
• degraded: มีอย่างน้อยหนึ่งเป้าหมายที่ยอมรับการเชื่อมต่อ แต่ไม่ได้ทำการวินิจฉัย RPC รายละเอียดครบถ้วน
• capability: ความสามารถที่ดีที่สุดที่เห็นในเป้าหมายที่เข้าถึงได้ (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope หรือ unknown)
• primaryTargetId: เป้าหมายที่ดีที่สุดให้ถือว่าเป็นผู้ชนะที่ใช้งานอยู่ตามลำดับนี้: URL ชัดเจน, อุโมงค์ SSH, รีโมตที่กำหนดค่าไว้ จากนั้น local loopback
• warnings[]: ระเบียนคำเตือนแบบพยายามเต็มที่พร้อม code, message และ targetIds แบบไม่บังคับ
• network: คำใบ้ URL local loopback/tailnet ที่ได้จากคอนฟิกปัจจุบันและเครือข่ายโฮสต์
• discovery.timeoutMs และ discovery.count: งบประมาณ/จำนวนผลลัพธ์ discovery จริงที่ใช้สำหรับรอบการตรวจสอบนี้

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

• ok: การเข้าถึงได้หลังการเชื่อมต่อ + การจัดประเภทแบบเสื่อมคุณภาพ
• rpcOk: ความสำเร็จของ RPC รายละเอียดครบถ้วน
• scopeLimited: RPC รายละเอียดล้มเหลวเนื่องจากขอบเขต operator หายไป

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

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

• ssh_tunnel_failed: การตั้งค่าอุโมงค์ SSH ล้มเหลว; คำสั่งถอยกลับไปใช้การตรวจสอบโดยตรง
• multiple_gateways: ตัวตน gateway ที่แตกต่างกันเข้าถึงได้ หรือ OpenClaw ไม่สามารถพิสูจน์ว่าเป้าหมายที่เข้าถึงได้เป็น gateway เดียวกัน อุโมงค์ SSH, URL proxy หรือ URL รีโมตที่กำหนดค่าไว้ไปยัง gateway เดียวกันจะไม่ทำให้เกิดคำเตือนนี้
• auth_secretref_unresolved: ไม่สามารถแก้ SecretRef การยืนยันตัวตนที่กำหนดค่าไว้สำหรับเป้าหมายที่ล้มเหลว
• probe_scope_limited: การเชื่อมต่อ WebSocket สำเร็จ แต่การตรวจสอบการอ่านถูกจำกัดเพราะไม่มี 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 แบบข้อความธรรมดาไว้
• สำหรับ password auth บน gateway run ให้เลือกใช้ OPENCLAW_GATEWAY_PASSWORD, --password-file หรือ gateway.auth.password ที่อิง SecretRef แทน --password แบบอินไลน์
• ในโหมด auth ที่อนุมาน ค่า OPENCLAW_GATEWAY_PASSWORD ที่อยู่เฉพาะในเชลล์จะไม่ผ่อนปรนข้อกำหนดโทเค็นของการติดตั้ง ใช้การกำหนดค่าที่คงทน (gateway.auth.password หรือ config env) เมื่อติดตั้งบริการที่จัดการ
• หากมีการกำหนดค่าทั้ง gateway.auth.token และ gateway.auth.password และไม่ได้ตั้งค่า gateway.auth.mode การติดตั้งจะถูกบล็อกจนกว่าจะตั้งค่าโหมดอย่างชัดเจน