---
read_when:
    - افزودن یا تغییر رفتار اجرای پس‌زمینه
    - اشکال‌زدایی وظایف اجرایی طولانی‌مدت
summary: اجرای پس‌زمینه و مدیریت فرایندها
title: اجرای پس‌زمینه و ابزار فرایند
x-i18n:
    generated_at: "2026-07-12T09:58:24Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: b540455797df71dcdb18b0caa5f5088e81ef8823e0ec79364bebad8e6f060f12
    source_path: gateway/background-process.md
    workflow: 16
---

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 استفاده کنید.

## نمونه‌ها

اجرای یک وظیفه طولانی و پایش آن در زمانی دیگر:

```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)