1Password

OpenClaw به دو روش مستقل با 1Password جفت می‌شود:

• اسرار پیکربندی: هر فیلد SecretRef در openclaw.json می‌تواند هنگام اجرا از طریق CLIِ op مقداردهی شود؛ بنابراین کلیدهای API هرگز در فایل پیکربندی قرار نمی‌گیرند.
• گردش‌کارهای عامل: مهارت همراهِ 1password به عامل‌ها می‌آموزد برای وظایف خود با op وارد شوند و اسرار را بخوانند یا تزریق کنند.

الزامات

• CLIِ 1Password ‏(op) روی میزبان Gateway نصب باشد (brew install 1password-cli در macOS).
• یک حالت احراز هویت برای op:
  • حساب سرویس (توصیه‌شده برای Gatewayهای بدون رابط): متغیر OP_SERVICE_ACCOUNT_TOKEN را در محیط سرویس Gateway صادر کنید. بدون برنامه دسکتاپ و بدون ورود تعاملی.
  • یکپارچه‌سازی با برنامه دسکتاپ: برنامه 1Password با یکپارچه‌سازی CLI فعال روی همان دستگاه اجرا می‌شود. فراخوانی‌های نخست ممکن است Touch ID یا احراز هویت سیستم را فعال کنند.
  • ورود مستقل: op signin در هر نشست درخواست ورود می‌کند. برای عامل‌ها از طریق مهارت قابل استفاده است، اما برای مقداردهی اسرار پیکربندی روی یک Gateway بدون رابط مناسب نیست.

مقداردهی اسرار پیکربندی با op

یک ارائه‌دهنده اسرار اجرایی تعریف کنید که op read را با یک ارجاع op://vault/item/field اجرا کند، سپس هر فیلدی را که از SecretRef پشتیبانی می‌کند به آن ارجاع دهید:

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // برای فایل‌های اجرایی پیوند نمادین‌شده Homebrew الزامی است        trustedDirs: ["/opt/homebrew"],        args: ["read", "op://Personal/OpenClaw QA API Key/password"],        passEnv: ["HOME"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },      },    },  },}

نحوه ارتباط اجزا:

• command باید یک مسیر مطلق باشد؛ trustedDirs پوشه آن را مورد اعتماد علامت‌گذاری می‌کند و allowSymlinkCommand لازم است، زیرا Homebrew، ‏op را به‌صورت پیوند نمادین نصب می‌کند.
• args ارجاع op://vault/item/field را عیناً منتقل می‌کند. OpenClaw طرح‌واره op:// را خودش تجزیه نمی‌کند؛ فایل اجرایی op آن را مقداردهی می‌کند.
• passEnv متغیرهای فهرست‌شده را از محیط Gateway منتقل می‌کند. یکپارچه‌سازی با برنامه دسکتاپ به HOME نیاز دارد؛ حساب‌های سرویس نیز به حضور OP_SERVICE_ACCOUNT_TOKEN در محیط سرویس Gateway نیاز دارند (آن را به passEnv اضافه کنید، یا فقط درصورتی آن را از طریق env تنظیم کنید که خوانا بودن توکن در فایل پیکربندی را می‌پذیرید).
• برای خروجی تک‌مقداری، id: "value" را حفظ کنید. با jsonOnly: true و یک بار داده JSON، به‌جای آن فیلدها را با شناسه اشاره‌گر JSON آدرس‌دهی کنید.
• یک ورودی ارائه‌دهنده به‌ازای هر سر، قابلیت ممیزی ارجاعات را حفظ می‌کند؛ ارائه‌دهندگان را بر اساس مصرف‌کننده آن‌ها نام‌گذاری کنید (onepassword_openai، onepassword_telegram).

برای ترتیب مقداردهی، ذخیره‌سازی موقت و معناشناسی شکست به اسرار Gateway و برای تمام فیلدهایی که SecretRef می‌پذیرند به سطح اعتبارنامه SecretRef مراجعه کنید.

راه‌اندازی حساب سرویس برای Gatewayهای بدون رابط

1. در حساب 1Password خود یک حساب سرویس ایجاد کنید و فقط دسترسی خواندن به موارد مخزنی را بدهید که Gateway به آن‌ها نیاز دارد.
2. OP_SERVICE_ACCOUNT_TOKEN را در اختیار سرویس Gateway قرار دهید (plist مربوط به launchd، واحد systemd یا محیط کانتینر).
3. "OP_SERVICE_ACCOUNT_TOKEN" را به فهرست passEnv ارائه‌دهنده اضافه کنید.
4. از محیط میزبان Gateway تأیید کنید: op whoami باید حساب سرویس را بدون درخواست ورود نمایش دهد.

خواندن با حساب سرویس مستلزم آن است که نام مخزن صریحاً در ارجاع op:// ذکر شود. دامنه دسترسی حساب را محدود نگه دارید؛ این یک اعتبارنامه حامل است.

مهارت 1password برای عامل‌ها

OpenClaw یک مهارت 1password به‌همراه دارد که عامل‌ها را به اپراتورهای ماهر op تبدیل می‌کند: حالت احراز هویت موجود (حساب سرویس، یکپارچه‌سازی با برنامه دسکتاپ یا ورود مستقل) را تشخیص می‌دهد، پیش از خواندن هر چیزی دسترسی را با op whoami تأیید می‌کند و op run / op inject را به نوشتن مقادیر اسرار روی دیسک ترجیح می‌دهد. این مهارت به فایل اجرایی op نیاز دارد و در صورت نبود آن، نصب با Homebrew را پیشنهاد می‌کند.

عامل‌ها از آن برای گردش‌کارهای خود استفاده می‌کنند؛ برای مثال، خواندن توکن استقرار در میانه وظیفه یا تزریق متغیرهای محیطی به یک فرمان. این قابلیت مستقل از مقداردهی اسرار پیکربندی است؛ Gateway بدون دخالت هیچ مهارتی SecretRefها را مقداردهی می‌کند.

نکات امنیتی

• مقادیر اسراری که از طریق ارائه‌دهندگان اجرایی مقداردهی می‌شوند در حافظه Gateway باقی می‌مانند؛ عکس‌های فوری پیکربندی و پاسخ‌های config.get فیلدهای SecretRef را می‌پوشانند.
• هرگز مقادیر اسرار را در openclaw.json، گزارش‌ها یا گفت‌وگو قرار ندهید. نام موارد را در پیکربندی و مقادیر را در 1Password نگه دارید.
• ردپای ممیزی 1Password هر خواندن حساب سرویس را نشان می‌دهد و چرخش کلید و بررسی رخداد را عملی می‌کند.

عیب‌یابی

• command not found یا خطاهای ایجاد فرایند: از مسیر مطلق op استفاده کنید و پوشه آن را در trustedDirs بگنجانید.
• op مقداردهی می‌شود، اما خواندن‌ها با خطاهای پیوند نمادین شکست می‌خورند: برای نصب‌های Homebrew، ‏allowSymlinkCommand: true را تنظیم کنید.
• account is not signed in: برای حساب‌های سرویس، تأیید کنید که OP_SERVICE_ACCOUNT_TOKEN به سرویس Gateway می‌رسد و در passEnv فهرست شده است؛ برای یکپارچه‌سازی دسکتاپ، تأیید کنید برنامه در حال اجرا و باز است.
• کندی خواندن‌های نخست: timeoutMs را در ارائه‌دهنده افزایش دهید؛ شروع سرد op در میزبان‌های شلوغ ممکن است از مهلت‌های زمانی سخت‌گیرانه فراتر رود.