---
read_when:
    - به یک سابقهٔ ماندگار از عملکرد Gateway نیاز دارید، بدون ذخیره‌کردن محتوا
    - در حال تصمیم‌گیری هستید که آیا ممیزی چرخه عمر پیام را فعال کنید یا نه
    - باید توضیح دهید که سوابق ممیزی چه چیزهایی را اثبات می‌کنند و چه چیزهایی را اثبات نمی‌کنند
summary: تاریخچهٔ ممیزیِ صرفاً فراداده‌ای برای اجراهای عامل، اقدامات ابزار و چرخه‌های عمر پیامِ مبتنی بر رضایت صریح
title: تاریخچه ممیزی
x-i18n:
    generated_at: "2026-07-16T16:49:09Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 1005b214a674f0f888d759837bd627be458cefcf9ed61bda722499333361dc45
    source_path: gateway/audit.md
    workflow: 16
---

# تاریخچه ممیزی

Gateway یک دفتر ممیزی محدود و صرفاً شامل فراداده را در پایگاه داده وضعیت مشترک OpenClaw نگه می‌دارد. این دفتر به پرسش‌های عملیاتی مانند «کدام عامل، چه زمانی اجرا شد و اجرای آن چگونه پایان یافت»، «یک اجرا چه کنش‌های ابزاری را انجام داد» و، هنگامی که ممیزی پیام فعال است، «آیا یک پیام ورودی پذیرفته‌شده به مرحله ارسال برای پردازش رسید» و «آیا یک پیام خروجی به وضعیت نهایی تحویل رسید» پاسخ می‌دهد.

این دفتر، هویت، ترتیب، منشأ، کنش، وضعیت و کدهای نتیجه نرمال‌شده را ذخیره می‌کند. این دفتر هرگز اعلان‌ها، بدنه پیام‌ها، آرگومان‌های ابزار، نتایج ابزار، پیوست‌ها، نام فایل‌ها، نشانی‌های URL، خروجی فرمان یا متن خام خطا را ذخیره نمی‌کند.

## خانواده‌های رکورد

رویدادهای اجرا و ابزار هرگاه ممیزی فعال باشد ثبت می‌شوند (حالت پیش‌فرض). رویدادهای چرخه حیات پیام اختیاری‌اند و به‌طور پیش‌فرض غیرفعال هستند.

| خانواده       | کنش‌ها                                                  | پیش‌فرض |
| ------------ | -------------------------------------------------------- | ------- |
| اجراهای عامل   | `agent.run.started`، `agent.run.finished`                | روشن      |
| کنش‌های ابزار | `tool.action.started`، `tool.action.finished`            | روشن      |
| پیام‌ها     | `message.inbound.processed`، `message.outbound.finished` | خاموش     |

هر رکورد دارای شناسه رویداد پایدار، توالی یکنواخت دفتر، برچسب زمانی چرخه حیات، کنشگر، کنش، وضعیت، `schemaVersion: 1` و `redaction: "metadata_only"` است. برای مرجع کامل فیلدها و فیلترهای پرس‌وجو، به [رکوردهای ممیزی](/cli/audit) مراجعه کنید.

## رویدادهای چرخه حیات پیام

برای انتخاب موارد ثبت‌شونده، [`audit.messages`](/fa/gateway/configuration-reference#audit) را تنظیم کنید، سپس Gateway را دوباره راه‌اندازی کنید:

- `off` (پیش‌فرض): بدون رکورد پیام.
- `direct`: فقط پیام‌های مکالمات مستقیم.
- `all`: پیام‌های مستقیم، گروهی و کانال‌ها.

دو مرز معتبر رکوردهای پیام را تولید می‌کنند:

- ردیف‌های **ورودی** هنگامی نوشته می‌شوند که یک پیام پذیرفته‌شده به مرحله ارسال برای پردازش هسته برسد،
  از جمله نتایج پردازش تکراری و نهایی.
- ردیف‌های **خروجی** هنگامی نوشته می‌شوند که تحویل پایدار مشترک به یک
  نتیجه نهایی برسد: ارسال‌شده، سرکوب‌شده، ناموفق یا یک `unknown` صریح برای
  ارسال‌های مبهم به‌دلیل خرابی. نتایج بازیابی صف و نامه مرده نیز لحاظ می‌شوند.
  هر محتوای پاسخ منطقی اصلی یک ردیف نهایی دریافت می‌کند؛ قطعه‌بندی و
  توزیع چندگانه آداپتور در `resultCount` تجمیع می‌شوند.

### طبقه‌بندی نوع مکالمه

حالت `direct` یک مرز حریم خصوصی است، بنابراین یک پیام تنها زمانی به‌عنوان مکالمه مستقیم طبقه‌بندی می‌شود که واقعیت‌های مقصد آن را اثبات کنند: مسیر ارسال، نوع مکالمه مقصد را اعلام کرده باشد، یا مسیر نشست تحویل دقیقاً کانال و همتایی را نام ببرد که تحویل به آن‌ها انجام می‌شود. سیگنال‌های ضعیف‌تر، مانند وضعیت خط‌مشی یا مکالمه مبدأ، می‌توانند یک پیام را به‌عنوان `group` طبقه‌بندی کنند (و آن را از گردآوری `direct` کنار بگذارند)، اما هرگز نمی‌توانند `direct` را ادعا کنند. پیام‌هایی که مستقیم‌بودن آن‌ها قابل اثبات نیست، `unknown` طبقه‌بندی می‌شوند و در حالت `direct` ثبت نمی‌شوند. بنابراین، کانال‌هایی که انواع گفت‌وگو را اعلام نمی‌کنند ممکن است در حالت `direct` ردیف‌های کمتری نسبت به حالت `all` ثبت کنند.

## مدل حریم خصوصی

ردیف‌های پیام هرگز شناسه‌های خام پلتفرم را ذخیره نمی‌کنند. شناسه‌های حساب، مکالمه، پیام و مقصد، هنگامی که هم‌بستگی در دسترس باشد، فقط به‌صورت نام‌های مستعار کلیددار و محلیِ نصب صادر می‌شوند
(`hmac-sha256:v1:<keyId>:<digest>`):

- کلید HMAC در نخستین استفاده تولید می‌شود، برای هر نوع شناسه جداسازی دامنه دارد و در همان پایگاه داده وضعیت دفتر نگهداری می‌شود.
- نام‌های مستعار در یک نصب پایدار هستند، بنابراین ردیف‌های مربوط به یک مکالمه بدون افشای شناسه پلتفرم با یکدیگر هم‌بسته می‌شوند.
- این **هم‌بستگی است، نه ناشناس‌سازی**: هر کسی که دسترسی خواندن به پایگاه داده وضعیت داشته باشد، کلید را نیز در اختیار دارد و می‌تواند شناسه‌های خام احتمالی را با نام‌های مستعار تطبیق دهد. خروجی‌های RPC و CLI هرگز کلید را شامل نمی‌شوند.
- اگر درحالی‌که ردیف‌های پیام نگه داشته شده‌اند، داده کلید مفقود یا خراب باشد، Gateway به‌صورت بسته و ایمن عمل می‌کند و به‌جای چرخش بی‌سروصدای کلید به یک کلید جدید که هم‌بستگی را تقسیم می‌کند، رکوردهای پیام جدید را کنار می‌گذارد.

رکوردهای اجرا و ابزار برای هم‌بستگی، `sessionKey` و `sessionId` را نگه می‌دارند؛ کلیدهای متعارف نشست ممکن است خود شامل شناسه‌های حساب یا همتای پلتفرم باشند. رکوردهای پیام عمداً هر دو را حذف می‌کنند.

خروجی‌های ممیزی حتی بدون محتوا نیز فراداده عملیاتی حساس باقی می‌مانند: زمان‌بندی، کانال‌ها، نتایج و نام‌های مستعار پایدار می‌توانند فعالیت را هم‌بسته کنند. از خروجی‌ها با همان کنترل‌های دسترسی و شیوه‌های نگه‌داری سایر رکوردهای اپراتور محافظت کنید.

## محدودیت‌های پوشش و اثبات

این دفتر بر مبنای بهترین تلاش عمل می‌کند و عمداً محدود است. آن را مدرکی از آنچه ثبت شده است بدانید، نه اثبات آنچه رخ داده است:

- **نبود یک ردیف هیچ‌چیز را اثبات نمی‌کند.** حذف پیام‌های ورودی پیش از پذیرش، ارسال از فرایندهای CLI بدون ثبت‌کننده در حال اجرای Gateway و مسیرهای محلی Plugin یا ارسال مستقیم که تحویل پایدار مشترک را دور می‌زنند، هیچ رکوردی بر جای نمی‌گذارند.
- نوشتن‌ها از طریق یک پردازشگر پس‌زمینه محدود انجام می‌شوند؛ خرابی پردازشگر یا اشباع صف باعث حذف رکوردها و ثبت یک هشدار عملیاتی می‌شود.
- ارسال‌های خروجی مبهم به‌دلیل خرابی، به‌جای نتایج ساختگی، به‌صورت `unknown` ثبت می‌شوند.

این دفتر برای اشکال‌زدایی و بازبینی عملیاتی کاربرد دارد. این یک بایگانی انطباق بدون اتلاف نیست؛ اگر به چنین بایگانی‌ای نیاز دارید، از یک سامانه خارجی تغذیه‌شده با [OpenTelemetry](/fa/gateway/opentelemetry) یا ابزارهای سطح کانال استفاده کنید.

## ذخیره‌سازی، نگه‌داری و مهاجرت

رکوردها در پایگاه داده وضعیت مشترک (`state/openclaw.sqlite`) قرار دارند و خارج از مسیر داغ تحویل نوشته می‌شوند. پرس‌وجوها هرگز رکوردهای قدیمی‌تر از 30 روز را بازنمی‌گردانند و دفتر به 100,000 ردیف محدود است؛ ردیف‌های منقضی‌شده هنگام راه‌اندازی، نگه‌داری ساعتی و نوشتن‌های بعدی هرس می‌شوند. نگه‌داری همچنان حتی در صورت غیرفعال‌بودن گردآوری اجرا می‌شود.

ارتقا از Gateway دارای دفتر پیشینِ مختص اجرا/ابزار، طرح‌واره را هنگام راه‌اندازی (یا از طریق `openclaw doctor --fix`) به‌طور خودکار مهاجرت می‌دهد؛ ردیف‌های موجود و توالی‌های دفتر آن‌ها حفظ می‌شوند.

## پرس‌وجو

- CLI: [`openclaw audit`](/cli/audit) با فیلترهایی برای عامل، نشست، اجرا، نوع، وضعیت، جهت، کانال، محدوده‌های زمانی و صفحه‌بندی مکان‌نما.
- RPC Gateway: ‏`audit.activity.list` (نیازمند `operator.read`) اجتماع نسخه‌دار رویدادهای فعالیت V1 را بازمی‌گرداند؛ RPC عرضه‌شده `audit.list` برای کلاینت‌های قدیمی‌تر اجرا/ابزار بدون تغییر باقی می‌ماند. به
  [پروتکل Gateway](/fa/gateway/protocol#audit-ledger-rpc) مراجعه کنید.

## مرتبط

- [CLI رکوردهای ممیزی](/cli/audit)
- [مرجع پیکربندی](/fa/gateway/configuration-reference#audit)
- [پروتکل Gateway](/fa/gateway/protocol#audit-ledger-rpc)
- [OpenTelemetry](/fa/gateway/opentelemetry)