--- read_when: - การเรียกใช้โฮสต์ Node แบบไม่มีส่วนติดต่อผู้ใช้ - จับคู่ Node ที่ไม่ใช่ macOS สำหรับ system.run summary: เอกสารอ้างอิง CLI สำหรับ `openclaw node` (โฮสต์ Node แบบ headless) title: Node x-i18n: generated_at: "2026-07-19T07:06:55Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: c229e50dcff790a08ef155561a15a39220d6dccdc263d4a3d01ab8592f48de73 source_path: cli/node.md workflow: 16 --- # `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](/th/nodes#node-hosted-mcp-servers) ## พร็อกซีเบราว์เซอร์ (ไม่ต้องกำหนดค่า) โฮสต์ Node จะประกาศพร็อกซีเบราว์เซอร์โดยอัตโนมัติหากไม่ได้ปิด `browser.enabled` บน Node ซึ่งช่วยให้เอเจนต์ใช้ระบบอัตโนมัติของเบราว์เซอร์บน Node นั้น ได้โดยไม่ต้องกำหนดค่าเพิ่มเติม โดยค่าเริ่มต้น พร็อกซีจะเปิดให้ใช้พื้นผิวโปรไฟล์เบราว์เซอร์ปกติของ Node หาก ตั้งค่า `nodeHost.browserProxy.allowProfiles` พร็อกซีจะเข้มงวดขึ้น: การกำหนดเป้าหมายโปรไฟล์ที่ไม่อยู่ในรายการอนุญาตจะถูกปฏิเสธ และเส้นทางสำหรับ สร้าง/ลบโปรไฟล์ถาวรจะถูกบล็อกผ่านพร็อกซี ปิดบน Node หากจำเป็น: ```json5 { nodeHost: { browserProxy: { enabled: false, }, }, } ``` ## เรียกใช้ (เบื้องหน้า) ```bash openclaw node run --host --port 18789 ``` ตัวเลือก: - `--host `: โฮสต์ Gateway WebSocket (ค่าเริ่มต้น: `127.0.0.1`) - `--port `: พอร์ต Gateway WebSocket (ค่าเริ่มต้น: `18789`) - `--context-path `: พาธบริบทของ Gateway WebSocket (เช่น `/openclaw-gw`) โดยจะต่อท้าย URL ของ WebSocket - `--tls`: ใช้ TLS สำหรับการเชื่อมต่อ Gateway - `--no-tls`: บังคับใช้การเชื่อมต่อ Gateway แบบข้อความธรรมดา แม้ว่าการกำหนดค่า Gateway ภายในเครื่องจะเปิดใช้ TLS - `--tls-fingerprint `: ลายนิ้วมือใบรับรอง TLS ที่คาดไว้ (sha256) - `--node-id `: แทนที่ ID อินสแตนซ์ไคลเอ็นต์ที่จัดเก็บในสถานะ SQLite ที่ใช้ร่วมกัน (ไม่รีเซ็ตการจับคู่) - `--display-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) ```bash openclaw node install --host --port 18789 ``` ตัวเลือก: - `--host `: โฮสต์ Gateway WebSocket (ค่าเริ่มต้น: `127.0.0.1`) - `--port `: พอร์ต Gateway WebSocket (ค่าเริ่มต้น: `18789`) - `--context-path `: พาธบริบทของ Gateway WebSocket (เช่น `/openclaw-gw`) โดยจะต่อท้าย URL ของ WebSocket - `--tls`: ใช้ TLS สำหรับการเชื่อมต่อ Gateway - `--tls-fingerprint `: ลายนิ้วมือใบรับรอง TLS ที่คาดไว้ (sha256) - `--node-id `: แทนที่ ID อินสแตนซ์ไคลเอ็นต์ที่จัดเก็บในสถานะ SQLite ที่ใช้ร่วมกัน (ไม่รีเซ็ตการจับคู่) - `--display-name `: แทนที่ชื่อที่แสดงของ Node - `--runtime `: รันไทม์ของบริการ (`node`) - `--force`: ติดตั้งใหม่/เขียนทับหากติดตั้งไว้แล้ว จัดการบริการ: ```bash openclaw node status openclaw node start openclaw node stop openclaw node restart openclaw 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](/th/gateway/pairing#ssh-verified-device-auto-approval-default) สำหรับข้อกำหนดและวิธีปิด (`gateway.nodes.pairing.sshVerify: false`) หากไม่เป็นเช่นนั้น ให้อนุมัติด้วยตนเองผ่าน: ```bash openclaw devices list openclaw devices approve ``` ตรวจสอบข้อมูลประจำตัว Node ภายในเครื่องที่ Gateway ใช้ยืนยัน: ```bash openclaw node identity --json ``` คำสั่งนี้จะแสดง ID อุปกรณ์และคีย์สาธารณะจากแถว `primary` ใน `state/openclaw.sqlite` และจะไม่สร้างฐานข้อมูลหรือข้อมูลประจำตัวใหม่ ในเครือข่าย Node ที่ควบคุมอย่างเข้มงวด ผู้ดูแล Gateway สามารถเลือกใช้อย่างชัดเจน เพื่ออนุมัติการจับคู่ Node ครั้งแรกโดยอัตโนมัติจาก CIDR ที่เชื่อถือได้: ```json5 { 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` เมื่อตั้งค่าไว้): | สถานะ | วัตถุประสงค์ | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `state/openclaw.sqlite` (`node_host_config`) | ID อินสแตนซ์ไคลเอ็นต์ ชื่อที่แสดง และข้อมูลเมตาการเชื่อมต่อ Gateway ไคลเอ็นต์จะส่ง ID นี้เป็น `instanceId` | | `state/openclaw.sqlite` (`device_identities`, `primary`) | คู่คีย์ Ed25519 ที่ลงนามและ ID อุปกรณ์ที่ได้มา สำหรับการเชื่อมต่อแบบลงนาม ID อุปกรณ์นี้คือ ID ของ Node ที่ใช้กำหนดเส้นทางและข้อมูลประจำตัวในการจับคู่ | | `identity/device-auth.json` | โทเค็นอุปกรณ์ที่จับคู่แล้ว โดยใช้ ID อุปกรณ์เชิงการเข้ารหัสและบทบาทเป็นคีย์ | `--node-id` จะเปลี่ยนเฉพาะ ID อินสแตนซ์ไคลเอ็นต์ในสถานะ SQLite ที่ใช้ร่วมกันเท่านั้น โดย จะไม่เปลี่ยน ID อุปกรณ์เชิงการเข้ารหัสหรือล้างการยืนยันตัวตนสำหรับการจับคู่ การย้าย `node.json` ที่เลิกใช้แล้วด้วย `openclaw doctor --fix` ก็จะไม่รีเซ็ตการจับคู่เช่นกัน หากต้องการ เพิกถอนและจับคู่ Node ใหม่: 1. บน Gateway ให้เรียกใช้ `openclaw nodes remove --node ` 2. บน Node ให้รีสตาร์ตบริการที่ติดตั้งด้วย `openclaw node restart` หรือ หยุดแล้วเรียกใช้คำสั่ง `openclaw node run` เบื้องหน้าอีกครั้ง ซึ่งจะเริ่ม ขั้นตอนการจับคู่อุปกรณ์ หาก `openclaw devices list` ไม่แสดงคำขอ และ Node รายงาน `AUTH_DEVICE_TOKEN_MISMATCH` ให้รีสตาร์ตหรือเรียกใช้อีกครั้ง หนึ่งรอบ ความพยายามที่ถูกปฏิเสธจะล้างโทเค็นภายในเครื่องที่ถูกเพิกถอนไปแล้ว จากนั้น ความพยายามครั้งถัดไปจึงสามารถขอจับคู่ได้ 3. บน Gateway ให้เรียกใช้ `openclaw devices list` จากนั้น `openclaw devices approve ` 4. รีสตาร์ตหรือเรียกใช้ Node อีกครั้ง ไคลเอ็นต์ที่หยุดพักเพื่อรอการจับคู่จะไม่ทำงานต่อ โดยอัตโนมัติหลังจากอนุมัติ การเชื่อมต่อใหม่นี้จะสร้างคำขอ พื้นผิวคำสั่งแยกต่างหาก 5. บน Gateway ให้เรียกใช้ `openclaw nodes pending` จากนั้น `openclaw nodes approve ` 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` เมื่อไม่ได้ตั้งค่าตัวแปร - [การอนุมัติการเรียกใช้](/th/tools/exec-approvals) - `openclaw approvals --node ` (แก้ไขจาก Gateway) สำหรับการเรียกใช้ Node แบบอะซิงโครนัสที่ได้รับอนุมัติ OpenClaw จะจัดเตรียม `systemRunPlan` มาตรฐานก่อนแจ้งขออนุมัติ การส่งต่อ `system.run` ที่ได้รับอนุมัติในภายหลัง จะใช้แผนที่จัดเก็บไว้นั้นซ้ำ ดังนั้นการแก้ไขฟิลด์คำสั่ง/cwd/เซสชันหลังจากสร้าง คำขออนุมัติแล้วจะถูกปฏิเสธ แทนที่จะเปลี่ยนสิ่งที่ Node เรียกใช้ ## ที่เกี่ยวข้อง - [ข้อมูลอ้างอิง CLI](/th/cli) - [Nodes](/th/nodes)