การบันทึก日志

OpenClaw มีพื้นผิวบันทึกหลักสองแบบ:

• บันทึกไฟล์ (บรรทัด JSON) ที่เขียนโดย Gateway
• เอาต์พุตคอนโซล ที่แสดงในเทอร์มินัลและ Gateway Debug UI

แท็บ Logs ของ Control UI ติดตามไฟล์บันทึกของ Gateway แบบต่อท้าย หน้านี้อธิบายว่าบันทึกอยู่ที่ใด วิธีอ่านบันทึก และวิธีกำหนดค่าระดับและรูปแบบบันทึก

ตำแหน่งที่เก็บบันทึก

โดยค่าเริ่มต้น Gateway จะเขียนไฟล์บันทึกแบบหมุนเวียนไว้ใต้:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

วันที่ใช้เขตเวลาท้องถิ่นของโฮสต์ Gateway

แต่ละไฟล์จะหมุนเวียนเมื่อมีขนาดถึง logging.maxFileBytes (ค่าเริ่มต้น: 100 MB) OpenClaw จะเก็บไฟล์เก็บถาวรที่มีหมายเลขไว้ข้างไฟล์ที่ใช้งานอยู่สูงสุดห้าไฟล์ เช่น openclaw-YYYY-MM-DD.1.log และจะเขียนต่อไปยังไฟล์บันทึกที่ใช้งานอยู่ไฟล์ใหม่แทนที่จะระงับข้อมูลวินิจฉัย

คุณสามารถแทนที่ค่านี้ได้ใน ~/.openclaw/openclaw.json:

{  "logging": {    "file": "/path/to/openclaw.log"  }}

วิธีอ่านบันทึก

CLI: ติดตามแบบสด (แนะนำ)

ใช้ CLI เพื่อติดตามไฟล์บันทึกของ Gateway ผ่าน RPC:

openclaw logs --follow

ตัวเลือกปัจจุบันที่มีประโยชน์:

• --local-time: แสดงเวลาในเขตเวลาท้องถิ่นของคุณ
• --url <url> / --token <token> / --timeout <ms>: แฟล็ก RPC มาตรฐานของ Gateway
• --expect-final: แฟล็กรอคำตอบสุดท้ายของ RPC ที่มีเอเจนต์รองรับ (ยอมรับที่นี่ผ่านเลเยอร์ไคลเอนต์ร่วม)

โหมดเอาต์พุต:

• เซสชัน TTY: บรรทัดบันทึกแบบสวยงาม มีสี และมีโครงสร้าง
• เซสชันที่ไม่ใช่ TTY: ข้อความธรรมดา
• --json: JSON แบบคั่นตามบรรทัด (หนึ่งเหตุการณ์บันทึกต่อบรรทัด)
• --plain: บังคับใช้ข้อความธรรมดาในเซสชัน TTY
• --no-color: ปิดใช้งานสี ANSI

เมื่อคุณส่ง --url อย่างชัดเจน CLI จะไม่ใช้ข้อมูลประจำตัวจากการกำหนดค่าหรือสภาพแวดล้อมโดยอัตโนมัติ; ให้ใส่ --token เองหาก Gateway เป้าหมายต้องมีการยืนยันตัวตน

ในโหมด JSON CLI จะปล่อยอ็อบเจกต์ที่ติดแท็ก type:

• meta: เมตาดาตาสตรีม (ไฟล์ เคอร์เซอร์ ขนาด)
• log: รายการบันทึกที่แยกวิเคราะห์แล้ว
• notice: คำใบ้การตัดทอน / การหมุนเวียน
• raw: บรรทัดบันทึกที่ยังไม่ได้แยกวิเคราะห์

หาก Gateway แบบ local loopback โดยนัยขอการจับคู่ ปิดระหว่างเชื่อมต่อ หรือหมดเวลาก่อนที่ logs.tail จะตอบ openclaw logs จะย้อนกลับไปใช้ไฟล์บันทึก Gateway ที่กำหนดค่าไว้โดยอัตโนมัติ เป้าหมาย --url ที่ระบุอย่างชัดเจนจะไม่ใช้การย้อนกลับนี้ openclaw logs --follow เข้มงวดกว่า: บน Linux จะใช้วารสาร Gateway ของ user-systemd ที่ใช้งานอยู่ตาม PID เมื่อมี และไม่เช่นนั้นจะลองเชื่อมต่อ Gateway แบบสดซ้ำต่อไปแทนการติดตามไฟล์ข้างเคียงที่อาจล้าสมัย

หากติดต่อ Gateway ไม่ได้ CLI จะพิมพ์คำใบ้สั้น ๆ ให้เรียกใช้:

openclaw doctor

Control UI (เว็บ)

แท็บ Logs ของ Control UI ติดตามไฟล์เดียวกันโดยใช้ logs.tail ดู Control UI สำหรับวิธีเปิดใช้งาน

บันทึกเฉพาะแชนเนล

หากต้องการกรองกิจกรรมแชนเนล (WhatsApp/Telegram/อื่น ๆ) ให้ใช้:

openclaw channels logs --channel whatsapp

รูปแบบบันทึก

บันทึกไฟล์ (JSONL)

แต่ละบรรทัดในไฟล์บันทึกเป็นอ็อบเจกต์ JSON CLI และ Control UI จะแยกวิเคราะห์รายการเหล่านี้เพื่อแสดงเอาต์พุตแบบมีโครงสร้าง (เวลา ระดับ ระบบย่อย ข้อความ)

ระเบียน JSONL ของบันทึกไฟล์ยังมีฟิลด์ระดับบนสุดที่เครื่องกรองได้เมื่อมี:

• hostname: ชื่อโฮสต์ Gateway
• message: ข้อความบันทึกที่ทำให้แบนราบสำหรับการค้นหาข้อความแบบเต็ม
• agent_id: id ของเอเจนต์ที่ใช้งานอยู่เมื่อการเรียกบันทึกมีบริบทเอเจนต์
• session_id: id/คีย์ของเซสชันที่ใช้งานอยู่เมื่อการเรียกบันทึกมีบริบทเซสชัน
• channel: แชนเนลที่ใช้งานอยู่เมื่อการเรียกบันทึกมีบริบทแชนเนล

OpenClaw จะคงอาร์กิวเมนต์บันทึกแบบมีโครงสร้างต้นฉบับไว้ข้างฟิลด์เหล่านี้ เพื่อให้ตัวแยกวิเคราะห์เดิมที่อ่านคีย์อาร์กิวเมนต์ tslog แบบมีหมายเลขยังทำงานได้

กิจกรรมการพูดคุย เสียงแบบเรียลไทม์ และห้องที่จัดการจะปล่อยระเบียนบันทึกวงจรชีวิตแบบมีขอบเขตผ่านไปป์ไลน์บันทึกไฟล์เดียวกันนี้ ระเบียนเหล่านี้มีประเภทเหตุการณ์ โหมด การขนส่ง ผู้ให้บริการ และการวัดขนาด/เวลาเมื่อมี แต่ละเว้นข้อความถอดเสียง เพย์โหลดเสียง turn ids, call ids และ provider item ids

เอาต์พุตคอนโซล

บันทึกคอนโซล รับรู้ TTY และจัดรูปแบบเพื่อให้อ่านง่าย:

• คำนำหน้าระบบย่อย (เช่น gateway/channels/whatsapp)
• การใส่สีตามระดับ (info/warn/error)
• โหมดกะทัดรัดหรือ JSON ที่เลือกได้

การจัดรูปแบบคอนโซลถูกควบคุมโดย logging.consoleStyle

บันทึก WebSocket ของ Gateway

openclaw gateway ยังมีการบันทึกโปรโตคอล WebSocket สำหรับทราฟฟิก RPC:

• โหมดปกติ: เฉพาะผลลัพธ์ที่น่าสนใจ (ข้อผิดพลาด ข้อผิดพลาดการแยกวิเคราะห์ การเรียกที่ช้า)
• --verbose: ทราฟฟิกคำขอ/คำตอบทั้งหมด
• --ws-log auto|compact|full: เลือกรูปแบบการแสดงผล verbose
• --compact: นามแฝงของ --ws-log compact

ตัวอย่าง:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw gateway --verbose --ws-log full

การกำหนดค่าการบันทึก

การกำหนดค่าการบันทึกทั้งหมดอยู่ใต้ logging ใน ~/.openclaw/openclaw.json

{  "logging": {    "level": "info",    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",    "consoleLevel": "info",    "consoleStyle": "pretty",    "redactSensitive": "tools",    "redactPatterns": ["sk-.*"]  }}

ระดับบันทึก

• logging.level: ระดับของ บันทึกไฟล์ (JSONL)
• logging.consoleLevel: ระดับความละเอียดของ คอนโซล

คุณสามารถแทนที่ทั้งสองค่าผ่านตัวแปรสภาพแวดล้อม OPENCLAW_LOG_LEVEL (เช่น OPENCLAW_LOG_LEVEL=debug) ตัวแปรสภาพแวดล้อมมีลำดับความสำคัญเหนือไฟล์กำหนดค่า ดังนั้นคุณจึงเพิ่มความละเอียดสำหรับการเรียกใช้ครั้งเดียวได้โดยไม่ต้องแก้ไข openclaw.json คุณยังสามารถส่งตัวเลือก CLI ส่วนกลาง --log-level <level> (เช่น openclaw --log-level debug gateway run) ซึ่งจะแทนที่ตัวแปรสภาพแวดล้อมสำหรับคำสั่งนั้น

--verbose มีผลเฉพาะกับเอาต์พุตคอนโซลและความละเอียดของบันทึก WS; ไม่เปลี่ยนระดับบันทึกไฟล์

การวินิจฉัยการขนส่งโมเดลแบบเจาะจง

เมื่อดีบักการเรียกผู้ให้บริการ ให้ใช้แฟล็กสภาพแวดล้อมแบบเจาะจงแทนการเพิ่มบันทึกทั้งหมดเป็น debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

แฟล็กที่มี:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: ปล่อยการเริ่มคำขอ การตอบกลับ fetch ส่วนหัว SDK เหตุการณ์สตรีมแรก การจบสตรีม และข้อผิดพลาดการขนส่งที่ระดับ info
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: รวมสรุปเพย์โหลดคำขอแบบมีขอบเขตในบันทึกคำขอโมเดล
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: รวมชื่อเครื่องมือทั้งหมดที่หันหาโมเดลในสรุปเพย์โหลด
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: รวมสแนปช็อตเพย์โหลด JSON ที่ปกปิดแล้วและจำกัดขนาด ใช้เฉพาะขณะดีบัก; ความลับจะถูกปกปิด แต่พรอมป์และข้อความอาจยังคงมีอยู่
• OPENCLAW_DEBUG_SSE=events: ปล่อยเวลาของเหตุการณ์แรกและการจบสตรีม
• OPENCLAW_DEBUG_SSE=peek: ปล่อยเพย์โหลดเหตุการณ์ SSE ห้ารายการแรกที่ปกปิดแล้วเพิ่มเติม โดยจำกัดขนาดต่อเหตุการณ์
• OPENCLAW_DEBUG_CODE_MODE=1: ปล่อยการวินิจฉัยพื้นผิวโมเดลของโหมดโค้ด รวมถึงเมื่อเครื่องมือผู้ให้บริการแบบเนทีฟถูกซ่อนเพราะโหมดโค้ดเป็นเจ้าของพื้นผิวเครื่องมือ

แฟล็กเหล่านี้บันทึกผ่านการบันทึกปกติของ OpenClaw ดังนั้น openclaw logs --follow และแท็บ Logs ของ Control UI จะแสดงรายการเหล่านี้ หากไม่มีแฟล็ก การวินิจฉัยเดียวกันยังคงมีให้ที่ระดับ debug

เมตาดาตาการเริ่มต้นและการตอบกลับของ [model-fetch] (ผู้ให้บริการ API โมเดล สถานะ เวลาแฝง และฟิลด์คำขอ เช่น เมธอด URL หมดเวลา พร็อกซี และนโยบาย) จะถูกปล่อยที่ระดับ info เสมอโดยไม่ขึ้นกับ OPENCLAW_DEBUG_MODEL_TRANSPORT ดังนั้นสุขอนามัยพื้นฐานของการขนส่งโมเดลจึงมองเห็นได้โดยไม่ต้องใช้แฟล็กดีบัก

การเชื่อมโยงร่องรอย

บันทึกไฟล์เป็น JSONL เมื่อการเรียกบันทึกมีบริบท diagnostic trace ที่ถูกต้อง OpenClaw จะเขียนฟิลด์ trace เป็นคีย์ JSON ระดับบนสุด (traceId, spanId, parentSpanId, traceFlags) เพื่อให้ตัวประมวลผลบันทึกภายนอกเชื่อมโยงบรรทัดกับ OTEL spans และการเผยแพร่ traceparent ของผู้ให้บริการได้

คำขอ HTTP ของ Gateway และเฟรม WebSocket ของ Gateway จะสร้างขอบเขตร่องรอยคำขอภายใน บันทึกและเหตุการณ์วินิจฉัยที่ปล่อยภายในขอบเขต async นั้นจะสืบทอดร่องรอยคำขอเมื่อไม่ได้ส่งบริบท trace อย่างชัดเจน ร่องรอยการรันเอเจนต์และการเรียกโมเดลจะกลายเป็นลูกของร่องรอยคำขอที่ใช้งานอยู่ ดังนั้นบันทึกในเครื่อง สแนปช็อตวินิจฉัย OTEL spans และส่วนหัว traceparent ของผู้ให้บริการที่เชื่อถือได้จึงสามารถเชื่อมเข้าด้วยกันด้วย traceId โดยไม่ต้องบันทึกคำขอดิบหรือเนื้อหาโมเดล

ระเบียนบันทึกวงจรชีวิตของการพูดคุยยังไหลไปยังการส่งออกบันทึก diagnostics-otel เมื่อเปิดใช้การส่งออกบันทึก OpenTelemetry โดยใช้แอตทริบิวต์แบบมีขอบเขตเดียวกับบันทึกไฟล์ กำหนดค่า diagnostics.otel.logsExporter เพื่อเลือก OTLP, stdout JSONL หรือทั้งสองปลายทาง

ขนาดและเวลาของการเรียกโมเดล

การวินิจฉัยการเรียกโมเดลบันทึกการวัดคำขอ/คำตอบแบบมีขอบเขตโดยไม่จับเนื้อหาพรอมป์หรือคำตอบดิบ:

• requestPayloadBytes: ขนาดเป็นไบต์ UTF-8 ของเพย์โหลดคำขอโมเดลสุดท้าย
• responseStreamBytes: ขนาดเป็นไบต์ UTF-8 ของเพย์โหลดชังก์คำตอบโมเดลแบบสตรีม เหตุการณ์ข้อความความถี่สูง การคิด และเดลตาการเรียกเครื่องมือนับเฉพาะไบต์ delta ที่เพิ่มขึ้นแทนสแนปช็อต partial ทั้งหมด
• timeToFirstByteMs: เวลาที่ผ่านไปก่อนเหตุการณ์คำตอบแบบสตรีมแรก
• durationMs: ระยะเวลารวมของการเรียกโมเดล

ฟิลด์เหล่านี้พร้อมใช้กับสแนปช็อตวินิจฉัย hooks ของ Plugin สำหรับการเรียกโมเดล และ spans/metrics ของ OTEL สำหรับการเรียกโมเดลเมื่อเปิดใช้การส่งออกการวินิจฉัย

รูปแบบคอนโซล

logging.consoleStyle:

• pretty: เป็นมิตรต่อมนุษย์ มีสี และมีเวลา
• compact: เอาต์พุตกระชับกว่า (ดีที่สุดสำหรับเซสชันยาว)
• json: JSON ต่อบรรทัด (สำหรับตัวประมวลผลบันทึก)

การปกปิดข้อมูล

OpenClaw สามารถปกปิดโทเค็นอ่อนไหวก่อนที่จะไปถึงเอาต์พุตคอนโซล บันทึกไฟล์ ระเบียนบันทึก OTLP ข้อความถอดเสียงเซสชันที่คงไว้ หรือเพย์โหลดเหตุการณ์เครื่องมือของ Control UI (อาร์กิวเมนต์เริ่มเครื่องมือ เพย์โหลดผลลัพธ์บางส่วน/สุดท้าย เอาต์พุต exec ที่ได้มา และสรุปแพตช์):

• logging.redactSensitive: off | tools (ค่าเริ่มต้น: tools)
• logging.redactPatterns: รายการสตริง regex เพื่อแทนที่ชุดค่าเริ่มต้น รูปแบบแบบกำหนดเองจะใช้ทับค่าเริ่มต้นในตัวสำหรับเพย์โหลดเครื่องมือของ Control UI ดังนั้นการเพิ่มรูปแบบจะไม่ทำให้การปกปิดค่าที่ค่าเริ่มต้นจับได้อยู่แล้วอ่อนลง

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

ค่าเริ่มต้นในตัวครอบคลุมข้อมูลประจำตัว API และชื่อฟิลด์ข้อมูลประจำตัวการชำระเงินทั่วไป เช่น หมายเลขบัตร CVC/CVV โทเค็นการชำระเงินที่ใช้ร่วมกัน และข้อมูลประจำตัวการชำระเงิน เมื่อปรากฏเป็นฟิลด์ JSON พารามิเตอร์ URL แฟล็ก CLI หรือการกำหนดค่า

logging.redactSensitive: "off" ปิดใช้งานเฉพาะนโยบายบันทึก/ข้อความถอดเสียงทั่วไปนี้ OpenClaw ยังคงปกปิดเพย์โหลดขอบเขตความปลอดภัยที่อาจแสดงให้ไคลเอนต์ UI ชุดข้อมูลสนับสนุน ผู้สังเกตการณ์การวินิจฉัย พรอมป์อนุมัติ หรือเครื่องมือเอเจนต์ ตัวอย่างรวมถึงเหตุการณ์การเรียกเครื่องมือของ Control UI, เอาต์พุต sessions_history, การส่งออกข้อมูลสนับสนุนการวินิจฉัย, การสังเกตข้อผิดพลาดของผู้ให้บริการ, การแสดงคำสั่งอนุมัติ exec และบันทึกโปรโตคอล WebSocket ของ Gateway logging.redactPatterns แบบกำหนดเองยังสามารถเพิ่มรูปแบบเฉพาะโปรเจกต์บนพื้นผิวเหล่านั้นได้

การวินิจฉัยและ OpenTelemetry

การวินิจฉัยคือเหตุการณ์แบบมีโครงสร้างที่เครื่องอ่านได้สำหรับการรันโมเดลและเทเลเมทรีของ message-flow (webhooks, การเข้าคิว, สถานะเซสชัน) สิ่งเหล่านี้ ไม่ แทนที่บันทึก — แต่ป้อนข้อมูลให้เมตริก ร่องรอย และตัวส่งออก เหตุการณ์จะถูกปล่อยภายในกระบวนการไม่ว่าคุณจะส่งออกหรือไม่

พื้นผิวที่อยู่ติดกันสองแบบ:

• การส่งออก OpenTelemetry — ส่งเมตริก ร่องรอย และบันทึกผ่าน OTLP/HTTP ไปยังตัวรวบรวมหรือแบ็กเอนด์ที่เข้ากันได้กับ OpenTelemetry ใดก็ได้ (Grafana, Datadog, Honeycomb, New Relic, Tempo และอื่น ๆ) การกำหนดค่าทั้งหมด แคตตาล็อกสัญญาณ ชื่อเมตริก/span ตัวแปรสภาพแวดล้อม และโมเดลความเป็นส่วนตัวอยู่ในหน้าเฉพาะ: การส่งออก OpenTelemetry
• แฟล็กการวินิจฉัย — แฟล็กบันทึกดีบักแบบเจาะจงที่ส่งบันทึกเพิ่มเติมไปยัง logging.file โดยไม่เพิ่ม logging.level แฟล็กไม่คำนึงถึงตัวพิมพ์เล็กใหญ่ และรองรับไวลด์การ์ด (telegram.*, *) กำหนดค่าภายใต้ diagnostics.flags หรือผ่านการแทนที่สภาพแวดล้อม OPENCLAW_DIAGNOSTICS=... คู่มือฉบับเต็ม: แฟล็กการวินิจฉัย

หากต้องการเปิดใช้เหตุการณ์การวินิจฉัยสำหรับ Plugin หรือปลายทางแบบกำหนดเองโดยไม่ส่งออก OTLP:

{  diagnostics: { enabled: true },}

สำหรับการส่งออก OTLP ไปยัง collector โปรดดู การส่งออก OpenTelemetry

เคล็ดลับการแก้ไขปัญหา

• เข้าถึง Gateway ไม่ได้ใช่ไหม รัน openclaw doctor ก่อน
• Logs ว่างอยู่ใช่ไหม ตรวจสอบว่า Gateway กำลังทำงานและเขียนไปยังเส้นทางไฟล์ ใน logging.file
• ต้องการรายละเอียดเพิ่มเติมใช่ไหม ตั้งค่า logging.level เป็น debug หรือ trace แล้วลองอีกครั้ง

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

• การส่งออก OpenTelemetry — การส่งออก OTLP/HTTP, แค็ตตาล็อก metric/span, โมเดลความเป็นส่วนตัว
• แฟล็ก Diagnostics — แฟล็ก debug-log แบบเจาะจง
• รายละเอียดภายในของการ logging ของ Gateway — รูปแบบ log ของ WS, คำนำหน้าระบบย่อย และการจับข้อมูล console
• ข้อมูลอ้างอิงการกำหนดค่า — ข้อมูลอ้างอิงฟิลด์ diagnostics.* ฉบับเต็ม