Gateway
اجرای پسزمینه و ابزار پردازش
OpenClaw فرمانهای پوسته را از طریق ابزار exec اجرا میکند و وظایف طولانیمدت را در حافظه نگه میدارد. ابزار process آن نشستهای پسزمینه را مدیریت میکند.
ابزار exec
پارامترها:
| پارامتر | توضیحات |
|---|---|
command |
الزامی. فرمان پوستهای که باید اجرا شود. |
workdir |
دایرکتوری کاری؛ برای استفاده از cwd پیشفرض، وارد نکنید. |
env |
متغیرهای محیطی اضافی برای فرمان. |
yieldMs |
مدت انتظار برحسب میلیثانیه پیش از انتقال به پسزمینه (پیشفرض 10000). |
background |
بلافاصله در پسزمینه اجرا شود. |
timeout |
مهلت زمانی برحسب ثانیه (پیشفرض tools.exec.timeoutSeconds)؛ پس از انقضا فرایند را متوقف میکند. برای غیرفعالکردن مهلت زمانی فرایند exec در آن فراخوانی، timeout: 0 را تنظیم کنید. |
pty |
در صورت دسترسبودن، در شبهپایانه اجرا شود (CLIهای نیازمند TTY، عاملهای کدنویسی). |
elevated |
اگر حالت ارتقایافته فعال/مجاز است، خارج از محیط ایزوله اجرا شود (بهطور پیشفرض gateway، یا هنگامی که مقصد exec برابر node است، node). |
host |
مقصد exec: auto، sandbox، gateway یا node. |
node |
شناسه/نام Node که همراه host: "node" استفاده میشود. |
رفتار:
- اجراهای پیشزمینه خروجی را مستقیماً برمیگردانند.
- هنگام انتقال به پسزمینه (بهصورت صریح یا بر اثر مهلت زمانی
yieldMs)، ابزارstatus: "running"+sessionIdو بخش کوتاهی از انتهای خروجی را برمیگرداند. - اجراهای پسزمینه و
yieldMs، مگر آنکه فراخوانیtimeoutصریحی ارسال کند،tools.exec.timeoutSecondsرا به ارث میبرند. - خروجی تا زمانی که نشست پایش یا پاکسازی شود، در حافظه باقی میماند.
- اگر ابزار
processمجاز نباشد، اجراهایexecهمگام اجرا میشوند وyieldMs/backgroundرا نادیده میگیرند. - فرمانهای exec ایجادشده، برای قواعد پوسته/پروفایل حساس به زمینه،
OPENCLAW_SHELL=execرا دریافت میکنند. - برای کار طولانیمدتی که اکنون آغاز میشود: آن را یکبار شروع کنید و پس از تولید خروجی یا شکست فرمان، به بیدارسازی خودکار هنگام تکمیل (در صورت فعالبودن) تکیه کنید.
- اگر بیدارسازی خودکار هنگام تکمیل در دسترس نیست، یا برای فرمانی که بدون خروجی و با موفقیت خاتمه مییابد به تأیید موفقیت بیصدا نیاز دارید، با
processپایش کنید. - یادآورها یا پیگیریهای تأخیردار را با حلقههای
sleepیا پایش مکرر شبیهسازی نکنید — برای کارهای آینده از Cron استفاده کنید.
بازنویسیهای محیطی
| متغیر | اثر |
|---|---|
OPENCLAW_BASH_YIELD_MS |
مدت yield پیشفرض پیش از انتقال به پسزمینه (میلیثانیه). پیشفرض 10000، محدود به 10-120000. |
OPENCLAW_BASH_MAX_OUTPUT_CHARS |
سقف خروجی درونحافظهای (نویسه). |
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS |
سقف stdout/stderr در انتظار برای هر جریان (نویسه). |
OPENCLAW_BASH_JOB_TTL_MS |
TTL نشستهای پایانیافته (میلیثانیه)، محدود به 1m-3h. |
OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS |
آستانه بیخروجیبودن که پس از آن نشستهای پسزمینه قابلنوشتن بهعنوان نشستهایی که احتمالاً منتظر ورودی هستند علامتگذاری میشوند. پیشفرض 15000. |
پیکربندی (ترجیح دادهشده به بازنویسیهای محیطی)
| کلید | پیشفرض | اثر |
|---|---|---|
tools.exec.backgroundMs |
10000 | همان OPENCLAW_BASH_YIELD_MS. |
tools.exec.timeoutSeconds |
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/بازگشت carriage را به یک نشست مبتنی بر PTY ارسال میکند. |
paste |
متن تحتاللفظی را ارسال میکند و در صورت درخواست، آن را در حالت bracketed 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 ms،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?
