---
read_when:
    - باید مشخص کنید چه کسی یک عامل یا ابزار را اجرا کرده، چه زمانی اجرا شده و چگونه پایان یافته است
    - به فرادادهٔ چرخهٔ حیات پیام ورودی یا خروجیِ بدون محتوا نیاز دارید
    - به یک خروجی فعالیت محدود و ایمن از نظر حذف اطلاعات حساس نیاز دارید
summary: مرجع CLI برای رکوردهای ممیزی چرخهٔ حیات اجرا، ابزار و پیام که فقط شامل فراداده هستند
title: سوابق ممیزی
x-i18n:
    generated_at: "2026-07-27T15:00:28Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: da9df6f388b0a24c3b79d755fa59d047cce99262bc6d9c890be7a83da75693a8
    source_path: cli/audit.md
    workflow: 16
---

# `openclaw audit`

دفترکل ممیزیِ صرفاً فراداده‌ای Gateway را برای اجرای عامل‌ها، اقدامات ابزارها و
رکوردهای چرخهٔ حیات پیام که به‌صورت اختیاری فعال شده‌اند، جست‌وجو کنید.

دفترکل برای رویدادهای اجرا و ابزار به‌طور پیش‌فرض فعال است. برای توقف ثبت همهٔ
رویدادهای جدید، [`audit.enabled: false`](/fa/gateway/configuration-reference#audit) را تنظیم و
Gateway را راه‌اندازی مجدد کنید. رکوردهای پیام به‌طور جداگانه و به‌صورت پیش‌فرض
غیرفعال‌اند؛ برای ثبت آن‌ها، `audit.messages` را روی `direct` یا `all` تنظیم
و Gateway را راه‌اندازی مجدد کنید. رکوردهای موجود تا زمان انقضا (30 روز)
قابل جست‌وجو باقی می‌مانند.

دفترکل از رونوشت‌های مکالمه جدا است: هویت، ترتیب، منشأ، اقدام، وضعیت و
کدهای نرمال‌شدهٔ نتیجه را ثبت می‌کند، اما هرگز محتوا را ذخیره نمی‌کند و شناسه‌های
پیام فقط به‌شکل نام‌های مستعار کلیددار و محلیِ نصب ظاهر می‌شوند. [تاریخچهٔ ممیزی](/fa/gateway/audit)
مالک مدل کامل داده، معناشناسی حریم خصوصی، محدوده‌های ذخیره‌سازی/نگه‌داری و
محدودیت‌های پوشش است؛ این صفحه سطح فرمان را پوشش می‌دهد.

```bash
openclaw audit
openclaw audit --agent main --status failed
openclaw audit --session "agent:main:main" --after 2026-07-01T00:00:00Z
openclaw audit --run 8c69f72e-8b11-4c54-98d5-1a3dd67450c3
openclaw audit --kind tool_action --limit 50 --json
openclaw audit --kind message --direction outbound --channel telegram --json
```

## فیلترها

- `--agent <id>`: شناسهٔ دقیق عامل
- `--session <key>`: کلید دقیق نشست
- `--run <id>`: شناسهٔ دقیق اجرا
- `--kind <kind>`: `agent_run`، `tool_action` یا `message`
- `--status <status>`: `started`، `succeeded`، `failed`، `cancelled`،
  `timed_out`، `blocked` یا `unknown`
- `--direction <direction>`: جهت پیام، `inbound` یا `outbound`
- `--channel <channel>`: کانال دقیق پیام
- `--after <timestamp>` / `--before <timestamp>`: مُهر زمانی ISO به‌صورت شامل یا
  میلی‌ثانیهٔ Unix
- `--limit <count>`: اندازهٔ صفحه از 1 تا 500؛ پیش‌فرض `100`
- `--cursor <sequence>`: ادامهٔ یک جست‌وجوی پیشین با ترتیب جدیدترین به قدیمی‌ترین
- `--json`: چاپ صفحهٔ محدودشده به‌صورت JSON

CLI از RPC فعالیتِ نسخه‌بندی‌شده پرس‌وجو می‌کند تا یک فرمان، کل دفترکل
پیکربندی‌شده را نمایش دهد. خروجی متنی زمان، نوع، جهت، کانال، وضعیت، عامل،
اجرا و اقدام را نشان می‌دهد. منشأ مفقود پیام به‌شکل `-` نمایش داده می‌شود؛
OpenClaw شناسهٔ عامل یا اجرا جعل نمی‌کند. اقدامات ابزار نام ابزار را نیز نشان
می‌دهند. خروجی JSON وقتی صفحهٔ دیگری وجود داشته باشد، شامل `nextCursor` است.
برای ادامه، آن مقدار را به `--cursor` بدهید تا رکوردهایی که هنگام صفحه‌بندی
می‌رسند، دوباره مرتب نشوند.

این خروجی‌ها با وجود نبود بدنهٔ پیام‌ها و فیلدهای خام هویت پیام، همچنان
فرادادهٔ عملیاتی حساس محسوب می‌شوند. شناسه‌های عامل، نشست و اجرا، زمان‌بندی،
کانال‌ها، نتایج و ارجاعات پایدار HMAC می‌توانند فعالیت‌ها را به یکدیگر مرتبط
کنند. از آن‌ها با همان کنترل‌های دسترسی و شیوه‌های نگه‌داری سایر رکوردهای
اپراتور محافظت کنید.

## رویدادهای ثبت‌شده

Gateway جریان‌های چرخهٔ حیات قابل‌اعتماد را به شش اقدام نگاشت می‌کند:

- `agent.run.started`
- `agent.run.finished`
- `tool.action.started`
- `tool.action.finished`
- `message.inbound.processed`
- `message.outbound.finished`

هر رکورد بازگردانده‌شده دارای شناسهٔ پایدار رویداد، توالی دفترکل با افزایش
یکنواخت، مُهر زمانی چرخهٔ حیات، کنشگر، اقدام، وضعیت، نشانگر
`schemaVersion: 1`، توالی منبع و `redaction: "metadata_only"` است.
منشأ عامل/نشست/اجرا و فیلدهای مختص رویداد فقط زمانی وجود دارند که
منبع قابل‌اعتماد آن‌ها را فراهم کند. رکوردهای پیام عمداً
`sessionKey` و `sessionId` را حذف می‌کنند، بنابراین فیلترهای `--session` فقط روی رکوردهای اجرا و ابزار اعمال می‌شوند.

رکوردهای نهایی اجرا و ابزار، موفقیت، شکست، لغو، پایان مهلت و مسدودسازی‌های
سیاستی را با وضعیت‌ها و کدهای خطای بسته از هم متمایز می‌کنند. وقتی یک زمان‌اجرای
بالادستی نتیجهٔ نهایی معتبری ارائه نمی‌کند، `unknown` یک نتیجهٔ صریح
ناموفق است. شناسه‌های فراخوانی ابزار فقط به‌صورت اثرانگشت‌های پایدار صادر
می‌شوند. نام ابزارها باید با قرارداد فشردهٔ نامِ قابل‌مشاهده برای مدل مطابقت
داشته باشند؛ سایر مقادیر به `unknown` تبدیل می‌شوند.

رکوردهای پیام، جهت، کانال، نوع مکالمه، نتیجه و در صورت وجود نوع تحویل،
مرحلهٔ شکست، مدت‌زمان، تعداد نتایج، کد نرمال‌شدهٔ دلیل و نام‌های مستعار کلیددار
حساب/مکالمه/پیام/مقصد را اضافه می‌کنند. مرز ورودی فعلی پیام‌های پذیرفته‌شده‌ای
را پوشش می‌دهد که به توزیع هسته می‌رسند، از جمله نتایج پردازش تکراری و نهایی
هسته. مرز خروجی برای هر محتوای پاسخ منطقی اصلی که به تحویل پایدار مشترک
می‌رسد، یک ردیف نهایی می‌نویسد؛ قطعه‌بندی و انشعاب آداپتور در
`resultCount` تجمیع می‌شوند. ارسال‌های در صفِ قابل‌تلاش مجدد یا مبهم فقط پس از
آن ثبت می‌شوند که تأیید دریافت، انتقال به نامه‌های مرده یا تطبیق، نتیجه را
نهایی کند. مسیرهای محلی Plugin و ارسال مستقیم که این مرزهای مشترک را دور
می‌زنند، هنوز پوشش داده نشده‌اند؛ نبود یک ردیف ثابت نمی‌کند که هیچ پیامی
وجود نداشته است.

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

برای ردیف‌های ورودی، `durationMs` توزیع هسته را اندازه‌گیری می‌کند و `resultCount`
محتواهای نهایی‌شدهٔ ابزار، مسدودسازی و پاسخِ در صف را می‌شمارد. برای ردیف‌های
خروجی، `durationMs` مالکیت تحویل را تا وضعیت نهایی آن (و در نتیجه زمان انتظار
در صف) دربر می‌گیرد، درحالی‌که `resultCount` ارسال‌های فیزیکی شناسایی‌شدهٔ
پلتفرم را می‌شمارد. `deliveryKind`، در صورت وجود، محتوای مؤثر پس از هوک و
پس از رندر را توصیف می‌کند؛ ردیف‌های سرکوب‌شده و دارای ابهام ناشی از خرابی،
آن را حذف می‌کنند.

## RPC در Gateway

`audit.activity.list` به `operator.read` نیاز دارد و همان فیلترها را می‌پذیرد. این RPC
اتحاد نام‌گذاری‌شدهٔ رویداد فعالیت V1، شامل رکوردهای اجرا، ابزار، پیام ورودی
و پیام خروجی را بازمی‌گرداند.

```bash
openclaw gateway call audit.activity.list --params '{"channel":"telegram","limit":50}'
```

نتیجه `{ "events": AuditActivityEventV1[], "nextCursor"?: string }` است.
نتایج با جدیدترین مورد آغاز می‌شوند و در هر درخواست به 500 رکورد محدودند.

RPC عرضه‌شدهٔ `audit.list` برای کلاینت‌های قدیمی‌تر اجرا/ابزار بدون تغییر باقی
می‌ماند. وقتی `audit.activity.list` در یک Gateway قدیمی‌تر در دسترس نباشد، CLI فقط
درصورتی دوباره با `audit.list` تلاش می‌کند که همهٔ فیلترهای درخواستی توسط آن
روش قدیمی پشتیبانی شوند. `--kind message`، `--direction` و `--channel` در یک Gateway
قدیمی‌تر به‌جای اینکه بی‌سروصدا نادیده گرفته شوند، با پیام ارتقا ناموفق
می‌شوند.

## مرتبط

- [تاریخچهٔ ممیزی](/fa/gateway/audit)
- [پروتکل Gateway](/fa/gateway/protocol#audit-ledger-rpc)
- [نشست‌ها](/fa/cli/sessions)
- [وظایف](/fa/cli/tasks)
- [کارهای Cron](/fa/automation/cron-jobs)