การบันทึกล็อก

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

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

แท็บ บันทึก ของ 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 ที่ระบุอย่างชัดเจนจะไม่ใช้ กลไกย้อนกลับนี้

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

openclaw doctor

Control UI (เว็บ)

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

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

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

openclaw channels logs --channel whatsapp

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

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

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

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

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

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

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

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

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

• คำนำหน้าระบบย่อย (เช่น gateway/channels/whatsapp)
• สีตามระดับ (info/warn/error)
• โหมดแบบกะทัดรัดหรือ 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-.*"]  }}

ระดับบันทึก

• 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 และแท็บบันทึกของ Control UI จะแสดงข้อมูลเหล่านี้ หากไม่มีแฟล็ก การวินิจฉัยเดียวกัน ยังพร้อมใช้งานที่ระดับ debug

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

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

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

ระเบียนบันทึกวงจรชีวิตของการสนทนายังไหลไปยังบันทึก OTLP เมื่อเปิดใช้งานการส่งออกบันทึก OpenTelemetry โดยใช้แอตทริบิวต์แบบมีขอบเขตเดียวกับบันทึกไฟล์

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

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

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

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

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

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

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

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

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

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

{  diagnostics: { enabled: true },}

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

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

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

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

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