การบันทึกบันทึกเหตุการณ์

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

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

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

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

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

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

วันที่ใช้เขตเวลาท้องถิ่นของโฮสต์ Gateway เมื่อ /tmp/openclaw ไม่ปลอดภัย หรือไม่พร้อมใช้งาน (และบน Windows เสมอ) OpenClaw จะใช้ไดเรกทอรี openclaw-<uid> ที่จำกัดขอบเขตตามผู้ใช้ภายใต้ไดเรกทอรีชั่วคราวของระบบปฏิบัติการแทน ไฟล์บันทึกที่ระบุวันที่ จะถูกลบออกหลังจาก 24 ชั่วโมง

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

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

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

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

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

ติดตามไฟล์บันทึกของ Gateway ผ่าน RPC:

openclaw logs --follow

ตัวเลือก:

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

• เซสชัน TTY: บรรทัดบันทึกแบบมีโครงสร้างที่สวยงาม มีสี
• เซสชันที่ไม่ใช่ TTY: ข้อความธรรมดา

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

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

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

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

หากไม่สามารถเข้าถึง Gateway ได้ CLI จะแสดงคำแนะนำสั้น ๆ ให้เรียกใช้:

openclaw doctor

UI ควบคุม (เว็บ)

แท็บ บันทึก ของ UI ควบคุมจะติดตามไฟล์เดียวกันโดยใช้ logs.tail ดูวิธีเปิดได้ที่ UI ควบคุม

บันทึกเฉพาะช่องทาง

หากต้องการกรองกิจกรรมของช่องทาง (WhatsApp/Telegram/ฯลฯ) ให้ใช้:

openclaw channels logs --channel whatsapp

--channel มีค่าเริ่มต้นเป็น all นอกจากนี้ยังมี --lines <n> (ค่าเริ่มต้น 200) และ --json ให้ใช้งาน

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

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

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

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

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

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

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

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

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

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

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

บันทึก WebSocket ของ Gateway

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

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

ระดับบันทึก

ระดับ: silent, fatal, error, warn, info, debug, trace

• logging.level: ระดับของ บันทึกไฟล์ (JSONL) (ค่าเริ่มต้น: info)
• 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: ส่งออกจุดเริ่มต้นคำขอ การตอบกลับจากการดึงข้อมูล ส่วนหัว 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 และแท็บบันทึกของ UI ควบคุมจะแสดงข้อมูลเหล่านี้ หากไม่มีแฟล็ก ข้อมูลวินิจฉัยเดียวกัน จะยังคงพร้อมใช้งานที่ระดับ debug

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

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

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

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

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

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

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

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

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

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

logging.consoleStyle:

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

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

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

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

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

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

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

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

ข้อมูลการวินิจฉัยคือเหตุการณ์แบบมีโครงสร้างที่เครื่องอ่านได้ สำหรับการเรียกใช้โมเดลและเทเลเมทรีของโฟลว์ข้อความ (webhooks, การเข้าคิว, สถานะเซสชัน) ข้อมูลเหล่านี้ ไม่ได้ ใช้แทนบันทึก แต่จะป้อนข้อมูลให้เมตริก เทรซ และตัวส่งออก โดยค่าเริ่มต้น เหตุการณ์จะถูกปล่อยภายในกระบวนการ (ตั้งค่า diagnostics.enabled: false เพื่อปิด) ส่วนการส่งออกเหตุการณ์เป็นการตั้งค่าแยกต่างหาก

มีสองพื้นผิวที่เกี่ยวข้องกัน:

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

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

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

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

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

• การส่งออก OpenTelemetry — การส่งออกผ่าน OTLP/HTTP, แค็ตตาล็อกเมตริก/สแปน, โมเดลความเป็นส่วนตัว
• แฟล็กการวินิจฉัย — แฟล็กบันทึกการแก้ไขจุดบกพร่องแบบเจาะจง
• กลไกภายในของการบันทึก Gateway — รูปแบบบันทึก WS, คำนำหน้าระบบย่อย และการจับเอาต์พุตคอนโซล
• เอกสารอ้างอิงการกำหนดค่า — เอกสารอ้างอิงฟิลด์ diagnostics.* ฉบับเต็ม