کارگزار اسرار 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 همراه را فعال کنید:

openclaw plugins enable onepassword

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

mkdir -p ~/.openclaw/credentials/onepasswordchmod 700 ~/.openclaw/credentials/onepasswordprintf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \  ~/.openclaw/credentials/onepassword/service-account-tokenchmod 600 ~/.openclaw/credentials/onepassword/service-account-tokenunset OP_SERVICE_ACCOUNT_TOKEN

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

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

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

{  "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 است.

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

{ "action": "list" }

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

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

{  "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 یا حذف، رد یا تغییر مقصد یک اسلاگ، مجوزهای در انتظار و مقادیر حافظه نهان را نامعتبر می‌کند.

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

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

openclaw onepassword status

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

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

openclaw onepassword auditopenclaw onepassword audit --limit 100

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

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

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

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

کدهای خطا

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

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

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