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

• model_not_found กับเซิร์ฟเวอร์ local สไตล์ MLX/vLLM → ตรวจสอบว่า baseUrl มี /v1, api เป็น "openai-completions" สำหรับ backend /v1/chat/completions และ models.providers.<provider>.models[].id เป็น bare provider-local id เลือกด้วย provider prefix ครั้งเดียว เช่น mlx/mlx-community/Qwen3-30B-A3B-6bit; เก็บรายการ catalog เป็น mlx-community/Qwen3-30B-A3B-6bit
• messages[...].content: invalid type: sequence, expected a string → backend ปฏิเสธ structured Chat Completions content parts การแก้ไข: ตั้ง models.providers.<provider>.models[].compat.requiresStringContent: true
• incomplete turn detected ... stopReason=stop payloads=0 → backend ทำคำขอ Chat Completions เสร็จแล้ว แต่ไม่ส่งข้อความ assistant ที่ผู้ใช้มองเห็นได้สำหรับ turn นั้น OpenClaw retry turn ว่างที่เข้ากันได้กับ OpenAI และ replay-safe หนึ่งครั้ง; หากยังล้มเหลวซ้ำมักหมายความว่า backend กำลังส่ง content ว่าง/ไม่ใช่ข้อความ หรือ suppress ข้อความ final-answer
• คำขอเล็กมากแบบตรงสำเร็จ แต่การรัน agent ของ OpenClaw ล้มเหลวด้วย backend/model crash (เช่น Gemma บน build inferrs บางตัว) → transport ของ OpenClaw มีแนวโน้มว่าถูกต้องแล้ว; backend ล้มเหลวกับรูปแบบ prompt agent-runtime ที่ใหญ่กว่า
• ความล้มเหลวลดลงหลังปิด tools แต่ไม่หายไป → tool schemas เป็นส่วนหนึ่งของแรงกดดัน แต่ปัญหาที่เหลือยังเป็นความจุของ upstream model/server หรือ bug ของ backend

1. ตั้ง compat.requiresStringContent: true สำหรับ backend Chat Completions ที่รับเฉพาะ string
2. ตั้ง compat.supportsTools: false สำหรับโมเดล/backend ที่จัดการ tool schema surface ของ OpenClaw ได้ไม่น่าเชื่อถือ
3. ลดแรงกดดันของ prompt เมื่อทำได้: workspace bootstrap ที่เล็กลง, ประวัติ session ที่สั้นลง, โมเดล local ที่เบากว่า หรือ backend ที่รองรับ long-context ได้ดีกว่า
4. หากคำขอเล็กมากแบบตรงยังผ่าน แต่ turn agent ของ OpenClaw ยัง crash ภายใน backend ให้ถือว่าเป็นข้อจำกัดของ upstream server/model และส่ง repro ที่นั่นพร้อมรูปแบบ payload ที่ backend ยอมรับ

• device identity required → context ไม่ secure หรือขาด device auth
• origin not allowed → browser Origin ไม่อยู่ใน gateway.controlUi.allowedOrigins (หรือคุณกำลังเชื่อมต่อจาก browser origin ที่ไม่ใช่ loopback โดยไม่มี allowlist ที่ระบุชัดเจน)
• device nonce required / device nonce mismatch → client ไม่ได้ทำ flow device auth แบบ challenge-based ให้เสร็จ (connect.challenge + device.nonce)
• device signature invalid / device signature expired → client ลงนาม payload ผิด (หรือ timestamp เก่า) สำหรับ handshake ปัจจุบัน
• AUTH_TOKEN_MISMATCH พร้อม canRetryWithDeviceToken=true → client สามารถ retry แบบ trusted ได้หนึ่งครั้งด้วย device token ที่ cache ไว้
• การ retry ด้วย cached-token นั้นใช้ชุด scope ที่ cache ไว้ซึ่งเก็บพร้อมกับ paired device token ผู้เรียกที่ส่ง deviceToken ชัดเจน / scopes ชัดเจน จะคงชุด scope ที่ร้องขอไว้แทน
• นอก path retry นั้น ลำดับความสำคัญของ connect auth คือ shared token/password ที่ระบุชัดเจนก่อน จากนั้น deviceToken ที่ระบุชัดเจน จากนั้น stored device token แล้วจึงเป็น bootstrap token
• บน path async Tailscale Serve Control UI ความพยายามที่ล้มเหลวสำหรับ {scope, ip} เดียวกันจะถูก serialize ก่อนที่ limiter จะบันทึกความล้มเหลว ดังนั้นการ retry พร้อมกันที่ผิดสองครั้งจาก client เดียวกันอาจแสดง retry later ในครั้งที่สองแทนที่จะเป็น mismatch ธรรมดาสองครั้ง
• too many failed authentication attempts (retry later) จาก browser-origin local loopback client → ความล้มเหลวซ้ำจาก normalized Origin เดียวกันนั้นถูก lock out ชั่วคราว; origin localhost อื่นใช้ bucket แยกกัน
• unauthorized ซ้ำหลัง retry นั้น → shared token/device token drift; refresh การกำหนดค่า token และ re-approve/rotate device token หากจำเป็น
• gateway connect failed: → เป้าหมาย host/port/url ผิด

• Gateway start blocked: set gateway.mode=local หรือ existing config is missing gateway.mode → ยังไม่ได้เปิดใช้โหมด Gateway แบบโลคัล หรือไฟล์ config ถูกเขียนทับจนสูญเสีย gateway.mode วิธีแก้: ตั้งค่า gateway.mode="local" ใน config ของคุณ หรือรัน openclaw onboard --mode local / openclaw setup อีกครั้งเพื่อประทับ config โหมดโลคัลที่คาดไว้ใหม่ หากคุณรัน OpenClaw ผ่าน Podman พาธ config เริ่มต้นคือ ~/.openclaw/openclaw.json
• refusing to bind gateway ... without auth → การ bind ที่ไม่ใช่ loopback โดยไม่มีพาธการยืนยันตัวตน Gateway ที่ถูกต้อง (โทเค็น/รหัสผ่าน หรือ trusted-proxy เมื่อกำหนดค่าไว้)
• another gateway instance is already listening / EADDRINUSE → พอร์ตขัดแย้ง
• Other gateway-like services detected (best effort) → มีหน่วย launchd/systemd/schtasks ที่ค้างอยู่หรือทำงานขนานกัน การตั้งค่าส่วนใหญ่ควรมี Gateway หนึ่งตัวต่อเครื่อง หากคุณจำเป็นต้องมีมากกว่าหนึ่งจริงๆ ให้แยกพอร์ต + config/state/workspace ดู /gateway#multiple-gateways-same-host
• System-level OpenClaw gateway service detected จาก doctor → มี systemd system unit อยู่ขณะที่บริการระดับผู้ใช้หายไป ลบหรือปิดใช้งานตัวซ้ำก่อนอนุญาตให้ doctor ติดตั้งบริการผู้ใช้ หรือตั้งค่า OPENCLAW_SERVICE_REPAIR_POLICY=external หาก system unit เป็น supervisor ที่ตั้งใจใช้
• Gateway service port does not match current gateway config → supervisor ที่ติดตั้งไว้ยังคงตรึง --port เก่าไว้ รัน openclaw doctor --fix หรือ openclaw gateway install --force จากนั้นรีสตาร์ตบริการ Gateway

• config ไม่ผ่านการตรวจสอบระหว่างเริ่มต้น, hot reload หรือการเขียนที่ OpenClaw เป็นเจ้าของ
• การเริ่มต้น Gateway ล้มเหลวแบบปิดแทนที่จะเขียน openclaw.json ใหม่
• Hot reload ข้ามการแก้ไขภายนอกที่ไม่ถูกต้องและคง config runtime ปัจจุบันไว้
• การเขียนที่ OpenClaw เป็นเจ้าของปฏิเสธ payload ที่ไม่ถูกต้อง/ทำลายข้อมูลก่อน commit และบันทึก .rejected.*
• openclaw doctor --fix เป็นเจ้าของการซ่อมแซม โดยสามารถลบ prefix ที่ไม่ใช่ JSON หรือกู้คืนสำเนา last-known-good พร้อมเก็บ payload ที่ถูกปฏิเสธไว้เป็น .clobbered.*

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

• มี .clobbered.* → doctor เก็บการแก้ไขภายนอกที่เสียหายไว้ขณะซ่อม config ที่ใช้งานอยู่
• มี .rejected.* → การเขียน config ที่ OpenClaw เป็นเจ้าของล้มเหลวจาก schema หรือการตรวจสอบการเขียนทับก่อน commit
• Config write rejected: → การเขียนพยายามลดรูปทรงที่จำเป็น ลดขนาดไฟล์อย่างมาก หรือคง config ที่ไม่ถูกต้อง
• config reload skipped (invalid config): → การแก้ไขโดยตรงไม่ผ่านการตรวจสอบและถูก Gateway ที่กำลังทำงานละเว้น
• Invalid config at ... → การเริ่มต้นล้มเหลวก่อนบริการ Gateway บูต
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good หรือ size-drop-vs-last-good:* → การเขียนที่ OpenClaw เป็นเจ้าของถูกปฏิเสธเพราะสูญเสียฟิลด์หรือขนาดเมื่อเทียบกับข้อมูลสำรอง last-known-good
• Config last-known-good promotion skipped → candidate มี placeholder ความลับที่ถูกปกปิด เช่น ***

1. รัน openclaw doctor --fix เพื่อให้ doctor ซ่อม config ที่มี prefix/ถูกเขียนทับ หรือกู้คืน last-known-good
2. คัดลอกเฉพาะคีย์ที่ตั้งใจจาก .clobbered.* หรือ .rejected.* จากนั้นนำไปใช้ด้วย openclaw config set หรือ config.patch
3. รัน openclaw config validate ก่อนรีสตาร์ต
4. หากคุณแก้ไขด้วยมือ ให้คง config JSON5 แบบเต็มไว้ ไม่ใช่แค่วัตถุบางส่วนที่คุณต้องการเปลี่ยน

• cron: scheduler disabled; jobs will not run automatically → Cron ถูกปิดใช้งาน
• cron: timer tick failed → จังหวะเวลาของตัวจัดตารางเวลาล้มเหลว ให้ตรวจสอบข้อผิดพลาดของไฟล์/ล็อก/รันไทม์
• heartbeat skipped พร้อม reason=quiet-hours → อยู่นอกช่วงเวลาทำงาน
• heartbeat skipped พร้อม reason=empty-heartbeat-file → มี HEARTBEAT.md อยู่ แต่มีเฉพาะบรรทัดว่าง / หัวข้อ markdown ดังนั้น OpenClaw จึงข้ามการเรียกโมเดล
• heartbeat skipped พร้อม reason=no-tasks-due → HEARTBEAT.md มีบล็อก tasks: แต่ไม่มีงานใดถึงกำหนดในจังหวะนี้
• heartbeat: unknown accountId → รหัสบัญชีไม่ถูกต้องสำหรับปลายทางการส่ง Heartbeat
• heartbeat skipped พร้อม reason=dm-blocked → เป้าหมาย Heartbeat ถูก resolve เป็นปลายทางแบบ DM ขณะที่ agents.defaults.heartbeat.directPolicy (หรือ override ต่อเอเจนต์) ถูกตั้งค่าเป็น block

• unknown command "browser" หรือ unknown command 'browser' → Plugin เบราว์เซอร์ที่บันเดิลมาถูกยกเว้นโดย plugins.allow
• เครื่องมือเบราว์เซอร์ขาดหาย / ไม่พร้อมใช้งานขณะที่ browser.enabled=true → plugins.allow ไม่รวม browser ดังนั้น Plugin จึงไม่เคยโหลด
• Failed to start Chrome CDP on port → กระบวนการเบราว์เซอร์เริ่มทำงานไม่สำเร็จ
• browser.executablePath not found → เส้นทางที่กำหนดค่าไม่ถูกต้อง
• browser.cdpUrl must be http(s) or ws(s) → URL ของ CDP ที่กำหนดค่าใช้ scheme ที่ไม่รองรับ เช่น file: หรือ ftp:
• browser.cdpUrl has invalid port → URL ของ CDP ที่กำหนดค่ามีพอร์ตไม่ถูกต้องหรืออยู่นอกช่วง
• Playwright is not available in this gateway build; '<feature>' is unsupported. → การติดตั้ง Gateway ปัจจุบันขาด dependency รันไทม์เบราว์เซอร์หลัก ให้ติดตั้งใหม่หรืออัปเดต OpenClaw แล้วรีสตาร์ท Gateway สแนปช็อต ARIA และภาพหน้าจอพื้นฐานของหน้าเว็บยังคงทำงานได้ แต่การนำทาง, สแนปช็อต AI, ภาพหน้าจอองค์ประกอบด้วย CSS-selector และการส่งออก PDF ยังคงไม่พร้อมใช้งาน

• Could not find DevToolsActivePort for chrome → existing-session ของ Chrome MCP ยังไม่สามารถแนบกับไดเรกทอรีข้อมูลเบราว์เซอร์ที่เลือกได้ เปิดหน้าตรวจสอบของเบราว์เซอร์ เปิดใช้ remote debugging เปิดเบราว์เซอร์ค้างไว้ อนุมัติพรอมป์แนบครั้งแรก แล้วลองใหม่ หากไม่ต้องใช้สถานะการลงชื่อเข้าใช้ ให้ใช้โปรไฟล์ openclaw ที่จัดการให้แทน
• No Chrome tabs found for profile="user" → โปรไฟล์แนบของ Chrome MCP ไม่มีแท็บ Chrome ในเครื่องที่เปิดอยู่
• Remote CDP for profile "<name>" is not reachable → ปลายทาง remote CDP ที่กำหนดค่าไม่สามารถเข้าถึงได้จากโฮสต์ Gateway
• Browser attachOnly is enabled ... not reachable หรือ Browser attachOnly is enabled and CDP websocket ... is not reachable → โปรไฟล์ attach-only ไม่มีเป้าหมายที่เข้าถึงได้ หรือ HTTP endpoint ตอบกลับแล้วแต่ยังไม่สามารถเปิด CDP WebSocket ได้

• fullPage is not supported for element screenshots → คำขอภาพหน้าจอผสม --full-page กับ --ref หรือ --element
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → การเรียกภาพหน้าจอของ Chrome MCP / existing-session ต้องใช้การจับภาพหน้าเว็บหรือ --ref จากสแนปช็อต ไม่ใช่ CSS --element
• existing-session file uploads do not support element selectors; use ref/inputRef. → ฮุกอัปโหลดของ Chrome MCP ต้องใช้ refs จากสแนปช็อต ไม่ใช่ CSS selectors
• existing-session file uploads currently support one file at a time. → ส่งไฟล์อัปโหลดหนึ่งไฟล์ต่อหนึ่งการเรียกบนโปรไฟล์ Chrome MCP
• existing-session dialog handling does not support timeoutMs. → ฮุกกล่องโต้ตอบบนโปรไฟล์ Chrome MCP ไม่รองรับการ override timeout
• existing-session type does not support timeoutMs overrides. → ละเว้น timeoutMs สำหรับ act:type บน profile="user" / โปรไฟล์ existing-session ของ Chrome MCP หรือใช้โปรไฟล์เบราว์เซอร์แบบ managed/CDP เมื่อต้องกำหนด timeout เอง
• existing-session evaluate does not support timeoutMs overrides. → ละเว้น timeoutMs สำหรับ act:evaluate บน profile="user" / โปรไฟล์ existing-session ของ Chrome MCP หรือใช้โปรไฟล์เบราว์เซอร์แบบ managed/CDP เมื่อต้องกำหนด timeout เอง
• response body is not supported for existing-session profiles yet. → responsebody ยังต้องใช้เบราว์เซอร์ที่จัดการให้หรือโปรไฟล์ CDP แบบ raw
• viewport / dark-mode / locale / offline overrides ที่ค้างอยู่บนโปรไฟล์ attach-only หรือ remote CDP → รัน openclaw browser stop --browser-profile <name> เพื่อปิดเซสชันควบคุมที่ใช้งานอยู่และปล่อยสถานะ emulation ของ Playwright/CDP โดยไม่ต้องรีสตาร์ท Gateway ทั้งหมด

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

สิ่งที่ต้องตรวจสอบ:

• หาก gateway.mode=remote การเรียก CLI อาจกำลังชี้ไปที่ remote ขณะที่บริการในเครื่องของคุณปกติ
• การเรียก --url แบบระบุชัดเจนจะไม่ fallback ไปใช้ข้อมูลประจำตัวที่เก็บไว้

ลายเซ็นที่พบบ่อย:

• gateway connect failed: → เป้าหมาย URL ไม่ถูกต้อง
• unauthorized → endpoint เข้าถึงได้แต่การยืนยันตัวตนไม่ถูกต้อง

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

สิ่งที่ต้องตรวจสอบ:

• การ bind ที่ไม่ใช่ loopback (lan, tailnet, custom) ต้องมีเส้นทางยืนยันตัวตนของ Gateway ที่ถูกต้อง: การยืนยันตัวตนด้วย token/password ที่ใช้ร่วมกัน หรือ deployment trusted-proxy แบบไม่ใช่ loopback ที่กำหนดค่าอย่างถูกต้อง
• คีย์เก่าอย่าง gateway.token ไม่ได้แทนที่ gateway.auth.token

ลายเซ็นที่พบบ่อย:

• refusing to bind gateway ... without auth → bind แบบไม่ใช่ loopback โดยไม่มีเส้นทางยืนยันตัวตนของ Gateway ที่ถูกต้อง
• Connectivity probe: failed ขณะที่รันไทม์กำลังทำงาน → Gateway ยังทำงานอยู่แต่เข้าถึงไม่ได้ด้วย auth/url ปัจจุบัน

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

สิ่งที่ต้องตรวจสอบ:

• การอนุมัติอุปกรณ์ที่รอดำเนินการสำหรับแดชบอร์ด/Nodes
• การอนุมัติการจับคู่ DM ที่รอดำเนินการหลังเปลี่ยนนโยบายหรือตัวตน

ลายเซ็นที่พบบ่อย:

• device identity required → ยังไม่ผ่านการยืนยันตัวตนอุปกรณ์
• pairing required → ผู้ส่ง/อุปกรณ์ต้องได้รับอนุมัติ