اشکال‌زدایی

راهنماهای اشکال‌زدایی برای خروجی جریانی، به‌ویژه وقتی یک ارائه‌دهنده استدلال را با متن عادی ترکیب می‌کند.

بازنویسی‌های اشکال‌زدایی زمان اجرا

از /debug در چت استفاده کنید تا بازنویسی‌های پیکربندی فقط زمان اجرا را تنظیم کنید (در حافظه، نه روی دیسک). /debug به‌طور پیش‌فرض غیرفعال است؛ با commands.debug: true فعالش کنید. این زمانی کاربردی است که لازم است تنظیمات کم‌استفاده را بدون ویرایش openclaw.json تغییر دهید.

مثال‌ها:

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

/debug reset همه بازنویسی‌ها را پاک می‌کند و به پیکربندی روی دیسک برمی‌گردد.

خروجی ردگیری نشست

وقتی می‌خواهید خط‌های ردگیری/اشکال‌زدایی متعلق به Plugin را در یک نشست ببینید، بدون اینکه حالت پرجزئیات کامل را روشن کنید، از /trace استفاده کنید.

مثال‌ها:

/trace/trace on/trace off

از /trace برای عیب‌یابی‌های Plugin مانند خلاصه‌های اشکال‌زدایی Active Memory استفاده کنید. برای خروجی معمول وضعیت/ابزار پرجزئیات همچنان از /verbose استفاده کنید، و برای بازنویسی‌های پیکربندی فقط زمان اجرا همچنان از /debug استفاده کنید.

ردگیری چرخهٔ حیات Plugin

وقتی فرمان‌های چرخهٔ حیات Plugin کند به نظر می‌رسند و به یک تفکیک مرحله‌ای داخلی برای فرادادهٔ Plugin، کشف، رجیستری، آینهٔ زمان اجرا، تغییر پیکربندی، و کارهای تازه‌سازی نیاز دارید، از OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 استفاده کنید. ردگیری اختیاری است و در stderr نوشته می‌شود، بنابراین خروجی JSON فرمان همچنان قابل تجزیه می‌ماند.

مثال:

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

نمونه خروجی:

[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"

پیش از رفتن سراغ پروفایلر CPU، از این برای بررسی چرخهٔ حیات Plugin استفاده کنید. اگر فرمان از یک checkout منبع اجرا می‌شود، ترجیحاً پس از pnpm build زمان اجرای ساخته‌شده را با node dist/entry.js ... اندازه‌گیری کنید؛ pnpm openclaw ... سربار اجراکنندهٔ منبع را نیز اندازه‌گیری می‌کند.

پروفایل‌گیری راه‌اندازی CLI و فرمان‌ها

وقتی یک فرمان کند به نظر می‌رسد، از بنچمارک راه‌اندازی ثبت‌شده در مخزن استفاده کنید:

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

برای پروفایل‌گیری موردی از مسیر اجراکنندهٔ منبع معمول، OPENCLAW_RUN_NODE_CPU_PROF_DIR را تنظیم کنید:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

اجراکنندهٔ منبع پرچم‌های پروفایل CPU مربوط به Node را اضافه می‌کند و برای فرمان یک .cpuprofile می‌نویسد. پیش از افزودن ابزارگذاری موقت به کد فرمان، از این استفاده کنید.

برای توقف‌های راه‌اندازی که شبیه کار همگام فایل‌سیستم یا بارگذار ماژول هستند، پرچم ردگیری I/O همگام Node را از طریق اجراکنندهٔ منبع اضافه کنید:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch این پرچم را به‌طور پیش‌فرض برای فرزند تحت‌نظر Gateway غیرفعال می‌گذارد. وقتی صراحتاً خروجی ردگیری I/O همگام Node را در حالت watch می‌خواهید، OPENCLAW_TRACE_SYNC_IO=1 را تنظیم کنید.

حالت watch برای Gateway

برای تکرار سریع، Gateway را زیر نظر watcher فایل اجرا کنید:

pnpm gateway:watch

به‌طور پیش‌فرض، این کار یک نشست tmux با نام openclaw-gateway-watch-main (یا گونه‌ای وابسته به پروفایل/درگاه مانند openclaw-gateway-watch-dev-19001) را شروع یا بازراه‌اندازی می‌کند و از ترمینال‌های تعاملی به‌صورت خودکار متصل می‌شود. پوسته‌های غیرتعاملی، CI، و فراخوانی‌های exec عامل جدا می‌مانند و به‌جای آن دستورالعمل اتصال را چاپ می‌کنند. در صورت نیاز دستی متصل شوید:

tmux attach -t openclaw-gateway-watch-main

پنجرهٔ tmux watcher خام را اجرا می‌کند:

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

وقتی tmux مطلوب نیست، از حالت پیش‌زمینه استفاده کنید:

pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

اتصال خودکار را غیرفعال کنید و مدیریت tmux را حفظ کنید:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

هنگام اشکال‌زدایی نقاط داغ راه‌اندازی/زمان اجرا، زمان CPU مربوط به Gateway تحت‌نظر را پروفایل کنید:

pnpm gateway:watch --benchmark

wrapper مربوط به watch، --benchmark را پیش از فراخوانی Gateway مصرف می‌کند و به‌ازای هر خروج فرزند Gateway، یک .cpuprofile مربوط به V8 را زیر .artifacts/gateway-watch-profiles/ می‌نویسد. Gateway تحت‌نظر را متوقف یا بازراه‌اندازی کنید تا پروفایل فعلی flush شود، سپس آن را با Chrome DevTools یا Speedscope باز کنید:

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

وقتی پروفایل‌ها را در جای دیگری می‌خواهید، از --benchmark-dir <path> استفاده کنید. وقتی می‌خواهید فرزند بنچمارک‌شده پاک‌سازی پیش‌فرض درگاه با --force را رد کند و اگر درگاه Gateway از قبل در حال استفاده است سریع شکست بخورد، از --benchmark-no-force استفاده کنید. حالت بنچمارک به‌طور پیش‌فرض هرزنامهٔ ردگیری sync-I/O را سرکوب می‌کند. وقتی صراحتاً هم پروفایل‌های CPU و هم stack traceهای sync-I/O در Node را می‌خواهید، OPENCLAW_TRACE_SYNC_IO=1 را همراه با --benchmark تنظیم کنید. در حالت بنچمارک، آن بلوک‌های ردگیری در gateway-watch-output.log زیر دایرکتوری بنچمارک نوشته می‌شوند و از پنجرهٔ ترمینال فیلتر می‌شوند؛ لاگ‌های عادی Gateway همچنان دیده می‌شوند.

wrapper مربوط به tmux انتخاب‌گرهای رایج غیرمحرمانهٔ زمان اجرا مانند OPENCLAW_PROFILE، OPENCLAW_CONFIG_PATH، OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT، و OPENCLAW_SKIP_CHANNELS را به پنجره منتقل می‌کند. اعتبارنامه‌های ارائه‌دهنده را در پروفایل/پیکربندی معمول خود قرار دهید، یا برای رازهای موقت موردی از حالت خام پیش‌زمینه استفاده کنید. اگر Gateway تحت‌نظر هنگام راه‌اندازی خارج شود، watcher یک‌بار openclaw doctor --fix --non-interactive را اجرا می‌کند و فرزند Gateway را بازراه‌اندازی می‌کند. وقتی شکست راه‌اندازی اولیه را بدون گذر تعمیر فقط توسعه می‌خواهید، از OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 استفاده کنید. پنجرهٔ مدیریت‌شدهٔ tmux نیز برای خوانایی به‌طور پیش‌فرض لاگ‌های رنگی Gateway را فعال می‌کند؛ برای غیرفعال‌کردن خروجی ANSI، هنگام شروع pnpm gateway:watch مقدار FORCE_COLOR=0 را تنظیم کنید.

watcher با تغییر فایل‌های مرتبط با build زیر src/، فایل‌های منبع extension، فرادادهٔ package.json و openclaw.plugin.json مربوط به extension، tsconfig.json, package.json، و tsdown.config.ts بازراه‌اندازی می‌شود. تغییرات فرادادهٔ extension، gateway را بدون اجبار به rebuild با tsdown بازراه‌اندازی می‌کند؛ تغییرات منبع و پیکربندی همچنان ابتدا dist را rebuild می‌کنند.

هر پرچم CLI مربوط به gateway را پس از gateway:watch اضافه کنید تا در هر بازراه‌اندازی منتقل شود. اجرای دوبارهٔ همان فرمان watch، پنجرهٔ tmux نام‌گذاری‌شده را دوباره spawn می‌کند، و watcher خام همچنان قفل تک-watcher خود را حفظ می‌کند تا والدهای watcher تکراری به‌جای انباشته‌شدن جایگزین شوند.

پروفایل dev + Gateway dev (--dev)

از پروفایل dev برای جداسازی state و بالا آوردن یک چیدمان ایمن و دورریختنی برای اشکال‌زدایی استفاده کنید. دو پرچم --dev وجود دارد:

• --dev سراسری (پروفایل): state را زیر ~/.openclaw-dev جدا می‌کند و درگاه پیش‌فرض gateway را 19001 می‌گذارد (درگاه‌های مشتق‌شده همراه آن جابه‌جا می‌شوند).
• gateway --dev: به Gateway می‌گوید در صورت نبود، یک پیکربندی پیش‌فرض + workspace را خودکار بسازد (و BOOTSTRAP.md را رد کند).

جریان پیشنهادی (پروفایل dev + bootstrap dev):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

اگر هنوز نصب سراسری ندارید، CLI را از طریق pnpm openclaw ... اجرا کنید.

این کار چه می‌کند:

1. جداسازی پروفایل (--dev سراسری)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001 (browser/canvas متناسب با آن جابه‌جا می‌شوند)

2. bootstrap توسعه (gateway --dev)

   • اگر موجود نباشد، یک پیکربندی حداقلی می‌نویسد (gateway.mode=local، bind روی loopback).
   • agent.workspace را روی workspace توسعه تنظیم می‌کند.
   • agent.skipBootstrap=true را تنظیم می‌کند (بدون BOOTSTRAP.md).
   • اگر فایل‌های workspace موجود نباشند، آن‌ها را seed می‌کند: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
   • هویت پیش‌فرض: C3-PO (protocol droid).
   • در حالت dev ارائه‌دهندگان channel را رد می‌کند (OPENCLAW_SKIP_CHANNELS=1).

جریان reset (شروع تازه):

pnpm gateway:dev:reset

--reset پیکربندی، اعتبارنامه‌ها، نشست‌ها، و workspace توسعه را پاک می‌کند (با استفاده از trash، نه rm) و سپس چیدمان پیش‌فرض dev را دوباره می‌سازد.

لاگ‌گیری stream خام (OpenClaw)

OpenClaw می‌تواند stream خام assistant را پیش از هرگونه فیلتر/قالب‌بندی لاگ کند. این بهترین راه برای دیدن این است که آیا reasoning به‌صورت deltaهای متن ساده می‌رسد (یا به‌صورت بلوک‌های thinking جداگانه).

از طریق CLI فعالش کنید:

pnpm gateway:watch --raw-stream

بازنویسی اختیاری مسیر:

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

متغیرهای محیطی معادل:

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

فایل پیش‌فرض:

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

لاگ‌گیری chunk خام (pi-mono)

برای ثبت chunkهای خام سازگار با OpenAI پیش از اینکه به بلوک‌ها تجزیه شوند، pi-mono یک logger جداگانه ارائه می‌کند:

PI_RAW_STREAM=1

مسیر اختیاری:

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

فایل پیش‌فرض:

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

نکته: این فقط توسط فرایندهایی منتشر می‌شود که از ارائه‌دهندهٔ openai-completions متعلق به pi-mono استفاده می‌کنند.

نکات ایمنی

• لاگ‌های stream خام می‌توانند شامل promptهای کامل، خروجی ابزار، و داده‌های کاربر باشند.
• لاگ‌ها را محلی نگه دارید و پس از اشکال‌زدایی حذفشان کنید.
• اگر لاگ‌ها را به اشتراک می‌گذارید، ابتدا رازها و PII را پاک‌سازی کنید.

اشکال‌زدایی در VSCode

source mapها برای فعال‌کردن اشکال‌زدایی در IDEهای مبتنی بر VSCode لازم هستند، چون بسیاری از فایل‌های تولیدشده به‌عنوان بخشی از فرایند build در نهایت نام‌های hash‌شده می‌گیرند. پیکربندی‌های launch.json موجود سرویس Gateway را هدف می‌گیرند، اما می‌توان آن‌ها را سریعاً برای اهداف دیگر سازگار کرد:

1. Rebuild and Debug Gateway - سرویس Gateway را پس از ایجاد یک build جدید اشکال‌زدایی می‌کند
2. Debug Gateway - سرویس Gateway مربوط به یک build از پیش موجود را اشکال‌زدایی می‌کند

راه‌اندازی

پیکربندی پیش‌فرض Rebuild and Debug Gateway همه‌چیز را همراه خود دارد؛ به‌طور خودکار پوشهٔ /dist را حذف می‌کند و پروژه را با اشکال‌زدایی فعال rebuild می‌کند:

1. پنل Run and Debug را از Activity Bar باز کنید یا Ctrl+Shift+D را فشار دهید
2. در IDE مطمئن شوید Rebuild and Debug Gateway در dropdown پیکربندی انتخاب شده است و سپس دکمهٔ Start Debugging را فشار دهید

یا اگر ترجیح می‌دهید فرایندهای build و اشکال‌زدایی را دستی مدیریت کنید:

1. یک ترمینال باز کنید و source mapها را فعال کنید:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. در همان ترمینال، پروژه را rebuild کنید: pnpm clean:dist && pnpm build
3. در IDE، گزینهٔ Debug Gateway را در dropdown پیکربندی Run and Debug انتخاب کنید و سپس دکمهٔ Start Debugging را فشار دهید

اکنون می‌توانید در فایل‌های منبع TypeScript خود (دایرکتوری src/) breakpoint تنظیم کنید و debugger، breakpointها را از طریق source mapها به‌درستی به JavaScript کامپایل‌شده نگاشت خواهد کرد. می‌توانید متغیرها را بررسی کنید، قدم‌به‌قدم از کد عبور کنید، و call stackها را همان‌طور که انتظار می‌رود بررسی کنید.

یادداشت‌ها

• اگر از گزینهٔ "Rebuild and Debug Gateway" استفاده می‌کنید، هر بار که debugger اجرا شود، پوشهٔ /dist را کاملاً حذف می‌کند و پیش از شروع Gateway یک pnpm build کامل با source mapهای فعال اجرا می‌کند
• اگر از گزینهٔ "Debug Gateway" استفاده می‌کنید، نشست‌های اشکال‌زدایی را می‌توان هر زمان بدون اثر روی پوشهٔ /dist شروع و متوقف کرد، اما باید از یک فرایند ترمینال جداگانه هم برای فعال‌کردن اشکال‌زدایی و هم برای مدیریت چرخهٔ build استفاده کنید
• تنظیمات launch.json مربوط به args را تغییر دهید تا بخش‌های دیگر پروژه را اشکال‌زدایی کنید
• اگر لازم است از CLI ساخته‌شدهٔ OpenClaw برای کارهای دیگر استفاده کنید (مثلاً dashboard --no-open اگر نشست اشکال‌زدایی شما یک token احراز هویت جدید spawn می‌کند)، می‌توانید آن را در ترمینالی دیگر به‌صورت node ./openclaw.mjs اجرا کنید یا یک alias پوسته مانند alias openclaw-build="node $(pwd)/openclaw.mjs" بسازید

مرتبط

• عیب‌یابی
• پرسش‌های متداول