---
read_when:
    - بدون افزایش سطح ثبت گزارش سراسری، به گزارش‌های اشکال‌زدایی هدفمند نیاز دارید
    - برای دریافت پشتیبانی، باید گزارش‌های مختص زیرسامانه را ثبت کنید
summary: پرچم‌های عیب‌یابی برای گزارش‌های اشکال‌زدایی هدفمند
title: پرچم‌های عیب‌یابی
x-i18n:
    generated_at: "2026-07-12T09:58:17Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 9847f464fde89d9e639b089fe54fb933deb9debad2a6d8b120ab01bacff181a8
    source_path: diagnostics/flags.md
    workflow: 16
---

پرچم‌های عیب‌یابی، ثبت گزارش اضافی را برای یک زیرسامانه فعال می‌کنند، بدون اینکه
`logging.level` را به‌صورت سراسری افزایش دهند. یک پرچم فقط زمانی اثر دارد که زیرسامانه‌ای آن را بررسی کند.

## نحوهٔ کار

- پرچم‌ها رشته‌هایی بدون حساسیت به بزرگی و کوچکی حروف هستند که از `diagnostics.flags` در
  پیکربندی به‌همراه بازنویسی متغیر محیطی `OPENCLAW_DIAGNOSTICS` استخراج، تکراری‌زدایی و با حروف کوچک تبدیل می‌شوند.
- `name.*` با خود `name` و هر چیزی زیر `name.` مطابقت دارد (برای مثال،
  `telegram.*` با `telegram.http` مطابقت دارد).
- `*` یا `all` همهٔ پرچم‌ها را فعال می‌کند.
- پس از تغییر `diagnostics.flags` در پیکربندی، Gateway را راه‌اندازی مجدد کنید؛ این مقدار
  به‌صورت آنی بارگذاری مجدد نمی‌شود.

## پرچم‌های شناخته‌شده

| پرچم            | فعال می‌کند                                                    |
| ---------------- | -------------------------------------------------------------- |
| `telegram.http`  | ثبت خطاهای HTTP مربوط به Telegram Bot API                      |
| `brave.http`     | ثبت درخواست، پاسخ و حافظهٔ نهان Brave Search                   |
| `profiler`       | پروفایلر مرحلهٔ پاسخ و پروفایلر app-server متعلق به Codex (هر دو) |
| `reply.profiler` | فقط پروفایلر مرحلهٔ پاسخ                                       |
| `codex.profiler` | فقط پروفایلر app-server متعلق به Codex                         |
| `timeline`       | آرتیفکت خط زمانی ساخت‌یافتهٔ JSONL (پایین را ببینید)           |

## فعال‌سازی از طریق پیکربندی

```json
{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}
```

چند پرچم:

```json
{
  "diagnostics": {
    "flags": ["telegram.http", "brave.http", "gateway.*"]
  }
}
```

## بازنویسی با متغیر محیطی (یک‌باره)

```bash
OPENCLAW_DIAGNOSTICS=telegram.http,brave.http
```

مقادیر با ویرگول یا فاصلهٔ خالی جدا می‌شوند. مقادیر ویژه:

| مقدار                       | اثر                                                   |
| --------------------------- | ----------------------------------------------------- |
| `0`, `false`, `off`, `none` | غیرفعال‌کردن همهٔ پرچم‌ها، حتی با بازنویسی پیکربندی   |
| `1`, `true`, `all`, `*`     | فعال‌کردن همهٔ پرچم‌ها                                |

`OPENCLAW_DIAGNOSTICS=0` پرچم‌های متغیر محیطی و پیکربندی را برای آن
فرایند غیرفعال می‌کند؛ این کار برای بی‌صداکردن موقت پرچم پروفایلری که در پیکربندی فعال مانده است،
بدون ویرایش فایل، مفید است.

## پرچم‌های پروفایلر

پرچم‌های پروفایلر بازه‌های زمان‌سنجی سبک را کنترل می‌کنند؛ در حالت غیرفعال هیچ سرباری اضافه نمی‌کنند.

فعال‌کردن همهٔ بازه‌های تحت کنترل پروفایلر برای یک اجرای Gateway:

```bash
OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run
```

فعال‌کردن فقط بازه‌های پروفایلر ارسال پاسخ:

```bash
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run
```

فعال‌کردن فقط بازه‌های پروفایلر راه‌اندازی، ابزار و رشتهٔ app-server متعلق به Codex:

```bash
OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run
```

`profiler` هم پروفایلر پاسخ و هم پروفایلر Codex را فعال می‌کند؛ برای فعال‌کردن فقط یکی،
از نام‌های پرچم دارای دامنه استفاده کنید.

یا آن را در پیکربندی تنظیم کنید:

```json
{
  "diagnostics": {
    "flags": ["reply.profiler", "codex.profiler"]
  }
}
```

پس از تغییر پرچم‌های پیکربندی، Gateway را راه‌اندازی مجدد کنید. برای غیرفعال‌کردن یک پرچم پروفایلر،
آن را از `diagnostics.flags` حذف و Gateway را راه‌اندازی مجدد کنید، یا فرایند را با
`OPENCLAW_DIAGNOSTICS=0` آغاز کنید تا همهٔ پرچم‌های عیب‌یابی برای آن اجرا بازنویسی شوند.

## آرتیفکت‌های خط زمانی

پرچم `timeline` (نام مستعار: `diagnostics.timeline`) رویدادهای زمان‌سنجی ساخت‌یافتهٔ راه‌اندازی
و زمان اجرا را برای چارچوب‌های کنترل کیفیت خارجی، به‌صورت JSONL می‌نویسد:

```bash
OPENCLAW_DIAGNOSTICS=timeline \
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \
openclaw gateway run
```

یا آن را در پیکربندی فعال کنید:

```json
{
  "diagnostics": {
    "flags": ["timeline"]
  }
}
```

مسیر خروجی همیشه از `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH` گرفته می‌شود، حتی
وقتی خود پرچم در پیکربندی تنظیم شده باشد؛ هیچ کلید پیکربندی‌ای برای مسیر وجود ندارد.
وقتی `timeline` فقط از طریق پیکربندی فعال شود، نخستین بازه‌های بارگذاری پیکربندی
ثبت نمی‌شوند، زیرا OpenClaw هنوز پیکربندی را نخوانده است؛ بازه‌های بعدی راه‌اندازی
به‌طور معمول ثبت می‌شوند.

`OPENCLAW_DIAGNOSTICS=1`، `=all` و `=*` نیز خط زمانی را فعال می‌کنند، زیرا
همهٔ پرچم‌ها را فعال می‌کنند. وقتی فقط آرتیفکت JSONL را می‌خواهید و نه همهٔ
پرچم‌های عیب‌یابی دیگر را، پرچم دامنه‌دار `timeline` را ترجیح دهید.

نمونه‌های تأخیر حلقهٔ رویداد در خط زمانی، علاوه بر `timeline` به یک فعال‌سازی اختیاری دیگر
نیاز دارند: در کنار فعال‌کردن خط زمانی، `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`
(یا `on`/`true`/`yes`) را تنظیم کنید.

رکوردهای خط زمانی از پوشش `openclaw.diagnostics.v1` استفاده می‌کنند و می‌توانند شامل
شناسه‌های فرایند، نام فازها، نام بازه‌ها، مدت‌زمان‌ها، شناسه‌های Plugin، تعداد
وابستگی‌ها، نمونه‌های تأخیر حلقهٔ رویداد، نام عملیات ارائه‌دهنده، وضعیت خروج
زیرفرایند و نام‌ها یا پیام‌های خطای راه‌اندازی باشند. فایل‌های خط زمانی را آرتیفکت‌های
عیب‌یابی محلی در نظر بگیرید؛ پیش از اشتراک‌گذاری آن‌ها خارج از دستگاه خود، بررسی‌شان کنید.

## گزارش‌ها کجا ذخیره می‌شوند

پرچم‌ها گزارش‌ها را در فایل استاندارد گزارش عیب‌یابی ثبت می‌کنند. به‌طور پیش‌فرض:

```
/tmp/openclaw/openclaw-YYYY-MM-DD.log
```

اگر `logging.file` را تنظیم کرده‌اید، به‌جای آن از همان مسیر استفاده کنید. گزارش‌ها JSONL هستند
(یک شیء JSON در هر خط). پوشاندن اطلاعات حساس همچنان بر اساس `logging.redactSensitive`
اعمال می‌شود. برای مدل کامل تعیین مسیر گزارش، چرخش و پوشاندن اطلاعات حساس، به
[ثبت گزارش](/fa/logging) مراجعه کنید.

## استخراج گزارش‌ها

جدیدترین فایل گزارش را انتخاب کنید:

```bash
ls -t /tmp/openclaw/openclaw-*.log | head -n 1
```

فیلترکردن عیب‌یابی HTTP مربوط به Telegram:

```bash
rg "telegram http error" /tmp/openclaw/openclaw-*.log
```

فیلترکردن عیب‌یابی HTTP مربوط به Brave Search:

```bash
rg "brave http" /tmp/openclaw/openclaw-*.log
```

یا هنگام بازتولید مشکل، گزارش را به‌صورت زنده دنبال کنید:

```bash
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
```

برای Gatewayهای راه‌دور، به‌جای آن از `openclaw logs --follow` استفاده کنید (به
[/cli/logs](/fa/cli/logs) مراجعه کنید).

## نکات

- اگر `logging.level` بالاتر از `warn` تنظیم شده باشد، ممکن است گزارش‌های تحت کنترل پرچم
  سرکوب شوند. مقدار پیش‌فرض `info` مناسب است.
- `brave.http` نشانی‌های اینترنتی و پارامترهای پرس‌وجوی درخواست Brave Search، وضعیت
  و زمان‌بندی پاسخ و رویدادهای اصابت، عدم اصابت و نوشتن حافظهٔ نهان را ثبت می‌کند. این پرچم کلید API
  (که به‌صورت سرآیند درخواست ارسال می‌شود) یا بدنهٔ پاسخ‌ها را ثبت نمی‌کند، اما عبارت‌های جست‌وجو ممکن است
  حساس باشند.
- فعال‌ماندن پرچم‌ها ایمن است؛ آن‌ها فقط حجم گزارش زیرسامانهٔ
  مشخص‌شده را تحت تأثیر قرار می‌دهند.
- برای تغییر مقصد، سطح و پوشاندن اطلاعات حساس گزارش‌ها، از [/logging](/fa/logging) استفاده کنید.

## مرتبط

- [عیب‌یابی Gateway](/fa/gateway/diagnostics)
- [رفع اشکال Gateway](/fa/gateway/troubleshooting)