---
read_when:
    - افزودن یا تغییر رفتار اجرای پس‌زمینه
    - اشکال‌زدایی از وظایف exec طولانی‌مدت
summary: اجرای exec در پس‌زمینه و مدیریت فرایندها
title: ابزار اجرای پس‌زمینه و فرایند
x-i18n:
    generated_at: "2026-05-10T19:39:18Z"
    model: gpt-5.5
    provider: openai
    source_hash: 95fb986cf0c07ef3d054189ce2838b441ae24f07703f8edc1ddb8aca3a58b300
    source_path: gateway/background-process.md
    workflow: 16
---

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" }
```

## مرتبط

- [ابزار Exec](/fa/tools/exec)
- [تأییدهای Exec](/fa/tools/exec-approvals)