แอป iOS

ความพร้อมใช้งาน: บิลด์แอป iPhone เผยแพร่ผ่านช่องทางของ Apple เมื่อเปิดใช้งานสำหรับรีลีส นอกจากนี้ยังสามารถเรียกใช้บิลด์สำหรับการพัฒนาในเครื่องจากซอร์สได้

การทำงาน

• เชื่อมต่อกับ Gateway ผ่าน WebSocket (LAN หรือ tailnet)
• ให้ความสามารถของ Node ได้แก่ Canvas, สแนปช็อตหน้าจอ, การจับภาพจากกล้อง, ตำแหน่งที่ตั้ง, โหมด Talk, การปลุกด้วยเสียง และสรุปข้อมูลสุขภาพแบบเลือกเข้าร่วม
• รับคำสั่ง node.invoke และรายงานเหตุการณ์สถานะของ Node
• เรียกดูพื้นที่ทำงานของเอเจนต์ที่เลือกแบบอ่านอย่างเดียวจากหน้าจอเอเจนต์ (ไฟล์): เจาะลึกไดเรกทอรี, ดูตัวอย่างข้อความพร้อมไฮไลต์ไวยากรณ์, ดูตัวอย่างรูปภาพ และส่งออกผ่านแผ่นงานแชร์ ไม่มีการดำเนินการเขียน โดย Gateway จำกัดขนาดของตัวอย่าง
• เก็บแคชออฟไลน์ขนาดเล็กแบบอ่านอย่างเดียวของเซสชันแชทและบทถอดเสียงล่าสุดแยกตาม Gateway ที่จับคู่: เมื่อเปิดแอปจากสถานะปิด ระบบจะแสดงบทถอดเสียงล่าสุดที่ทราบทันทีและรีเฟรชเมื่อ Gateway ตอบกลับ แชทล่าสุดยังคงเรียกดูได้ระหว่างขาดการเชื่อมต่อ และการรีเซ็ต/ลืมจะล้างแคชในเครื่องที่ได้รับการปกป้อง
• จัดคิวข้อความที่ส่งขณะขาดการเชื่อมต่อไว้ในกล่องขาออกที่คงอยู่แยกตาม Gateway (สูงสุด 50 ข้อความ): บับเบิลที่อยู่ในคิวจะแสดงในบทถอดเสียง ส่งตามลำดับเมื่อเชื่อมต่อใหม่พร้อมลองซ้ำแบบ idempotent คงอยู่จนกว่าประวัติมาตรฐานจะยืนยันการส่ง ลองซ้ำโดยเพิ่มช่วงหน่วงก่อนแสดงการดำเนินการลองซ้ำ/ลบ และหมดอายุแทนการส่งหลังออฟไลน์ 48 ชั่วโมง การรีเซ็ต/ลืมจะล้างคิวพร้อมกับแคช
• แชทเป็นหน้าจอเดียวสำหรับข้อความและเสียง การดำเนินการในแชทสามารถเปิดหน้าจอเซสชันแบบเต็มโดยไม่ออกจากแชท และสามารถแสดงหรือซ่อนกระบวนการให้เหตุผลของผู้ช่วยและกิจกรรมของเครื่องมือได้ แตะไมโครโฟนเพื่อป้อนเสียงเป็นฉบับร่าง เปิดเมนูของไมโครโฟนเพื่อบันทึกข้อความเสียง หรือใช้ตัวควบคุม Talk แบบอินไลน์สำหรับเสียงแบบเรียลไทม์ ตัวควบคุม Talk จะแสดงภาพเคลื่อนไหวตามระดับเสียงสดจากไมโครโฟนหรือการเล่นเสียงขณะกำลังฟังหรือพูด
• อ่านออกเสียงข้อความของผู้ช่วยเมื่อต้องการ: กดข้อความในแชทค้างไว้แล้วเลือก Listen แอปจะเล่นคลิป tts.speak จาก Gateway ที่รองรับด้วยผู้ให้บริการ TTS ที่กำหนดค่าไว้ และใช้การสังเคราะห์เสียงบนอุปกรณ์แทนเมื่อเสียงจาก Gateway ใช้งานไม่ได้หรือเล่นไม่ได้ การเล่นจะหยุดเมื่อสลับเซสชันหรือเมื่อแอปเข้าสู่เบื้องหลัง

ข้อกำหนด

• Gateway ทำงานอยู่บนอุปกรณ์อื่น (macOS, Linux หรือ Windows ผ่าน WSL2)
• เส้นทางเครือข่าย:
  • LAN เดียวกันผ่าน Bonjour หรือ
  • Tailnet ผ่าน unicast DNS-SD (โดเมนตัวอย่าง: openclaw.internal.) หรือ
  • โฮสต์/พอร์ตที่ระบุด้วยตนเอง (ทางเลือกสำรอง)

เริ่มต้นอย่างรวดเร็ว (จับคู่ + เชื่อมต่อ)

เมื่อเปิดแอปครั้งแรก แอปจะแนะนำคำอธิบายสั้น ๆ เกี่ยวกับการจับคู่และหน้า สิทธิ์ (การแจ้งเตือน, กล้อง, ไมโครโฟน, รูปภาพ, รายชื่อ, ปฏิทิน, เตือนความจำ, ตำแหน่งที่ตั้ง) การให้สิทธิ์ทั้งหมดเป็นทางเลือกและสามารถเปลี่ยนแปลงได้ ภายหลังใน Settings -> Permissions หรือในแอป Settings ของ iOS

1. เริ่ม Gateway ที่ยืนยันตัวตนแล้วโดยใช้เส้นทางที่โทรศัพท์เข้าถึงได้ Tailscale Serve เป็นเส้นทางระยะไกลที่แนะนำ:

openclaw gateway --port 18789 --tailscale serve

สำหรับการตั้งค่าบน LAN เดียวกันที่เชื่อถือได้ ให้ใช้ gateway.bind: "lan" ที่ยืนยันตัวตนแล้ว แทน ค่าเริ่มต้นที่ผูกกับ loopback ไม่สามารถเข้าถึงได้จากโทรศัพท์ หากยังไม่ได้ กำหนดค่า Gateway ให้เรียกใช้ openclaw onboard ก่อน เพื่อให้การสร้างรหัสตั้งค่า มีเส้นทางการยืนยันตัวตนด้วยโทเค็นหรือรหัสผ่าน

2. เปิด UI ควบคุม เลือก Nodes แล้วคลิก Pair mobile device ในหน้า Devices แนะนำให้ใช้สิทธิ์เข้าถึงแบบเต็ม และจะถูกเลือกไว้โดยค่าเริ่มต้น เลือก Limited access เฉพาะเมื่อต้องการละเว้น ตัวควบคุมการดูแลระบบของ Gateway จากนั้นคลิก Create setup code

3. ในแอป iOS เปิด Settings -> Gateway สแกนคิวอาร์โค้ด (หรือวาง รหัสตั้งค่า) แล้วเชื่อมต่อ

   หากรหัสตั้งค่ามีทั้งเส้นทาง LAN และ Tailscale Serve แอป จะตรวจสอบตามลำดับและบันทึกปลายทางแรกที่เข้าถึงได้

   Gateway ที่จับคู่แล้วจะยังคงอยู่ในรายการ Gateways เครื่องหมายถูกระบุ Gateway ที่โฟกัสอยู่ ใช้ตัวควบคุมรูปสายฟ้าในแถวอื่นเพื่อคงการเชื่อมต่อ เซสชันผู้ควบคุมของ Gateway นั้นไว้พร้อมกัน การสลับโฟกัสจะไม่ ตัดการเชื่อมต่อ Gateway อื่นที่เปิดใช้งานอยู่ เฉพาะ Gateway ที่โฟกัสเท่านั้นที่ได้รับ เซสชัน Node ของ iPhone ซึ่งมีความสามารถของอุปกรณ์ ดังนั้นคำสั่งกล้อง หน้าจอ ตำแหน่งที่ตั้ง และ คำสั่งอื่น ๆ ของอุปกรณ์จะมีเจ้าของที่ชัดเจนเพียงรายเดียวเสมอ iOS อาจพัก การเชื่อมต่อเบื้องหน้าเหล่านี้หลังจากแอปเข้าสู่เบื้องหลัง

4. แอปอย่างเป็นทางการจะเชื่อมต่อโดยอัตโนมัติ หาก Pending approval แสดง คำขอ ให้ตรวจสอบบทบาทและขอบเขตของคำขอก่อนอนุมัติ

   Settings → Gateway แสดงว่าการเชื่อมต่อผู้ควบคุมที่บันทึกไว้มีสิทธิ์เข้าถึงแบบ Full หรือ Limited การตั้งค่า LAN แบบข้อความธรรมดา ws:// จะถูก จำกัดโดยอัตโนมัติเพื่อความปลอดภัยของ bearer token หากถูกจำกัด ให้กำหนดค่า wss:// หรือ Tailscale Serve สแกนรหัสสิทธิ์เต็มใหม่จาก UI ควบคุมหรือ openclaw qr แล้วเชื่อมต่อใหม่เพื่อเปิดใช้การตั้งค่าและการอัปเกรด

ปุ่ม UI ควบคุมต้องใช้เซสชันที่จับคู่ไว้แล้วซึ่งมี operator.admin หากต้องใช้เทอร์มินัลเป็นทางเลือกสำรอง ให้เลือก Gateway ที่ค้นพบในแอป iOS (หรือเปิดใช้ Manual Host แล้วป้อนโฮสต์/พอร์ต) จากนั้นอนุมัติคำขอบนโฮสต์ Gateway:

openclaw devices listopenclaw devices approve <requestId>

หากแอปลองจับคู่ใหม่โดยเปลี่ยนรายละเอียดการยืนยันตัวตน (บทบาท/ขอบเขต/คีย์สาธารณะ) คำขอที่รออนุมัติก่อนหน้าจะถูกแทนที่และสร้าง requestId ใหม่ เรียกใช้ openclaw devices list อีกครั้งก่อนอนุมัติ

ไม่บังคับ: หาก Node iOS เชื่อมต่อจากซับเน็ตที่ควบคุมอย่างเข้มงวดเสมอ คุณสามารถเลือกเปิดใช้การอนุมัติ Node ครั้งแรกโดยอัตโนมัติด้วย CIDR หรือ IP ที่ระบุอย่างชัดเจน:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

ฟังก์ชันนี้ปิดใช้งานโดยค่าเริ่มต้น และใช้เฉพาะกับการจับคู่ role: node ใหม่ที่ไม่ได้ร้องขอขอบเขตเท่านั้น การจับคู่ผู้ควบคุม/เบราว์เซอร์ และการเปลี่ยนแปลงบทบาท ขอบเขต เมทาดาทา หรือคีย์สาธารณะใด ๆ ยังคงต้องได้รับการอนุมัติด้วยตนเอง

5. ตรวจสอบการเชื่อมต่อ:

openclaw nodes statusopenclaw gateway call node.list --params "{}"

สรุปข้อมูลสุขภาพ

Node iOS สามารถส่งคืนข้อมูลรวม HealthKit แบบอ่านอย่างเดียวและเลือกเข้าร่วมสำหรับ วันปฏิทินปัจจุบันได้ ความยินยอมบนอุปกรณ์ iOS และการอนุญาตคำสั่ง Gateway อย่างชัดแจ้งเป็น ด่านตรวจที่แยกจากกัน ดู สรุป HealthKit สำหรับ การตั้งค่า การเรียกใช้ ฟิลด์เพย์โหลด พฤติกรรมด้านความเป็นส่วนตัว และการแก้ไขปัญหา

โดยค่าเริ่มต้น แอปคู่หูบน Apple Watch จะยังคงใช้รีเลย์ของ iPhone ที่มีอยู่และ ไม่จำเป็นต้องจับคู่ Gateway แยกต่างหาก จับคู่ Watch กับ iPhone ใน แอป Watch ของ Apple ติดตั้ง OpenClaw จาก Watch app -> My Watch -> Available Apps จากนั้นเปิด OpenClaw หนึ่งครั้งบนอุปกรณ์ทั้งสอง

ตรวจสอบการอนุมัติคำสั่ง

การเชื่อมต่อผู้ควบคุมที่มี operator.admin หรือการเชื่อมต่อ operator.approvals ที่จับคู่ไว้และ Gateway ระบุเป็นเป้าหมายอย่างชัดเจน สามารถตรวจสอบ คำขอ exec ที่รอดำเนินการบน iPhone ได้ การ์ดอนุมัติแสดงตัวอย่างคำสั่งที่ Gateway ปรับให้ปลอดภัยแล้ว คำเตือน บริบทของโฮสต์ เวลาหมดอายุ และเฉพาะ ตัวเลือกการตัดสินใจที่คำขอนั้นเสนอ Apple Watch ที่จับคู่ไว้จะได้รับ พรอมต์ที่ปลอดภัยสำหรับผู้ตรวจสอบแบบเดียวกันผ่านรีเลย์ของ iPhone ที่มีอยู่ และมีชุดตัวเลือก อนุญาตครั้งเดียว/ปฏิเสธแบบย่อ โหมด Gateway โดยตรงของ Watch จะไม่ส่ง พรอมต์การอนุมัติ

สถานะการอนุมัติจะใช้ร่วมกับ UI ควบคุมและหน้าจอแชทที่รองรับ คำตอบแรกที่ยืนยันแล้วมีผล iPhone และ Watch จะดึงระเบียน เทอร์มินัลมาตรฐานของ Gateway หลังจากหน้าจออื่นแก้ไขคำขอ หลังจากได้รับการแจ้งเตือน ว่าแก้ไขจากระยะไกลแล้ว และเมื่อใดก็ตามที่การตอบรับการแก้ไขอาจ สูญหาย การดำเนินการจะยังใช้งานไม่ได้จนกว่าการอ่านกลับจะยืนยันว่า คำขอยังคงรอดำเนินการอยู่หรือไม่

ความเป็นเจ้าของการอนุมัติผูกกับ Gateway ที่เลือก การสลับ Gateway ไม่สามารถ นำพรอมต์เก่าไปใช้กับการเชื่อมต่อใหม่ได้ Gateway ที่มีอยู่ก่อน วิธีการอนุมัติแบบรวมจะใช้วิธีการเฉพาะสำหรับ exec ที่เผยแพร่แล้วเป็นทางเลือกสำรอง สถานะเทอร์มินัลที่คงอยู่และผลลัพธ์ข้ามหน้าจอที่มีรายละเอียดมากขึ้นต้องใช้ Gateway ที่อัปเดตแล้ว

ตอบคำถามของเอเจนต์

แชทจะแสดงคำถามจาก Gateway ที่รอดำเนินการเป็นการ์ดเนทีฟสำหรับการเชื่อมต่อผู้ควบคุม ที่มี operator.questions (หรือ operator.admin) การ์ดรองรับตัวเลือกแบบเลือกได้หนึ่งรายการและ หลายรายการ คำอธิบายตัวเลือก คำตอบ Other แบบข้อความอิสระ และ การนับถอยหลังจนหมดอายุ การเชื่อมต่อใหม่จะโหลดคำถามที่รอดำเนินการจาก Gateway อีกครั้ง การ์ด จะล็อกเมื่ออุปกรณ์นี้ตอบคำถาม หน้าจออื่นตอบก่อน หรือ คำถามหมดอายุหรือถูกยกเลิก

Node โดยตรงบน Apple Watch แบบไม่บังคับ

โหมดโดยตรงทำให้ Watch มีข้อมูลประจำตัว Node ที่ลงนามแล้วและการเชื่อมต่อ Gateway เป็นของตนเอง คำสั่ง Node ที่รองรับยังคงทำงานผ่าน Wi-Fi หรือเครือข่ายเซลลูลาร์ของ Watch ขณะที่ OpenClaw ทำงานอยู่ แม้ว่า iPhone ที่จับคู่ไว้จะไม่พร้อมใช้งาน

ข้อกำหนด:

• iPhone เชื่อมต่อกับ Gateway โดยมีขอบเขต operator.admin
• รหัสตั้งค่าประกาศปลายทาง Gateway แบบ wss:// พร้อมใบรับรองที่ watchOS เชื่อถือ Watch จะสำรวจต้นทาง https:// ที่สอดคล้องกัน ไม่รองรับ HTTP แบบข้อความธรรมดาและ ความเชื่อถือแบบลงนามด้วยตนเองหรืออาศัยลายนิ้วมือเพียงอย่างเดียว ดู การจับคู่ที่ Gateway เป็นเจ้าของ สำหรับการกำหนดค่าปลายทาง เส้นทาง loopback, เฉพาะ iPhone และเฉพาะ tailnet ไม่สามารถเข้าถึงได้โดยอิสระจาก Watch
• การใช้งานเครือข่ายเซลลูลาร์ต้องใช้ Apple Watch ที่รองรับเซลลูลาร์และมีบริการที่ใช้งานอยู่
• OpenClaw ทำงานอยู่บน Watch Apple ไม่อนุญาตให้แอป watchOS ทั่วไป รักษาการเชื่อมต่อ WebSocket/TCP แบบทั่วไปไว้ ดังนั้น Node โดยตรงจึงใช้การสำรวจ HTTPS ระยะสั้นและเชื่อมต่อใหม่เมื่อแอปกลับสู่เบื้องหน้า ดู แนวทางเครือข่ายระดับต่ำของ watchOS จาก Apple

การตั้งค่า:

1. บน iPhone เปิด Settings -> Apple Watch
2. แตะ Enable Direct Gateway Connection
3. เปิด OpenClaw บน Watch ก่อนรหัสตั้งค่าอายุสั้นจะหมดอายุ
4. ตรวจสอบแถว Apple Watch แยกต่างหากด้วย openclaw nodes status

รหัสตั้งค่ามีข้อมูลประจำตัวสำหรับบูตสแตรปเฉพาะ Node ที่มีอายุสั้น ให้ถือว่าเป็น รหัสผ่านจนกว่าจะหมดอายุ รหัสนี้จะไม่มีรหัสผ่านหรือโทเค็น Gateway ที่บันทึกไว้ของ iPhone หลังจากจับคู่แล้ว Watch จะจัดเก็บโทเค็นอุปกรณ์ของตนเองและ ลบข้อมูลประจำตัวสำหรับบูตสแตรป โหมดโดยตรงครอบคลุมเฉพาะคำสั่งด้านล่าง แชท, Talk, การอนุมัติ และโฟลว์การแจ้งเตือน watch.* ที่มีอยู่ยังคงเป็น ฟีเจอร์รีเลย์ผ่าน iPhone และยังต้องใช้ iPhone ที่จับคู่ไว้

คำสั่ง Node โดยตรงของ watchOS:

watchOS ไม่เปิดเผย WebKit ให้แอปของบุคคลที่สาม ดังนั้น Node โดยตรงบน Watch จึงไม่ประกาศคำสั่ง Canvas

พุชผ่านรีเลย์สำหรับบิลด์อย่างเป็นทางการ

บิลด์ iOS อย่างเป็นทางการที่เผยแพร่จะใช้รีเลย์พุชภายนอกแทนการเผยแพร่โทเค็น APNs ดิบไปยัง Gateway บิลด์ App Store อย่างเป็นทางการจากช่องทางรีลีสสาธารณะใช้รีเลย์ที่โฮสต์ไว้ที่ https://ios-push-relay.openclaw.ai โดย URL ฐานนี้ถูกกำหนดไว้ตายตัวสำหรับการเผยแพร่ผ่าน App Store และจะไม่อ่านค่าทดแทนใด ๆ

การติดตั้งใช้งานรีเลย์แบบกำหนดเองต้องใช้เส้นทางการบิลด์/ติดตั้งใช้งาน iOS ที่แยกต่างหากโดยเจตนา ซึ่ง URL รีเลย์ตรงกับ URL รีเลย์ของ Gateway ช่องทางรีลีส App Store จะไม่ยอมรับ URL รีเลย์แบบกำหนดเอง หากใช้บิลด์รีเลย์แบบกำหนดเอง ให้ตั้งค่า URL รีเลย์ของ Gateway ให้ตรงกัน:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",        },      },    },  },}

โฟลว์ทำงานดังนี้:

• แอป iOS ลงทะเบียนกับรีเลย์โดยใช้ App Attest และ JWS ของธุรกรรมแอป StoreKit
• รีเลย์ส่งคืนแฮนเดิลรีเลย์แบบทึบพร้อมสิทธิ์ส่งที่จำกัดขอบเขตเฉพาะการลงทะเบียน
• แอป iOS ดึงข้อมูลประจำตัวของ Gateway ที่จับคู่แล้ว (gateway.identity.get) และรวมข้อมูลดังกล่าวในการลงทะเบียนรีเลย์ เพื่อมอบหมายการลงทะเบียนที่ใช้รีเลย์นั้นให้กับ Gateway ดังกล่าวโดยเฉพาะ
• แอปส่งต่อการลงทะเบียนที่ใช้รีเลย์นั้นไปยัง Gateway ที่จับคู่แล้วด้วย push.apns.register
• Gateway ใช้แฮนเดิลรีเลย์ที่จัดเก็บไว้นั้นสำหรับ push.test การปลุกในเบื้องหลัง และการกระตุ้นให้ปลุก
• หากภายหลังแอปเชื่อมต่อกับ Gateway อื่นหรือบิลด์ที่มี URL ฐานของรีเลย์ต่างออกไป แอปจะรีเฟรชการลงทะเบียนรีเลย์แทนการใช้การผูกเดิมซ้ำ

สิ่งที่ Gateway ไม่ จำเป็นต้องมีสำหรับเส้นทางนี้: ไม่ต้องมีโทเค็นรีเลย์ที่ใช้ทั่วทั้งการปรับใช้ และไม่ต้องมีคีย์ APNs โดยตรงสำหรับการส่งผ่านรีเลย์อย่างเป็นทางการของ App Store

ขั้นตอนที่คาดหวังสำหรับผู้ดำเนินการ:

1. ติดตั้งแอป iOS อย่างเป็นทางการ
2. ไม่บังคับ: ตั้งค่า gateway.push.apns.relay.baseUrl บน Gateway เฉพาะเมื่อใช้บิลด์รีเลย์แบบกำหนดเองที่แยกออกจากกันโดยเจตนา
3. จับคู่แอปกับ Gateway และรอให้แอปเชื่อมต่อจนเสร็จสมบูรณ์
4. แอปเผยแพร่ push.apns.register เมื่อได้รับโทเค็น APNs เซสชันผู้ดำเนินการเชื่อมต่อแล้ว และการลงทะเบียนรีเลย์สำเร็จ
5. หลังจากนั้น push.test การปลุกเพื่อเชื่อมต่อใหม่ และการกระตุ้นให้ปลุกจะใช้การลงทะเบียนที่ใช้รีเลย์ซึ่งจัดเก็บไว้ได้

บีคอนยืนยันว่ายังทำงานอยู่ในเบื้องหลัง

เมื่อ iOS ปลุกแอปเนื่องจากพุชแบบเงียบ การรีเฟรชในเบื้องหลัง หรือเหตุการณ์การเปลี่ยนแปลงตำแหน่งอย่างมีนัยสำคัญ แอปจะพยายามเชื่อมต่อ Node ใหม่เป็นเวลาสั้น ๆ แล้วเรียก node.event ด้วย event: "node.presence.alive" Gateway จะบันทึกข้อมูลนี้เป็น lastSeenAtMs/lastSeenReason ในเมทาดาทาของ Node/อุปกรณ์ที่จับคู่แล้ว เฉพาะหลังจากทราบข้อมูลประจำตัวของอุปกรณ์ Node ที่ผ่านการตรวจสอบสิทธิ์แล้วเท่านั้น

แอปจะถือว่าการปลุกในเบื้องหลังได้รับการบันทึกสำเร็จ เฉพาะเมื่อการตอบกลับของ Gateway มี handled: true Gateway รุ่นเก่าอาจตอบรับ node.event ด้วย { "ok": true } การตอบกลับดังกล่าวเข้ากันได้ แต่ไม่นับเป็นการอัปเดตเวลาที่พบล่าสุดแบบคงทน

หมายเหตุเกี่ยวกับความเข้ากันได้:

• OPENCLAW_APNS_RELAY_BASE_URL ยังคงใช้เป็นการแทนที่ชั่วคราวผ่านตัวแปรสภาพแวดล้อมสำหรับ Gateway ได้ (gateway.push.apns.relay.baseUrl เป็นเส้นทางที่ให้ความสำคัญกับการกำหนดค่าก่อน)
• โหมดพุชของบิลด์รุ่นเผยแพร่บน App Store กำหนดโฮสต์รีเลย์ที่โฮสต์ไว้ตายตัวและจะไม่อ่านค่าการแทนที่ URL ของรีเลย์ ตัวแปรสภาพแวดล้อมขณะบิลด์ OPENCLAW_PUSH_RELAY_BASE_URL มีผลเฉพาะกับโหมดบิลด์ iOS แบบภายในเครื่อง/แซนด์บ็อกซ์เท่านั้น

ขั้นตอนการตรวจสอบสิทธิ์และความเชื่อถือ

รีเลย์มีไว้เพื่อบังคับใช้ข้อจำกัดสองประการที่การใช้ APNs โดยตรงบน Gateway ไม่สามารถรองรับสำหรับบิลด์ iOS อย่างเป็นทางการ:

• เฉพาะบิลด์ OpenClaw iOS ของแท้ที่เผยแพร่ผ่าน Apple เท่านั้นที่สามารถใช้รีเลย์ที่โฮสต์ไว้
• Gateway สามารถส่งพุชที่ใช้รีเลย์ได้เฉพาะสำหรับอุปกรณ์ iOS ที่จับคู่กับ Gateway นั้นโดยเฉพาะ

แต่ละช่วงการเชื่อมต่อมีดังนี้:

1. iOS app -> gateway: แอปจับคู่กับ Gateway ผ่านขั้นตอนการตรวจสอบสิทธิ์ตามปกติของ Gateway ทำให้ได้รับทั้งเซสชัน Node ที่ผ่านการตรวจสอบสิทธิ์และเซสชันผู้ดำเนินการที่ผ่านการตรวจสอบสิทธิ์ เซสชันผู้ดำเนินการเรียก gateway.identity.get
2. iOS app -> relay: แอปเรียกปลายทางการลงทะเบียนของรีเลย์ผ่าน HTTPS โดยส่งหลักฐาน App Attest พร้อม JWS ของธุรกรรมแอป StoreKit รีเลย์ตรวจสอบ bundle ID, หลักฐาน App Attest และหลักฐานการเผยแพร่ของ Apple รวมทั้งกำหนดให้ใช้เส้นทางการเผยแพร่อย่างเป็นทางการ/สำหรับใช้งานจริง ซึ่งเป็นสิ่งที่ป้องกันไม่ให้บิลด์ Xcode/สำหรับการพัฒนาภายในเครื่องใช้รีเลย์ที่โฮสต์ไว้ เพราะบิลด์ภายในเครื่องไม่สามารถแสดงหลักฐานการเผยแพร่อย่างเป็นทางการของ Apple ได้
3. gateway identity delegation: ก่อนลงทะเบียนรีเลย์ แอปจะดึงข้อมูลประจำตัวของ Gateway ที่จับคู่แล้วจาก gateway.identity.get และรวมไว้ในเพย์โหลดการลงทะเบียนรีเลย์ รีเลย์จะส่งคืนแฮนเดิลรีเลย์และสิทธิ์ส่งที่จำกัดขอบเขตเฉพาะการลงทะเบียน ซึ่งมอบหมายให้กับข้อมูลประจำตัวของ Gateway นั้น
4. gateway -> relay: Gateway จัดเก็บแฮนเดิลรีเลย์และสิทธิ์ส่งจาก push.apns.register เมื่อเกิด push.test การปลุกเพื่อเชื่อมต่อใหม่ และการกระตุ้นให้ปลุก Gateway จะลงนามคำขอส่งด้วยข้อมูลประจำตัวของอุปกรณ์ตนเอง รีเลย์จะตรวจสอบทั้งสิทธิ์ส่งที่จัดเก็บไว้และลายเซ็นของ Gateway เทียบกับข้อมูลประจำตัวของ Gateway ที่ได้รับมอบหมายระหว่างการลงทะเบียน Gateway อื่นไม่สามารถใช้การลงทะเบียนที่จัดเก็บไว้นั้นซ้ำได้ แม้จะได้แฮนเดิลมาด้วยวิธีใดก็ตาม
5. relay -> APNs: รีเลย์เป็นผู้ถือครองข้อมูลประจำตัว APNs สำหรับใช้งานจริงและโทเค็น APNs ดิบสำหรับบิลด์อย่างเป็นทางการ Gateway จะไม่จัดเก็บโทเค็น APNs ดิบสำหรับบิลด์อย่างเป็นทางการที่ใช้รีเลย์ รีเลย์จะส่งพุชขั้นสุดท้ายไปยัง APNs ในนามของ Gateway ที่จับคู่แล้ว

เหตุผลที่สร้างการออกแบบนี้ขึ้น: เพื่อเก็บข้อมูลประจำตัว APNs สำหรับใช้งานจริงไว้นอก Gateway ของผู้ใช้ หลีกเลี่ยงการจัดเก็บโทเค็น APNs ดิบของบิลด์อย่างเป็นทางการบน Gateway อนุญาตให้เฉพาะบิลด์ OpenClaw iOS อย่างเป็นทางการใช้รีเลย์ที่โฮสต์ไว้ และป้องกันไม่ให้ Gateway หนึ่งส่งพุชปลุกไปยังอุปกรณ์ iOS ที่เป็นของ Gateway อื่น

บิลด์ภายในเครื่อง/แบบติดตั้งด้วยตนเองยังคงใช้ APNs โดยตรง หากกำลังทดสอบบิลด์เหล่านั้นโดยไม่ใช้รีเลย์ Gateway ยังคงต้องมีข้อมูลประจำตัว APNs โดยตรง:

export OPENCLAW_APNS_TEAM_ID="TEAMID"export OPENCLAW_APNS_KEY_ID="KEYID"export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"

รายการเหล่านี้เป็นตัวแปรสภาพแวดล้อมรันไทม์ของโฮสต์ Gateway ไม่ใช่การตั้งค่า Fastlane โดย apps/ios/fastlane/.env จะจัดเก็บเฉพาะข้อมูลการตรวจสอบสิทธิ์ของ App Store Connect เช่น APP_STORE_CONNECT_KEY_ID และ APP_STORE_CONNECT_ISSUER_ID เท่านั้น และไม่ได้กำหนดค่าการส่ง APNs โดยตรงสำหรับบิลด์ iOS ภายในเครื่อง

ตำแหน่งจัดเก็บที่แนะนำบนโฮสต์ Gateway ซึ่งสอดคล้องกับข้อมูลประจำตัวของผู้ให้บริการรายอื่นภายใต้ ~/.openclaw/credentials/:

mkdir -p ~/.openclaw/credentials/apnschmod 700 ~/.openclaw/credentials/apnsmv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"

อย่าคอมมิตไฟล์ .p8 หรือวางไฟล์ดังกล่าวไว้ภายใต้เช็กเอาต์ของรีโพซิทอรี

เส้นทางการค้นหา

Bonjour (LAN)

แอป iOS เรียกดู _openclaw-gw._tcp บน local. และเมื่อกำหนดค่าไว้ จะเรียกดูโดเมนการค้นหา DNS-SD แบบเครือข่ายบริเวณกว้างเดียวกันด้วย Gateway ที่อยู่ใน LAN เดียวกันจะปรากฏโดยอัตโนมัติจาก local. ส่วนการค้นหาข้ามเครือข่ายสามารถใช้โดเมนแบบเครือข่ายบริเวณกว้างที่กำหนดค่าไว้ได้โดยไม่ต้องเปลี่ยนประเภทบีคอน

Tailnet (ข้ามเครือข่าย)

หาก mDNS ถูกบล็อก ให้ใช้โซน DNS-SD แบบยูนิแคสต์ (เลือกโดเมน เช่น openclaw.internal.) และ DNS แบบแยกของ Tailscale ดูตัวอย่าง CoreDNS ที่ Bonjour

โฮสต์/พอร์ตแบบกำหนดเอง

ใน Settings ให้เปิดใช้ Manual Host แล้วป้อนโฮสต์และพอร์ตของ Gateway (ค่าเริ่มต้น 18789)

Gateway หลายรายการ

แอปเก็บรีจิสทรีของ Gateway ทุกตัวที่เคยจับคู่ไว้ เพื่อให้สลับระหว่างกันได้โดยไม่ต้องจับคู่ใหม่:

• Settings -> Gateway แสดงรายการ Paired Gateways พร้อมทำเครื่องหมาย Gateway ที่ใช้งานอยู่ แตะรายการเพื่อสลับ แอปจะยุติเซสชันปัจจุบันและเชื่อมต่อกับ Gateway ที่เลือกใหม่ เมนูสลับด่วนจะปรากฏถัดจากแถวการเชื่อมต่อเมื่อจับคู่ Gateway มากกว่าหนึ่งรายการ
• ข้อมูลประจำตัว การตัดสินใจเกี่ยวกับความเชื่อถือ TLS การกำหนดลักษณะเฉพาะแต่ละ Gateway และประวัติแชตที่แคชไว้จะจัดเก็บแยกตาม Gateway การสลับจะไม่ผสมสถานะระหว่าง Gateway และการลงทะเบียนพุชจะติดตาม Gateway ที่ใช้งานอยู่
• ปัด Gateway ที่จับคู่แล้ว (หรือใช้เมนูบริบทของ Gateway นั้น) เพื่อเลือก Forget ซึ่งจะลบข้อมูลประจำตัว โทเค็นอุปกรณ์ พิน TLS และแชตที่แคชไว้
• Gateway ที่ค้นพบต้องมองเห็นได้บนเครือข่ายจึงจะสลับไปใช้ได้ ส่วน Gateway แบบกำหนดเองจะเชื่อมต่อใหม่โดยใช้โฮสต์และพอร์ตที่บันทึกไว้

Canvas + A2UI

Node iOS แสดงผล Canvas แบบ WKWebView ใช้ node.invoke เพื่อควบคุม:

openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/canvas/"}'

หมายเหตุ:

• โฮสต์ Canvas ของ Gateway ให้บริการ /__openclaw__/canvas/ และ /__openclaw__/a2ui/ จากเซิร์ฟเวอร์ HTTP ของ Gateway (พอร์ตเดียวกับ gateway.port ค่าเริ่มต้น 18789)
• Node iOS ใช้โครงเริ่มต้นในตัวเป็นมุมมองเริ่มต้นเมื่อเชื่อมต่อ canvas.a2ui.push และ canvas.a2ui.reset ใช้หน้า A2UI ที่รวมมากับแอปและเป็นของแอป
• หน้า A2UI ของ Gateway ระยะไกลแสดงผลได้อย่างเดียวบน iOS ระบบจะยอมรับการทำงานของปุ่ม A2UI แบบเนทีฟเฉพาะจากหน้าที่รวมมากับแอปและเป็นของแอปเท่านั้น
• กลับไปยังโครงเริ่มต้นในตัวด้วย canvas.navigate และ {"url":""}

ความสัมพันธ์กับ Computer Use

แอป iOS เป็นพื้นผิว Node บนอุปกรณ์เคลื่อนที่ ไม่ใช่แบ็กเอนด์ Codex Computer Use โดย Codex Computer Use และ cua-driver mcp ควบคุมเดสก์ท็อป macOS ภายในเครื่องผ่านเครื่องมือ MCP ส่วนแอป iOS เปิดให้ใช้ความสามารถของ iPhone ผ่านคำสั่ง Node ของ OpenClaw เช่น canvas.*, camera.*, screen.*, location.* และ talk.*

Agent ยังคงควบคุมแอป iOS ผ่าน OpenClaw ได้โดยเรียกใช้คำสั่ง Node แต่การเรียกเหล่านั้นจะผ่านโปรโตคอล Node ของ Gateway และอยู่ภายใต้ข้อจำกัดการทำงานเบื้องหน้า/เบื้องหลังของ iOS ใช้ Codex Computer Use สำหรับการควบคุมเดสก์ท็อปภายในเครื่อง และใช้หน้านี้สำหรับความสามารถของ Node iOS

การประเมินผล / สแนปช็อตของ Canvas

openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'

openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

การปลุกด้วยเสียง + โหมดสนทนา

• การปลุกด้วยเสียงและโหมดสนทนามีให้ใช้ใน Settings
• การสนทนาแบบเรียลไทม์ของ OpenAI ใช้ WebRTC ที่ไคลเอนต์เป็นผู้ควบคุมเมื่อ talk.realtime.transport เป็น webrtc ส่วนการกำหนดค่า gateway-relay อย่างชัดเจนยังคงอยู่ภายใต้การควบคุมของ Gateway ดู โหมดสนทนา
• Node iOS ที่รองรับการสนทนาจะประกาศความสามารถ talk และสามารถประกาศ talk.ptt.start, talk.ptt.stop, talk.ptt.cancel และ talk.ptt.once ได้ Gateway อนุญาตคำสั่งกดเพื่อพูดเหล่านั้นโดยค่าเริ่มต้นสำหรับ Node ที่เชื่อถือได้และรองรับการสนทนา
• iOS อาจระงับเสียงในเบื้องหลัง ให้ถือว่าฟีเจอร์เสียงทำงานแบบพยายามให้ดีที่สุดเมื่อแอปไม่ได้ทำงานอยู่

ข้อผิดพลาดทั่วไป

• NODE_BACKGROUND_UNAVAILABLE: นำแอป iOS มาไว้เบื้องหน้า (คำสั่ง Canvas/กล้อง/หน้าจอต้องใช้แอปในเบื้องหน้า)
• A2UI_HOST_UNAVAILABLE: ไม่สามารถเข้าถึงหน้า A2UI ที่รวมมากับแอปใน WebView ของแอปได้ ให้เปิดแอปค้างไว้เบื้องหน้าที่แท็บ Screen แล้วลองอีกครั้ง
• ข้อความแจ้งให้จับคู่ไม่ปรากฏ: เรียกใช้ openclaw devices list และอนุมัติด้วยตนเอง
• Watch ไม่แสดงสถานะของ iPhone: ยืนยันว่า iPhone รายงาน watchPaired: true และ watchAppInstalled: true ใน watch.status หากสถานะการจับคู่เป็น false ให้จับคู่ Watch ในแอป Watch ของ Apple หากสถานะการติดตั้งเป็น false ให้ติดตั้งแอปคู่หู จาก My Watch -> Available Apps หลังจากเปลี่ยนแปลงรายการใดรายการหนึ่งแล้ว ให้เปิด OpenClaw บน Watch หนึ่งครั้ง การเข้าถึงได้ทันทีจะยังคงกำหนดให้ทั้งสองแอปทำงานอยู่ ส่วนการอัปเดตที่เข้าคิวไว้สามารถมาถึงภายหลังในเบื้องหลังได้
• เชื่อมต่อใหม่ไม่สำเร็จหลังติดตั้งใหม่: โทเค็นการจับคู่ใน Keychain ถูกล้างแล้ว ให้จับคู่ Node ใหม่

เอกสารที่เกี่ยวข้อง

• การจับคู่
• การค้นหา
• Bonjour