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

นี่คือคู่มือปฏิบัติงานเชิงลึก เริ่มที่ /help/troubleshooting เพื่อทำตามขั้นตอนการคัดกรองปัญหาแบบรวดเร็วก่อน

ลำดับคำสั่ง

เรียกใช้ตามลำดับนี้:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

สัญญาณที่บ่งชี้ว่าระบบทำงานเป็นปกติ:

• openclaw gateway status แสดง Runtime: running, Connectivity probe: ok และบรรทัด Capability: ...
• openclaw doctor รายงานว่าไม่มีปัญหาการกำหนดค่าหรือบริการที่ขัดขวางการทำงาน
• openclaw channels status --probe แสดงสถานะการรับส่งข้อมูลแบบสดสำหรับแต่ละบัญชี และแสดง works หรือ audit ok ในกรณีที่รองรับ

หลังการอัปเดต

ใช้เมื่อการอัปเดตเสร็จสิ้นแล้ว แต่ Gateway หยุดทำงาน ช่องไม่มีข้อมูล หรือการเรียกโมเดลล้มเหลวด้วยข้อผิดพลาด 401

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

ตรวจสอบสิ่งต่อไปนี้:

• Update restart ใน openclaw status / openclaw status --all การส่งต่องานที่รอดำเนินการหรือล้มเหลวจะระบุคำสั่งถัดไปที่ต้องเรียกใช้
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix ใต้ Channels: การกำหนดค่าช่องยังคงอยู่ แต่การลงทะเบียน Plugin ล้มเหลวก่อนที่จะโหลดช่องได้
• ข้อผิดพลาด 401 จากผู้ให้บริการหลังยืนยันตัวตนอีกครั้ง: openclaw doctor --fix ตรวจหาเงาข้อมูลยืนยันตัวตน OAuth ที่ล้าสมัยของแต่ละเอเจนต์และนำสำเนาเก่าออก เพื่อให้เอเจนต์ทั้งหมดเลือกใช้โปรไฟล์ที่แชร์ร่วมกันในปัจจุบัน

การติดตั้งที่แยกกันทำงานและกลไกป้องกันการกำหนดค่าจากเวอร์ชันใหม่กว่า

ใช้เมื่อบริการ Gateway หยุดทำงานโดยไม่คาดคิดหลังการอัปเดต หรือบันทึกแสดงว่าไบนารี openclaw หนึ่งรายการเก่ากว่าเวอร์ชันที่เขียน openclaw.json ครั้งล่าสุด

OpenClaw ประทับเวอร์ชันลงในการเขียนการกำหนดค่าด้วย meta.lastTouchedVersion คำสั่งแบบอ่านอย่างเดียวสามารถตรวจสอบการกำหนดค่าที่เขียนโดย OpenClaw เวอร์ชันใหม่กว่าได้ แต่การเปลี่ยนแปลงกระบวนการและบริการจะไม่ยอมทำงานจากไบนารีเวอร์ชันเก่ากว่า การดำเนินการที่ถูกบล็อก ได้แก่ การเริ่ม/หยุด/เริ่มใหม่/ถอนการติดตั้งบริการ Gateway, การบังคับติดตั้งบริการใหม่, การเริ่ม Gateway ในโหมดบริการ และการล้างพอร์ต gateway --force

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

โปรโตคอลไม่ตรงกันหลังย้อนกลับ

ใช้เมื่อบันทึกยังคงแสดง protocol mismatch หลังการดาวน์เกรดหรือย้อนกลับ Gateway เวอร์ชันเก่ากำลังทำงานอยู่ แต่กระบวนการไคลเอนต์ในเครื่องเวอร์ชันใหม่กว่ายังคงเชื่อมต่อใหม่ด้วยช่วงโปรโตคอลที่ Gateway เวอร์ชันเก่าไม่รองรับ

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

ตรวจสอบสิ่งต่อไปนี้:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> ในบันทึกของ Gateway
• Established clients: ใน openclaw gateway status --deep หรือ Gateway clients ใน openclaw doctor --deep: ไคลเอนต์ TCP ที่ใช้งานอยู่และเชื่อมต่อกับพอร์ต Gateway พร้อม PID และบรรทัดคำสั่งเมื่อระบบปฏิบัติการอนุญาต
• กระบวนการไคลเอนต์ที่บรรทัดคำสั่งชี้ไปยังการติดตั้งหรือตัวห่อหุ้ม OpenClaw เวอร์ชันใหม่กว่าที่คุณย้อนกลับมา

วิธีแก้ไข:

1. หยุดหรือเริ่มกระบวนการไคลเอนต์ OpenClaw ที่ล้าสมัยซึ่ง gateway status --deep แสดงขึ้นมาใหม่
2. เริ่มแอปหรือตัวห่อหุ้มที่ฝัง OpenClaw ใหม่ ได้แก่ แดชบอร์ดในเครื่อง ตัวแก้ไข ตัวช่วยแอปเซิร์ฟเวอร์ หรือเชลล์ openclaw logs --follow ที่ทำงานเป็นเวลานาน
3. เรียกใช้ openclaw gateway status --deep หรือ openclaw doctor --deep อีกครั้ง และยืนยันว่า PID ของไคลเอนต์ที่ล้าสมัยหายไปแล้ว

อย่าทำให้ Gateway เวอร์ชันเก่ายอมรับโปรโตคอลเวอร์ชันใหม่กว่าที่เข้ากันไม่ได้ การเพิ่มเวอร์ชันโปรโตคอลช่วยปกป้องสัญญาการสื่อสารผ่านสาย ส่วนการกู้คืนหลังย้อนกลับเป็นปัญหาที่ต้องล้างกระบวนการและเวอร์ชัน

ข้าม symlink ของ Skill เนื่องจากออกนอกขอบเขตพาธ

ใช้เมื่อบันทึกมีข้อความ:

ข้ามพาธ Skill ที่ออกนอกขอบเขตรูทที่กำหนดค่าไว้: ... reason=symlink-escape

รูทของ Skill ทุกแห่งเป็นขอบเขตจำกัดพื้นที่ symlink ภายใต้ ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills หรือ ~/.openclaw/skills จะถูกข้ามเมื่อเป้าหมายจริงชี้ออกนอกรูทนั้น เว้นแต่เป้าหมายดังกล่าวได้รับความเชื่อถืออย่างชัดเจน

ตรวจสอบลิงก์:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

หากตั้งใจใช้เป้าหมายนั้น ให้กำหนดค่าทั้งรูทของ Skill โดยตรงและเป้าหมาย symlink ที่อนุญาต:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

จากนั้นเริ่มเซสชันใหม่หรือรอให้ตัวเฝ้าดู Skills รีเฟรช เริ่ม Gateway ใหม่หากกระบวนการที่กำลังทำงานเริ่มต้นขึ้นก่อนมีการเปลี่ยนแปลงการกำหนดค่า

อย่าใช้เป้าหมายที่กว้าง เช่น ~, / หรือทั้งโฟลเดอร์โครงการที่ซิงค์ไว้ จำกัดขอบเขต allowSymlinkTargets ไว้เฉพาะรูทของ Skill จริงซึ่งมีไดเรกทอรี SKILL.md ที่เชื่อถือได้

หากการนำการเปลี่ยนแปลงจาก Skill Workshop ไปใช้ควรเขียนผ่านพาธ Skill ในพื้นที่ทำงานที่เป็น symlink และได้รับความเชื่อถือเหล่านั้นด้วย ให้เปิดใช้ skills.workshop.allowSymlinkTargetWrites ปิดไว้สำหรับรูทของ Skill ที่แชร์ร่วมกันแบบอ่านอย่างเดียว

ข้อมูลที่เกี่ยวข้อง:

• การกำหนดค่า Skills
• ตัวอย่างการกำหนดค่า

Anthropic 429 ต้องใช้สิทธิ์การใช้งานเพิ่มเติมสำหรับบริบทยาว

ใช้เมื่อบันทึกหรือข้อผิดพลาดมีข้อความ: HTTP 429: rate_limit_error: Extra usage is required for long context requests

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

ตรวจสอบสิ่งต่อไปนี้:

• โมเดล Anthropic ที่เลือกเป็นโมเดล Claude 4.x ที่รองรับ 1M แบบ GA (Opus 4.6/4.7/4.8, Sonnet 4.6) หรือการกำหนดค่าโมเดลยังคงมี params.context1m: true แบบเดิม
• ข้อมูลประจำตัว Anthropic ปัจจุบันไม่มีสิทธิ์ใช้งานบริบทยาว
• คำขอล้มเหลวเฉพาะในเซสชันหรือการเรียกใช้โมเดลที่ยาวและต้องใช้เส้นทางบริบท 1M

ตัวเลือกในการแก้ไข:

ข้อมูลที่เกี่ยวข้อง:

• Anthropic
• การใช้โทเค็นและค่าใช้จ่าย
• เหตุใดจึงพบ HTTP 429 จาก Anthropic

การตอบกลับ 403 ที่ถูกบล็อกจากระบบต้นทาง

ใช้เมื่อผู้ให้บริการ LLM ต้นทางส่งคืน 403 ทั่วไป เช่น Your request was blocked

อย่าสันนิษฐานว่านี่เป็นปัญหาการกำหนดค่า OpenClaw เสมอไป การตอบกลับอาจมาจากชั้นความปลอดภัยต้นทาง เช่น CDN, WAF, กฎการจัดการบอต หรือพร็อกซีย้อนกลับที่อยู่หน้าเอ็นด์พอยต์ที่เข้ากันได้กับ OpenAI

openclaw statusopenclaw gateway statusopenclaw logs --follow

ตรวจสอบสิ่งต่อไปนี้:

• โมเดลหลายรายการภายใต้ผู้ให้บริการเดียวกันล้มเหลวในลักษณะเดียวกัน
• มี HTML หรือข้อความความปลอดภัยทั่วไปแทนข้อผิดพลาด API ตามปกติของผู้ให้บริการ
• มีเหตุการณ์ด้านความปลอดภัยฝั่งผู้ให้บริการในเวลาเดียวกับคำขอ
• การตรวจสอบ curl โดยตรงขนาดเล็กมากสำเร็จ แต่คำขอที่มีรูปแบบตาม SDK ตามปกติล้มเหลว

แก้ไขการกรองฝั่งผู้ให้บริการก่อนเมื่อหลักฐานชี้ว่าเกิดการบล็อกจาก WAF/CDN ควรใช้กฎอนุญาตหรือข้ามที่จำกัดขอบเขตอย่างแคบสำหรับพาธ API ที่ OpenClaw ใช้ และหลีกเลี่ยงการปิดการป้องกันทั้งเว็บไซต์

ข้อมูลที่เกี่ยวข้อง:

• เอ็นด์พอยต์ที่เข้ากันได้กับ OpenAI
• การกำหนดค่าผู้ให้บริการ
• บันทึก

แบ็กเอนด์ในเครื่องที่เข้ากันได้กับ OpenAI ผ่านการตรวจสอบโดยตรง แต่การทำงานของเอเจนต์ล้มเหลว

ใช้เมื่อ:

• curl ... /v1/models ทำงานได้
• การเรียก /v1/chat/completions โดยตรงขนาดเล็กทำงานได้
• การเรียกใช้โมเดล OpenClaw ล้มเหลวเฉพาะในรอบการทำงานตามปกติของเอเจนต์

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

ตรวจสอบสิ่งต่อไปนี้:

• การเรียกโดยตรงขนาดเล็กสำเร็จ แต่การทำงานของ OpenClaw ล้มเหลวเฉพาะเมื่อใช้พรอมต์ขนาดใหญ่ขึ้น
• model_not_found หรือข้อผิดพลาด 404 แม้ว่า /v1/chat/completions โดยตรงจะทำงานได้ด้วยรหัสโมเดลเปล่าเดียวกัน
• ข้อผิดพลาดของแบ็กเอนด์ที่ระบุว่า messages[].content ต้องเป็นสตริง
• คำเตือน incomplete turn detected ... stopReason=stop payloads=0 ที่เกิดขึ้นเป็นระยะกับแบ็กเอนด์ในเครื่องที่เข้ากันได้กับ OpenAI
• แบ็กเอนด์ขัดข้องเฉพาะเมื่อมีจำนวนโทเค็นพรอมต์มากขึ้นหรือใช้พรอมต์รันไทม์ของเอเจนต์แบบเต็ม

ข้อมูลที่เกี่ยวข้อง:

• การกำหนดค่า
• โมเดลภายในเครื่อง
• เอนด์พอยต์ที่เข้ากันได้กับ OpenAI

ไม่มีการตอบกลับ

หากช่องทางทำงานอยู่แต่ไม่มีการตอบกลับ ให้ตรวจสอบการกำหนดเส้นทางและนโยบายก่อนเชื่อมต่อสิ่งใดใหม่

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

ตรวจหา:

• การจับคู่ที่รอดำเนินการสำหรับผู้ส่งข้อความส่วนตัว
• การจำกัดด้วยการกล่าวถึงในกลุ่ม (requireMention, mentionPatterns)
• รายการอนุญาตของช่องทาง/กลุ่มไม่ตรงกัน

รูปแบบที่พบบ่อย:

• drop guild message (mention required → ระบบจะเพิกเฉยต่อข้อความกลุ่มจนกว่าจะมีการกล่าวถึง
• pairing request → ผู้ส่งต้องได้รับการอนุมัติ
• blocked / allowlist → ผู้ส่ง/ช่องทางถูกกรองโดยนโยบาย

หัวข้อที่เกี่ยวข้อง:

• การแก้ไขปัญหาช่องทาง
• กลุ่ม
• การจับคู่

การเชื่อมต่อ UI ควบคุมของแดชบอร์ด

เมื่อแดชบอร์ด/UI ควบคุมเชื่อมต่อไม่ได้ ให้ตรวจสอบ URL, โหมดการยืนยันตัวตน และข้อกำหนดเกี่ยวกับบริบทที่ปลอดภัย

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

ตรวจหา:

• URL สำหรับตรวจสอบและ URL ของแดชบอร์ดที่ถูกต้อง
• โหมดการยืนยันตัวตน/โทเค็นระหว่างไคลเอ็นต์กับ Gateway ไม่ตรงกัน
• มีการใช้ HTTP ในกรณีที่ต้องใช้ข้อมูลประจำตัวของอุปกรณ์

หากเบราว์เซอร์ภายในเครื่องเชื่อมต่อกับ 127.0.0.1:18789 ไม่ได้หลังการอัปเดต ให้กู้คืนบริการ Gateway ภายในเครื่องก่อน และยืนยันว่าบริการกำลังให้บริการแดชบอร์ด:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

หาก curl ส่งคืน HTML ของ OpenClaw แสดงว่า Gateway ทำงานอยู่ และปัญหาที่เหลือน่าจะเกิดจากแคชของเบราว์เซอร์ ดีปลิงก์เก่า หรือสถานะแท็บที่ค้างอยู่ เปิด http://127.0.0.1:18789 โดยตรงแล้วนำทางจากแดชบอร์ด หากหลังรีสตาร์ตบริการไม่ทำงานต่อ ให้เรียกใช้ openclaw gateway start และตรวจสอบ openclaw gateway status อีกครั้ง

แผนผังด่วนของรหัสรายละเอียดการยืนยันตัวตน

ใช้ error.details.code จากการตอบกลับ connect ที่ล้มเหลวเพื่อเลือกการดำเนินการถัดไป:

การตรวจสอบการย้ายข้อมูลการยืนยันตัวตนอุปกรณ์ v2:

openclaw --versionopenclaw doctoropenclaw gateway status

หากบันทึกแสดงข้อผิดพลาด nonce/ลายเซ็น ให้อัปเดตไคลเอ็นต์ที่เชื่อมต่อและตรวจสอบดังนี้:

หาก openclaw devices rotate / revoke / remove ถูกปฏิเสธโดยไม่คาดคิด:

• เซสชันโทเค็นอุปกรณ์ที่จับคู่สามารถจัดการได้เฉพาะอุปกรณ์ ของตนเอง เว้นแต่ผู้เรียกจะมี operator.admin ด้วย
• openclaw devices rotate --scope ... สามารถร้องขอได้เฉพาะขอบเขตผู้ปฏิบัติงานที่เซสชันของผู้เรียกมีอยู่แล้วเท่านั้น

หัวข้อที่เกี่ยวข้อง:

• การกำหนดค่า (โหมดการยืนยันตัวตนของ Gateway)
• UI ควบคุม
• อุปกรณ์
• การเข้าถึงจากระยะไกล
• การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือได้

บริการ Gateway ไม่ทำงาน

ใช้เมื่อบริการติดตั้งแล้ว แต่กระบวนการทำงานไม่ต่อเนื่อง

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # ตรวจสอบบริการระดับระบบด้วย

ตรวจหา:

• Runtime: stopped พร้อมคำใบ้เกี่ยวกับการออกจากกระบวนการ
• การกำหนดค่าบริการไม่ตรงกัน (Config (cli) กับ Config (service))
• พอร์ต/ตัวรับฟังขัดแย้งกัน
• มีการติดตั้ง launchd/systemd/schtasks เพิ่มเติมเมื่อใช้ --deep
• คำใบ้การล้างข้อมูล Other gateway-like services detected (best effort)

หัวข้อที่เกี่ยวข้อง:

• การดำเนินการเบื้องหลังและเครื่องมือกระบวนการ
• การกำหนดค่า
• Doctor

Gateway บน macOS หยุดตอบสนองโดยไม่มีข้อความแจ้ง แล้วกลับมาทำงานต่อเมื่อโต้ตอบกับแดชบอร์ด

ใช้เมื่อช่องทางต่าง ๆ (Telegram, WhatsApp เป็นต้น) บนโฮสต์ macOS เงียบหายไปครั้งละหลายนาทีถึงหลายชั่วโมง และดูเหมือนว่า Gateway จะกลับมาทันทีที่เปิด Control UI, เชื่อมต่อผ่าน SSH หรือโต้ตอบกับโฮสต์ด้วยวิธีอื่น โดยปกติจะไม่พบอาการที่ชัดเจนใน openclaw status เพราะเมื่อเข้าไปตรวจสอบ Gateway ก็กลับมาทำงานแล้ว

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

ให้มองหาสิ่งต่อไปนี้:

• บันเดิล *-uncaught_exception.json อย่างน้อยหนึ่งรายการใน ~/.openclaw/logs/stability/ ซึ่งตั้งค่า error.code เป็นรหัสเครือข่ายชั่วคราว เช่น ENETDOWN, ENETUNREACH, EHOSTUNREACH หรือ ECONNREFUSED
• บรรทัด pmset -g log เช่น Entering Sleep state due to 'Maintenance Sleep' หรือ en0 driver is slow (msg: WillChangeState to 0) ที่ตรงกับการประทับเวลาของการขัดข้อง Power Nap / Maintenance Sleep จะทำให้ไดรเวอร์ Wi-Fi เข้าสู่สถานะ 0 ชั่วครู่ การเชื่อมต่อ connect() ขาออกใด ๆ ที่เกิดขึ้นในช่วงนั้นอาจล้มเหลวด้วย ENETDOWN แม้ว่าโดยปกติโฮสต์จะเชื่อมต่อเครือข่ายได้อย่างสมบูรณ์
• เอาต์พุต launchctl print ที่แสดง state = not running พร้อม runs หลายรายการที่เพิ่งเกิดขึ้นและรหัสออก โดยเฉพาะเมื่อช่วงเวลาระหว่างการขัดข้องกับการเริ่มทำงานครั้งถัดไปอยู่ในระดับหนึ่งชั่วโมงแทนที่จะเป็นไม่กี่วินาที launchd ของ macOS ใช้กลไกป้องกันการเกิดซ้ำซึ่งไม่มีการบันทึกไว้หลังจากเกิดการขัดข้องต่อเนื่อง กลไกนี้อาจหยุดทำตาม KeepAlive=true จนกว่าทริกเกอร์ภายนอก เช่น การเข้าสู่ระบบแบบโต้ตอบ การเชื่อมต่อแดชบอร์ด หรือ launchctl kickstart จะเปิดใช้งานกลไกดังกล่าวอีกครั้ง

ลักษณะที่พบบ่อย:

• บันเดิลความเสถียรที่มี error.code เป็น ENETDOWN หรือรหัสอื่นในกลุ่มเดียวกัน โดย call stack ชี้ไปที่ Node net lookupAndConnect / Socket.connect OpenClaw 2026.5.26 และรุ่นใหม่กว่าจะจัดประเภทข้อผิดพลาดเหล่านี้เป็นข้อผิดพลาดเครือข่ายชั่วคราวที่ไม่เป็นอันตราย จึงไม่ส่งต่อไปยังตัวจัดการข้อยกเว้นระดับบนสุดอีกต่อไป หากใช้รุ่นเก่ากว่า ให้อัปเกรดก่อน
• ช่วงเวลาที่เงียบหายเป็นเวลานานและสิ้นสุดลงทันทีที่เชื่อมต่อกับ Control UI หรือ SSH เข้าโฮสต์: กิจกรรมที่ผู้ใช้มองเห็นเป็นสิ่งที่เปิดใช้งานกลไกการเกิดซ้ำของ launchd อีกครั้ง ไม่ใช่การกระทำใด ๆ ของแดชบอร์ดต่อ Gateway
• จำนวน runs เพิ่มขึ้นตลอดทั้งวันโดยไม่มีบรรทัด received SIG*; shutting down ที่สอดคล้องกันใน ~/Library/Logs/openclaw/gateway.log: การปิดระบบตามปกติจะบันทึกสัญญาณลงในบันทึก แต่การขัดข้องชั่วคราวจะไม่บันทึก

สิ่งที่ต้องทำ:

1. อัปเกรด Gateway หากกำลังใช้รุ่นก่อน 2026.5.26 หลังจากอัปเกรดแล้ว ข้อผิดพลาด ENETDOWN ที่เกิดขึ้นในอนาคตจะถูกบันทึกเป็นคำเตือนแทนที่จะยุติโพรเซส

2. ลดกิจกรรมการพักเครื่องเพื่อบำรุงรักษา บนโฮสต์ Mac mini / เดสก์ท็อปที่มีไว้ให้ทำงานเป็นเซิร์ฟเวอร์แบบเปิดตลอดเวลา:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   วิธีนี้ช่วยลดความผันผวนของไดรเวอร์ที่เป็นสาเหตุพื้นฐานได้อย่างมาก แต่ไม่สามารถกำจัดได้ทั้งหมด ระบบยังอาจพักเครื่องเพื่อบำรุงรักษาบางส่วนสำหรับ TCP keepalive และการดูแลรักษา mDNS โดยไม่ขึ้นกับแฟล็กเหล่านี้

3. เพิ่มตัวเฝ้าระวังสถานะการทำงาน เพื่อให้ตรวจพบได้อย่างรวดเร็วหากการขัดข้องต่อเนื่องในอนาคตถูก launchd พักไว้:

   # ตัวอย่างการตรวจสอบสถานะการทำงานที่รองรับ launchd เหมาะสำหรับ Cron หรือ LaunchAgent ที่ทำงานทุก 5 นาทีstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   จุดประสงค์คือเปิดใช้งานกลไกการเกิดซ้ำจากภายนอกอีกครั้ง โดย KeepAlive=true เพียงอย่างเดียวไม่เพียงพอบน macOS หลังจากเกิดการขัดข้องต่อเนื่อง

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

• หมายเหตุเกี่ยวกับแพลตฟอร์ม macOS
• การบันทึกล็อก
• Doctor

ลูปตัวควบคุม launchd ของ macOS เมื่อมี LaunchAgent สำหรับ Gateway/Node ซ้ำกัน

ใช้เมื่อการติดตั้งบน macOS เริ่มทำงานใหม่ทุก ๆ ไม่กี่วินาที การตรวจสอบสถานะ openclaw สลับไปมาระหว่างพร้อมใช้งานและไม่พร้อมใช้งาน และการส่งข้อมูลผ่านช่องทางหยุดชะงัก แม้ว่าดูเหมือนว่าบริการกำลังทำงานอยู่ก็ตาม

ปัญหานี้พบในการติดตั้งรุ่นเก่าซึ่งทั้ง ai.openclaw.gateway และ ai.openclaw.node LaunchAgent ทำงานอยู่ และแต่ละรายการแทรก OPENCLAW_LAUNCHD_LABEL ในสถานะดังกล่าว OpenClaw อาจตรวจพบการควบคุมโดย launchd พยายามส่งมอบการเริ่มทำงานใหม่กลับไปให้ launchd และเข้าสู่ลูป EADDRINUSE/การเกิดซ้ำอย่างรวดเร็ว แทนที่จะมีโพรเซส Gateway ที่เสถียรเพียงหนึ่งโพรเซส

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

ให้มองหาสิ่งต่อไปนี้:

• มี PID ของ Gateway มากกว่าหนึ่งรายการในตัวอย่างช่วงเวลา 30 วินาที แทนที่จะมี โพรเซสที่เสถียรเพียงหนึ่งโพรเซส
• EADDRINUSE, another gateway instance is already listening หรือบรรทัด การเริ่มทำงานใหม่/การส่งมอบที่เกิดซ้ำใน gateway.log
• ทั้ง ~/Library/LaunchAgents/ai.openclaw.gateway.plist และ ~/Library/LaunchAgents/ai.openclaw.node.plist ถูกโหลดพร้อมกันบน โฮสต์ที่ควรเรียกใช้บริการ Gateway ที่มีการจัดการเพียงบริการเดียว

สิ่งที่ต้องทำ:

1. หากโฮสต์นี้ควรเรียกใช้เฉพาะบริการ Gateway ให้ลบบริการ Node ที่มีการจัดการ ผ่าน OpenClaw ข้ามขั้นตอนนี้ หากยังพึ่งพาบริการ Node สำหรับฟีเจอร์ Node ระยะไกลอยู่ การถอนการติดตั้งจะหยุดฟีเจอร์เหล่านั้นบน โฮสต์นี้:

   openclaw node uninstall

2. ติดตั้ง Wrapper ของ Gateway แบบถาวร ซึ่งจะล้างตัวทำเครื่องหมาย launchd ที่สืบทอดมาก่อนเริ่ม OpenClaw ใช้ตัวเลือก --wrapper ที่รองรับ ห้ามแก้ไขไฟล์ที่สร้างขึ้นภายใต้ ~/.openclaw/service-env/ เนื่องจากการติดตั้งบริการใหม่ การอัปเดต และการซ่อมแซมด้วย Doctor จะสร้างไฟล์นั้นขึ้นใหม่:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install จะเก็บเส้นทางของ wrapper ไว้แม้มีการติดตั้งใหม่แบบบังคับ การอัปเดต และการซ่อมแซมโดย doctor

3. ตรวจสอบว่า Gateway ทำงานได้อย่างเสถียรและให้บริการ RPC ไม่ใช่เพียงแค่รับฟังการเชื่อมต่อ:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   ตัวอย่าง PID ควรแสดงกระบวนการที่เสถียรหนึ่งกระบวนการ แทนที่จะเป็นชุด PID ที่เปลี่ยนวนไปมา และการส่งต่อช่องทางขาเข้าควรกลับมาทำงาน

4. หลังจากอัปเกรดเป็นรุ่นที่แก้ไขลูป LaunchAgent คู่ซึ่งเป็นสาเหตุแล้ว ให้นำวิธีแก้ปัญหาชั่วคราวออกและติดตั้งบริการที่มีการจัดการตามปกติใหม่:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

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

• หมายเหตุเกี่ยวกับแพลตฟอร์ม macOS
• Doctor
• Gateway CLI

Gateway หยุดทำงานระหว่างการใช้หน่วยความจำสูง

ใช้เมื่อ Gateway หายไปขณะมีภาระงานสูง ตัวควบคุมรายงานการรีสตาร์ตในลักษณะ OOM หรือบันทึกกล่าวถึง critical memory pressure bundle written

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

มองหา:

• Reason: diagnostic.memory.pressure.critical ในชุดข้อมูลความเสถียรล่าสุด
• Memory pressure: ที่มี critical/rss_threshold, critical/heap_threshold หรือ critical/rss_growth
• ค่า V8 heap: ที่ใกล้ถึงขีดจำกัดฮีป
• รายการ Largest session files: เช่น agents/<agent>/sessions/<session>.jsonl หรือ sessions/<session>.jsonl
• ตัวนับหน่วยความจำ cgroup ของ Linux เมื่อ Gateway ทำงานภายในคอนเทนเนอร์หรือบริการที่จำกัดหน่วยความจำ

ลักษณะที่พบบ่อย:

• critical memory pressure bundle written ปรากฏไม่นานก่อนรีสตาร์ต → OpenClaw บันทึกชุดข้อมูลความเสถียรก่อนเกิด OOM ตรวจสอบด้วย openclaw gateway stability --bundle latest
• memory pressure: level=critical ปรากฏในบันทึกของ Gateway → OpenClaw ตรวจพบภาวะหน่วยความจำตึงตัวขั้นวิกฤตและบันทึกข้อมูลหน่วยความจำภายในกระบวนการที่มีอยู่
• Largest session files: ชี้ไปยังพาธทรานสคริปต์ที่ปกปิดข้อมูลและมีขนาดใหญ่มาก → ลดประวัติเซสชันที่เก็บไว้ ตรวจสอบการเติบโตของเซสชัน หรือย้ายทรานสคริปต์เก่าออกจากที่เก็บที่ใช้งานอยู่ก่อนรีสตาร์ต
• จำนวนไบต์ที่ใช้ของ V8 heap: ใกล้ถึงขีดจำกัดฮีป → ลดภาระจากพรอมต์/เซสชันหรือลดงานที่ทำพร้อมกันก่อน สำหรับบริการที่มีการจัดการ ให้ตรวจสอบ Gateway heap: ใน openclaw gateway status; หากระบุว่า not set ให้สร้างเมทาดาทาของบริการเก่าใหม่ด้วย openclaw gateway install --force ระบบจงใจไม่สนใจ NODE_OPTIONS ของเชลล์แวดล้อม ใช้การกำหนดค่าฮีปทับที่ระดับตัวควบคุมดูแลอย่างชัดเจนเฉพาะหลังจากยืนยันภาระงานต่อเนื่องและเหลือพื้นที่สำรองสำหรับหน่วยความจำเนทีฟเพียงพอแล้ว
• Memory pressure: critical/rss_growth → หน่วยความจำเพิ่มขึ้นอย่างรวดเร็วภายในช่วงการสุ่มตัวอย่างหนึ่งช่วง ตรวจสอบบันทึกล่าสุดเพื่อหาการนำเข้าขนาดใหญ่ เอาต์พุตเครื่องมือที่เพิ่มขึ้นไม่หยุด การลองซ้ำหลายครั้ง หรือกลุ่มงานเอเจนต์ที่อยู่ในคิว
• ภาวะหน่วยความจำตึงตัวขั้นวิกฤตปรากฏในบันทึกแต่ไม่มีชุดข้อมูล → บันทึก openclaw gateway diagnostics export หลังเกิดเหตุการณ์เพื่อเก็บหลักฐานการปฏิบัติงานที่มีอยู่

ชุดข้อมูลความเสถียรไม่มีเพย์โหลด โดยมีหลักฐานหน่วยความจำเชิงปฏิบัติการและพาธไฟล์แบบสัมพัทธ์ที่ปกปิดข้อมูล แต่ไม่มีข้อความ เนื้อหา Webhook ข้อมูลประจำตัว โทเค็น คุกกี้ หรือรหัสเซสชันดิบ ให้แนบไฟล์ส่งออกการวินิจฉัยกับรายงานข้อบกพร่องแทนการคัดลอกบันทึกดิบ

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

• สถานะการทำงานของ Gateway
• ไฟล์ส่งออกการวินิจฉัย
• เซสชัน

Gateway ปฏิเสธการกำหนดค่าที่ไม่ถูกต้อง

ใช้เมื่อการเริ่มต้น Gateway ล้มเหลวโดยแสดง Invalid config หรือบันทึกการโหลดใหม่แบบทันทีระบุว่าข้ามการแก้ไขที่ไม่ถูกต้อง

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

มองหา:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• ไฟล์ openclaw.json.rejected.* ที่มีการประทับเวลาอยู่ข้างการกำหนดค่าที่ใช้งานอยู่
• ไฟล์ openclaw.json.clobbered.* ที่มีการประทับเวลา หาก doctor --fix ซ่อมแซมการแก้ไขโดยตรงที่เสียหาย
• OpenClaw เก็บไฟล์ .clobbered.* ล่าสุด 32 ไฟล์สำหรับแต่ละพาธการกำหนดค่าและหมุนเวียนไฟล์ที่เก่ากว่าออก

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

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

• การกำหนดค่า
• การกำหนดค่า: การโหลดซ้ำแบบทันที
• การกำหนดค่า: การตรวจสอบความถูกต้องอย่างเข้มงวด
• Doctor

คำเตือนจากการตรวจสอบ Gateway

ใช้เมื่อ openclaw gateway probe เข้าถึงบางสิ่งได้ แต่ยังคงแสดงบล็อกคำเตือน

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

ตรวจหา:

• warnings[].code และ primaryTargetId ในเอาต์พุต JSON
• คำเตือนเกี่ยวกับการใช้ SSH สำรอง, Gateway หลายตัว, ขอบเขตสิทธิ์ที่ขาดหายไป หรือการอ้างอิงการยืนยันตัวตนที่ยังแก้ไขไม่ได้หรือไม่

ลักษณะที่พบบ่อย:

• SSH tunnel failed to start; falling back to direct probes. → การตั้งค่า SSH ล้มเหลว แต่คำสั่งยังคงลองใช้เป้าหมายที่กำหนดค่าโดยตรงหรือเป้าหมายแบบ loopback
• multiple reachable gateway identities detected → Gateway ที่แตกต่างกันตอบกลับ หรือ OpenClaw ไม่สามารถยืนยันได้ว่าเป้าหมายที่เข้าถึงได้นั้นเป็น Gateway เดียวกัน อุโมงค์ SSH, URL พร็อกซี หรือ URL ระยะไกลที่กำหนดค่าไว้ซึ่งชี้ไปยัง Gateway เดียวกัน จะถือว่าเป็น Gateway หนึ่งตัวที่มีการรับส่งข้อมูลหลายแบบ แม้ว่าพอร์ตการรับส่งข้อมูลจะแตกต่างกัน
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → เชื่อมต่อสำเร็จ แต่ RPC รายละเอียดถูกจำกัดด้วยขอบเขตสิทธิ์ ให้จับคู่อัตลักษณ์อุปกรณ์หรือใช้ข้อมูลประจำตัวที่มี operator.read
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → เชื่อมต่อสำเร็จ แต่ชุด RPC วินิจฉัยแบบเต็มหมดเวลาหรือล้มเหลว ให้ถือว่านี่คือ Gateway ที่เข้าถึงได้แต่ความสามารถในการวินิจฉัยลดลง โดยเปรียบเทียบ connect.ok และ connect.rpcOk ในเอาต์พุต --json
• Capability: pairing-pending หรือ gateway closed (1008): pairing required → Gateway ตอบกลับแล้ว แต่ไคลเอนต์นี้ยังต้องจับคู่หรือได้รับอนุมัติก่อนจึงจะเข้าถึงในฐานะผู้ดำเนินการได้ตามปกติ
• ข้อความเตือน SecretRef ของ gateway.auth.* / gateway.remote.* ที่ยังแก้ไขไม่ได้ → ข้อมูลการยืนยันตัวตนไม่พร้อมใช้งานในเส้นทางคำสั่งนี้สำหรับเป้าหมายที่ล้มเหลว

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

• Gateway
• Gateway หลายตัวบนโฮสต์เดียวกัน
• การเข้าถึงระยะไกล

ช่องทางเชื่อมต่อแล้ว แต่ข้อความไม่ไหลผ่าน

หากสถานะช่องทางเชื่อมต่อแล้วแต่ข้อความไม่ไหลผ่าน ให้มุ่งตรวจสอบนโยบาย สิทธิ์ และกฎการส่งเฉพาะของช่องทาง

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

ตรวจหา:

• นโยบาย DM (pairing, allowlist, open, disabled)
• รายการอนุญาตของกลุ่มและข้อกำหนดในการกล่าวถึง
• สิทธิ์หรือขอบเขตสิทธิ์ของ API ช่องทางที่ขาดหายไป

ลักษณะที่พบบ่อย:

• mention required → ข้อความถูกเพิกเฉยตามนโยบายการกล่าวถึงในกลุ่ม
• pairing / ร่องรอยการรออนุมัติ → ผู้ส่งยังไม่ได้รับอนุมัติ
• missing_scope, not_in_channel, Forbidden, 401/403 → ปัญหาเกี่ยวกับการยืนยันตัวตนหรือสิทธิ์ของช่องทาง

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

• การแก้ไขปัญหาช่องทาง
• Discord
• Telegram
• WhatsApp

การส่ง Cron และ Heartbeat

หาก Cron หรือ Heartbeat ไม่ทำงานหรือไม่ส่งข้อมูล ให้ตรวจสอบสถานะตัวกำหนดเวลาก่อน แล้วจึงตรวจสอบเป้าหมายการส่ง

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

ตรวจหา:

• Cron เปิดใช้งานอยู่และมีเวลาปลุกครั้งถัดไป
• สถานะประวัติการเรียกใช้งานงาน (ok, skipped, error)
• สาเหตุที่ข้าม Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due)

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

• Heartbeat
• งานตามกำหนดเวลา
• งานตามกำหนดเวลา: การแก้ไขปัญหา

จับคู่ Node แล้ว แต่เครื่องมือล้มเหลว

หากจับคู่ Node แล้วแต่เครื่องมือล้มเหลว ให้แยกตรวจสอบสถานะเบื้องหน้า สิทธิ์ และการอนุมัติ

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

ตรวจหา:

• Node ออนไลน์และมีความสามารถตามที่คาดไว้
• การอนุญาตสิทธิ์จากระบบปฏิบัติการสำหรับกล้อง ไมโครโฟน ตำแหน่ง และหน้าจอ
• สถานะการอนุมัติการดำเนินการและรายการอนุญาต

ลักษณะที่พบบ่อย:

• NODE_BACKGROUND_UNAVAILABLE → แอป Node ต้องอยู่เบื้องหน้า
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → ขาดสิทธิ์จากระบบปฏิบัติการ
• SYSTEM_RUN_DENIED: approval required → การอนุมัติการดำเนินการอยู่ระหว่างรอดำเนินการ
• SYSTEM_RUN_DENIED: allowlist miss → คำสั่งถูกบล็อกโดยรายการอนุญาต

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

• การอนุมัติการดำเนินการ
• การแก้ไขปัญหา Node
• Node

เครื่องมือเบราว์เซอร์ล้มเหลว

ใช้เมื่อการทำงานของเครื่องมือเบราว์เซอร์ล้มเหลว แม้ว่า Gateway จะทำงานเป็นปกติ

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

ตรวจหา:

• มีการตั้งค่า plugins.allow และมี browser อยู่หรือไม่
• พาธของไฟล์ปฏิบัติการเบราว์เซอร์ที่ถูกต้อง
• ความสามารถในการเข้าถึงโปรไฟล์ CDP
• ความพร้อมใช้งานของ Chrome ภายในเครื่องสำหรับโปรไฟล์ existing-session / user

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

• เบราว์เซอร์ (จัดการโดย OpenClaw)
• การแก้ไขปัญหาเบราว์เซอร์

หากอัปเกรดแล้วมีบางอย่างเสียหายกะทันหัน

ความเสียหายหลังการอัปเกรดส่วนใหญ่เกิดจากการกำหนดค่าคลาดเคลื่อนหรือการเริ่มบังคับใช้ค่าเริ่มต้นที่เข้มงวดยิ่งขึ้นในขณะนี้

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

หากการกำหนดค่าบริการและรันไทม์ยังไม่ตรงกันหลังจากตรวจสอบแล้ว ให้ติดตั้งเมทาดาทาของบริการอีกครั้งจากไดเรกทอรีโปรไฟล์/สถานะเดียวกัน:

openclaw gateway install --forceopenclaw gateway restart

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

• การยืนยันตัวตน
• การดำเนินการเบื้องหลังและเครื่องมือกระบวนการ
• การจับคู่ Node

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

• Doctor
• คำถามที่พบบ่อย
• คู่มือปฏิบัติงาน Gateway