---
read_when:
    - می‌خواهید عامل‌ها اسرار گزینش‌شدهٔ 1Password را درخواست کنند
    - به سیاست تأیید برای هر راز و تاریخچه ممیزی نیاز دارید
    - در حال پیکربندی یک حساب سرویس 1Password برای OpenClaw هستید
summary: از Plugin اختیاری 1Password به‌عنوان واسط ممیزی‌شدهٔ اسرار عامل استفاده کنید
title: کارگزار اسرار 1Password
x-i18n:
    generated_at: "2026-07-27T16:56:29Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 255ab4fd2c63754fef29d3ea87dcedc9ca2bd2f34bec1f81139e2ce5b6acdba2
    source_path: plugins/onepassword.md
    workflow: 16
---

# کارگزار اسرار 1Password

Plugin همراه `onepassword` یک ابزار تحت کنترل سیاست را در اختیار عامل‌ها می‌گذارد تا
مجموعه‌ای گزینش‌شده از فیلدهای 1Password را بخوانند. این Plugin به‌طور پیش‌فرض غیرفعال است و
تا زمانی که `plugins.entries.onepassword.config` وجود نداشته باشد، هیچ کاری انجام نمی‌دهد.

این یک ابزار عامل است، نه ارائه‌دهنده SecretRef. متغیرهای محیطی را تزریق نمی‌کند
و اسرار پیکربندی OpenClaw را برطرف نمی‌کند.

## مدل امنیتی

- فقط احراز هویت حساب سرویس. توکن در یک فایل اعتبارنامه محلی می‌ماند
  و هرگز در `openclaw.json` پذیرفته نمی‌شود.
- فقط رجیستری گزینش‌شده. عامل‌ها می‌توانند اسلاگ‌های پیکربندی‌شده را فهرست کنند، اما Plugin هرگز
  یک مخزن 1Password را فهرست نمی‌کند.
- سیاست `auto`، `approve` یا `deny` برای هر اسلاگ.
- مجوزهای تأیید منقضی می‌شوند. مقدار ذخیره‌شده در حافظه نهان هرگز سیاست جاری را دور نمی‌زند.
- هر تلاش برای دسترسی در وضعیت SQLite مشترک OpenClaw ثبت می‌شود. ردیف‌های
  ممیزی شامل دلیل ارائه‌شده هستند؛ دلایل نباید حساس باشند. کارگزار
  هرگز مقدار دریافت‌شده یا توکن سرویس را در یک ردیف ممیزی کپی نمی‌کند.
- پس از اجرای جاری ابزار، ماندگارسازی رونوشت تحت مالکیت OpenClaw
  مقدار موفق `get` را با فراداده ویرایش‌شده جایگزین می‌کند.
- مقدار برای مدل در همان اجرا قابل مشاهده است. اگر مدل آن را در فراخوانی ابزار یا پاسخ
  بعدی کپی کند، آن رکورد جداگانه خارج از هوک ماندگارسازی این Plugin است.
  سیاست‌ها را محدود نگه دارید و از مدل نخواهید مقداری را بازگو کند.
- Plugin برای هر خطای حافظه نهان، `op` را یک‌بار فراخوانی می‌کند. برای محدودیت نرخ یا
  خطاهای دیگر تلاش مجدد انجام نمی‌دهد.
- هر فراخوانی `op` با محیطی حداقلی اجرا می‌شود که یکپارچه‌سازی با
  برنامه دسکتاپ 1Password را غیرفعال می‌کند (`OP_LOAD_DESKTOP_APP_SETTINGS=false`،
  `OP_BIOMETRIC_UNLOCK_ENABLED=false`)، بنابراین برنامه 1Password نصب‌شده روی
  میزبان Gateway هرگز پنجره‌های مجوز بیومتریک یا macOS را فعال نمی‌کند.

به حساب سرویس فقط برای مخزن‌ها و آیتم‌هایی که در پیکربندی
Plugin ثبت شده‌اند، دسترسی خواندن بدهید.

## پیش از شروع

به موارد زیر نیاز دارید:

- CLI مربوط به 1Password ‏(`op`) نصب‌شده روی میزبان Gateway
- یک حساب سرویس 1Password با دسترسی به آیتم‌های انتخاب‌شده
- یک فایل توکن اختصاصی حساب سرویس

Plugin همراه را فعال کنید:

```bash
openclaw plugins enable onepassword
```

دایرکتوری و فایل توکن را در دایرکتوری وضعیت OpenClaw ایجاد کنید:

```bash
mkdir -p ~/.openclaw/credentials/onepassword
chmod 700 ~/.openclaw/credentials/onepassword
printf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \
  ~/.openclaw/credentials/onepassword/service-account-token
chmod 600 ~/.openclaw/credentials/onepassword/service-account-token
unset OP_SERVICE_ACCOUNT_TOKEN
```

وقتی `OPENCLAW_STATE_DIR` تنظیم شده است، `~/.openclaw` را با آن دایرکتوری جایگزین کنید.
اگر فایل توکن برای گروه یا کاربران دیگر قابل خواندن یا نوشتن باشد،
Plugin یک‌بار هشدار می‌دهد.

## پیکربندی اسرار ثبت‌شده

پیکربندی Plugin را به `openclaw.json` اضافه کنید:

```jsonc
{
  "plugins": {
    "entries": {
      "onepassword": {
        "enabled": true,
        "config": {
          "vault": "Automation",
          "defaultPolicy": "approve",
          "cacheTtlSeconds": 300,
          "grantTtlHours": 720,
          "opTimeoutMs": 15000,
          "items": {
            "repository-token": {
              "item": "Repository automation token",
              "field": "credential",
              "policy": "approve",
              "description": "Token for repository automation",
            },
            "model-key": {
              "item": "Model provider key",
              "vault": "Agent credentials",
              "policy": "auto",
            },
          },
        },
      },
    },
  },
}
```

اسلاگ‌ها از حروف کوچک، اعداد و خط تیره استفاده می‌کنند، با حرف یا
عدد شروع می‌شوند و حداکثر 64 نویسه دارند. یک رجیستری می‌تواند حداکثر 32
اسلاگ داشته باشد؛ توضیحات می‌توانند حداکثر 200 نویسه داشته باشند. `field` یک برچسب
یا شناسه فیلد را می‌پذیرد، نباید شامل ویرگول باشد و مقدار پیش‌فرض آن `credential` است.
یک `vault` در سطح آیتم، مخزن پیش‌فرض را بازنویسی می‌کند. `opBin` می‌تواند یک
مسیر مطلق برای فایل اجرایی `op` تنظیم کند؛ در غیر این صورت Plugin، ‏`op` را از `PATH` برطرف می‌کند.
عنوان آیتم‌ها نباید با خط تیره شروع شود.

## استفاده از ابزار عامل

نام ابزار `onepassword` است.

اسلاگ‌های ثبت‌شده را فهرست کنید:

```json
{ "action": "list" }
```

نتیجه فقط شامل اسلاگ، توضیحات، سیاست و فعال‌بودن یا نبودن یک
مجوز دائمی است. هرگز شامل مقدار یک راز نیست و 1Password را جست‌وجو نمی‌کند.

یک راز را درخواست کنید:

```json
{
  "action": "get",
  "slug": "repository-token",
  "reason": "Authenticate the requested repository operation"
}
```

`reason` الزامی است، نباید خالی باشد و به 300 نویسه محدود است. یک
`get` موفق، مقدار را به‌همراه اسلاگ پیکربندی‌شده، عنوان آیتم و
برچسب فیلد برمی‌گرداند.

شِمای ابزار همچنین یک پارامتر داخلی `authorizationNonce` را تعریف می‌کند.
لایه سیاست پس از ارزیابی درخواست، آن را تزریق می‌کند تا مجوز را
به فراخوانی در حال اجرای ابزار تحویل دهد. هرگز آن را دستی تنظیم نکنید: هوک سیاست
هر مقدار ارائه‌شده را بازنویسی می‌کند و مقدار ناشناخته باعث شکست درخواست می‌شود.

## سطوح سیاست و تأییدها

- `auto`: فوراً دریافت و درخواست را ممیزی کن.
- `deny`: درخواست را مسدود و ممیزی کن.
- `approve`: از یک مجوز دائمی منقضی‌نشده استفاده کن، یا از یک انسان بخواه یک‌بار
  اجازه دهد، همیشه اجازه دهد یا رد کند.

اجازه یک‌باره فقط فراخوانی جاری ابزار را مجاز می‌کند. اجازه همیشگی یک مجوز
دائمی برای آن عامل و اسلاگ در SQLite می‌نویسد؛ سایر عامل‌ها باید
تأیید خود را دریافت کنند. OpenClaw فقط زمانی اجازه همیشگی را ارائه می‌دهد که فراخواننده
یک هویت عامل مشخص داشته باشد. مجوز پس از `grantTtlHours` منقضی می‌شود که مقدار پیش‌فرض آن 720 ساعت است.
تأییدی که حل‌نشده بماند یا مهلتش تمام شود، درخواست را رد می‌کند؛ حداکثر زمان انتظار برای
تأیید 600 ثانیه است. Plugin حداکثر 1,024 مجوز دائمی را نگه می‌دارد؛ در این
حد، قدیمی‌ترین مجوز حذف می‌شود و عامل آن باید دسترسی بعدی را تأیید کند.

هر مجوز ارزیابی‌شده یک‌بارمصرف است و از طریق وضعیت SQLite مشترک
به فراخوانی در حال اجرای ابزار تحویل داده می‌شود؛ بنابراین این تحویل حتی زمانی که بیش از یک
نمونه Plugin در فرایند Gateway فعال است نیز کار می‌کند. مجوزهای استفاده‌نشده
پس از پنجره تأیید 600 ثانیه‌ای منقضی می‌شوند.

مقدار پیش‌فرض حافظه نهان درون‌حافظه‌ای 300 ثانیه است و به رجیستری اسلاگ
پیکربندی‌شده محدود می‌شود. برای غیرفعال‌کردن آن، `cacheTtlSeconds` را روی `0` تنظیم کنید. سیاست
پیش از هر جست‌وجوی حافظه نهان ارزیابی می‌شود و اصابت‌های حافظه نهان ممیزی می‌شوند. بارگذاری‌های مجدد
پیکربندی زمان اجرا در هر مرز سیاست و اجرا اعمال می‌شوند؛ غیرفعال‌کردن Plugin یا
حذف، رد یا تغییر مقصد یک اسلاگ، مجوزهای در انتظار و
مقادیر حافظه نهان را نامعتبر می‌کند.

## بررسی وضعیت و تاریخچه ممیزی

آمادگی و شمار رجیستری را نمایش دهید:

```bash
openclaw onepassword status
```

این فرمان گزارش می‌دهد که آیا فایل توکن وجود دارد، آیا `op` برطرف شده و مسیر آن چیست،
تعداد آیتم‌های ثبت‌شده و شمار هر سیاست چقدر است. این فرمان هرگز توکن یا
مقادیر راز را نمی‌خواند یا چاپ نمی‌کند.

50 ردیف اخیر ممیزی را نمایش دهید:

```bash
openclaw onepassword audit
openclaw onepassword audit --limit 100
```

ردیف‌ها از جدیدترین به قدیمی‌ترین مرتب شده‌اند و مُهر زمانی، عامل، اسلاگ، نتیجه، یک `errorCode`
در صورت شکست تلاش و دلیل کوتاه‌شده را نشان می‌دهند. دلیل همان‌طور که
ارائه شده ذخیره می‌شود؛ کارگزار هرگز مقدار دریافت‌شده را به گزارش ممیزی اضافه نمی‌کند.

## رفتار CLI مربوط به 1Password

در هر خطای حافظه نهان، `op item get` با آیتم و مخزن پیکربندی‌شده، انتخابگر دقیق
فیلد، خروجی JSON، مهلت زمانی محدود و `--cache=false` اجرا می‌شود. فرایند فرزند
فقط همان فیلد را دریافت می‌کند، نه کل آیتم را. فقط
`OP_SERVICE_ACCOUNT_TOKEN` و `HOME` در محیط فرایند فرزند وجود دارند.

Plugin یک‌بار تلاش می‌کند. خطاهای `RATE_LIMITED` باید با انتظار
پیش از درخواست بعدی عامل مدیریت شوند؛ Plugin حلقه تلاش مجدد
خودکار ایجاد نمی‌کند.

## کدهای خطا

تلاش‌های ناموفق یک کد خطای بسته را در نتیجه ابزار و ردیف
ممیزی حمل می‌کنند.

خطاهای دسترسی 1Password:

| کد               | معنا                                                             |
| ----------------- | ---------------------------------------------------------------- |
| `TOKEN_MISSING`   | فایل توکن وجود ندارد یا خالی است                                |
| `OP_NOT_FOUND`    | فایل باینری `op` قابل یافتن نبود                                |
| `ITEM_NOT_FOUND`  | آیتم پیکربندی‌شده در مخزن نیست                                  |
| `FIELD_NOT_FOUND` | فیلد پیکربندی‌شده در آیتم نیست؛ برچسب‌های موجود فهرست می‌شوند |
| `RATE_LIMITED`    | محدودیت نرخ حساب سرویس 1Password فرا رسیده است                  |
| `AUTH_FAILED`     | احراز هویت حساب سرویس ناموفق بود                               |
| `TIMEOUT`         | `op` از `opTimeoutMs` فراتر رفت                                      |
| `OP_ERROR`        | هر شکست دیگر `op` یا خروجی نامعتبر                              |

خطاهای سیاست و اعتبارسنجی:

| کد                                                | معنا                                                                         |
| -------------------------------------------------- | ---------------------------------------------------------------------------- |
| `INVALID_ACTION`, `INVALID_REASON`, `INVALID_SLUG` | اعتبارسنجی ورودی درخواست ناموفق بود                                         |
| `UNKNOWN_SLUG`                                     | اسلاگ در رجیستری پیکربندی‌شده نیست                                          |
| `TOOL_CALL_ID_MISSING`                             | فراخوانی بدون شناسه فراخوانی ابزار رسید                                     |
| `POLICY_NOT_EVALUATED`                             | هیچ مجوز منطبقی برای این فراخوانی وجود ندارد؛ درخواست از نظر سیاست تأیید نشده بود |
| `POLICY_CHANGED`                                   | پیکربندی میان تأیید و اجرا تغییر کرد                                        |
| `GRANT_EXPIRED`                                    | مجوز دائمی پیش از اجرا منقضی شد                                              |
| `APPROVAL_CANCELLED`                               | اجرا در زمان انتظار برای تأیید متوقف شد                                     |