---
read_when:
    - คุณต้องการภาพรวมเกี่ยวกับการบันทึกล็อกของ OpenClaw ที่เป็นมิตรกับผู้เริ่มต้น
    - คุณต้องการกำหนดค่าระดับล็อก รูปแบบ หรือการปกปิดข้อมูล
    - คุณกำลังแก้ไขปัญหาและต้องค้นหาบันทึกอย่างรวดเร็ว
summary: ไฟล์บันทึก, เอาต์พุตคอนโซล, การ tail ผ่าน CLI และแท็บบันทึกของ UI ควบคุม
title: การบันทึกล็อก
x-i18n:
    generated_at: "2026-05-11T20:33:34Z"
    model: gpt-5.5
    provider: openai
    source_hash: 49b28755998bbe667dd986ae8440d9006d03b0704679bb6d64b5a148a25fc50e
    source_path: logging.md
    workflow: 16
---

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`:

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

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

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

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

```bash
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 จะแสดงคำใบ้สั้น ๆ ให้เรียกใช้:

```bash
openclaw doctor
```

### Control UI (เว็บ)

แท็บ **บันทึก** ของ Control UI จะติดตามไฟล์เดียวกันโดยใช้ `logs.tail`
ดู [Control UI](/th/web/control-ui) สำหรับวิธีเปิดใช้งาน

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

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

```bash
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`

ตัวอย่าง:

```bash
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```

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

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

```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`:

```bash
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_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](/th/gateway/opentelemetry)
- **แฟล็กการวินิจฉัย** — แฟล็กบันทึกดีบักแบบเจาะจงที่ส่งบันทึกเพิ่มเติมไปยัง
  `logging.file` โดยไม่เพิ่ม `logging.level` แฟล็กไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก
  และรองรับไวลด์การ์ด (`telegram.*`, `*`) กำหนดค่าใต้ `diagnostics.flags`
  หรือผ่านการแทนที่ด้วยตัวแปรสภาพแวดล้อม `OPENCLAW_DIAGNOSTICS=...` คู่มือฉบับเต็ม:
  [แฟล็กการวินิจฉัย](/th/diagnostics/flags)

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

```json5
{
  diagnostics: { enabled: true },
}
```

สำหรับการส่งออก OTLP ไปยัง collector โปรดดู [การส่งออก OpenTelemetry](/th/gateway/opentelemetry)

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

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

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

- [การส่งออก OpenTelemetry](/th/gateway/opentelemetry) — การส่งออก OTLP/HTTP, แค็ตตาล็อก metric/span, โมเดลความเป็นส่วนตัว
- [แฟล็กการวินิจฉัย](/th/diagnostics/flags) — แฟล็กบันทึกดีบักแบบเจาะจง
- [กลไกภายในของการบันทึก Gateway](/th/gateway/logging) — รูปแบบบันทึก WS, คำนำหน้าระบบย่อย และการจับคอนโซล
- [ข้อมูลอ้างอิงการกำหนดค่า](/th/gateway/configuration-reference#diagnostics) — ข้อมูลอ้างอิงฟิลด์ `diagnostics.*` ทั้งหมด