docs/docs/id/help/debugging.md

read_when	summary	title	x-i18n
Anda perlu memeriksa keluaran model mentah untuk kebocoran penalaran Anda ingin menjalankan Gateway dalam mode pemantauan saat melakukan iterasi Anda memerlukan alur kerja debugging yang dapat diulang	Alat debugging: mode watch, stream model mentah, dan pelacakan kebocoran penalaran	Penelusuran kesalahan	generated_at model provider source_hash source_path workflow 2026-05-02T22:19:38Z gpt-5.5 openai 7a72a1508915e37ffdc5317889cdfde7024de3f5702739640abc2f03c3abadb7 help/debugging.md 16

Pembantu debugging untuk keluaran streaming, terutama ketika penyedia mencampurkan reasoning ke dalam teks normal.

Override debug runtime

Gunakan /debug di chat untuk menetapkan override konfigurasi hanya runtime (memori, bukan disk). /debug dinonaktifkan secara default; aktifkan dengan commands.debug: true. Ini berguna ketika Anda perlu mengaktifkan atau menonaktifkan pengaturan tersembunyi tanpa mengedit openclaw.json.

Contoh:

/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset

/debug reset menghapus semua override dan kembali ke konfigurasi di disk.

Keluaran jejak sesi

Gunakan /trace ketika Anda ingin melihat baris jejak/debug milik plugin dalam satu sesi tanpa mengaktifkan mode verbose penuh.

Contoh:

/trace
/trace on
/trace off

Gunakan /trace untuk diagnostik plugin seperti ringkasan debug Active Memory. Tetap gunakan /verbose untuk keluaran status/tool verbose normal, dan tetap gunakan /debug untuk override konfigurasi hanya runtime.

Jejak siklus hidup Plugin

Gunakan OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 ketika perintah siklus hidup plugin terasa lambat dan Anda memerlukan uraian fase bawaan untuk metadata plugin, discovery, registry, runtime mirror, mutasi konfigurasi, dan pekerjaan refresh. Jejak ini bersifat opt-in dan menulis ke stderr, sehingga keluaran perintah JSON tetap dapat diurai.

Contoh:

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

Contoh keluaran:

[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

Gunakan ini untuk investigasi siklus hidup plugin sebelum menggunakan profiler CPU. Jika perintah berjalan dari checkout sumber, lebih baik ukur runtime yang sudah dibangun dengan node dist/entry.js ... setelah pnpm build; pnpm openclaw ... juga mengukur overhead source-runner.

Startup CLI dan profiling perintah

Gunakan benchmark startup yang sudah diperiksa masuk ketika perintah terasa lambat:

pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

Untuk profiling sekali jalan melalui source runner normal, tetapkan OPENCLAW_RUN_NODE_CPU_PROF_DIR:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

Source runner menambahkan flag profil CPU Node dan menulis .cpuprofile untuk perintah tersebut. Gunakan ini sebelum menambahkan instrumentasi sementara ke kode perintah.

Mode watch Gateway

Untuk iterasi cepat, jalankan gateway di bawah file watcher:

pnpm gateway:watch

Secara default, ini memulai atau memulai ulang sesi tmux bernama openclaw-gateway-watch-main (atau varian khusus profil/port seperti openclaw-gateway-watch-dev-19001) dan melakukan auto-attach dari terminal interaktif. Shell non-interaktif, CI, dan panggilan exec agen tetap detached dan mencetak instruksi attach sebagai gantinya. Attach secara manual saat diperlukan:

tmux attach -t openclaw-gateway-watch-main

Pane tmux menjalankan watcher mentah:

node scripts/watch-node.mjs gateway --force

Gunakan mode foreground ketika tmux tidak diinginkan:

pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Nonaktifkan auto-attach sambil tetap mempertahankan manajemen tmux:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Profilkan waktu CPU Gateway yang dipantau saat men-debug hotspot startup/runtime:

pnpm gateway:watch --benchmark

Wrapper watch mengonsumsi --benchmark sebelum memanggil Gateway dan menulis satu .cpuprofile V8 per keluarnya child Gateway di bawah .artifacts/gateway-watch-profiles/. Hentikan atau mulai ulang gateway yang dipantau untuk flush profil saat ini, lalu buka dengan Chrome DevTools atau Speedscope:

npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile

Gunakan --benchmark-dir <path> ketika Anda menginginkan profil di tempat lain.

Wrapper tmux membawa selector runtime non-rahasia umum seperti OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT, dan OPENCLAW_SKIP_CHANNELS ke dalam pane. Letakkan kredensial penyedia di profil/konfigurasi normal Anda, atau gunakan mode foreground mentah untuk rahasia ephemeral sekali pakai. Pane tmux terkelola juga secara default menggunakan log Gateway berwarna agar lebih mudah dibaca; tetapkan FORCE_COLOR=0 saat memulai pnpm gateway:watch untuk menonaktifkan keluaran ANSI.

Watcher memulai ulang pada file relevan-build di bawah src/, file sumber ekstensi, metadata ekstensi package.json dan openclaw.plugin.json, tsconfig.json, package.json, dan tsdown.config.ts. Perubahan metadata ekstensi memulai ulang gateway tanpa memaksa rebuild tsdown; perubahan sumber dan konfigurasi tetap membangun ulang dist terlebih dahulu.

Tambahkan flag CLI gateway apa pun setelah gateway:watch dan flag tersebut akan diteruskan pada setiap restart. Menjalankan ulang perintah watch yang sama akan respawn pane tmux bernama tersebut, dan watcher mentah tetap mempertahankan kunci single-watcher sehingga parent watcher duplikat digantikan alih-alih menumpuk.

Profil dev + gateway dev (--dev)

Gunakan profil dev untuk mengisolasi state dan menjalankan setup yang aman dan dapat dibuang untuk debugging. Ada dua flag --dev:

• --dev global (profil): mengisolasi state di bawah ~/.openclaw-dev dan menetapkan port gateway default ke 19001 (port turunan bergeser bersamanya).
• gateway --dev: memberi tahu Gateway untuk otomatis membuat konfigurasi default + workspace ketika belum ada (dan melewati BOOTSTRAP.md).

Alur yang direkomendasikan (profil dev + bootstrap dev):

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Jika Anda belum memiliki instalasi global, jalankan CLI melalui pnpm openclaw ....

Yang dilakukan ini:

1. Isolasi profil (--dev global)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001 (browser/canvas bergeser sesuai)

2. Bootstrap dev (gateway --dev)

   • Menulis konfigurasi minimal jika belum ada (gateway.mode=local, bind loopback).
   • Menetapkan agent.workspace ke workspace dev.
   • Menetapkan agent.skipBootstrap=true (tanpa BOOTSTRAP.md).
   • Mengisi file workspace jika belum ada: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
   • Identitas default: C3‑PO (droid protokol).
   • Melewati penyedia channel dalam mode dev (OPENCLAW_SKIP_CHANNELS=1).

Alur reset (mulai baru):

pnpm gateway:dev:reset

`--dev` adalah flag profil **global** dan dimakan oleh beberapa runner. Jika Anda perlu menuliskannya eksplisit, gunakan bentuk env var:

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--reset menghapus konfigurasi, kredensial, sesi, dan workspace dev (menggunakan trash, bukan rm), lalu membuat ulang setup dev default.

Jika gateway non-dev sudah berjalan (launchd atau systemd), hentikan terlebih dahulu:

openclaw gateway stop

Logging stream mentah (OpenClaw)

OpenClaw dapat mencatat stream assistant mentah sebelum pemfilteran/pemformatan apa pun. Ini adalah cara terbaik untuk melihat apakah reasoning datang sebagai delta teks biasa (atau sebagai blok thinking terpisah).

Aktifkan melalui CLI:

pnpm gateway:watch --raw-stream

Override path opsional:

pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

Env var yang setara:

OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

File default:

~/.openclaw/logs/raw-stream.jsonl

Logging chunk mentah (pi-mono)

Untuk menangkap chunk kompatibel OpenAI mentah sebelum diurai menjadi blok, pi-mono menyediakan logger terpisah:

PI_RAW_STREAM=1

Path opsional:

PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

File default:

~/.pi-mono/logs/raw-openai-completions.jsonl

Catatan: ini hanya dipancarkan oleh proses yang menggunakan penyedia openai-completions milik pi-mono.

Catatan keamanan

• Log stream mentah dapat mencakup prompt penuh, keluaran tool, dan data pengguna.
• Simpan log secara lokal dan hapus setelah debugging.
• Jika Anda membagikan log, bersihkan rahasia dan PII terlebih dahulu.

Terkait

• Pemecahan masalah
• FAQ