---
read_when:
    - می‌خواهید یک عامل، پرسشی ساختاریافته از کاربر بپرسد
    - در حال پاسخ‌دادن به یک اعلان ask_user یا اشکال‌زدایی آن هستید
    - به طرح‌واره، مهلت زمانی یا رفتار کانالِ ask_user نیاز دارید
summary: چگونه ask_user نوبت عامل را برای یک تصمیم ساختاریافته انسانی متوقف می‌کند
title: از کاربر بپرسید
x-i18n:
    generated_at: "2026-07-27T15:51:50Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 32556314a34c26054c3aabfdd8ecc474cf85196e5cc71adb833face596edbd24
    source_path: tools/ask-user.md
    workflow: 16
---

`ask_user` به عامل اجازه می‌دهد از کاربر یک تا سه پرسش ساختاریافته بپرسد و
منتظر پاسخ‌ها بماند. این ابزار برای تصمیم‌هایی است که واقعاً بر عهدهٔ کاربر هستند،
نه تأییدهای معمول یا اطلاعاتی که عامل می‌تواند از درخواست،
کد یا یک مقدار پیش‌فرض معقول استخراج کند.

این ابزار فقط در نشست اصلی در دسترس است. زیرعامل‌ها و دیگر اجراهای غیراصلی
به آن دسترسی ندارند.

## پاسخ به یک پرسش

می‌توانید از هر سطح مکالمهٔ پشتیبانی‌شده‌ای پاسخ دهید:

- رابط کاربری وب Control UI پنل پرسش را مستقیماً بالای کادر نوشتن قرار می‌دهد. برای
  درخواست‌های چندپرسشی، پنل هر بار یک پرسش را نشان می‌دهد و
  در یک گام‌نمای کوتاه پیش می‌رود. پس از پاسخ‌گویی، پنل بسته می‌شود و گپ
  فقط خلاصه‌ای فشرده از پاسخ‌ها را نگه می‌دارد.
- Telegram، Discord و Slack برای یک درخواست تک‌پرسشی
  با انتخاب واحد، دکمه‌های بومی نمایش می‌دهند.
- پاسخ متنی ساده در هر کانالی کار می‌کند. با یک عدد، برچسب یک گزینه
  یا پاسخ خودتان جواب دهید.

OpenClaw همیشه پاسخ متن‌آزاد **سایر** را فعال می‌کند. عامل نباید گزینهٔ
`Other` را به فهرست گزینه‌های تعریف‌شده اضافه کند.

## رفتار پلتفرم

پاسخ‌ها در تمام سطوح مکالمهٔ پشتیبانی‌شده کار می‌کنند. رابط کاربری وب Control UI از
گام‌نمایی متصل استفاده می‌کند که در حالت باز جای کادر نوشتن را می‌گیرد؛ جمع‌کردن آن،
کادر کامل نوشتن را زیر یک نوار باریک پرسش بازمی‌گرداند. iOS، macOS و Android
کارت‌های درون‌خطی نشان می‌دهند؛ چند پرسش به‌عمد به‌شکل روی‌هم‌چیده باقی می‌مانند تا
برای تعامل لمسی مناسب باشند. هر پلتفرم خلاصهٔ پرسش و پاسخ را بدون حذف زمان‌بندی‌شده
در خط زمانی گپ فعال نگه می‌دارد و **رد کردن** همه‌جا در دسترس است.

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

## مهلت زمانی و نبود پاسخ

مهلت زمانی پیش‌فرض 900 ثانیه است. `timeoutSeconds` به بازهٔ
30 تا 3600 ثانیه محدود می‌شود.

اگر پیش از رسیدن پاسخ، مهلت پرسش منقضی یا پرسش لغو شود، ابزار
`status: "no_answer"` را برمی‌گرداند. سپس عامل با بهترین قضاوت خود ادامه می‌دهد.
توقف اجرای عامل، پرسش در انتظار آن در Gateway را لغو می‌کند.

## شِمای ابزار

```ts
{
  questions: Array<{
    id: string; // کلید پاسخ یکتای snake_case
    header: string; // برچسب کوتاه؛ به 12 نویسه کوتاه می‌شود
    question: string; // یک جمله
    options: Array<{
      label: string;
      description?: string;
    }>; // 2-4 گزینه
    multiSelect?: boolean;
  }>; // 1-3 پرسش
  timeoutSeconds?: number; // عدد صحیح؛ پیش‌فرض 900، محدودشده به 30-3600
}
```

با `multiSelect: true`، کاربر می‌تواند بیش از یک گزینه را انتخاب کند. مقادیر
پاسخ برای هر پرسش به‌صورت آرایه برگردانده می‌شوند.

نمونهٔ نتیجهٔ پاسخ‌داده‌شده:

```json
{
  "status": "answered",
  "answers": {
    "answers": {
      "deploy_target": ["Staging (Recommended)"]
    }
  }
}
```

## راهنمای مدل

قرارداد ارائه‌شده به مدل به عامل می‌گوید:

- فقط زمانی بپرسد که برای تصمیمی واقعاً متعلق به کاربر متوقف شده باشد؛
- یک پرسش را ترجیح دهد و بیش از سه پرسش مطرح نکند؛
- گزینهٔ پیشنهادی را نخست قرار دهد و `(Recommended)` را به انتهای برچسب آن بیفزاید؛
- گزینهٔ تعریف‌شدهٔ `Other` را حذف کند، زیرا متن آزاد به‌طور خودکار افزوده می‌شود؛
- پس از `no_answer` با بهترین قضاوت خود ادامه دهد.

عامل نباید از `ask_user` برای پرسیدن اجازهٔ ادامه یا تأیید
برنامهٔ خودش استفاده کند.