Gateway
اجرای پسزمینه و ابزار فرایند
OpenClaw فرمانهای پوسته را از طریق ابزار exec اجرا میکند و وظایف طولانیمدت را در حافظه نگه میدارد. ابزار process آن نشستهای پسزمینه را مدیریت میکند.
ابزار exec
پارامترها:
| پارامتر | توضیحات |
|---|---|
command |
الزامی. فرمان پوستهای که باید اجرا شود. |
workdir |
دایرکتوری کاری؛ برای استفاده از cwd پیشفرض، آن را وارد نکنید. |
env |
متغیرهای محیطی اضافی برای فرمان. |
yieldMs |
مدت انتظار بر حسب میلیثانیه پیش از انتقال به پسزمینه (پیشفرض 10000). |
background |
اجرای فوری در پسزمینه. |
timeout |
مهلت زمانی بر حسب ثانیه (پیشفرض tools.exec.timeoutSec)؛ پس از پایان مهلت، فرایند را متوقف میکند. برای غیرفعالکردن مهلت فرایند exec در آن فراخوانی، timeout: 0 را تنظیم کنید. |
pty |
در صورت موجود بودن، اجرا در شبهترمینال (برای CLIهای نیازمند TTY و عاملهای کدنویسی). |
elevated |
اگر حالت ارتقایافته فعال/مجاز باشد، اجرا خارج از محیط ایزوله (gateway بهطور پیشفرض، یا node هنگامی که مقصد exec برابر node است). |
host |
مقصد exec: auto، sandbox، gateway یا node. |
node |
شناسه/نام Node که همراه با host: "node" استفاده میشود. |
رفتار:
- اجراهای پیشزمینه، خروجی را مستقیماً برمیگردانند.
- هنگام انتقال به پسزمینه (بهصورت صریح یا بر اثر پایان مهلت
yieldMs)، ابزارstatus: "running"بههمراهsessionIdو بخش کوتاهی از انتهای خروجی را برمیگرداند. - اجراهای پسزمینه و اجراهای دارای
yieldMs، مگر اینکه فراخوانی مقدار صریحی برایtimeoutارسال کند،tools.exec.timeoutSecرا به ارث میبرند. - خروجی تا زمانی که نشست پایش یا پاک شود، در حافظه باقی میماند.
- اگر ابزار
processمجاز نباشد،execبهصورت همگام اجرا میشود وyieldMs/backgroundرا نادیده میگیرد. - فرمانهای exec ایجادشده برای قواعد آگاه از زمینه در پوسته/پروفایل،
OPENCLAW_SHELL=execرا دریافت میکنند. - برای کاری طولانیمدت که اکنون آغاز میشود: آن را یکبار شروع کنید و پس از تولید خروجی یا شکست فرمان، به بیدارباش خودکار تکمیل (در صورت فعال بودن) تکیه کنید.
- اگر بیدارباش خودکار تکمیل در دسترس نیست، یا برای فرمانی که بدون خروجی و با موفقیت پایان مییابد به تأیید موفقیت بیصدا نیاز دارید، با
processپایش کنید. - یادآورها یا پیگیریهای زماندار را با حلقههای
sleepیا پایش مکرر شبیهسازی نکنید؛ برای کارهای آینده از Cron استفاده کنید.
بازنویسیهای محیطی
| متغیر | اثر |
|---|---|
OPENCLAW_BASH_YIELD_MS |
زمان انتظار پیشفرض پیش از انتقال به پسزمینه (میلیثانیه). پیشفرض 10000، محدودشده به 10 تا 120000. |
OPENCLAW_BASH_MAX_OUTPUT_CHARS |
سقف خروجی درونحافظهای (تعداد نویسهها). |
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS |
سقف stdout/stderr در انتظار، برای هر جریان (تعداد نویسهها). |
OPENCLAW_BASH_JOB_TTL_MS |
TTL نشستهای پایانیافته (میلیثانیه)، محدودشده به 1 دقیقه تا 3 ساعت. |
OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS |
آستانه بیکاری خروجی که پس از آن نشستهای پسزمینه دارای ورودی نوشتنی، احتمالاً منتظر ورودی علامتگذاری میشوند. پیشفرض 15000. |
پیکربندی (مرجح بر بازنویسیهای محیطی)
| کلید | پیشفرض | اثر |
|---|---|---|
tools.exec.backgroundMs |
10000 | همانند OPENCLAW_BASH_YIELD_MS. |
tools.exec.timeoutSec |
1800 | مهلت زمانی پیشفرض برای هر فراخوانی. |
tools.exec.cleanupMs |
1800000 | همانند OPENCLAW_BASH_JOB_TTL_MS. |
tools.exec.notifyOnExit |
true | هنگام پایان یک exec پسزمینه، یک رویداد سیستمی را در صف قرار میدهد و Heartbeat درخواست میکند. |
tools.exec.notifyOnExitEmptySuccess |
false | برای اجراهای پسزمینه موفق و بدون خروجی نیز رویدادهای تکمیل را در صف قرار میدهد. |
پلزنی فرایند فرزند
هنگام ایجاد فرایندهای فرزند طولانیمدت خارج از ابزارهای exec/process (اجرای مجدد CLIها، ابزارهای کمکی Gateway)، ابزار کمکی پل فرایند فرزند را متصل کنید تا سیگنالهای خاتمه ارسال شوند و شنوندهها هنگام خروج/خطا جدا شوند. این کار از ایجاد فرایندهای یتیم در systemd جلوگیری میکند و خاموششدن را میان پلتفرمها سازگار نگه میدارد.
ابزار process
عملیات:
| عملیات | اثر |
|---|---|
list |
نشستهای در حال اجرا و پایانیافته. |
poll |
دریافت خروجی جدید یک نشست (و نیز گزارش وضعیت خروج). |
log |
خواندن خروجی تجمیعشده و راهنمای بازیابی ورودی. از offset و limit پشتیبانی میکند. |
write |
ارسال stdin (data، با eof اختیاری). |
send-keys |
ارسال توکنهای صریح کلید یا بایتها به یک نشست مبتنی بر PTY. |
submit |
ارسال Enter/بازگشت به ابتدای سطر به یک نشست مبتنی بر PTY. |
paste |
ارسال متن عینی، با امکان قرارگیری اختیاری در حالت چسباندن براکتدار. |
kill |
خاتمهدادن به یک نشست پسزمینه. |
clear |
حذف یک نشست پایانیافته از حافظه. |
remove |
اگر در حال اجرا باشد آن را خاتمه میدهد؛ در غیر این صورت، اگر پایان یافته باشد پاک میکند. |
نکات:
- فقط نشستهای پسزمینه فهرست و نگهداری میشوند؛ صرفاً در حافظه، نه روی دیسک. با راهاندازی مجدد فرایند، نشستها از بین میروند.
- یک نشست پسزمینه فعال، تعلیق مشارکتی میزبان و راهاندازی مجدد ایمن Gateway را تا زمانی مسدود میکند که مالک فرایند خروج واقعی آن را تأیید کند.
process removeمیتواند بلافاصله پس از درخواست خاتمه، نشست در حال اجرا را پنهان کند؛ تعلیق و راهاندازی مجدد تا زمان تأیید خروج همچنان مسدود میمانند.- گزارشهای نشست فقط در صورتی در تاریخچه گپ ذخیره میشوند که
process poll/logرا اجرا کنید و نتیجه ابزار ثبت شود. - دامنه
processبرای هر عامل جداگانه است؛ این ابزار فقط نشستهایی را میبیند که همان عامل آغاز کرده است. - وقتی بیدارباش خودکار تکمیل در دسترس نیست، برای وضعیت، گزارشها یا تأیید تکمیل از
poll/logاستفاده کنید. - پیش از بازیابی یک CLI تعاملی از
logاستفاده کنید تا رونوشت فعلی، وضعیت stdin و راهنمای انتظار برای ورودی همزمان قابل مشاهده باشند. - هنگامی که به ورودی یا مداخله نیاز دارید، از
write/send-keys/submit/paste/killاستفاده کنید. process listبرای مرور سریع، یکnameمشتقشده (فعل فرمان + مقصد) دارد.process list،pollوlogتنها زمانیwaitingForInputرا گزارش میکنند که نشست همچنان stdin قابلنوشتن داشته باشد و بیش از آستانه انتظار برای ورودی بیکار مانده باشد (پیشفرض 15000 میلیثانیه،OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).process logازoffset/limitمبتنی بر خط استفاده میکند. اگر هر دو وارد نشوند، 200 خط آخر را با راهنمای صفحهبندی برمیگرداند. اگرoffsetتنظیم شود اماlimitتنظیم نشود، ازoffsetتا پایان را برمیگرداند (به 200 محدود نمیشود).timeoutدرpollپیش از بازگشت، حداکثر به همان تعداد میلیثانیه منتظر میماند؛ مقادیر بیش از 30000 به 30000 محدود میشوند.- پایش برای بررسی وضعیت هنگام تقاضا است، نه زمانبندی حلقه انتظار. اگر کار باید بعداً انجام شود، از Cron استفاده کنید.
نمونهها
اجرای یک وظیفه طولانی و پایش آن در زمانی دیگر:
{ "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" }مطالب مرتبط
Was this useful?
