ابزار اجرای پس‌زمینه و فرایندها

OpenClaw فرمان‌های shell را از طریق ابزار exec اجرا می‌کند و کارهای طولانی‌مدت را در حافظه نگه می‌دارد. ابزار process آن نشست‌های پس‌زمینه را مدیریت می‌کند.

# ابزار exec

پارامترهای کلیدی:

• command (الزامی)
• yieldMs (پیش‌فرض 10000): پس از این تأخیر به‌طور خودکار به پس‌زمینه می‌رود
• background (bool): بلافاصله در پس‌زمینه اجرا می‌کند
• timeout (ثانیه، پیش‌فرض tools.exec.timeoutSec): پس از این مهلت فرایند را می‌کشد؛ فقط برای غیرفعال کردن مهلت زمانی فرایند exec برای همان فراخوانی، timeout: 0 را تنظیم کنید
• elevated (bool): اگر حالت elevated فعال/مجاز باشد، خارج از sandbox اجرا می‌کند (به‌طور پیش‌فرض gateway، یا وقتی هدف exec برابر node باشد، node)
• به یک TTY واقعی نیاز دارید؟ pty: true را تنظیم کنید.
• workdir, env

رفتار:

• اجراهای foreground خروجی را مستقیماً برمی‌گردانند.
• وقتی به پس‌زمینه برود (صریح یا به‌دلیل timeout)، ابزار status: "running" + sessionId و یک tail کوتاه را برمی‌گرداند.
• اجراهای background و yieldMs مقدار tools.exec.timeoutSec را به ارث می‌برند، مگر اینکه فراخوانی یک timeout صریح ارائه کند.
• خروجی تا زمانی که نشست poll یا clear شود، در حافظه نگه داشته می‌شود.
• اگر ابزار process مجاز نباشد، exec به‌صورت همگام اجرا می‌شود و yieldMs/background را نادیده می‌گیرد.
• فرمان‌های exec ایجادشده، برای قواعد shell/profile آگاه از زمینه، OPENCLAW_SHELL=exec را دریافت می‌کنند.
• برای کاری طولانی‌مدت که اکنون شروع می‌شود، آن را یک‌بار شروع کنید و وقتی فعال است و فرمان خروجی تولید می‌کند یا شکست می‌خورد، به wake خودکار تکمیل تکیه کنید.
• اگر wake خودکار تکمیل در دسترس نیست، یا برای فرمانی که بدون خروجی و با موفقیت خارج شده به تأیید موفقیت بی‌صدا نیاز دارید، از process برای تأیید تکمیل استفاده کنید.
• یادآورها یا پیگیری‌های تأخیری را با حلقه‌های sleep یا poll مکرر شبیه‌سازی نکنید؛ برای کارهای آینده از cron استفاده کنید.

# پل‌زنی فرایند فرزند

هنگام ایجاد فرایندهای فرزند طولانی‌مدت خارج از ابزارهای exec/process (برای مثال، respawnهای CLI یا کمک‌کننده‌های Gateway)، کمک‌کننده bridge فرایند فرزند را متصل کنید تا سیگنال‌های خاتمه ارسال شوند و listenerها هنگام exit/error جدا شوند. این کار از فرایندهای رهاشده در systemd جلوگیری می‌کند و رفتار shutdown را در پلتفرم‌ها یکسان نگه می‌دارد.

بازنویسی‌های محیطی:

• PI_BASH_YIELD_MS: yield پیش‌فرض (ms)
• PI_BASH_MAX_OUTPUT_CHARS: سقف خروجی درون‌حافظه‌ای (chars)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: سقف stdout/stderr در انتظار برای هر stream (chars)
• PI_BASH_JOB_TTL_MS: TTL برای نشست‌های پایان‌یافته (ms، محدود به 1m–3h)

پیکربندی (ترجیحی):

• tools.exec.backgroundMs (پیش‌فرض 10000)
• tools.exec.timeoutSec (پیش‌فرض 1800)
• tools.exec.cleanupMs (پیش‌فرض 1800000)
• tools.exec.notifyOnExit (پیش‌فرض true): وقتی یک exec پس‌زمینه خارج می‌شود، یک رویداد سیستمی را در صف قرار می‌دهد + درخواست Heartbeat می‌کند.
• tools.exec.notifyOnExitEmptySuccess (پیش‌فرض false): وقتی true باشد، برای اجراهای پس‌زمینه موفقی که هیچ خروجی تولید نکرده‌اند نیز رویدادهای تکمیل را در صف قرار می‌دهد.

# ابزار process

اقدام‌ها:

• list: نشست‌های در حال اجرا + پایان‌یافته
• poll: تخلیه خروجی جدید برای یک نشست (وضعیت exit را نیز گزارش می‌کند)
• log: خواندن خروجی تجمیع‌شده (از offset + limit پشتیبانی می‌کند)
• write: ارسال stdin (data، eof اختیاری)
• send-keys: ارسال key tokenهای صریح یا byteها به یک نشست متکی بر PTY
• submit: ارسال Enter / carriage return به یک نشست متکی بر PTY
• paste: ارسال متن literal، در صورت تمایل بسته‌بندی‌شده در حالت bracketed paste
• kill: خاتمه دادن به یک نشست پس‌زمینه
• clear: حذف یک نشست پایان‌یافته از حافظه
• remove: اگر در حال اجراست kill می‌کند، در غیر این صورت اگر پایان یافته clear می‌کند

نکته‌ها:

• فقط نشست‌های پس‌زمینه در حافظه فهرست/ماندگار می‌شوند.
• نشست‌ها با restart فرایند از دست می‌روند (ماندگاری دیسکی وجود ندارد).
• لاگ‌های نشست فقط زمانی در تاریخچه chat ذخیره می‌شوند که process poll/log را اجرا کنید و نتیجه ابزار ثبت شود.
• process برای هر agent محدود است؛ فقط نشست‌هایی را می‌بیند که همان agent شروع کرده است.
• از poll / log برای وضعیت، لاگ‌ها، تأیید موفقیت بی‌صدا، یا تأیید تکمیل وقتی wake خودکار تکمیل در دسترس نیست استفاده کنید.
• وقتی به input یا مداخله نیاز دارید، از write / send-keys / submit / paste / kill استفاده کنید.
• process list برای بررسی سریع، یک name مشتق‌شده (فعل فرمان + هدف) را شامل می‌شود.
• process log از offset/limit مبتنی بر خط استفاده می‌کند.
• وقتی هر دو offset و limit حذف شوند، 200 خط آخر را برمی‌گرداند و یک راهنمای صفحه‌بندی را شامل می‌شود.
• وقتی offset ارائه شود و limit حذف شود، از offset تا پایان را برمی‌گرداند (به 200 محدود نمی‌شود).
• Polling برای وضعیت درخواستی است، نه زمان‌بندی حلقه انتظار. اگر کار باید بعداً انجام شود، به‌جای آن از cron استفاده کنید.

# مثال‌ها

اجرای یک کار طولانی و poll کردن آن در آینده:

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }

شروع فوری در پس‌زمینه:

{ "tool": "exec", "command": "npm run build", "background": true }

ارسال stdin:

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

ارسال کلیدهای PTY:

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

ارسال خط فعلی:

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

چسباندن متن literal:

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

# مرتبط

• ابزار Exec
• تأییدهای Exec