---
read_when:
    - به یک سابقهٔ ماندگار از عملکرد Gateway نیاز دارید، بدون آنکه محتوا ذخیره شود
    - در حال تصمیم‌گیری درباره فعال‌کردن ممیزی چرخه عمر پیام هستید
    - باید توضیح دهید که سوابق ممیزی چه چیزی را اثبات می‌کنند و چه چیزی را اثبات نمی‌کنند
summary: تاریخچهٔ ممیزی صرفاً فراداده‌ای برای اجرای عامل‌ها، اقدامات ابزارها و چرخه‌های عمر پیام‌های اختیاری
title: تاریخچه ممیزی
x-i18n:
    generated_at: "2026-07-27T15:27:29Z"
    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"` است. برای مرجع کامل فیلدها و فیلترهای پرس‌وجو، به [رکوردهای ممیزی](/fa/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`](/fa/cli/audit) با فیلترهای عامل، نشست، اجرا، نوع، وضعیت، جهت، کانال، محدوده‌های زمانی و صفحه‌بندی با مکان‌نما.
- RPC در Gateway: `audit.activity.list` (نیازمند `operator.read`) اجتماع نسخه‌بندی‌شده رویدادهای فعالیت V1 را برمی‌گرداند؛ RPC عرضه‌شده `audit.list` برای کلاینت‌های قدیمی‌تر اجرا/ابزار بدون تغییر باقی مانده است. به
  [پروتکل Gateway](/fa/gateway/protocol#audit-ledger-rpc) مراجعه کنید.

## مرتبط

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