openclaw node

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

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

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

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

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

การเรียกใช้ยังคงถูกควบคุมด้วย การอนุมัติการเรียกใช้คำสั่ง และรายการอนุญาตแยกตามเอเจนต์บน โฮสต์ 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>: โฮสต์ Gateway WebSocket (ค่าเริ่มต้น: 127.0.0.1)
• --port <port>: พอร์ต Gateway WebSocket (ค่าเริ่มต้น: 18789)
• --context-path <path>: พาธบริบทของ Gateway WebSocket (เช่น /openclaw-gw) จะถูกต่อท้าย URL ของ WebSocket
• --tls: ใช้ TLS สำหรับการเชื่อมต่อ Gateway
• --no-tls: บังคับใช้การเชื่อมต่อ Gateway แบบข้อความธรรมดา แม้ว่าการกำหนดค่า Gateway ภายในเครื่องจะเปิดใช้ TLS
• --tls-fingerprint <sha256>: ลายนิ้วมือใบรับรอง TLS ที่คาดไว้ (sha256)
• --node-id <id>: แทนที่ ID อินสแตนซ์ไคลเอนต์แบบเดิมที่จัดเก็บใน node.json (ไม่รีเซ็ตการจับคู่)
• --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:// จะยอมรับ local loopback, ลิเทอรัล IP ส่วนตัว, .local และโฮสต์ Tailnet *.ts.net สำหรับชื่อ 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>: โฮสต์ Gateway WebSocket (ค่าเริ่มต้น: 127.0.0.1)
• --port <port>: พอร์ต Gateway WebSocket (ค่าเริ่มต้น: 18789)
• --context-path <path>: พาธบริบทของ Gateway WebSocket (เช่น /openclaw-gw) จะถูกต่อท้าย URL ของ WebSocket
• --tls: ใช้ TLS สำหรับการเชื่อมต่อ Gateway
• --tls-fingerprint <sha256>: ลายนิ้วมือใบรับรอง TLS ที่คาดไว้ (sha256)
• --node-id <id>: แทนที่ ID อินสแตนซ์ไคลเอนต์แบบเดิมที่จัดเก็บใน node.json (ไม่รีเซ็ตการจับคู่)
• --display-name <name>: แทนที่ชื่อที่แสดงของ Node
• --runtime <runtime>: รันไทม์ของบริการ (node หรือ bun)
• --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 อินสแตนซ์ไคลเอนต์ใน node.json เท่านั้น โดยไม่ เปลี่ยน ID อุปกรณ์เชิงการเข้ารหัสหรือล้างข้อมูลยืนยันตัวตนสำหรับการจับคู่ ในทำนองเดียวกัน การลบเฉพาะ node.json จะไม่รีเซ็ตการจับคู่ หากต้องการเพิกถอนและจับคู่ 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 รุ่นเก่าอาจทิ้งฟิลด์ token แบบเดิมไว้ใน node.json OpenClaw ปัจจุบันไม่ใช้ฟิลด์ดังกล่าว และจะลบออกเมื่อโฮสต์ Node บันทึกไฟล์ในครั้งถัดไป เก็บไฟล์ทั้งสองภายใต้ identity/ เป็นความลับ เพราะไฟล์เหล่านี้มี คู่คีย์อุปกรณ์และโทเค็นยืนยันตัวตน

การอนุมัติการเรียกใช้คำสั่ง

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

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

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

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

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