---
read_when:
    - باید فضای کاری عامل یا چیدمان فایل‌های آن را توضیح دهید
    - می‌خواهید از فضای کاری یک عامل نسخهٔ پشتیبان تهیه کنید یا آن را انتقال دهید
sidebarTitle: Agent workspace
summary: 'فضای کاری عامل: مکان، چیدمان و راهبرد پشتیبان‌گیری'
title: فضای کاری عامل
x-i18n:
    generated_at: "2026-07-27T16:22:41Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: b58ead9079c3dda4bcaec3253f8d55e67e7e554d5c5b87ccfec6b08ec4ba038f
    source_path: concepts/agent-workspace.md
    workflow: 16
---

فضای کاری خانهٔ عامل است: دایرکتوری کاری‌ای که برای ابزارهای فایل
و زمینهٔ فضای کاری استفاده می‌شود. آن را خصوصی نگه دارید و مانند حافظه با آن رفتار کنید.

این فضا از `~/.openclaw/` جدا است؛ آن محل پیکربندی، اطلاعات احراز هویت و نشست‌ها را نگه می‌دارد.

<Warning>
فضای کاری **cwd پیش‌فرض** است، نه یک سندباکس سخت‌گیرانه. ابزارها مسیرهای نسبی را بر اساس فضای کاری تفسیر می‌کنند، اما تا زمانی که سندباکس فعال نشده باشد، مسیرهای مطلق همچنان می‌توانند به بخش‌های دیگر میزبان دسترسی پیدا کنند. اگر به جداسازی نیاز دارید، از [`agents.defaults.sandbox`](/fa/gateway/sandboxing) (و/یا پیکربندی سندباکس مختص هر عامل) استفاده کنید.

وقتی سندباکس فعال باشد و `workspaceAccess` برابر با `"rw"` نباشد، ابزارها در فضای کاری سندباکس زیر `~/.openclaw/sandboxes` کار می‌کنند، نه در فضای کاری میزبان شما.
</Warning>

## مکان پیش‌فرض

- پیش‌فرض: `~/.openclaw/workspace`
- اگر `OPENCLAW_PROFILE` تنظیم شده و برابر با `"default"` نباشد، مقدار پیش‌فرض به `~/.openclaw/workspace-<profile>` تغییر می‌کند.
- در صورت تنظیم، `OPENCLAW_WORKSPACE_DIR` هر دو مورد بالا را نادیده می‌گیرد.
- فضای کاری عامل‌های غیراصلی (`agents.entries.*`) که فضای کاری صریحی ندارند، به `<state-dir>/workspace-<agentId>` نگاشت می‌شود، نه فضای کاری مشترک پیش‌فرض.

بازنویسی در `~/.openclaw/openclaw.json`:

```json5
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}
```

بازنویسی مختص هر عامل: `agents.entries.*.workspace`.

`openclaw onboard`، `openclaw configure` یا `openclaw setup` فضای کاری را ایجاد می‌کنند و اگر فایل‌های راه‌اندازی اولیه وجود نداشته باشند، آن‌ها را مقداردهی می‌کنند.

<Note>
کپی‌های اولیهٔ سندباکس فقط فایل‌های عادی داخل فضای کاری را می‌پذیرند؛ نام‌های مستعار پیوند نمادین/سخت که به خارج از فضای کاری مبدأ نگاشت می‌شوند، نادیده گرفته می‌شوند.
</Note>

اگر فایل‌های فضای کاری را خودتان مدیریت می‌کنید، ایجاد فایل‌های راه‌اندازی اولیه را غیرفعال کنید:

```json5
{ agents: { defaults: { skipBootstrap: true } } }
```

## پوشه‌های اضافی فضای کاری

نصب‌های قدیمی‌تر ممکن است `~/openclaw` را ایجاد کرده باشند. نگه‌داشتن چند دایرکتوری فضای کاری می‌تواند باعث سردرگمی در احراز هویت یا واگرایی وضعیت شود، زیرا در هر لحظه فقط یک فضای کاری فعال است.

<Note>
**توصیه:** فقط یک فضای کاری فعال نگه دارید. اگر دیگر از پوشه‌های اضافی استفاده نمی‌کنید، آن‌ها را بایگانی کنید یا به سطل زباله منتقل کنید (برای مثال `trash ~/openclaw`). اگر عمداً چند فضای کاری نگه می‌دارید، مطمئن شوید `agents.defaults.workspace` (یا کلید مختص هر عامل `workspace`) به فضای کاری فعال اشاره می‌کند.
</Note>

## نقشهٔ فایل‌های فضای کاری

فایل‌های استانداردی که OpenClaw انتظار دارد در فضای کاری وجود داشته باشند:

<AccordionGroup>
  <Accordion title="AGENTS.md - دستورالعمل‌های عملیاتی">
    دستورالعمل‌های عملیاتی عامل و نحوهٔ استفادهٔ آن از حافظه. در آغاز هر نشست بارگذاری می‌شود. محل مناسبی برای قوانین، اولویت‌ها و جزئیات «نحوهٔ رفتار» است.
  </Accordion>
  <Accordion title="SOUL.md - شخصیت و لحن">
    شخصیت، لحن و مرزها. در هر نشست بارگذاری می‌شود. راهنما: [راهنمای شخصیت SOUL.md](/fa/concepts/soul).
  </Accordion>
  <Accordion title="USER.md - کاربر کیست">
    کاربر کیست و چگونه باید او را خطاب کرد. در هر نشست بارگذاری می‌شود.
  </Accordion>
  <Accordion title="IDENTITY.md - نام، حال‌وهوا، ایموجی">
    نام، حال‌وهوا و ایموجی عامل. طی آیین راه‌اندازی اولیه ایجاد/به‌روزرسانی می‌شود.
  </Accordion>
  <Accordion title="TOOLS.md - قراردادهای ابزار محلی">
    یادداشت‌هایی دربارهٔ ابزارها و قراردادهای محلی شما. دسترس‌پذیری ابزارها را کنترل نمی‌کند؛ فقط راهنما است.
  </Accordion>
  <Accordion title="HEARTBEAT.md - چک‌لیست Heartbeat">
    چک‌لیست کوچک و اختیاری برای اجرای Heartbeat. برای جلوگیری از مصرف توکن، آن را کوتاه نگه دارید.
  </Accordion>
  <Accordion title="BOOT.md - چک‌لیست راه‌اندازی">
    چک‌لیست اختیاری راه‌اندازی که هنگام راه‌اندازی مجدد Gateway به‌طور خودکار اجرا می‌شود (وقتی [قلاب‌های داخلی](/fa/automation/hooks) فعال باشند). آن را کوتاه نگه دارید؛ برای ارسال‌های خروجی از ابزار پیام استفاده کنید.
  </Accordion>
  <Accordion title="BOOTSTRAP.md - آیین نخستین اجرا">
    آیین یک‌بارهٔ نخستین اجرا. فقط برای یک فضای کاری کاملاً جدید ایجاد می‌شود. پس از تکمیل آیین، آن را حذف کنید.
  </Accordion>
  <Accordion title="memory/YYYY-MM-DD.md - گزارش روزانهٔ حافظه">
    گزارش روزانهٔ حافظه (یک فایل برای هر روز). توصیه می‌شود هنگام شروع نشست، امروز + دیروز خوانده شوند.
  </Accordion>
  <Accordion title="MEMORY.md - حافظهٔ بلندمدت گزینش‌شده (اختیاری)">
    حافظهٔ بلندمدت گزینش‌شده: واقعیت‌های پایدار، ترجیحات، تصمیم‌ها و خلاصه‌های کوتاه. گزارش‌های تفصیلی را در `memory/YYYY-MM-DD.md` نگه دارید تا ابزارهای حافظه بتوانند بدون تزریق آن‌ها به همهٔ پرامپت‌ها، هنگام نیاز بازیابی‌شان کنند. `MEMORY.md` را فقط در نشست اصلی و خصوصی بارگذاری کنید (نه در زمینه‌های اشتراکی/گروهی). برای گردش کار و تخلیهٔ خودکار حافظه، [حافظه](/fa/concepts/memory) را ببینید.
  </Accordion>
  <Accordion title="skills/ - Skills فضای کاری (اختیاری)">
    Skills مختص فضای کاری. وقتی نام‌ها تداخل داشته باشند، این مکان برای Skills آن فضای کاری بالاترین اولویت را دارد و پیش از Skills عامل پروژه، Skills شخصی عامل، Skills مدیریت‌شده، Skills همراه و `skills.load.extraDirs` قرار می‌گیرد.
  </Accordion>
  <Accordion title="canvas/ - فایل‌های رابط کاربری Canvas (اختیاری)">
    فایل‌های رابط کاربری Canvas برای نمایش‌های Node (برای مثال `canvas/index.html`).
  </Accordion>
</AccordionGroup>

<Note>
اگر یک فایل راه‌اندازی اولیه وجود نداشته باشد، OpenClaw نشانگر «فایل مفقود» را به نشست تزریق می‌کند و ادامه می‌دهد. فایل‌های راه‌اندازی اولیهٔ بزرگ هنگام تزریق کوتاه می‌شوند؛ محدودیت‌ها را با `agents.defaults.bootstrapMaxChars` (پیش‌فرض: `20000`) و `agents.defaults.bootstrapTotalMaxChars` (پیش‌فرض: `60000`) تنظیم کنید. `openclaw setup` می‌تواند بدون بازنویسی فایل‌های موجود، مقادیر پیش‌فرض مفقود را دوباره ایجاد کند.
</Note>

## چه چیزهایی در فضای کاری نیستند

این موارد زیر `~/.openclaw/` قرار دارند و نباید در مخزن فضای کاری ثبت شوند:

- `~/.openclaw/openclaw.json` (پیکربندی)
- `~/.openclaw/state/openclaw.sqlite` (وضعیت راه‌اندازی و گواهی‌های فضای کاری مشترک)
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (پروفایل‌های احراز هویت مدل: OAuth + کلیدهای API)
- `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite` (ردیف‌های نشست، رونوشت‌ها و وضعیت زمان اجرای مختص هر عامل)
- `~/.openclaw/agents/<agentId>/agent/codex-home/` (حساب زمان اجرای Codex مختص هر عامل، پیکربندی، Skills، plugins و وضعیت بومی رشته)
- `~/.openclaw/credentials/` (وضعیت کانال/ارائه‌دهنده به‌همراه داده‌های قدیمی واردشدهٔ OAuth)
- `~/.openclaw/agents/<agentId>/sessions/` (منابع مهاجرت قدیمی و مصنوعات بایگانی/پشتیبانی)
- `~/.openclaw/skills/` (Skills مدیریت‌شده)

اگر لازم است نشست‌ها یا پیکربندی را منتقل کنید، آن‌ها را جداگانه کپی کنید و خارج از کنترل نسخه نگه دارید.

نسخه‌های قدیمی‌تر OpenClaw فایل‌های جانبی فضای کاری `openclaw-workspace-state.json`،
`.openclaw/workspace-state.json` و `.attested` را می‌نوشتند. زمان اجرای فعلی
برای این وضعیت فقط از پایگاه‌دادهٔ SQLite مشترک استفاده می‌کند. اگر Doctor یکی
از این فایل‌ها را گزارش کرد، `openclaw doctor --fix` را اجرا کنید؛ Doctor وضعیت
قدیمی معتبر را وارد می‌کند و فقط پس از تأیید ردیف‌های پایگاه‌داده، فایل مبدأ را حذف می‌کند.

## پشتیبان‌گیری با Git (توصیه‌شده، خصوصی)

با فضای کاری مانند حافظهٔ خصوصی رفتار کنید. آن را در یک مخزن git **خصوصی** قرار دهید تا پشتیبان‌گیری و بازیابی آن ممکن باشد.

این مراحل را روی ماشینی اجرا کنید که Gateway روی آن اجرا می‌شود (فضای کاری نیز همان‌جا قرار دارد).

<Steps>
  <Step title="مخزن را مقداردهی اولیه کنید">
    اگر git نصب باشد، فضای کاری کاملاً جدید به‌طور خودکار مقداردهی اولیه می‌شود. اگر این فضای کاری از قبل مخزن نیست، اجرا کنید:

    ```bash
    cd ~/.openclaw/workspace
    git init
    git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
    git commit -m "Add agent workspace"
    ```

  </Step>
  <Step title="یک راه‌دور خصوصی اضافه کنید">
    <Tabs>
      <Tab title="رابط وب GitHub">
        1. یک مخزن **خصوصی** جدید در GitHub ایجاد کنید.
        2. آن را با README مقداردهی اولیه نکنید (برای جلوگیری از تداخل ادغام).
        3. نشانی راه‌دور HTTPS را کپی کنید.
        4. راه‌دور را اضافه و push کنید:

        ```bash
        git branch -M main
        git remote add origin <https-url>
        git push -u origin main
        ```
      </Tab>
      <Tab title="GitHub CLI (gh)">
        ```bash
        gh auth login
        gh repo create openclaw-workspace --private --source . --remote origin --push
        ```
      </Tab>
      <Tab title="رابط وب GitLab">
        1. یک مخزن **خصوصی** جدید در GitLab ایجاد کنید.
        2. آن را با README مقداردهی اولیه نکنید (برای جلوگیری از تداخل ادغام).
        3. نشانی راه‌دور HTTPS را کپی کنید.
        4. راه‌دور را اضافه و push کنید:

        ```bash
        git branch -M main
        git remote add origin <https-url>
        git push -u origin main
        ```
      </Tab>
    </Tabs>

  </Step>
  <Step title="به‌روزرسانی‌های مستمر">
    ```bash
    git status
    git add .
    git commit -m "Update memory"
    git push
    ```
  </Step>
</Steps>

## اطلاعات محرمانه را commit نکنید

<Warning>
حتی در یک مخزن خصوصی، از ذخیره‌سازی اطلاعات محرمانه در فضای کاری خودداری کنید:

- کلیدهای API، توکن‌های OAuth، گذرواژه‌ها یا اطلاعات احراز هویت خصوصی.
- هر چیزی زیر `~/.openclaw/`.
- خروجی‌های خام گفت‌وگوها یا پیوست‌های حساس.

اگر مجبورید ارجاع‌های حساس را ذخیره کنید، از جای‌نگهدار استفاده کنید و اطلاعات محرمانهٔ واقعی را جای دیگری نگه دارید (مدیر گذرواژه، متغیرهای محیطی یا `~/.openclaw/`).
</Warning>

نمونهٔ آغازین پیشنهادی برای `.gitignore`:

```gitignore
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
```

## انتقال فضای کاری به یک ماشین جدید

<Steps>
  <Step title="مخزن را clone کنید">
    مخزن را در مسیر دلخواه clone کنید (پیش‌فرض `~/.openclaw/workspace`).
  </Step>
  <Step title="پیکربندی را به‌روزرسانی کنید">
    در `~/.openclaw/openclaw.json`، مقدار `agents.defaults.workspace` را روی آن مسیر تنظیم کنید.
  </Step>
  <Step title="فایل‌های مفقود را مقداردهی کنید">
    برای مقداردهی فایل‌های مفقود، `openclaw setup --workspace <path>` را اجرا کنید.
  </Step>
  <Step title="نشست‌ها را کپی کنید (اختیاری)">
    اگر به نشست‌ها نیاز دارید، `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`
    را جداگانه از ماشین قدیمی کپی کنید. `~/.openclaw/agents/<agentId>/sessions/`
    را فقط زمانی کپی کنید که به ورودی‌های مهاجرت قدیمی یا مصنوعات بایگانی/پشتیبانی نیز نیاز دارید.
  </Step>
</Steps>

## نکات پیشرفته

- مسیریابی چندعاملی می‌تواند از طریق `agents.entries.*.workspace` برای هر عامل از فضای کاری متفاوتی استفاده کند. برای پیکربندی مسیریابی، [مسیریابی کانال](/fa/channels/channel-routing) را ببینید.
- اگر `agents.defaults.sandbox` فعال باشد، نشست‌های غیراصلی می‌توانند از فضای کاری سندباکس مختص هر نشست زیر `agents.defaults.sandbox.workspaceRoot` استفاده کنند.

## مرتبط

- [Heartbeat](/fa/gateway/heartbeat) - فایل فضای کاری HEARTBEAT.md
- [سندباکس](/fa/gateway/sandboxing) - دسترسی به فضای کاری در محیط‌های سندباکس‌شده
- [نشست](/fa/concepts/session) - مسیرهای ذخیره‌سازی نشست
- [دستورهای دائمی](/fa/automation/standing-orders) - دستورالعمل‌های پایدار در فایل‌های فضای کاری
