---
read_when:
    - باید مشخص کنید چه کسی یک عامل یا ابزار را اجرا کرده، چه زمانی اجرا شده و چگونه پایان یافته است
    - به فرادادهٔ چرخهٔ عمر پیام‌های ورودی یا خروجیِ بدون محتوا نیاز دارید
    - به یک خروجی فعالیت محدود و ایمن برای حذف اطلاعات حساس نیاز دارید
summary: مرجع CLI برای رکوردهای حسابرسی چرخهٔ حیات اجرای صرفاً فراداده‌ای، ابزار و پیام
title: سوابق ممیزی
x-i18n:
    generated_at: "2026-07-16T15:42:20Z"
    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 روز) قابل پرس‌وجو باقی می‌مانند.

دفترکل از رونوشت‌های مکالمه جداست: هویت، ترتیب، منشأ، اقدام، وضعیت و کدهای
نرمال‌شدهٔ نتیجه را ثبت می‌کند، اما هرگز محتوا را ذخیره نمی‌کند و شناسه‌های پیام
فقط به‌شکل نام‌های مستعار کلیددارِ محلیِ نصب ظاهر می‌شوند. [تاریخچهٔ ممیزی](/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` نیاز دارد و همان فیلترها را می‌پذیرد. این
فراخوانی اجتماع نام‌گذاری‌شدهٔ رویداد فعالیت 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
قدیمی‌تر به‌جای حذف بی‌سروصدا، با پیام ارتقا ناموفق می‌شوند.

## مرتبط

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