Cloud Workers

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

เมื่องานเสร็จสิ้น (หรือกล่องหยุดทำงาน) เครื่องจะถูกทิ้ง สถานะถาวร ได้แก่ ทรานสคริปต์ คอมมิตของเวิร์กสเปซ และระเบียนการจัดวาง จะอยู่กับ Gateway

สิ่งใดทำงานที่ไหน

กล่องไม่ต้องใช้พอร์ตขาเข้าใดนอกจาก sshd: Gateway เชื่อมต่อออกผ่าน SSH ที่ตรึงไว้ และทันเนลย้อนกลับจะส่ง WebSocket ของ worker กลับมา ผู้ให้บริการ Crabbox ที่รวมมาให้บังคับใช้เส้นทาง SSH สาธารณะและปิดใช้การลงทะเบียน Tailscale ที่มีการจัดการ การเข้าถึงอินเทอร์เน็ตขาออกเป็นไปตามนโยบายของผู้ให้บริการ; โปรไฟล์ AWS เริ่มต้นสามารถเข้าถึงอินเทอร์เน็ตได้ เว้นแต่จะจำกัดเครือข่ายหรือกลุ่มความปลอดภัยของโปรไฟล์นั้น

ข้อกำหนด

• Plugin ผู้ให้บริการ worker Plugin crabbox ที่รวมมาให้ควบคุม CLI ของ Crabbox ซึ่งเป็นตัวกลางในการเช่าทรัพยากรจากแบ็กเอนด์คลาวด์ต่าง ๆ (AWS, Hetzner และอื่น ๆ) ไบนารี crabbox ต้องอยู่ใน PATH (หรือตั้งค่า settings.binary) และต้องกำหนดค่าข้อมูลประจำตัวของผู้ให้บริการไว้แล้ว การรับเข้าใช้งาน AWS ต้องใช้ Crabbox 0.38.1 หรือใหม่กว่า
• สำหรับ worker ของ Crabbox AWS ค่า aws.instanceProfile ที่มีผลต้องว่างเปล่า ผู้ให้บริการตรวจสอบ crabbox config show --json ก่อนจัดสรร จากนั้นกำหนดให้ crabbox inspect --json รายงาน providerMetadata.instanceProfileAttached: false จาก EC2 DescribeInstances การเช่าที่มีบทบาทอินสแตนซ์หรือไม่มีเมทาดาทาที่เชื่อถือได้จะถูกหยุดและปฏิเสธ
• Node.js บนเครื่องที่เช่า อิมเมจคลาวด์แบบพื้นฐานมักไม่มี Node.js — ให้ติดตั้งผ่านคำสั่ง setup ของโปรไฟล์
• เซสชันที่มี worktree แบบมีการจัดการซึ่งเซสชันเป็นเจ้าของ (สร้างด้วย worktree: true) การส่งงานจะย้ายเนื้อหาของ worktree นั้น; ไดเรกทอรีทั่วไปจะซิงค์เป็นสำเนามิเรอร์ตามแมนิเฟสต์

การกำหนดค่า

เพิ่มโปรไฟล์ภายใต้ cloudWorkers.profiles ใน openclaw.json:

{  "cloudWorkers": {    "profiles": {      "aws": {        "provider": "crabbox",        "install": "bundle",        "settings": {          "provider": "aws",          "class": "standard",          "ttl": "8h",          "idleTimeout": "45m",          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"        }      }    }  }}

ฟิลด์ของโปรไฟล์:

คำสั่งตั้งค่า

settings.setup ทำงานบนกล่องที่เช่าหลังจาก SSH พร้อมใช้งานและก่อนติดตั้ง OpenClaw คำสั่งนี้ทำงานในความพยายามจัดเตรียม ทุกครั้ง (รวมถึงการเล่นซ้ำหลังจากการส่งงานถูกขัดจังหวะ) ดังนั้นต้องทำงานซ้ำได้อย่างปลอดภัย — ป้องกันการติดตั้งด้วยการตรวจสอบ command -v/test -x ดังตัวอย่าง หากการตั้งค่าล้มเหลว ผู้ให้บริการจะหยุดการเช่าและการส่งงานจะล้มเหลวแบบปิดกั้น; จะไม่มีกล่องที่กำหนดค่าเพียงบางส่วนถูกปล่อยให้ทำงานอยู่

ช่องทางการติดตั้ง

• bundle แพ็ก dist ของ Gateway ที่กำลังทำงาน, package.json ที่ตัดส่วนไม่จำเป็นออก และแพ็กเกจเวิร์กสเปซใด ๆ ที่บิลด์อ้างอิง โดยทั้งหมดอยู่ภายใต้แฮชเนื้อหา กล่องจะตรวจสอบบันเดิลดั้งเดิมกับแฮชนั้น จากนั้นติดตั้งการขึ้นต่อกันของ npm สำหรับโปรดักชัน (ปิดใช้สคริปต์) วิธีนี้ใช้สำหรับเรียกบิลด์สำหรับการพัฒนาบน worker
• npm ยืนยันว่ารุ่นเผยแพร่มีอยู่ในรีจิสทรีสาธารณะ ตรึงค่าความถูกต้อง SHA-512 และติดตั้ง openclaw@<version> ให้ตรงกับ Gateway ทุกประการ

การส่งเซสชัน

ใน Control UI ให้เปิด New Session เลือกเอเจนต์ที่กำหนดค่ารันไทม์เป็น OpenClaw เลือกเป้าหมาย Cloud · profile ที่กำหนดค่าไว้จากเมนู Where แล้วเริ่มงาน การเลือกคลาวด์จะเปิดใช้ worktree แบบมีการจัดการที่จำเป็นโดยอัตโนมัติ; Gateway จะสร้างเซสชัน ส่งงานให้เสร็จสิ้น และส่งเทิร์นแรกหลังจากนั้นเท่านั้น ป้ายเซิร์ฟเวอร์ในแถบด้านข้างของเซสชันแสดงสถานะการจัดวางแบบถาวร เป้าหมายคลาวด์จะไม่แสดงสำหรับแค็ตตาล็อกเซสชัน CLI ภายนอก

ขั้นตอน RPC ที่เทียบเท่าคือ:

สร้างเซสชันพร้อม worktree แบบมีการจัดการ แล้วส่งงานไปยังเซสชันนั้น (RPC ต้องใช้ operator.admin และจะมีอยู่เฉพาะเมื่อกำหนดค่าโปรไฟล์แล้ว):

Cloud worker เรียกใช้รันไทม์เอเจนต์ OpenClaw เลือก openai/* หรือโมเดลอื่นที่แปลงไปยังรันไทม์นั้นได้; เซสชันที่กำหนดค่าให้ใช้รันไทม์ CLI ภายนอก เช่น claude-cli จะไม่สามารถส่งงานได้

openclaw gateway call sessions.create \  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}' openclaw gateway call sessions.dispatch \  --timeout 1500000 \  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'

sessions.dispatch ปิดการรับเทิร์นภายในเครื่อง รอให้งานที่กำลังทำอยู่สิ้นสุด จัดเตรียมการเช่า เรียกใช้การตั้งค่า บูตสแตรป OpenClaw ซิงค์เวิร์กสเปซ และส่งคืนเมื่อการจัดวางเข้าสู่การเป็นเจ้าของโดย worker ในสถานะ active ควรเผื่อเวลาหลายนาทีสำหรับการส่งงานครั้งแรก; การเช่าและการติดตั้งจะถูกแคชเมื่อผู้ให้บริการรองรับ หลังจากนั้นให้โต้ตอบกับเซสชันตามปกติ — เทิร์นจะถูกกำหนดเส้นทางไปยัง worker โดยอัตโนมัติ

เทิร์นของ worker ที่เสร็จสมบูรณ์จะปรับไฟล์เวิร์กสเปซที่เข้าเกณฑ์และมีขนาดไม่เกินขีดจำกัดกลับเข้าสู่ worktree แบบมีการจัดการของเซสชัน ก่อนปล่อยสิทธิ์การครอบครองเทิร์น เหตุการณ์สิ้นสุดของ worker จะสร้างแนวกั้นผลลัพธ์ที่รอดำเนินการแบบถาวรก่อนที่จะได้รับการตอบรับ จากนั้น Gateway จะจัดเตรียมผลลัพธ์คลาวด์ทั้งหมดเป็น Git ref ภายใต้ refs/openclaw/worker-results/ ก่อนนำไปใช้ ทำให้เวอร์ชันบนคลาวด์ยังกู้คืนได้แม้ Gateway หยุดระหว่างการนำไปใช้ ผลลัพธ์เวิร์กสเปซใช้ความหมายของไฟล์ตาม Git: เก็บรักษาไฟล์ปกติ บิตปฏิบัติการ ลิงก์สัญลักษณ์ การเพิ่ม การเปลี่ยนแปลง และการลบ ส่วนไดเรกทอรีว่างและโหมดไดเรกทอรีอื่นจะไม่ถูกเก็บรักษา การเปลี่ยนแปลงไฟล์ที่ได้จะคงอยู่ใน worktree แบบมีการจัดการเพื่อการตรวจสอบและคอมมิตตามปกติ

การนำไปใช้ใช้แมนิเฟสต์ ณ เวลาส่งงานเป็นฐานการผสาน การเปลี่ยนแปลงที่มีเฉพาะบนคลาวด์จะถูกนำไปใช้ การเปลี่ยนแปลงที่มีเฉพาะในเครื่องจะคงอยู่ และพาธที่เปลี่ยนแปลงทั้งสองฝั่งจะใช้นโยบายผสานสามทางแบบเก็บฝั่งในเครื่อง เทิร์นที่มีข้อขัดแย้งยังคงเสร็จสิ้นได้: ทรานสคริปต์จะรายงานสรุปพาธแบบจำกัดและ ref ของผลลัพธ์ที่จัดเตรียมไว้ การจัดวางจะแสดงข้อขัดแย้งเดียวกันสำหรับ Control UI และการเปลี่ยนแปลงบนคลาวด์ที่ไม่ขัดแย้งจะยังคงถูกนำไปใช้ ประกาศจะมี git show <ref>:<path> สำหรับตรวจสอบไฟล์บนคลาวด์ที่มีอยู่ และคำสั่ง git checkout <ref> -- <path> แบบ literal-pathspec ระดับบนสุดเพื่อดึงไฟล์นั้นจากไดเรกทอรีใดก็ได้ในเวิร์กสเปซ เรียกใช้คำสั่งใน Bash หรือ zsh (Git Bash บน Windows) หากคำสั่งตรวจสอบระบุว่าพาธไม่มีอยู่ แสดงว่าผลลัพธ์บนคลาวด์ลบพาธนั้นแล้ว; ให้ตรวจสอบและลบพาธในเครื่องที่เก็บไว้ด้วยตนเอง หาก checkout รายงานว่ามีไฟล์/ไดเรกทอรีกีดขวาง ให้ย้ายหรือลบพาธในเครื่องที่ขวางอยู่แล้วลองใหม่ หาก ref ที่จัดเตรียมไว้หายไป ให้ถือว่าประกาศล้าสมัยและอย่าเปลี่ยนพาธในเครื่อง ref ที่จัดเตรียมไว้ซึ่งมีข้อขัดแย้งจะยังคงพร้อมใช้งานหลังจากปล่อยแนวกั้นเทิร์นตามปกติ; ผลลัพธ์สะอาดในภายหลังจะล้างประกาศและเลิกใช้ ref เก่า ขณะที่การลบแนวกั้นอย่างชัดเจนเป็นขอบเขตการล้างข้อมูลขั้นสุดท้าย

ขณะที่ผลลัพธ์ซึ่งมีแนวกั้นยังอยู่ระหว่างการปรับข้อมูลให้สอดคล้อง เทิร์นใหม่จะรอสูงสุด 15 วินาทีให้สิทธิ์การครอบครองก่อนหน้าถูกปล่อย หากยังไม่ว่าง เทิร์นจะล้มเหลวพร้อมข้อความที่นำไปดำเนินการได้ว่า “ผลลัพธ์เวิร์กสเปซจากเทิร์นคลาวด์ก่อนหน้ายังอยู่ระหว่างการปรับข้อมูลให้สอดคล้อง” และสามารถลองใหม่ได้ในอีกสักครู่ เมื่อเริ่มระบบใหม่ กระบวนการกู้คืนจะค้นหาผลลัพธ์ที่รอดำเนินการและที่จัดเตรียมไว้ก่อนล้างสิทธิ์การครอบครองที่ล้าสมัย ดำเนินการหรือลองนำผลลัพธ์ไปใช้ในเครื่องอีกครั้ง และเรียกคืนสภาพแวดล้อมที่หยุดทำงานหลังจากรักษาผลลัพธ์ไว้แล้วเท่านั้น rollback journal ของ SQLite ที่มีขอบเขตจำกัดทำให้กู้คืนจากการนำไปใช้กับระบบไฟล์ที่ถูกขัดจังหวะได้ โดยไม่เล่นการเปลี่ยนแปลงที่ยอมรับแล้วซ้ำ

เมื่องานเสร็จสมบูรณ์และไม่มีเทิร์นกำลังทำงาน ให้เปิดเมนูเซสชันแล้วเลือก Stop cloud worker… Gateway จะปรับข้อมูลเวิร์กสเปซให้สอดคล้องเป็นครั้งสุดท้ายก่อนทำลายสภาพแวดล้อม การจัดวางที่อยู่ใน draining หรือ reconciling กำลังเสร็จสิ้นการรื้อถอน; รอให้ป้ายเปลี่ยนเป็น reclaimed ก่อนลบเซสชัน

สำหรับ worker ที่แนบอยู่ซึ่งเสียหายหรือทำงานผิดปกติจนควบคุมไม่ได้ ผู้ปฏิบัติงานสามารถเรียก environments.destroy พร้อม { "force": true } เป็นทางเลือกสุดท้าย การรื้อถอนแบบบังคับจะทำเครื่องหมายการจัดวางว่าล้มเหลวอย่างถาวร และละทิ้งผลลัพธ์ระยะไกลที่ยังไม่ได้ปรับให้สอดคล้องก่อนทำลายสภาพแวดล้อม

RPC สำหรับการดูแลระบบที่เทียบเท่าคือ:

openclaw gateway call sessions.reclaim \  --timeout 600000 \  --params '{"key":"agent:main:big-refactor"}'

ตำแหน่งการทำงานจะเปลี่ยนผ่านเครื่องสถานะที่คงทน (local → requested → provisioning → syncing → starting → active) ดังนั้นหาก Gateway รีสตาร์ตระหว่างการจัดส่ง ระบบจะกระทบยอดแทนที่จะปล่อยให้เครื่องรั่วไหล รอบการทำงานของโมเดลที่ล้มเหลวจะยังคงตำแหน่งที่ใช้งานอยู่ไว้สำหรับลองใหม่ ความขัดแย้งของพาธเวิร์กสเปซจะเก็บเวอร์ชันในเครื่องไว้ นำส่วนที่เหลือของผลลัพธ์จากคลาวด์มาใช้ และคง ref ของคลาวด์ที่จัดเตรียมไว้เพื่อการตรวจสอบ ส่วนความล้มเหลวอื่น ๆ ในการกระทบยอดหรือวงจรชีวิตจะคงขอบเขตการกู้คืนที่ทนทานและส่วนท้ายข้อมูลวินิจฉัยไว้ จนกว่าการกู้คืนจะสามารถลองใหม่หรือเรียกคืนสภาพแวดล้อมได้อย่างปลอดภัย

โมเดลความปลอดภัย

• ปิดการรับส่งข้อมูลขาเข้าสู่เวิร์กเกอร์ เวิร์กเกอร์สื่อสารผ่านโปรโตคอลเฉพาะบนซ็อกเก็ตที่ทำอุโมงค์ โดยมีรายการเมธอดที่อนุญาตแบบปิด เวิร์กเกอร์จึงไม่สามารถเรียก RPC ของผู้ปฏิบัติงานได้
• สร้างข้อมูลประจำตัวใหม่และจัดเก็บเป็นแฮช การจัดส่งแต่ละครั้งจะสร้างข้อมูลประจำตัวของเวิร์กเกอร์ โดย Gateway จัดเก็บเฉพาะแฮชของข้อมูลดังกล่าว การหมุนเวียนข้อมูลประจำตัวและการกั้นด้วย epoch ของเจ้าของรับประกันว่าแต่ละเซสชันจะมีเจ้าของที่ใช้งานอยู่ได้ไม่เกินหนึ่งราย เวิร์กเกอร์เก่าที่เชื่อมต่อใหม่จะถูกกั้นออกและไม่ถูกรวมเข้าด้วยกัน
• การตรึงคีย์โฮสต์ ผู้ให้บริการต้องเปิดเผยคีย์โฮสต์ SSH ของเครื่องขณะจัดสรร การบูตสแตรปจะเชื่อมต่อโดยใช้การตรึงอย่างเข้มงวดและหยุดทำงานอย่างปลอดภัยหากไม่มีคีย์ดังกล่าว
• ไม่มีข้อมูลประจำตัวของโมเดล ฟอร์จ หรือคลาวด์คงค้างอยู่บนเครื่อง การยืนยันตัวตนของโมเดลจะอยู่ที่ Gateway (การอนุมานส่งผ่านด้วยการอ้างอิง {provider, model}) คอมมิต git ของเวิร์กสเปซจะถูกสร้างโดยไม่มีข้อมูลประจำตัวของฟอร์จ และระบบจะตรวจสอบเมทาดาทาลีส AWS ของ Crabbox จากแหล่งข้อมูลที่เชื่อถือได้เพื่อหา instance role ก่อนการตั้งค่า คำสั่งตั้งค่าต้องไม่มีข้อมูลประจำตัวด้วย
• การรับส่งข้อมูลขาออกที่ผู้ให้บริการเป็นเจ้าของ อุโมงค์ย้อนกลับทำให้ OpenClaw ไม่จำเป็นต้องเข้าถึงโมเดลโดยตรง แต่ OpenClaw จะไม่เขียนไฟร์วอลล์ของผู้ให้บริการใหม่ ให้จำกัดการรับส่งข้อมูลขาออกในผู้ให้บริการเวิร์กเกอร์เมื่องานกำหนดให้ทำเช่นนั้น
• ทรานสคริปต์ที่คงทนและบันทึกเพียงครั้งเดียวอย่างเคร่งครัด เวิร์กเกอร์คอมมิตชุดทรานสคริปต์ผ่านโปรโตคอล compare-and-swap กับ leaf ของเซสชัน หากฐานข้อมูลเก่า กระบวนการจะหยุดทันทีแทนที่จะทำซ้ำหรือรีเบสผลลัพธ์ที่มีค่าใช้จ่าย

การแก้ไขปัญหา

• sessions.dispatch เป็นเมธอดที่ไม่รู้จัก — ไม่มีการกำหนดค่า cloudWorkers.profiles หรือผู้เรียกไม่มี operator.admin
• "รอบการทำงานของเวิร์กเกอร์คลาวด์ต้องใช้รันไทม์ OpenClaw" — เลือกโมเดลที่กำหนดค่ารันไทม์เป็น OpenClaw รันไทม์ CLI ภายนอก เช่น claude-cli ไม่รองรับการอนุมานของเวิร์กเกอร์
• "การบูตสแตรปเวิร์กเกอร์ต้องใช้ Node.js บนโฮสต์ที่เช่า" — เพิ่มการติดตั้ง Node ใน settings.setup (ดูด้านบน)
• การรับรอง instance role ของ AWS ล้มเหลว — ล้าง aws.instanceProfile (และ CRABBOX_AWS_INSTANCE_PROFILE หากตั้งค่าไว้) ติดตั้ง Crabbox 0.38.1 หรือใหม่กว่า ไบนารีรุ่นเก่าไม่เปิดเผยสัญญา providerMetadata.instanceProfileAttached ที่เชื่อถือได้ซึ่งจำเป็นสำหรับการอนุญาต AWS
• การจัดส่งล้มเหลวพร้อมข้อผิดพลาดจากผู้ให้บริการ — ระเบียนตำแหน่งและ environments.list จะเก็บข้อผิดพลาดล่าสุด รวมถึงส่วนท้าย stderr จากการตั้งค่า/บูตสแตรป ระบบจะทำลายเครื่องเมื่อล้มเหลว ดังนั้นส่วนท้ายดังกล่าวจึงเป็นหลักฐานหลักในการวิเคราะห์
• ไคลเอนต์หมดเวลาระหว่างการจัดส่ง — openclaw gateway call มีค่าหมดเวลาเริ่มต้นที่ 10s ให้ส่ง --timeout โดยเผื่อเวลาไว้อย่างเพียงพอ (ไม่ว่าอย่างไร การจัดส่งจะยังคงทำงานต่อทางฝั่งเซิร์ฟเวอร์ และการลองใหม่ระหว่างการจัดสรรจะถูกปฏิเสธด้วย session cannot dispatch from placement provisioning)
• การแจ้งเตือนความขัดแย้งของเวิร์กสเปซคลาวด์ — รอบการทำงานเสร็จสมบูรณ์และเก็บเวอร์ชันในเครื่องของแต่ละพาธที่แสดงไว้ ใช้คำสั่ง staged-ref ในการแจ้งเตือนเพื่อตรวจสอบหรือนำเวอร์ชันคลาวด์มาใช้ ไม่จำเป็นต้องลองใหม่สำหรับการเปลี่ยนแปลงที่ไม่ขัดแย้ง ซึ่งถูกนำมาใช้เรียบร้อยแล้ว
• “ผลลัพธ์เวิร์กสเปซของรอบการทำงานบนคลาวด์ก่อนหน้ายังคงอยู่ระหว่างการกระทบยอด” — Gateway รอขอบเขตที่คงทนของผลลัพธ์ก่อนหน้าเป็นเวลาสั้น ๆ แต่ไม่สามารถรับสิทธิ์อ้างสิทธิ์เซสชันได้ รอให้การกระทบยอดเสร็จสิ้นแล้วลองรอบการทำงานอีกครั้ง การรีสตาร์ต Gateway ปลอดภัย เนื่องจากการกู้คืนจะเก็บรักษาผลลัพธ์ที่จัดเตรียมไว้ก่อนเรียกคืนเวิร์กเกอร์ที่หยุดทำงาน
• การดูแลลีส — crabbox list --provider <backend> แสดงลีสที่ใช้งานอยู่ ส่วน crabbox stop --provider <backend> --id <lease> ปล่อยลีสหนึ่งรายการด้วยตนเอง ลีสที่ไม่ได้ใช้งานจะหมดอายุตาม idleTimeout ของโปรไฟล์

เนื้อหาที่เกี่ยวข้อง

• การทำแซนด์บ็อกซ์ — การลดขอบเขตผลกระทบของการเรียกใช้เครื่องมือภายในเครื่อง
• CLI สำหรับเซสชัน — การตรวจสอบเซสชันที่จัดเก็บไว้
• ข้อมูลอ้างอิงการกำหนดค่า