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

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

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

แท็บ บันทึก ใน 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

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

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

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

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

openclaw channels logs --channel whatsapp

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

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

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

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

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

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

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

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

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

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

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

# บันทึก WebSocket ของ Gateway

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

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

ตัวอย่าง:

openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw 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; ไม่เปลี่ยนระดับบันทึกไฟล์

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

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

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

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

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

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

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

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

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

logging.consoleStyle:

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

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

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

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

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

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

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

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

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

พื้นผิวใกล้เคียงสองส่วน:

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

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

{
  diagnostics: { enabled: true },
}

สำหรับการส่งออก OTLP ไปยังคอลเลกเตอร์ ดู การส่งออก OpenTelemetry

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

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

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

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