Gateway

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

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

ابزار exec

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

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

رفتار:

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

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

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

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

PI_BASH_YIELD_MS: yield پیش‌فرض (ms)
PI_BASH_MAX_OUTPUT_CHARS: سقف خروجی درون‌حافظه‌ای (نویسه)
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: سقف stdout/stderr در انتظار برای هر جریان (نویسه)
PI_BASH_JOB_TTL_MS: TTL برای نشست‌های پایان‌یافته (ms، محدود به 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: تخلیه خروجی جدید برای یک نشست (وضعیت خروج را نیز گزارش می‌کند)
log: خواندن خروجی تجمیع‌شده و نمایش راهنمایی‌های بازیابی ورودی (از offset + limit پشتیبانی می‌کند)
write: ارسال stdin (data، eof اختیاری)
send-keys: ارسال توکن‌های کلید یا بایت‌های صریح به یک نشست پشتیبانی‌شده با PTY
submit: ارسال Enter / carriage return به یک نشست پشتیبانی‌شده با PTY
paste: ارسال متن لفظی، به‌صورت اختیاری پیچیده‌شده در حالت paste کروشه‌دار
kill: پایان‌دادن به یک نشست پس‌زمینه
clear: حذف یک نشست پایان‌یافته از حافظه
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 قابل نوشتن داشته باشد و بیش از آستانه انتظار ورودی بیکار بوده باشد.
process log از offset/limit مبتنی بر خط استفاده می‌کند.
وقتی هر دو offset و limit حذف شوند، 200 خط آخر را برمی‌گرداند و یک راهنمای صفحه‌بندی را شامل می‌شود.
وقتی offset ارائه شود و limit حذف شود، از offset تا پایان را برمی‌گرداند (به 200 محدود نمی‌شود).
پایش برای وضعیت درخواستی است، نه زمان‌بندی حلقه انتظار. اگر کار باید بعداً انجام شود، به‌جای آن از cron استفاده کنید.

مثال‌ها

اجرای یک وظیفه طولانی و پایش بعدی:

json

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

json

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

بازبینی یک نشست تعاملی پیش از ارسال ورودی:

json

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

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

json

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

ارسال stdin:

json

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

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

json

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

ثبت خط فعلی:

json

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

چسباندن متن لفظی:

json

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

مرتبط

Was this useful?