เรียกใช้ โฮสต์ Node แบบไม่มีส่วนติดต่อผู้ใช้ ที่เชื่อมต่อกับ WebSocket ของ Gateway และเปิดให้ใช้งาน system.run / system.which บนเครื่องนี้

บน macOS แอปแถบเมนูได้ฝังรันไทม์โฮสต์ Node นี้ไว้ในการเชื่อมต่อ Node ของแอปเองอยู่แล้ว และเพิ่มความสามารถแบบเนทีฟของ Mac ใช้ openclaw node run บน Mac เฉพาะเมื่อตั้งใจใช้ Node แบบไม่มีส่วนติดต่อผู้ใช้โดยไม่ใช้แอป การเรียกใช้ ทั้งสองอย่างจะสร้างข้อมูลประจำตัวของ Node สองรายการสำหรับเครื่องเดียวกัน

เหตุใดจึงควรใช้โฮสต์ Node?

ใช้โฮสต์ Node เมื่อต้องการให้เอเจนต์ เรียกใช้คำสั่งบนเครื่องอื่น ใน เครือข่ายโดยไม่ต้องติดตั้งแอปคู่หู macOS แบบเต็มบนเครื่องเหล่านั้น

กรณีใช้งานทั่วไป:

• เรียกใช้คำสั่งบนเครื่อง Linux/Windows ระยะไกล (เซิร์ฟเวอร์บิลด์ เครื่องในห้องปฏิบัติการ NAS)
• คง exec ให้ทำงาน ภายในแซนด์บ็อกซ์ บน Gateway แต่มอบหมายการเรียกใช้ที่ได้รับอนุมัติให้โฮสต์อื่น
• จัดเตรียมเป้าหมายการดำเนินงานแบบเบาและไม่มีส่วนติดต่อผู้ใช้สำหรับระบบอัตโนมัติหรือ Node ของ CI

การดำเนินงานยังคงถูกควบคุมด้วย การอนุมัติ exec และรายการอนุญาตรายเอเจนต์บน โฮสต์ Node จึงสามารถจำกัดและระบุขอบเขตการเข้าถึงคำสั่งได้อย่างชัดเจน

openclaw node run สามารถเผยแพร่เครื่องมือที่รองรับโดย Plugin หรือ MCP หลังจากเชื่อมต่อแล้ว Gateway เชื่อถือตัวอธิบายจาก Node ที่จับคู่แล้วโดยค่าเริ่มต้น แต่กำหนดให้ คำสั่งของตัวอธิบายแต่ละรายการยังคงอยู่ในพื้นผิวคำสั่งที่ได้รับอนุมัติของ Node เอเจนต์จะเห็นตัวอธิบายแต่ละรายการที่ยอมรับเป็นเครื่องมือ Plugin ปกติ แต่การดำเนินงานยังคง ผ่าน node.invoke ดังนั้นการตัดการเชื่อมต่อ Node จะนำเครื่องมือออกจากการเรียกใช้ เอเจนต์ครั้งใหม่ ผู้ดูแล Gateway สามารถปิดการเผยแพร่ได้ด้วย gateway.nodes.pluginTools.enabled: false

สำหรับเครื่องมือ MCP แบบประกาศ ให้เพิ่มโครงสร้างเซิร์ฟเวอร์ MCP ปกติภายใต้ nodeHost.mcp.servers ใน openclaw.json บนเครื่อง Node แล้วเริ่ม โฮสต์ Node ใหม่ Node จะประกาศตระกูลคำสั่ง mcp.tools.call.v1 ที่ต้องผ่านการอนุมัติ และเผยแพร่เครื่องมือที่ระบุไว้หลังเชื่อมต่อ การเปลี่ยนรายการเซิร์ฟเวอร์ ภายหลังไม่จำเป็นต้องจับคู่ใหม่ ดู เซิร์ฟเวอร์ MCP ที่โฮสต์บน Node

พร็อกซีเบราว์เซอร์ (ไม่ต้องกำหนดค่า)

โฮสต์ Node จะประกาศพร็อกซีเบราว์เซอร์โดยอัตโนมัติหากไม่ได้ปิด browser.enabled บน Node ซึ่งช่วยให้เอเจนต์ใช้ระบบอัตโนมัติของเบราว์เซอร์บน Node นั้น ได้โดยไม่ต้องกำหนดค่าเพิ่มเติม

โดยค่าเริ่มต้น พร็อกซีจะเปิดให้ใช้พื้นผิวโปรไฟล์เบราว์เซอร์ปกติของ Node หาก ตั้งค่า nodeHost.browserProxy.allowProfiles พร็อกซีจะเข้มงวดขึ้น: การกำหนดเป้าหมายโปรไฟล์ที่ไม่อยู่ในรายการอนุญาตจะถูกปฏิเสธ และเส้นทาง สร้าง/ลบโปรไฟล์ถาวรจะถูกบล็อกผ่านพร็อกซี

ปิดใช้งานบน Node หากจำเป็น:

{  nodeHost: {    browserProxy: {      enabled: false,    },  },}

เรียกใช้ (เบื้องหน้า)

openclaw node run --host <gateway-host> --port 18789

ตัวเลือก:

• --host <host>: โฮสต์ WebSocket ของ Gateway (ค่าเริ่มต้น: 127.0.0.1)
• --port <port>: พอร์ต WebSocket ของ Gateway (ค่าเริ่มต้น: 18789)
• --context-path <path>: พาธบริบท WebSocket ของ Gateway (เช่น /openclaw-gw) ต่อท้าย URL ของ WebSocket
• --tls: ใช้ TLS สำหรับการเชื่อมต่อ Gateway
• --no-tls: บังคับใช้การเชื่อมต่อ Gateway แบบข้อความธรรมดา แม้ว่าการกำหนดค่า Gateway ภายในเครื่องจะเปิดใช้ TLS
• --tls-fingerprint <sha256>: ลายนิ้วมือใบรับรอง TLS ที่คาดไว้ (sha256)
• --node-id <id>: แทนที่ ID อินสแตนซ์ไคลเอนต์ที่จัดเก็บในสถานะ SQLite ที่ใช้ร่วมกัน (ไม่รีเซ็ตการจับคู่)
• --display-name <name>: แทนที่ชื่อที่แสดงของ Node

การยืนยันตัวตน Gateway สำหรับโฮสต์ Node

openclaw node run และ openclaw node install จะระบุการยืนยันตัวตน Gateway จากการกำหนดค่า/ตัวแปรสภาพแวดล้อม (คำสั่ง Node ไม่มีแฟล็ก --token/--password):

• ตรวจสอบ OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD ก่อน
• จากนั้นใช้การกำหนดค่าภายในเครื่องเป็นทางเลือกสำรอง: gateway.auth.token / gateway.auth.password
• ในโหมดภายในเครื่อง โฮสต์ Node ตั้งใจไม่รับช่วง gateway.remote.token / gateway.remote.password
• หากกำหนดค่า gateway.auth.token / gateway.auth.password อย่างชัดเจนผ่าน SecretRef แต่ไม่สามารถระบุค่าได้ การระบุการยืนยันตัวตนของ Node จะหยุดทำงานอย่างปลอดภัย (ไม่มีทางเลือกสำรองระยะไกลมาปกปิดปัญหา)
• ใน gateway.mode=remote ฟิลด์ไคลเอนต์ระยะไกล (gateway.remote.token / gateway.remote.password) ก็มีสิทธิ์ใช้ตามกฎลำดับความสำคัญระยะไกลเช่นกัน
• การระบุการยืนยันตัวตนของโฮสต์ Node ยอมรับเฉพาะตัวแปรสภาพแวดล้อม OPENCLAW_GATEWAY_*

สำหรับ Node ที่เชื่อมต่อกับ Gateway ws:// แบบข้อความธรรมดา ระบบจะยอมรับลูปแบ็ก ลิเทอรัล IP ส่วนตัว โฮสต์ .local และโฮสต์ *.ts.net ใน Tailnet สำหรับชื่อ DNS ส่วนตัวอื่น ที่เชื่อถือได้ ให้ตั้งค่า OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1; หากไม่มีค่านี้ การเริ่มต้น Node จะหยุดทำงานอย่างปลอดภัยและขอให้ใช้ wss://, อุโมงค์ SSH หรือ Tailscale นี่เป็นการเลือกเปิดใช้ผ่านสภาพแวดล้อมของกระบวนการ ไม่ใช่คีย์การกำหนดค่า openclaw.json openclaw node install จะบันทึกค่านี้ไว้ในบริการ Node ที่มีการควบคุมดูแล เมื่อค่า ดังกล่าวอยู่ในสภาพแวดล้อมของคำสั่งติดตั้ง

บริการ (เบื้องหลัง)

ติดตั้งโฮสต์ Node แบบไม่มีส่วนติดต่อผู้ใช้เป็นบริการของผู้ใช้ (launchd บน macOS, systemd บน Linux และ Windows Task Scheduler บน Windows)

openclaw node install --host <gateway-host> --port 18789

ตัวเลือก:

• --host <host>: โฮสต์ WebSocket ของ Gateway (ค่าเริ่มต้น: 127.0.0.1)
• --port <port>: พอร์ต WebSocket ของ Gateway (ค่าเริ่มต้น: 18789)
• --context-path <path>: พาธบริบท WebSocket ของ Gateway (เช่น /openclaw-gw) ต่อท้าย URL ของ WebSocket
• --tls: ใช้ TLS สำหรับการเชื่อมต่อ Gateway
• --tls-fingerprint <sha256>: ลายนิ้วมือใบรับรอง TLS ที่คาดไว้ (sha256)
• --node-id <id>: แทนที่ ID อินสแตนซ์ไคลเอนต์ที่จัดเก็บในสถานะ SQLite ที่ใช้ร่วมกัน (ไม่รีเซ็ตการจับคู่)
• --display-name <name>: แทนที่ชื่อที่แสดงของ Node
• --runtime <runtime>: รันไทม์ของบริการ (node)
• --force: ติดตั้งใหม่/เขียนทับหากติดตั้งไว้แล้ว

จัดการบริการ:

openclaw node statusopenclaw node startopenclaw node stopopenclaw node restartopenclaw node uninstall

ใช้ openclaw node run สำหรับโฮสต์ Node เบื้องหน้า (ไม่มีบริการ)

คำสั่งบริการรองรับ --json สำหรับเอาต์พุตที่เครื่องอ่านได้

โฮสต์ Node จะลองใหม่ภายในกระบวนการเมื่อ Gateway เริ่มใหม่หรือเครือข่ายปิดการเชื่อมต่อ หาก Gateway รายงานการหยุดพักเพื่อยืนยันตัวตนด้วยโทเค็น/รหัสผ่าน/บูตสแตรปแบบสิ้นสุด โฮสต์ Node จะบันทึกรายละเอียดการปิดและออกด้วยรหัสที่ไม่ใช่ศูนย์ เพื่อให้ launchd/systemd/Task Scheduler เริ่มใหม่ได้ด้วยการกำหนดค่าและข้อมูลประจำตัวใหม่ การหยุดพักที่ต้องจับคู่จะยังคงอยู่ใน ขั้นตอนเบื้องหน้า เพื่อให้สามารถอนุมัติคำขอที่รอดำเนินการได้

การจับคู่

การเชื่อมต่อครั้งแรกจะสร้างคำขอจับคู่อุปกรณ์ที่รอดำเนินการ (role: node) บน Gateway

เมื่อโฮสต์ Gateway สามารถเชื่อมต่อ SSH ไปยังโฮสต์ Node แบบไม่โต้ตอบได้ (ผู้ใช้เดียวกัน เชื่อถือคีย์โฮสต์) คำขอที่รอดำเนินการจะได้รับการอนุมัติโดยอัตโนมัติ: Gateway เรียกใช้ openclaw node identity --json บนโฮสต์ Node ผ่าน SSH และอนุมัติเมื่อ คีย์อุปกรณ์ตรงกันทุกประการ คุณสมบัตินี้เปิดใช้โดยค่าเริ่มต้น ดู การอนุมัติอุปกรณ์อัตโนมัติที่ตรวจสอบด้วย SSH สำหรับข้อกำหนดและวิธีปิดใช้งาน (gateway.nodes.pairing.sshVerify: false)

มิฉะนั้น ให้อนุมัติด้วยตนเองผ่าน:

openclaw devices listopenclaw devices approve <requestId>

ตรวจสอบข้อมูลประจำตัว Node ภายในเครื่องที่ Gateway ใช้ตรวจสอบ:

openclaw node identity --json

คำสั่งนี้จะแสดง ID อุปกรณ์และคีย์สาธารณะจาก identity/device.json และจะไม่ สร้างหรือแก้ไขไฟล์ข้อมูลประจำตัว

ในเครือข่าย Node ที่ควบคุมอย่างเข้มงวด ผู้ดูแล Gateway สามารถเลือกเปิดใช้ การอนุมัติการจับคู่ Node ครั้งแรกจาก CIDR ที่เชื่อถือได้โดยอัตโนมัติอย่างชัดเจน:

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

คุณสมบัตินี้ปิดใช้งานโดยค่าเริ่มต้น (ไม่ได้ตั้งค่า autoApproveCidrs) และใช้เฉพาะกับ การจับคู่ role: node ใหม่ที่ไม่มีขอบเขตที่ร้องขอ จาก IP ไคลเอนต์ที่ Gateway เชื่อถือเท่านั้น ไคลเอนต์ผู้ดูแล/เบราว์เซอร์, Control UI, WebChat รวมถึงการอัปเกรดบทบาท ขอบเขต เมทาดาทา หรือคีย์สาธารณะ ยังคงต้องอนุมัติด้วยตนเอง

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

สถานะข้อมูลประจำตัวและการจับคู่

Node แบบไม่มีส่วนติดต่อผู้ใช้จะแยก ID อินสแตนซ์ไคลเอนต์ออกจากข้อมูลประจำตัวอุปกรณ์ ที่ลงนาม ซึ่ง Gateway ใช้สำหรับการจับคู่และการกำหนดเส้นทาง สถานะนี้อยู่ใน ไดเรกทอรีสถานะ OpenClaw (~/.openclaw โดยค่าเริ่มต้น หรือ $OPENCLAW_STATE_DIR เมื่อตั้งค่าไว้):

--node-id เปลี่ยนเฉพาะ ID อินสแตนซ์ไคลเอนต์ในสถานะ SQLite ที่ใช้ร่วมกัน โดย ไม่เปลี่ยน ID อุปกรณ์แบบเข้ารหัสลับหรือล้างการยืนยันตัวตนการจับคู่ การย้าย node.json ที่เลิกใช้แล้วด้วย openclaw doctor --fix ก็ไม่รีเซ็ตการจับคู่เช่นกัน หากต้องการ เพิกถอนและจับคู่ Node ใหม่:

1. บน Gateway ให้เรียกใช้ openclaw nodes remove --node <id|name|ip>
2. บน Node ให้เริ่มบริการที่ติดตั้งไว้ใหม่ด้วย openclaw node restart หรือ หยุดและเรียกใช้คำสั่ง openclaw node run แบบเบื้องหน้าอีกครั้ง การดำเนินการนี้จะเริ่ม ขั้นตอนการจับคู่อุปกรณ์ หาก openclaw devices list ไม่แสดงคำขอ และ Node รายงาน AUTH_DEVICE_TOKEN_MISMATCH ให้เริ่มใหม่หรือเรียกใช้อีกครั้ง อีกหนึ่งรอบ ความพยายามที่ถูกปฏิเสธจะล้างโทเค็นภายในเครื่องที่ถูกเพิกถอนแล้ว จากนั้น ความพยายามครั้งถัดไปจึงจะขอจับคู่ได้
3. บน Gateway ให้เรียกใช้ openclaw devices list แล้วจึง openclaw devices approve <deviceRequestId>
4. เริ่มใหม่หรือเรียกใช้ Node อีกครั้ง ไคลเอนต์ที่หยุดพักเพื่อรอการจับคู่จะไม่ทำงานต่อ โดยอัตโนมัติหลังอนุมัติ การเชื่อมต่อใหม่นี้จะสร้างคำขอ พื้นผิวคำสั่งแยกต่างหาก
5. บน Gateway ให้เรียกใช้ openclaw nodes pending แล้วจึง openclaw nodes approve <nodeRequestId>

ID คำขอทั้งสองรายการแตกต่างกัน นโยบาย CIDR ที่เชื่อถือได้ซึ่งตรงเงื่อนไขสามารถ อนุมัติขั้นตอนการจับคู่อุปกรณ์ครั้งแรกโดยอัตโนมัติ ส่วนการอนุมัติพื้นผิวคำสั่งยังคงเป็น การตรวจสอบแยกต่างหาก

OpenClaw รุ่นเก่าจัดเก็บสถานะโฮสต์ Node ไว้ใน node.json และอาจเหลือ ฟิลด์ token ที่เลิกใช้แล้วไว้ในนั้น หยุดโฮสต์ Node แล้วเรียกใช้ openclaw doctor --fix หนึ่งครั้ง Doctor จะนำเข้าฟิลด์ข้อมูลประจำตัวและการเชื่อมต่อที่รองรับไปยัง SQLite ทิ้งฟิลด์โทเค็นที่ไม่ได้ใช้ ตรวจสอบแถว และนำไฟล์ที่เลิกใช้ออก คำสั่ง Node ปกติจะหยุดทำงานอย่างปลอดภัยพร้อมคำแนะนำให้ซ่อมแซมนี้ ขณะที่ไฟล์หรือ การอ้างสิทธิ์ของ Doctor ที่ถูกขัดจังหวะยังคงอยู่ เก็บไฟล์ทั้งสองภายใต้ identity/ เป็นส่วนตัว เนื่องจากมีคู่คีย์อุปกรณ์และโทเค็นการยืนยันตัวตน

การอนุมัติ Exec

system.run ถูกควบคุมด้วยการอนุมัติ exec ภายในเครื่อง:

• $OPENCLAW_STATE_DIR/exec-approvals.json หรือ ~/.openclaw/exec-approvals.json เมื่อตัวแปรไม่ได้ตั้งค่า
• การอนุมัติ Exec
• openclaw approvals --node <id|name|ip> (แก้ไขจาก Gateway)

สำหรับ exec แบบอะซิงโครนัสของ Node ที่ได้รับอนุมัติ OpenClaw จะเตรียม systemRunPlan มาตรฐานก่อนแจ้งขออนุมัติ การส่งต่อ system.run ที่ได้รับอนุมัติในภายหลังจะนำแผน ที่จัดเก็บไว้นั้นกลับมาใช้ ดังนั้นการแก้ไขฟิลด์คำสั่ง/cwd/เซสชันหลังสร้างคำขออนุมัติแล้ว จะถูกปฏิเสธแทนที่จะเปลี่ยนสิ่งที่ Node ดำเนินการ

ที่เกี่ยวข้อง

• เอกสารอ้างอิง CLI
• Node