openclaw node

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

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

เหตุใดจึงควรใช้โฮสต์ 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 อินสแตนซ์ไคลเอ็นต์ที่จัดเก็บในสถานะ SQLite ที่ใช้ร่วมกัน (ไม่รีเซ็ตการจับคู่)
• --display-name <name>: แทนที่ชื่อที่แสดงของ Node

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

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

• ตรวจสอบ 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>: โฮสต์ 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 อินสแตนซ์ไคลเอ็นต์ที่จัดเก็บในสถานะ 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 อุปกรณ์และคีย์สาธารณะจากแถว primary ใน state/openclaw.sqlite และจะไม่สร้างฐานข้อมูลหรือข้อมูลประจำตัวใหม่

ในเครือข่าย 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 และข้อมูลประจำตัว ที่ลงนามไว้ใน identity/device.json ให้หยุดโฮสต์ Node แล้วเรียกใช้ openclaw doctor --fix หนึ่งครั้ง โดย Doctor จะอ้างสิทธิ์แต่ละแหล่งที่เลิกใช้ ตรวจสอบความถูกต้อง นำเข้าและยืนยันแถว SQLite มาตรฐาน จากนั้นลบไฟล์เก่า คำสั่ง Node ปกติ จะล้มเหลวแบบปิดพร้อมคำแนะนำให้ซ่อมแซมนี้ ตราบใดที่ยังมีไฟล์ที่เลิกใช้รายการใดรายการหนึ่ง หรือการอ้างสิทธิ์ของ Doctor ที่ถูกขัดจังหวะอยู่ เก็บ state/openclaw.sqlite และ identity/device-auth.json ไว้เป็นส่วนตัว เนื่องจากมีคู่คีย์อุปกรณ์และโทเค็น การยืนยันตัวตน การยืนยันตัวตนอุปกรณ์ยังคงเป็นที่เก็บแยกต่างหากและจะไม่ถูกเขียนใหม่โดย การย้ายข้อมูลประจำตัว

การอนุมัติการเรียกใช้

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

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

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

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

• ข้อมูลอ้างอิง CLI
• Nodes