Gateway
تاریخچه ممیزی
تاریخچه ممیزی
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" است. برای مرجع کامل فیلدها و فیلترهای پرسوجو، به رکوردهای ممیزی مراجعه کنید.
رویدادهای چرخه حیات پیام
برای انتخاب موارد ثبتشونده، audit.messages را تنظیم کنید، سپس 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 یا ابزارهای سطح کانال استفاده کنید.
ذخیرهسازی، نگهداری و مهاجرت
رکوردها در پایگاه داده وضعیت مشترک (state/openclaw.sqlite) قرار دارند و خارج از مسیر داغ تحویل نوشته میشوند. پرسوجوها هرگز رکوردهای قدیمیتر از 30 روز را بازنمیگردانند و دفتر به 100,000 ردیف محدود است؛ ردیفهای منقضیشده هنگام راهاندازی، نگهداری ساعتی و نوشتنهای بعدی هرس میشوند. نگهداری همچنان حتی در صورت غیرفعالبودن گردآوری اجرا میشود.
ارتقا از Gateway دارای دفتر پیشینِ مختص اجرا/ابزار، طرحواره را هنگام راهاندازی (یا از طریق openclaw doctor --fix) بهطور خودکار مهاجرت میدهد؛ ردیفهای موجود و توالیهای دفتر آنها حفظ میشوند.
پرسوجو
- CLI:
openclaw auditبا فیلترهایی برای عامل، نشست، اجرا، نوع، وضعیت، جهت، کانال، محدودههای زمانی و صفحهبندی مکاننما. - RPC Gateway:
audit.activity.list(نیازمندoperator.read) اجتماع نسخهدار رویدادهای فعالیت V1 را بازمیگرداند؛ RPC عرضهشدهaudit.listبرای کلاینتهای قدیمیتر اجرا/ابزار بدون تغییر باقی میماند. به پروتکل Gateway مراجعه کنید.
