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

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

ابزار exec

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

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

رفتار:

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

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

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

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

• OPENCLAW_BASH_YIELD_MS: yield پیش‌فرض (میلی‌ثانیه)
• OPENCLAW_BASH_MAX_OUTPUT_CHARS: سقف خروجی درون‌حافظه‌ای (نویسه)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: سقف stdout/stderr در انتظار برای هر stream (نویسه)
• OPENCLAW_BASH_JOB_TTL_MS: TTL برای نشست‌های پایان‌یافته (میلی‌ثانیه، محدود به 1m–3h)
• OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS: آستانه خروجی بیکار پیش از اینکه نشست‌های پس‌زمینه قابل‌نوشتن به‌عنوان احتمالا در انتظار ورودی علامت‌گذاری شوند (پیش‌فرض 15000 ms)

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

• 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: توکن‌های کلید یا بایت‌های صریح را به یک نشست پشتیبانی‌شده با PTY ارسال می‌کند
• submit: Enter / carriage return را به یک نشست پشتیبانی‌شده با PTY ارسال می‌کند
• paste: متن خام را ارسال می‌کند، به‌صورت اختیاری پیچیده‌شده در حالت bracketed paste
• kill: یک نشست پس‌زمینه را پایان می‌دهد
• clear: یک نشست پایان‌یافته را از حافظه حذف می‌کند
• remove: اگر در حال اجرا باشد kill می‌کند، وگرنه اگر پایان یافته باشد clear می‌کند

نکات:

• فقط نشست‌های پس‌زمینه در حافظه فهرست/ماندگار می‌شوند.
• نشست‌ها با راه‌اندازی مجدد فرایند از دست می‌روند (هیچ ماندگاری دیسکی وجود ندارد).
• گزارش‌های نشست فقط اگر process poll/log را اجرا کنید و نتیجه ابزار ثبت شود، در تاریخچه چت ذخیره می‌شوند.
• process به ازای هر عامل محدوده‌بندی شده است؛ فقط نشست‌هایی را می‌بیند که همان عامل شروع کرده است.
• برای وضعیت، گزارش‌ها، تایید موفقیت بی‌صدا، یا تایید تکمیل وقتی بیدارسازی تکمیل خودکار در دسترس نیست، از poll / log استفاده کنید.
• پیش از بازیابی یک CLI تعاملی، از log استفاده کنید تا transcript فعلی، وضعیت stdin، و نکته انتظار ورودی با هم قابل مشاهده باشند.
• وقتی به ورودی یا مداخله نیاز دارید، از write / send-keys / submit / paste / kill استفاده کنید.
• process list برای مرور سریع، یک name مشتق‌شده (فعل فرمان + هدف) را شامل می‌شود.
• process list، poll و log فقط زمانی waitingForInput را گزارش می‌کنند که نشست هنوز stdin قابل‌نوشتن داشته باشد و بیش از آستانه انتظار ورودی بیکار مانده باشد.
• 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": "process", "action": "log", "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>" }

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

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

مرتبط

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