امنیت

# ابتدا دامنه: مدل امنیتی دستیار شخصی

راهنمای امنیتی OpenClaw یک استقرار دستیار شخصی را فرض می‌کند: یک مرز عملگر مورداعتماد، احتمالا با agentهای متعدد.

• وضعیت امنیتی پشتیبانی‌شده: یک مرز کاربر/اعتماد برای هر gateway (ترجیحا یک کاربر/میزبان/VPS سیستم‌عامل برای هر مرز).
• مرز امنیتی پشتیبانی‌نشده: یک gateway/agent مشترک که توسط کاربران متقابلا نامطمئن یا متخاصم استفاده می‌شود.
• اگر جداسازی کاربر متخاصم لازم است، بر اساس مرز اعتماد جدا کنید (gateway + اعتبارنامه‌های جداگانه، و در حالت ایده‌آل کاربران/میزبان‌های سیستم‌عامل جداگانه).
• اگر چند کاربر نامطمئن بتوانند به یک agent دارای ابزار پیام بدهند، آن‌ها را به‌عنوان کسانی در نظر بگیرید که همان اختیار ابزار تفویض‌شده برای آن agent را به اشتراک می‌گذارند.

این صفحه سخت‌سازی را درون همان مدل توضیح می‌دهد. ادعای جداسازی چندمستاجره خصمانه روی یک gateway مشترک ندارد.

# بررسی سریع: openclaw security audit

همچنین ببینید: راستی‌آزمایی رسمی (مدل‌های امنیتی)

این را به‌طور منظم اجرا کنید (به‌ویژه پس از تغییر config یا در معرض شبکه قرار دادن سطوح):

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix
openclaw security audit --json

security audit --fix عمدا محدود می‌ماند: policyهای گروهی باز رایج را به allowlist تبدیل می‌کند، logging.redactSensitive: "tools" را بازمی‌گرداند، مجوزهای state/config/include-file را سخت‌گیرانه‌تر می‌کند، و هنگام اجرا روی Windows به‌جای POSIX chmod از بازنشانی‌های ACL ویندوز استفاده می‌کند.

این دستور خطاهای رایج را نشانه‌گذاری می‌کند (در معرض بودن احراز هویت Gateway، در معرض بودن کنترل مرورگر، allowlistهای ارتقایافته، مجوزهای فایل‌سیستم، تاییدیه‌های exec سهل‌گیرانه، و در معرض بودن ابزار کانال باز).

OpenClaw هم یک محصول است و هم یک آزمایش: شما رفتار frontier-model را به سطوح پیام‌رسانی واقعی و ابزارهای واقعی وصل می‌کنید. هیچ راه‌اندازی «کاملا امنی» وجود ندارد. هدف این است که آگاهانه درباره این موارد تصمیم بگیرید:

• چه کسی می‌تواند با bot شما صحبت کند
• bot مجاز است کجا عمل کند
• bot به چه چیزهایی می‌تواند دست بزند

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

# استقرار و اعتماد میزبان

OpenClaw فرض می‌کند مرز میزبان و config مورداعتماد است:

• اگر کسی بتواند وضعیت/config میزبان Gateway را تغییر دهد (~/.openclaw، از جمله openclaw.json)، او را به‌عنوان عملگر مورداعتماد در نظر بگیرید.
• اجرای یک Gateway برای چند عملگر متقابلا نامطمئن/متخاصم راه‌اندازی توصیه‌شده‌ای نیست.
• برای تیم‌های با اعتماد ترکیبی، مرزهای اعتماد را با gatewayهای جداگانه جدا کنید (یا حداقل کاربران/میزبان‌های سیستم‌عامل جداگانه).
• پیش‌فرض توصیه‌شده: یک کاربر برای هر ماشین/میزبان (یا VPS)، یک gateway برای آن کاربر، و یک یا چند agent در آن gateway.
• درون یک نمونه Gateway، دسترسی عملگر احراز هویت‌شده یک نقش control-plane مورداعتماد است، نه یک نقش مستاجر به‌ازای هر کاربر.
• شناسه‌های session (sessionKey، شناسه‌های session، برچسب‌ها) انتخابگرهای مسیریابی هستند، نه tokenهای مجوزدهی.
• اگر چند نفر بتوانند به یک agent دارای ابزار پیام بدهند، هرکدام از آن‌ها می‌توانند همان مجموعه مجوز را هدایت کنند. جداسازی session/memory به‌ازای هر کاربر به حریم خصوصی کمک می‌کند، اما یک agent مشترک را به مجوزدهی میزبان به‌ازای هر کاربر تبدیل نمی‌کند.

# عملیات فایل امن

OpenClaw از @openclaw/fs-safe برای دسترسی فایل محدود به root، نوشتن‌های اتمیک، استخراج آرشیو، workspaceهای موقت، و helperهای فایل secret استفاده می‌کند. OpenClaw helper اختیاری POSIX Python در fs-safe را به‌صورت پیش‌فرض خاموش می‌کند؛ OPENCLAW_FS_SAFE_PYTHON_MODE=auto یا require را فقط زمانی تنظیم کنید که سخت‌سازی اضافه mutation مبتنی بر fd-relative را می‌خواهید و می‌توانید runtime پایتون را پشتیبانی کنید.

جزئیات: عملیات فایل امن.

# فضای کاری Slack مشترک: ریسک واقعی

اگر «همه در Slack می‌توانند به bot پیام بدهند»، ریسک اصلی اختیار ابزار تفویض‌شده است:

• هر فرستنده مجاز می‌تواند در چارچوب policy آن agent باعث فراخوانی ابزارها (exec، مرورگر، ابزارهای شبکه/فایل) شود؛
• تزریق prompt/content از یک فرستنده می‌تواند باعث اقداماتی شود که روی state، دستگاه‌ها، یا خروجی‌های مشترک اثر می‌گذارند؛
• اگر یک agent مشترک اعتبارنامه‌ها/فایل‌های حساس داشته باشد، هر فرستنده مجاز می‌تواند بالقوه از طریق استفاده از ابزار، خروج داده را هدایت کند.

برای گردش‌کارهای تیمی از agent/gatewayهای جداگانه با حداقل ابزارها استفاده کنید؛ agentهای داده شخصی را خصوصی نگه دارید.

# agent مشترک شرکت: الگوی قابل‌قبول

این زمانی قابل‌قبول است که همه استفاده‌کنندگان از آن agent در همان مرز اعتماد باشند (برای مثال یک تیم شرکت) و agent کاملا در محدوده کسب‌وکار باشد.

• آن را روی یک ماشین/VM/container اختصاصی اجرا کنید؛
• برای آن runtime از کاربر سیستم‌عامل اختصاصی + مرورگر/profile/accountهای اختصاصی استفاده کنید؛
• آن runtime را وارد حساب‌های شخصی Apple/Google یا profileهای شخصی password-manager/browser نکنید.

اگر هویت‌های شخصی و شرکتی را روی یک runtime ترکیب کنید، جداسازی را از بین می‌برید و ریسک در معرض قرار گرفتن داده‌های شخصی را افزایش می‌دهید.

# مفهوم اعتماد Gateway و Node

Gateway و Node را یک دامنه اعتماد عملگر واحد با نقش‌های متفاوت در نظر بگیرید:

• Gateway سطح control plane و policy است (gateway.auth، policy ابزار، مسیریابی).
• Node سطح اجرای راه‌دور جفت‌شده با آن Gateway است (فرمان‌ها، اقدام‌های دستگاه، قابلیت‌های محلی میزبان).
• فراخواننده‌ای که در Gateway احراز هویت شده است، در دامنه Gateway مورداعتماد است. پس از pairing، اقدام‌های Node اقدام‌های عملگر مورداعتماد روی آن Node هستند.
• سطوح دامنه عملگر و بررسی‌های زمان تایید در دامنه‌های عملگر خلاصه شده‌اند.
• clientهای backend مستقیم local loopback که با token/password مشترک gateway احراز هویت شده‌اند می‌توانند بدون ارائه هویت دستگاه کاربر، RPCهای داخلی control-plane انجام دهند. این bypass برای pairing راه‌دور یا مرورگر نیست: clientهای شبکه، clientهای Node، clientهای device-token، و هویت‌های صریح دستگاه همچنان از pairing و اجرای scope-upgrade عبور می‌کنند.
• sessionKey انتخاب مسیریابی/context است، نه احراز هویت به‌ازای هر کاربر.
• تاییدیه‌های Exec (allowlist + ask) guardrailهایی برای قصد عملگر هستند، نه جداسازی چندمستاجره خصمانه.
• پیش‌فرض محصول OpenClaw برای راه‌اندازی‌های تک‌عملگر مورداعتماد این است که host exec روی gateway/node بدون prompt تایید مجاز است (security="full"، ask="off" مگر اینکه آن را سخت‌گیرانه‌تر کنید). آن پیش‌فرض UX عمدی است، نه به‌خودی‌خود آسیب‌پذیری.
• تاییدیه‌های Exec به context دقیق درخواست و عملوندهای مستقیم فایل محلی به‌صورت best-effort متصل می‌شوند؛ آن‌ها هر مسیر loader مربوط به runtime/interpreter را از نظر معنایی مدل نمی‌کنند. برای مرزهای قوی از sandboxing و جداسازی میزبان استفاده کنید.

اگر به جداسازی کاربر خصمانه نیاز دارید، مرزهای اعتماد را بر اساس کاربر/میزبان سیستم‌عامل جدا کنید و gatewayهای جداگانه اجرا کنید.

# ماتریس مرز اعتماد

هنگام triage ریسک، از این به‌عنوان مدل سریع استفاده کنید:

مرز یا کنترل	معنایش چیست	برداشت نادرست رایج
gateway.auth (token/password/trusted-proxy/device auth)	فراخواننده‌ها را برای APIهای gateway احراز هویت می‌کند	«برای امن بودن به امضاهای به‌ازای هر پیام روی هر frame نیاز دارد»
sessionKey	کلید مسیریابی برای انتخاب context/session	«کلید session یک مرز احراز هویت کاربر است»
guardrailهای Prompt/content	ریسک سوءاستفاده از مدل را کاهش می‌دهند	«تزریق prompt به‌تنهایی bypass احراز هویت را ثابت می‌کند»
canvas.eval / browser evaluate	قابلیت عمدی عملگر هنگام فعال بودن	«هر primitive ارزیابی JS خودکار در این مدل اعتماد یک vuln است»
shell محلی TUI !	اجرای محلی صریحا فعال‌شده توسط عملگر	«فرمان راحتی shell محلی تزریق راه‌دور است»
pairing Node و فرمان‌های Node	اجرای راه‌دور در سطح عملگر روی دستگاه‌های جفت‌شده	«کنترل دستگاه راه‌دور باید به‌صورت پیش‌فرض دسترسی کاربر نامطمئن تلقی شود»
gateway.nodes.pairing.autoApproveCidrs	policy ثبت‌نام Node در شبکه مورداعتماد به‌صورت opt-in	«یک allowlist غیرفعال به‌صورت پیش‌فرض، آسیب‌پذیری pairing خودکار است»

# طبق طراحی، آسیب‌پذیری نیستند

Common findings that are out of scope

این الگوها زیاد گزارش می‌شوند و معمولا بدون اقدام بسته می‌شوند، مگر اینکه یک bypass واقعی مرز نشان داده شود:

• زنجیره‌های فقط prompt-injection بدون bypass در policy، auth، یا sandbox.
• ادعاهایی که اجرای چندمستاجره خصمانه روی یک میزبان یا config مشترک را فرض می‌کنند.
• ادعاهایی که دسترسی عادی مسیر خواندن عملگر (برای مثال sessions.list / sessions.preview / chat.history) را در یک راه‌اندازی shared-gateway به‌عنوان IDOR طبقه‌بندی می‌کنند.
• یافته‌های استقرار فقط localhost (برای مثال HSTS روی یک gateway فقط loopback).
• یافته‌های امضای Discord inbound webhook برای مسیرهای inbound که در این repo وجود ندارند.
• گزارش‌هایی که metadata مربوط به pairing Node را به‌عنوان لایه تایید دوم و مخفی به‌ازای هر فرمان برای system.run در نظر می‌گیرند، در حالی که مرز واقعی اجرا همچنان policy سراسری فرمان Node در gateway به‌علاوه تاییدیه‌های exec خود Node است.
• گزارش‌هایی که gateway.nodes.pairing.autoApproveCidrs پیکربندی‌شده را به‌خودی‌خود آسیب‌پذیری تلقی می‌کنند. این تنظیم به‌صورت پیش‌فرض غیرفعال است، به ورودی‌های صریح CIDR/IP نیاز دارد، فقط برای pairing بار اول role: node بدون scopeهای درخواستی اعمال می‌شود، و operator/browser/Control UI، WebChat، ارتقای role، ارتقای scope، تغییرات metadata، تغییرات public-key، یا مسیرهای header مربوط به loopback trusted-proxy همان میزبان را auto-approve نمی‌کند، مگر اینکه auth مربوط به loopback trusted-proxy صراحتا فعال شده باشد.
• یافته‌های «نبود مجوزدهی به‌ازای هر کاربر» که sessionKey را به‌عنوان token احراز هویت در نظر می‌گیرند.

# baseline سخت‌شده در ۶۰ ثانیه

ابتدا از این baseline استفاده کنید، سپس ابزارها را به‌صورت گزینشی برای هر agent مورداعتماد دوباره فعال کنید:

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "replace-with-long-random-token" },
  },
  session: {
    dmScope: "per-channel-peer",
  },
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"],
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
  channels: {
    whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } },
  },
}

این کار Gateway را فقط محلی نگه می‌دارد، DMها را جدا می‌کند، و ابزارهای control-plane/runtime را به‌صورت پیش‌فرض غیرفعال می‌کند.

# قانون سریع inbox مشترک

اگر بیش از یک نفر می‌تواند به bot شما DM بدهد:

• session.dmScope: "per-channel-peer" را تنظیم کنید (یا برای کانال‌های چندحسابی "per-account-channel-peer").
• dmPolicy: "pairing" یا allowlistهای سخت‌گیرانه را نگه دارید.
• هرگز DMهای مشترک را با دسترسی گسترده ابزار ترکیب نکنید.
• این کار inboxهای تعاملی/مشترک را سخت‌سازی می‌کند، اما برای جداسازی co-tenant خصمانه وقتی کاربران دسترسی نوشتن host/config را به اشتراک می‌گذارند طراحی نشده است.

# مدل دیدپذیری context

OpenClaw دو مفهوم را جدا می‌کند:

• مجوز trigger: چه کسی می‌تواند agent را trigger کند (dmPolicy، groupPolicy، allowlistها، گیت‌های mention).
• دیدپذیری context: چه context تکمیلی‌ای به ورودی مدل تزریق می‌شود (بدنه پاسخ، متن نقل‌شده، تاریخچه thread، metadata فورواردشده).

Allowlists مجوز trigger و فرمان را کنترل می‌کند. تنظیم contextVisibility کنترل می‌کند context تکمیلی (پاسخ‌های نقل‌شده، ریشه‌های thread، تاریخچه fetchشده) چگونه فیلتر شود:

• contextVisibility: "all" (پیش‌فرض) زمینهٔ تکمیلی را همان‌طور که دریافت شده نگه می‌دارد.
• contextVisibility: "allowlist" زمینهٔ تکمیلی را فیلتر می‌کند تا فقط فرستندگانی ارسال شوند که بررسی‌های فهرست مجاز فعال اجازه می‌دهند.
• contextVisibility: "allowlist_quote" مانند allowlist رفتار می‌کند، اما همچنان یک پاسخ نقل‌شدهٔ صریح را نگه می‌دارد.

contextVisibility را برای هر کانال یا هر اتاق/گفت‌وگو تنظیم کنید. برای جزئیات راه‌اندازی، گپ‌های گروهی را ببینید.

راهنمای تریاژ مشورتی:

• ادعاهایی که فقط نشان می‌دهند «مدل می‌تواند متن نقل‌شده یا تاریخی را از فرستندگانی که در فهرست مجاز نیستند ببیند»، یافته‌های سخت‌سازی هستند که با contextVisibility قابل رسیدگی‌اند، نه به‌خودی‌خود دور زدن مرزهای احراز هویت یا sandbox.
• برای داشتن اثر امنیتی، گزارش‌ها همچنان به یک دور زدن اثبات‌شدهٔ مرز اعتماد نیاز دارند (احراز هویت، سیاست، sandbox، تأیید، یا مرز مستند دیگر).

# آنچه audit بررسی می‌کند (در سطح کلی)

• دسترسی ورودی (سیاست‌های پیام مستقیم، سیاست‌های گروه، فهرست‌های مجاز): آیا افراد ناشناس می‌توانند bot را فعال کنند؟
• شعاع اثر ابزار (ابزارهای ارتقایافته + اتاق‌های باز): آیا تزریق prompt می‌تواند به عملیات shell/فایل/شبکه تبدیل شود؟
• انحراف تأیید exec (security=full، autoAllowSkills، فهرست‌های مجاز مفسر بدون strictInlineEval): آیا حفاظ‌های host-exec هنوز همان کاری را می‌کنند که فکر می‌کنید؟
  • security="full" یک هشدار وضعیت گسترده است، نه اثبات یک bug. این پیش‌فرض انتخاب‌شده برای راه‌اندازی‌های دستیار شخصیِ مورد اعتماد است؛ فقط زمانی آن را سخت‌گیرانه‌تر کنید که مدل تهدید شما به حفاظ‌های تأیید یا فهرست مجاز نیاز داشته باشد.
• در معرض بودن شبکه (bind/auth در Gateway، Tailscale Serve/Funnel، توکن‌های احراز هویت ضعیف/کوتاه).
• در معرض بودن کنترل مرورگر (nodeهای راه‌دور، پورت‌های relay، endpointهای CDP راه‌دور).
• بهداشت دیسک محلی (مجوزها، symlinkها، includeهای config، مسیرهای «پوشهٔ همگام‌سازی‌شده»).
• Plugins (plugins بدون فهرست مجاز صریح بارگذاری می‌شوند).
• انحراف/پیکربندی نادرست سیاست (تنظیمات sandbox docker پیکربندی شده‌اند اما حالت sandbox خاموش است؛ الگوهای gateway.nodes.denyCommands بی‌اثرند چون تطبیق فقط دقیقاً بر اساس نام فرمان انجام می‌شود (برای نمونه system.run) و متن shell را بررسی نمی‌کند؛ ورودی‌های خطرناک gateway.nodes.allowCommands؛ مقدار سراسری tools.profile="minimal" توسط پروفایل‌های per-agent بازنویسی شده است؛ ابزارهای متعلق به plugin تحت سیاست ابزار permissive قابل دسترسی‌اند).
• انحراف انتظار runtime (برای نمونه فرض اینکه exec ضمنی هنوز یعنی sandbox، درحالی‌که tools.exec.host اکنون به‌طور پیش‌فرض auto است، یا تنظیم صریح tools.exec.host="sandbox" در حالی که حالت sandbox خاموش است).
• بهداشت مدل (هشدار می‌دهد وقتی مدل‌های پیکربندی‌شده قدیمی به نظر می‌رسند؛ مانع سخت نیست).

اگر --deep را اجرا کنید، OpenClaw همچنین تلاش می‌کند یک probe زندهٔ Gateway را به‌صورت best-effort انجام دهد.

# نقشهٔ ذخیره‌سازی اعتبارنامه‌ها

هنگام audit کردن دسترسی یا تصمیم‌گیری دربارهٔ موارد پشتیبان‌گیری از این استفاده کنید:

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• توکن bot در Telegram: config/env یا channels.telegram.tokenFile (فقط فایل عادی؛ symlinkها رد می‌شوند)
• توکن bot در Discord: config/env یا SecretRef (providerهای env/file/exec)
• توکن‌های Slack: config/env (channels.slack.*)
• فهرست‌های مجاز pairing:
  • ~/.openclaw/credentials/<channel>-allowFrom.json (حساب پیش‌فرض)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (حساب‌های غیرپیش‌فرض)
• پروفایل‌های احراز هویت مدل: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• وضعیت runtime در Codex: ~/.openclaw/agents/<agentId>/agent/codex-home/
• payload اسرار مبتنی بر فایل (اختیاری): ~/.openclaw/secrets.json
• واردسازی OAuth قدیمی: ~/.openclaw/credentials/oauth.json

# چک‌لیست audit امنیتی

وقتی audit یافته‌ها را چاپ می‌کند، با این ترتیب اولویت برخورد کنید:

1. هر چیز «باز» + ابزارهای فعال: ابتدا پیام‌های مستقیم/گروه‌ها را محدود کنید (pairing/فهرست‌های مجاز)، سپس سیاست ابزار/sandboxing را سخت‌گیرانه‌تر کنید.
2. در معرض بودن شبکهٔ عمومی (bind در LAN، Funnel، نبود احراز هویت): فوراً اصلاح کنید.
3. در معرض بودن راه‌دور کنترل مرورگر: آن را مانند دسترسی اپراتور در نظر بگیرید (فقط tailnet، nodeها را عامدانه pair کنید، از در معرض بودن عمومی پرهیز کنید).
4. مجوزها: مطمئن شوید state/config/credentials/auth برای group/world قابل خواندن نیستند.
5. Plugins: فقط چیزی را بارگذاری کنید که صریحاً به آن اعتماد دارید.
6. انتخاب مدل: برای هر bot دارای ابزار، مدل‌های مدرن و سخت‌سازی‌شده در برابر دستورالعمل را ترجیح دهید.

# واژه‌نامهٔ audit امنیتی

هر یافتهٔ audit با یک checkId ساخت‌یافته کلیدگذاری می‌شود (برای نمونه gateway.bind_no_auth یا tools.exec.security_full_configured). کلاس‌های رایج شدت بحرانی:

• fs.* - مجوزهای filesystem روی state، config، credentials، پروفایل‌های auth.
• gateway.* - حالت bind، auth، Tailscale، رابط کاربری کنترل، تنظیمات trusted-proxy.
• hooks.*، browser.*، sandbox.*، tools.exec.* - سخت‌سازی برای هر سطح.
• plugins.*، skills.* - زنجیرهٔ تأمین plugin/skill و یافته‌های scan.
• security.exposure.* - بررسی‌های فراگیر، جایی که سیاست دسترسی با شعاع اثر ابزار تلاقی می‌کند.

catalog کامل را با سطح شدت، کلیدهای fix و پشتیبانی auto-fix در بررسی‌های audit امنیتی ببینید.

# رابط کاربری کنترل روی HTTP

رابط کاربری کنترل برای تولید هویت دستگاه به یک زمینهٔ امن (HTTPS یا localhost) نیاز دارد. gateway.controlUi.allowInsecureAuth یک toggle سازگاری محلی است:

• روی localhost، اجازه می‌دهد وقتی صفحه از طریق HTTP ناامن بارگذاری شده، احراز هویت رابط کاربری کنترل بدون هویت دستگاه انجام شود.
• بررسی‌های pairing را دور نمی‌زند.
• الزامات هویت دستگاه راه‌دور (غیر-localhost) را آسان‌تر نمی‌کند.

HTTPS (Tailscale Serve) را ترجیح دهید یا UI را روی 127.0.0.1 باز کنید.

فقط برای سناریوهای اضطراری، gateway.controlUi.dangerouslyDisableDeviceAuth بررسی‌های هویت دستگاه را کاملاً غیرفعال می‌کند. این یک کاهش امنیتی شدید است؛ مگر وقتی فعالانه در حال debugging هستید و می‌توانید سریع برگردانید، آن را خاموش نگه دارید.

جدا از آن flagهای خطرناک، موفقیت gateway.auth.mode: "trusted-proxy" می‌تواند sessionهای رابط کاربری کنترل اپراتور را بدون هویت دستگاه بپذیرد. این یک رفتار عمدی auth-mode است، نه میان‌بر allowInsecureAuth، و همچنان به sessionهای رابط کاربری کنترل با نقش node گسترش پیدا نمی‌کند.

openclaw security audit وقتی این تنظیم فعال باشد هشدار می‌دهد.

# خلاصهٔ flagهای ناامن یا خطرناک

وقتی switchهای debug شناخته‌شدهٔ ناامن/خطرناک فعال باشند، openclaw security audit مقدار config.insecure_or_dangerous_flags را مطرح می‌کند. در production این‌ها را unset نگه دارید.

# پیکربندی reverse proxy

اگر Gateway را پشت یک reverse proxy اجرا می‌کنید (nginx، Caddy، Traefik و غیره)، gateway.trustedProxies را برای مدیریت درست IP کلاینت forwarded پیکربندی کنید.

وقتی Gateway هدرهای proxy را از آدرسی تشخیص دهد که در trustedProxies نیست، اتصالات را به‌عنوان کلاینت‌های محلی در نظر نمی‌گیرد. اگر auth در gateway غیرفعال باشد، آن اتصالات رد می‌شوند. این از دور زدن احراز هویت جلوگیری می‌کند؛ جایی که اتصالات proxied در غیر این صورت انگار از localhost آمده‌اند و اعتماد خودکار دریافت می‌کنند.

gateway.trustedProxies همچنین به gateway.auth.mode: "trusted-proxy" خوراک می‌دهد، اما آن حالت auth سخت‌گیرانه‌تر است:

• احراز هویت trusted-proxy به‌طور پیش‌فرض روی proxyهای با منبع loopback به‌صورت fail closed عمل می‌کند
• reverse proxyهای loopback روی همان host می‌توانند از gateway.trustedProxies برای تشخیص کلاینت محلی و مدیریت IP forwarded استفاده کنند
• reverse proxyهای loopback روی همان host فقط وقتی می‌توانند gateway.auth.mode: "trusted-proxy" را برآورده کنند که gateway.auth.trustedProxy.allowLoopback = true باشد؛ در غیر این صورت از احراز هویت token/password استفاده کنید

gateway:
  trustedProxies:
    - "10.0.0.1" # reverse proxy IP
  # Optional. Default false.
  # Only enable if your proxy cannot provide X-Forwarded-For.
  allowRealIpFallback: false
  auth:
    mode: password
    password: ${OPENCLAW_GATEWAY_PASSWORD}

وقتی trustedProxies پیکربندی شده باشد، Gateway از X-Forwarded-For برای تعیین IP کلاینت استفاده می‌کند. X-Real-IP به‌طور پیش‌فرض نادیده گرفته می‌شود مگر اینکه gateway.allowRealIpFallback: true صریحاً تنظیم شده باشد.

هدرهای trusted proxy باعث نمی‌شوند pairing دستگاه Node به‌طور خودکار مورد اعتماد شود. gateway.nodes.pairing.autoApproveCidrs یک سیاست اپراتوری جداگانه است که به‌طور پیش‌فرض غیرفعال است. حتی وقتی فعال باشد، مسیرهای هدر trusted-proxy با منبع loopback از auto-approval Node کنار گذاشته می‌شوند، چون فراخوان‌های محلی می‌توانند آن هدرها را جعل کنند، از جمله وقتی auth trusted-proxy روی loopback صریحاً فعال شده باشد.

رفتار خوب reverse proxy (بازنویسی هدرهای forwarding ورودی):

proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;

رفتار بد reverse proxy (افزودن/حفظ هدرهای forwarding نامطمئن):

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

# نکات HSTS و origin

• Gateway در OpenClaw ابتدا محلی/local loopback است. اگر TLS را در یک reverse proxy پایان می‌دهید، HSTS را همان‌جا روی دامنهٔ HTTPS روبه‌روی proxy تنظیم کنید.
• اگر خود gateway پایان‌دهندهٔ HTTPS است، می‌توانید gateway.http.securityHeaders.strictTransportSecurity را تنظیم کنید تا header HSTS از پاسخ‌های OpenClaw صادر شود.
• راهنمایی تفصیلی deployment در احراز هویت Trusted Proxy آمده است.
• برای deploymentهای رابط کاربری کنترل غیر-loopback، gateway.controlUi.allowedOrigins به‌طور پیش‌فرض لازم است.
• gateway.controlUi.allowedOrigins: ["*"] یک سیاست صریح allow-all برای browser-origin است، نه یک پیش‌فرض hardening شده. خارج از آزمایش محلیِ کاملاً کنترل‌شده از آن پرهیز کنید.
• شکست‌های auth مربوط به browser-origin روی loopback همچنان rate-limit می‌شوند، حتی وقتی معافیت عمومی loopback فعال باشد، اما کلید lockout به‌جای یک bucket مشترک localhost برای هر مقدار نرمال‌شدهٔ Origin scoped می‌شود.
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true حالت fallback برای origin مبتنی بر Host-header را فعال می‌کند؛ آن را به‌عنوان یک سیاست خطرناک انتخاب‌شده توسط اپراتور در نظر بگیرید.
• DNS rebinding و رفتار proxy-host header را نگرانی‌های سخت‌سازی deployment تلقی کنید؛ trustedProxies را محدود نگه دارید و از قرار دادن مستقیم gateway در معرض اینترنت عمومی خودداری کنید.

# لاگ‌های session محلی روی دیسک قرار دارند

OpenClaw رونوشت‌های نشست را روی دیسک در مسیر ~/.openclaw/agents/<agentId>/sessions/*.jsonl ذخیره می‌کند. این کار برای تداوم نشست و (به‌صورت اختیاری) نمایه‌سازی حافظه نشست لازم است، اما همچنین یعنی هر پردازش/کاربری که به فایل‌سیستم دسترسی داشته باشد می‌تواند آن لاگ‌ها را بخواند. دسترسی به دیسک را مرز اعتماد در نظر بگیرید و مجوزهای ~/.openclaw را محدود کنید (بخش ممیزی پایین را ببینید). اگر به جداسازی قوی‌تر بین عامل‌ها نیاز دارید، آن‌ها را زیر کاربران جداگانه سیستم‌عامل یا روی میزبان‌های جداگانه اجرا کنید.

# اجرای Node (system.run)

اگر یک Node مربوط به macOS جفت شده باشد، Gateway می‌تواند system.run را روی آن Node فراخوانی کند. این کار اجرای کد از راه دور روی Mac است:

• به جفت‌سازی Node نیاز دارد (تأیید + توکن).
• جفت‌سازی Node در Gateway یک سطح تأیید به‌ازای هر دستور نیست. این کار هویت/اعتماد Node و صدور توکن را برقرار می‌کند.
• Gateway یک سیاست کلی و سراسری برای فرمان‌های Node را از طریق gateway.nodes.allowCommands / denyCommands اعمال می‌کند.
• روی Mac از طریق تنظیمات → تأییدهای اجرا کنترل می‌شود (امنیت + پرسش + فهرست مجاز).
• سیاست system.run به‌ازای هر Node همان فایل تأییدهای اجرای خود Node است (exec.approvals.node.*) که می‌تواند سخت‌گیرانه‌تر یا آسان‌گیرانه‌تر از سیاست سراسری شناسه فرمان در Gateway باشد.
• Nodeای که با security="full" و ask="off" اجرا می‌شود، از مدل پیش‌فرض اپراتور قابل‌اعتماد پیروی می‌کند. مگر اینکه استقرار شما صراحتاً موضع تأیید یا فهرست مجاز سخت‌گیرانه‌تری لازم داشته باشد، این را رفتار مورد انتظار در نظر بگیرید.
• حالت تأیید، زمینه دقیق درخواست و، در صورت امکان، یک عملوند مشخص اسکریپت/فایل محلی را مقید می‌کند. اگر OpenClaw نتواند دقیقاً یک فایل محلی مستقیم را برای یک دستور مفسر/زمان اجرا شناسایی کند، اجرای مبتنی بر تأیید رد می‌شود، نه اینکه پوشش معنایی کامل وعده داده شود.
• برای host=node، اجراهای مبتنی بر تأیید همچنین یک systemRunPlan آماده‌شده و کانونی را ذخیره می‌کنند؛ ارسال‌های تأییدشده بعدی از همان برنامه ذخیره‌شده دوباره استفاده می‌کنند، و اعتبارسنجی Gateway ویرایش‌های فراخواننده روی command/cwd/session context پس از ایجاد درخواست تأیید را رد می‌کند.
• اگر اجرای از راه دور نمی‌خواهید، امنیت را روی deny تنظیم کنید و جفت‌سازی Node را برای آن Mac حذف کنید.

این تمایز برای تریاژ مهم است:

• اگر یک Node جفت‌شده که دوباره متصل می‌شود فهرست فرمان متفاوتی اعلام کند، این به‌تنهایی آسیب‌پذیری نیست، در صورتی که سیاست سراسری Gateway و تأییدهای اجرای محلی Node همچنان مرز واقعی اجرا را اعمال کنند.
• گزارش‌هایی که فراداده جفت‌سازی Node را به‌عنوان لایه دوم و پنهان تأیید به‌ازای هر دستور در نظر می‌گیرند، معمولاً سردرگمی سیاست/UX هستند، نه دور زدن مرز امنیتی.

# Skills پویا (ناظر / Nodeهای راه دور)

OpenClaw می‌تواند فهرست Skills را در میانه نشست تازه‌سازی کند:

• ناظر Skills: تغییرات در SKILL.md می‌تواند snapshot مربوط به Skills را در نوبت بعدی عامل به‌روزرسانی کند.
• Nodeهای راه دور: اتصال یک Node مربوط به macOS می‌تواند Skills مختص macOS را واجد شرایط کند (بر اساس کاوش bin).

پوشه‌های Skill را کد قابل‌اعتماد در نظر بگیرید و محدود کنید چه کسی می‌تواند آن‌ها را تغییر دهد.

# مدل تهدید

دستیار هوش مصنوعی شما می‌تواند:

• فرمان‌های shell دلخواه را اجرا کند
• فایل‌ها را بخواند/بنویسد
• به سرویس‌های شبکه دسترسی داشته باشد
• به هر کسی پیام بفرستد (اگر به آن دسترسی WhatsApp بدهید)

افرادی که به شما پیام می‌دهند می‌توانند:

• تلاش کنند هوش مصنوعی شما را فریب دهند تا کارهای بد انجام دهد
• برای دسترسی به داده‌های شما مهندسی اجتماعی کنند
• جزئیات زیرساخت را کاوش کنند

# مفهوم اصلی: کنترل دسترسی پیش از هوشمندی

بیشتر شکست‌ها در اینجا اکسپلویت‌های پیچیده نیستند؛ بلکه این‌اند که «کسی به ربات پیام داد و ربات همان کاری را انجام داد که خواسته بودند.»

موضع OpenClaw:

• ابتدا هویت: تصمیم بگیرید چه کسی می‌تواند با ربات صحبت کند (جفت‌سازی DM / فهرست‌های مجاز / «باز» صریح).
• سپس دامنه: تصمیم بگیرید ربات کجا مجاز به عمل کردن است (فهرست‌های مجاز گروه + دروازه‌گذاری mention، ابزارها، sandboxing، مجوزهای دستگاه).
• در پایان مدل: فرض کنید مدل می‌تواند دست‌کاری شود؛ طراحی را طوری انجام دهید که دست‌کاری شعاع اثر محدودی داشته باشد.

# مدل مجوزدهی فرمان

دستورهای Slash و دستورالعمل‌ها فقط برای فرستنده‌های مجاز پذیرفته می‌شوند. مجوزدهی از فهرست‌های مجاز/جفت‌سازی کانال به‌همراه commands.useAccessGroups مشتق می‌شود (پیکربندی و دستورهای Slash را ببینید). اگر فهرست مجاز یک کانال خالی باشد یا شامل "*" باشد، دستورها عملاً برای آن کانال باز هستند.

/exec یک امکان ساده‌سازی فقط در همان نشست برای اپراتورهای مجاز است. این دستور config را نمی‌نویسد یا نشست‌های دیگر را تغییر نمی‌دهد.

# ریسک ابزارهای control plane

دو ابزار داخلی می‌توانند تغییرات پایدار در control plane ایجاد کنند:

• gateway می‌تواند config را با config.schema.lookup / config.get بررسی کند، و می‌تواند با config.apply، config.patch و update.run تغییرات پایدار ایجاد کند.
• cron می‌تواند کارهای زمان‌بندی‌شده‌ای بسازد که پس از پایان گفت‌وگو/وظیفه اصلی همچنان اجرا شوند.

ابزار زمان اجرای مالک‌محور gateway همچنان از بازنویسی tools.exec.ask یا tools.exec.security خودداری می‌کند؛ aliasهای قدیمی tools.bash.* پیش از نوشتن، به همان مسیرهای exec محافظت‌شده نرمال‌سازی می‌شوند. ویرایش‌های gateway config.apply و gateway config.patch که توسط عامل انجام می‌شوند به‌صورت پیش‌فرض بسته‌در-خطا هستند: فقط مجموعه باریکی از مسیرهای prompt، model و mention-gating قابل تنظیم توسط عامل هستند. بنابراین درخت‌های config حساس جدید محافظت می‌شوند، مگر اینکه عمداً به فهرست مجاز اضافه شده باشند.

برای هر عامل/سطحی که محتوای نامطمئن را پردازش می‌کند، این‌ها را به‌صورت پیش‌فرض رد کنید:

{
  tools: {
    deny: ["gateway", "cron", "sessions_spawn", "sessions_send"],
  },
}

commands.restart=false فقط کنش‌های راه‌اندازی مجدد را مسدود می‌کند. این گزینه کنش‌های config/update مربوط به gateway را غیرفعال نمی‌کند.

# Plugins

Plugins به‌صورت درون‌پردازشی با Gateway اجرا می‌شوند. آن‌ها را کد قابل‌اعتماد در نظر بگیرید:

• فقط Plugins را از منابعی نصب کنید که به آن‌ها اعتماد دارید.
• فهرست‌های مجاز صریح plugins.allow را ترجیح دهید.
• پیش از فعال‌سازی، config مربوط به Plugin را بازبینی کنید.
• پس از تغییرات Plugin، Gateway را دوباره راه‌اندازی کنید.
• اگر Plugins را نصب یا به‌روزرسانی می‌کنید (openclaw plugins install <package>، openclaw plugins update <id>)، با آن مانند اجرای کد نامطمئن رفتار کنید:
  • مسیر نصب، دایرکتوری به‌ازای هر Plugin زیر ریشه نصب فعال Plugin است.
  • OpenClaw پیش از install/update یک اسکن داخلی کد خطرناک اجرا می‌کند. یافته‌های critical به‌صورت پیش‌فرض مسدود می‌شوند.
  • نصب‌های Plugin از npm و git همگرایی وابستگی package-manager را فقط هنگام جریان صریح install/update اجرا می‌کنند. مسیرهای محلی و archiveها بسته‌های مستقل Plugin محسوب می‌شوند؛ OpenClaw آن‌ها را بدون اجرای npm install کپی/ارجاع می‌کند.
  • نسخه‌های سنجاق‌شده و دقیق (@scope/[email protected]) را ترجیح دهید و پیش از فعال‌سازی، کد unpack‌شده روی دیسک را بررسی کنید.
  • --dangerously-force-unsafe-install فقط برای موارد اضطراری false positive اسکن داخلی در جریان‌های install/update مربوط به Plugin است. این گزینه مسدودسازی‌های سیاست hook مربوط به Plugin before_install را دور نمی‌زند و خطاهای اسکن را نیز دور نمی‌زند.
  • نصب وابستگی‌های Skill مبتنی بر Gateway از همان تفکیک خطرناک/مشکوک پیروی می‌کند: یافته‌های داخلی critical مسدود می‌شوند مگر اینکه فراخواننده صراحتاً dangerouslyForceUnsafeInstall را تنظیم کند، در حالی که یافته‌های مشکوک همچنان فقط هشدار می‌دهند. openclaw skills install جریان جداگانه دانلود/نصب Skill از ClawHub باقی می‌ماند.

جزئیات: Plugins

# مدل دسترسی DM: جفت‌سازی، فهرست مجاز، باز، غیرفعال

همه کانال‌های فعلی دارای قابلیت DM از یک سیاست DM (dmPolicy یا *.dm.policy) پشتیبانی می‌کنند که DMهای ورودی را پیش از پردازش پیام دروازه‌گذاری می‌کند:

• pairing (پیش‌فرض): فرستنده‌های ناشناس یک کد کوتاه جفت‌سازی دریافت می‌کنند و ربات پیام آن‌ها را تا زمان تأیید نادیده می‌گیرد. کدها پس از ۱ ساعت منقضی می‌شوند؛ DMهای تکراری تا زمانی که درخواست جدیدی ایجاد نشود، کد را دوباره ارسال نمی‌کنند. درخواست‌های معلق به‌صورت پیش‌فرض به ۳ مورد به‌ازای هر کانال محدود می‌شوند.
• allowlist: فرستنده‌های ناشناس مسدود می‌شوند (بدون دست‌دادن جفت‌سازی).
• open: اجازه می‌دهد هر کسی DM بفرستد (عمومی). لازم است فهرست مجاز کانال شامل "*" باشد (opt-in صریح).
• disabled: DMهای ورودی را کاملاً نادیده بگیر.

تأیید از طریق CLI:

openclaw pairing list <channel>
openclaw pairing approve <channel> <code>

جزئیات + فایل‌ها روی دیسک: جفت‌سازی

# جداسازی نشست DM (حالت چندکاربره)

به‌صورت پیش‌فرض، OpenClaw همه DMها را به نشست اصلی هدایت می‌کند تا دستیار شما در دستگاه‌ها و کانال‌ها تداوم داشته باشد. اگر چند نفر می‌توانند به ربات DM بدهند (DMهای باز یا یک فهرست مجاز چندنفره)، جداسازی نشست‌های DM را در نظر بگیرید:

{
  session: { dmScope: "per-channel-peer" },
}

این کار از نشت زمینه بین کاربران جلوگیری می‌کند، در حالی که گفت‌وگوهای گروهی را جدا نگه می‌دارد.

این یک مرز زمینه پیام‌رسانی است، نه یک مرز مدیر میزبان. اگر کاربران با یکدیگر متخاصم‌اند و میزبان/config یکسان Gateway را به اشتراک می‌گذارند، به‌جای آن برای هر مرز اعتماد Gatewayهای جداگانه اجرا کنید.

# حالت امن DM (توصیه‌شده)

قطعه بالا را حالت امن DM در نظر بگیرید:

• پیش‌فرض: session.dmScope: "main" (همه DMها برای تداوم یک نشست مشترک دارند).
• پیش‌فرض onboarding محلی CLI: وقتی تنظیم نشده باشد session.dmScope: "per-channel-peer" را می‌نویسد (مقادیر صریح موجود را حفظ می‌کند).
• حالت امن DM: session.dmScope: "per-channel-peer" (هر جفت کانال+فرستنده یک زمینه DM جداشده دریافت می‌کند).
• جداسازی peer بین‌کانالی: session.dmScope: "per-peer" (هر فرستنده در همه کانال‌های هم‌نوع یک نشست دریافت می‌کند).

اگر چند حساب روی یک کانال اجرا می‌کنید، به‌جای آن از per-account-channel-peer استفاده کنید. اگر همان شخص از چند کانال با شما تماس می‌گیرد، از session.identityLinks برای ادغام آن نشست‌های DM در یک هویت کانونی استفاده کنید. مدیریت نشست و پیکربندی را ببینید.

# فهرست‌های مجاز برای DMها و گروه‌ها

OpenClaw دو لایه جداگانه «چه کسی می‌تواند مرا فعال کند؟» دارد:

• فهرست مجاز DM (allowFrom / channels.discord.allowFrom / channels.slack.allowFrom؛ قدیمی: channels.discord.dm.allowFrom، channels.slack.dm.allowFrom): چه کسی مجاز است در پیام‌های مستقیم با ربات صحبت کند.
  • وقتی dmPolicy="pairing" باشد، تأییدها در store فهرست مجاز جفت‌سازی در دامنه حساب زیر ~/.openclaw/credentials/ نوشته می‌شوند (<channel>-allowFrom.json برای حساب پیش‌فرض، <channel>-<accountId>-allowFrom.json برای حساب‌های غیرپیش‌فرض)، و با فهرست‌های مجاز config ادغام می‌شوند.
• فهرست مجاز گروه (مختص کانال): ربات اساساً از کدام گروه‌ها/کانال‌ها/guildها پیام می‌پذیرد.
  • الگوهای رایج:
    • channels.whatsapp.groups، channels.telegram.groups، channels.imessage.groups: پیش‌فرض‌های به‌ازای هر گروه مثل requireMention؛ وقتی تنظیم شود، همچنین به‌عنوان فهرست مجاز گروه عمل می‌کند (برای حفظ رفتار اجازه به همه، "*" را درج کنید).
    • groupPolicy="allowlist" + groupAllowFrom: محدود می‌کند چه کسی می‌تواند ربات را داخل یک نشست گروهی فعال کند (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams).
    • channels.discord.guilds / channels.slack.channels: فهرست‌های مجاز به‌ازای هر سطح + پیش‌فرض‌های mention.
  • بررسی‌های گروه به این ترتیب اجرا می‌شوند: ابتدا groupPolicy/فهرست‌های مجاز گروه، سپس فعال‌سازی mention/reply.
  • پاسخ دادن به پیام ربات (mention ضمنی) فهرست‌های مجاز فرستنده مانند groupAllowFrom را دور نمی‌زند.
  • نکته امنیتی: dmPolicy="open" و groupPolicy="open" را تنظیمات آخرین راه‌حل در نظر بگیرید. این‌ها باید به‌ندرت استفاده شوند؛ مگر اینکه به همه اعضای اتاق کاملاً اعتماد دارید، جفت‌سازی + فهرست‌های مجاز را ترجیح دهید.

جزئیات: پیکربندی و گروه‌ها

# تزریق prompt (چیست، چرا مهم است)

تزریق prompt زمانی است که مهاجم پیامی می‌سازد که مدل را به انجام کاری ناامن دست‌کاری می‌کند («دستورالعمل‌هایت را نادیده بگیر»، «فایل‌سیستم خودت را dump کن»، «این لینک را دنبال کن و فرمان‌ها را اجرا کن»، و غیره).

حتی با system promptهای قوی، تزریق prompt حل نشده است. گاردریل‌های system prompt فقط راهنمایی نرم هستند؛ اعمال سخت‌گیرانه از سیاست ابزار، تأییدهای exec، sandboxing و فهرست‌های مجاز کانال می‌آید (و اپراتورها طبق طراحی می‌توانند این‌ها را غیرفعال کنند). آنچه در عمل کمک می‌کند:

• پیام‌های مستقیم ورودی را محدود نگه دارید (جفت‌سازی/فهرست‌های مجاز).
• در گروه‌ها دروازه‌گذاری با mention را ترجیح دهید؛ از بات‌های «همیشه روشن» در اتاق‌های عمومی پرهیز کنید.
• لینک‌ها، پیوست‌ها، و دستورالعمل‌های چسبانده‌شده را به‌صورت پیش‌فرض خصمانه در نظر بگیرید.
• اجرای ابزارهای حساس را در یک sandbox انجام دهید؛ رازها را بیرون از فایل‌سیستمی نگه دارید که عامل به آن دسترسی دارد.
• نکته: sandboxing اختیاری است. اگر حالت sandbox خاموش باشد، host=auto ضمنی به میزبان Gateway حل می‌شود. host=sandbox صریح همچنان بسته و امن شکست می‌خورد، چون runtime مربوط به sandbox در دسترس نیست. اگر می‌خواهید این رفتار در پیکربندی صریح باشد، host=gateway را تنظیم کنید.
• ابزارهای پرخطر (exec, browser, web_fetch, web_search) را به عامل‌های مورد اعتماد یا فهرست‌های مجاز صریح محدود کنید.
• اگر مفسرها (python, node, ruby, perl, php, lua, osascript) را در فهرست مجاز قرار می‌دهید، tools.exec.strictInlineEval را فعال کنید تا فرم‌های eval درون‌خطی همچنان به تأیید صریح نیاز داشته باشند.
• تحلیل تأیید shell همچنین فرم‌های گسترش پارامتر POSIX ($VAR, $?, $$, $1, $@, ${…}) را داخل heredocهای بدون نقل‌قول رد می‌کند، بنابراین بدنه heredoc مجاز نمی‌تواند گسترش shell را به‌عنوان متن ساده از بررسی فهرست مجاز عبور دهد. برای انتخاب معنای بدنه تحت‌اللفظی، پایان‌دهنده heredoc را نقل‌قول‌گذاری کنید (برای مثال <<'EOF')؛ heredocهای بدون نقل‌قول که متغیرها را گسترش می‌دادند رد می‌شوند.
• انتخاب مدل مهم است: مدل‌های قدیمی‌تر/کوچک‌تر/میراثی در برابر تزریق پرامپت و سوءاستفاده از ابزارها به‌طور چشمگیری کم‌مقاومت‌تر هستند. برای عامل‌های دارای ابزار، از قوی‌ترین مدل نسل جدیدِ سخت‌سازی‌شده با دستورالعمل که در دسترس است استفاده کنید.

نشانه‌های خطر که باید نامطمئن تلقی شوند:

• «این فایل/URL را بخوان و دقیقاً همان کاری را انجام بده که می‌گوید.»
• «پرامپت سیستمی یا قواعد ایمنی خود را نادیده بگیر.»
• «دستورالعمل‌های پنهان یا خروجی‌های ابزار خود را آشکار کن.»
• «محتوای کامل ~/.openclaw یا لاگ‌های خودت را جای‌گذاری کن.»

# پاک‌سازی توکن‌های ویژه محتوای خارجی

OpenClaw پیش از آنکه محتوای خارجی و فراداده‌های بسته‌بندی‌شده به مدل برسند، literalهای رایج توکن ویژه قالب گفتگوی LLMهای خودمیزبان را از آن‌ها حذف می‌کند. خانواده نشانگرهای پوشش‌داده‌شده شامل توکن‌های نقش/نوبت Qwen/ChatML، Llama، Gemma، Mistral، Phi، و GPT-OSS هستند.

چرا:

• بک‌اندهای سازگار با OpenAI که مدل‌های خودمیزبان را در جلو قرار می‌دهند گاهی به‌جای ماسک‌کردن، توکن‌های ویژه‌ای را که در متن کاربر ظاهر می‌شوند حفظ می‌کنند. مهاجمی که بتواند در محتوای خارجی ورودی بنویسد (یک صفحه واکشی‌شده، بدنه ایمیل، خروجی ابزار محتوای فایل) در غیر این صورت می‌تواند یک مرز نقش ساختگی assistant یا system تزریق کند و از حفاظ‌های محتوای بسته‌بندی‌شده خارج شود.
• پاک‌سازی در لایه بسته‌بندی محتوای خارجی انجام می‌شود، بنابراین به‌جای وابستگی به هر ارائه‌دهنده، به‌صورت یکنواخت روی ابزارهای fetch/read و محتوای کانال ورودی اعمال می‌شود.
• پاسخ‌های خروجی مدل از قبل یک پاک‌ساز جداگانه دارند که <tool_call>، <function_calls>، <system-reminder>، <previous_response>، و scaffolding runtime داخلی مشابه نشت‌کرده را از پاسخ‌های قابل مشاهده برای کاربر در مرز نهایی تحویل کانال حذف می‌کند. پاک‌ساز محتوای خارجی همتای ورودی آن است.

این جایگزین سایر سخت‌سازی‌های این صفحه نیست - dmPolicy، فهرست‌های مجاز، تأییدهای exec، sandboxing، و contextVisibility همچنان کار اصلی را انجام می‌دهند. این کار یک دورزدن مشخص در لایه tokenizer را علیه پشته‌های خودمیزبان می‌بندد که متن کاربر را با توکن‌های ویژه دست‌نخورده ارسال می‌کنند.

# پرچم‌های دورزدن ناامن محتوای خارجی

OpenClaw شامل پرچم‌های دورزدن صریحی است که بسته‌بندی ایمنی محتوای خارجی را غیرفعال می‌کنند:

• hooks.mappings[].allowUnsafeExternalContent
• hooks.gmail.allowUnsafeExternalContent
• فیلد payload مربوط به Cron یعنی allowUnsafeExternalContent

راهنما:

• در production آن‌ها را تنظیم‌نشده/false نگه دارید.
• فقط به‌صورت موقت برای اشکال‌زدایی با دامنه بسیار محدود فعال کنید.
• اگر فعال شد، آن عامل را ایزوله کنید (sandbox + ابزارهای حداقلی + فضای نام session اختصاصی).

یادداشت ریسک hooks:

• payloadهای hook محتوای نامطمئن هستند، حتی وقتی تحویل از سیستم‌هایی می‌آید که کنترلشان می‌کنید (محتوای ایمیل/اسناد/وب می‌تواند تزریق پرامپت حمل کند).
• رده‌های مدل ضعیف این ریسک را افزایش می‌دهند. برای خودکارسازی مبتنی بر hook، رده‌های مدل مدرن و قوی را ترجیح دهید و سیاست ابزار را سخت‌گیرانه نگه دارید (tools.profile: "messaging" یا سخت‌گیرانه‌تر)، به‌علاوه sandboxing در صورت امکان.

# تزریق پرامپت به پیام‌های مستقیم عمومی نیاز ندارد

حتی اگر فقط شما بتوانید به بات پیام دهید، تزریق پرامپت همچنان می‌تواند از طریق هر محتوای نامطمئنی که بات می‌خواند رخ دهد (نتایج web search/fetch، صفحات browser، ایمیل‌ها، اسناد، پیوست‌ها، لاگ/کد چسبانده‌شده). به بیان دیگر: فرستنده تنها سطح تهدید نیست؛ خود محتوا می‌تواند دستورالعمل‌های خصمانه حمل کند.

وقتی ابزارها فعال هستند، ریسک معمول خروج context یا تحریک فراخوانی ابزارها است. شعاع آسیب را با این کارها کاهش دهید:

• استفاده از یک عامل خواننده فقط‌خواندنی یا بدون ابزار برای خلاصه‌کردن محتوای نامطمئن، سپس عبور دادن خلاصه به عامل اصلی خود.
• خاموش نگه داشتن web_search / web_fetch / browser برای عامل‌های دارای ابزار مگر در صورت نیاز.
• برای ورودی‌های URL مربوط به OpenResponses (input_file / input_image)، gateway.http.endpoints.responses.files.urlAllowlist و gateway.http.endpoints.responses.images.urlAllowlist را سخت‌گیرانه تنظیم کنید و maxUrlParts را پایین نگه دارید. فهرست‌های مجاز خالی به‌عنوان تنظیم‌نشده تلقی می‌شوند؛ اگر می‌خواهید واکشی URL را کاملاً غیرفعال کنید از files.allowUrl: false / images.allowUrl: false استفاده کنید.
• برای ورودی‌های فایل OpenResponses، متن decodeشده input_file همچنان به‌عنوان محتوای خارجی نامطمئن تزریق می‌شود. صرفاً چون Gateway آن را محلی decode کرده است، به قابل اعتماد بودن متن فایل تکیه نکنید. بلوک تزریق‌شده همچنان نشانگرهای مرزی صریح <<&lt;EXTERNAL_UNTRUSTED_CONTENT ...&gt;>> به‌علاوه فراداده Source: External را حمل می‌کند، هرچند این مسیر بنر طولانی‌تر SECURITY NOTICE: را حذف می‌کند.
• همان بسته‌بندی مبتنی بر نشانگر وقتی اعمال می‌شود که media-understanding پیش از افزودن متن به پرامپت media، متن را از اسناد پیوست‌شده استخراج می‌کند.
• فعال‌کردن sandboxing و فهرست‌های مجاز سخت‌گیرانه ابزار برای هر عاملی که با ورودی نامطمئن تماس دارد.
• نگه داشتن رازها بیرون از پرامپت‌ها؛ آن‌ها را در عوض از طریق env/config روی میزبان Gateway عبور دهید.

# بک‌اندهای LLM خودمیزبان

بک‌اندهای خودمیزبان سازگار با OpenAI مانند vLLM، SGLang، TGI، LM Studio، یا پشته‌های tokenizer سفارشی Hugging Face می‌توانند در نحوه مدیریت توکن‌های ویژه قالب گفتگو با ارائه‌دهندگان میزبانی‌شده متفاوت باشند. اگر یک بک‌اند رشته‌های literal مانند <|im_start|>، <|start_header_id|>، یا <start_of_turn> را به‌عنوان توکن‌های ساختاری قالب گفتگو داخل محتوای کاربر tokenize کند، متن نامطمئن می‌تواند در لایه tokenizer تلاش کند مرزهای نقش را جعل کند.

OpenClaw پیش از ارسال محتوای خارجی بسته‌بندی‌شده به مدل، literalهای رایج توکن ویژه خانواده‌های مدل را از آن حذف می‌کند. بسته‌بندی محتوای خارجی را فعال نگه دارید، و وقتی در دسترس است تنظیمات بک‌اندی را ترجیح دهید که توکن‌های ویژه را در محتوای ارائه‌شده توسط کاربر جدا یا escape می‌کنند. ارائه‌دهندگان میزبانی‌شده مانند OpenAI و Anthropic از قبل پاک‌سازی سمت درخواست خودشان را اعمال می‌کنند.

# قدرت مدل (یادداشت امنیتی)

مقاومت در برابر تزریق پرامپت در رده‌های مدل یکسان نیست. مدل‌های کوچک‌تر/ارزان‌تر عموماً بیشتر مستعد سوءاستفاده از ابزار و ربایش دستورالعمل هستند، به‌ویژه تحت پرامپت‌های خصمانه.

توصیه‌ها:

• برای هر باتی که می‌تواند ابزارها را اجرا کند یا با فایل‌ها/شبکه‌ها تماس داشته باشد، از مدل نسل جدید و بهترین رده استفاده کنید.
• برای عامل‌های دارای ابزار یا inboxهای نامطمئن، از رده‌های قدیمی‌تر/ضعیف‌تر/کوچک‌تر استفاده نکنید؛ ریسک تزریق پرامپت بیش از حد بالاست.
• اگر مجبورید از مدل کوچک‌تر استفاده کنید، شعاع آسیب را کاهش دهید (ابزارهای فقط‌خواندنی، sandboxing قوی، دسترسی حداقلی به فایل‌سیستم، فهرست‌های مجاز سخت‌گیرانه).
• هنگام اجرای مدل‌های کوچک، برای همه sessionها sandboxing را فعال کنید و web_search/web_fetch/browser را غیرفعال کنید مگر اینکه ورودی‌ها کاملاً کنترل‌شده باشند.
• برای دستیارهای شخصی فقط‌چت با ورودی مورد اعتماد و بدون ابزار، مدل‌های کوچک‌تر معمولاً مناسب هستند.

# Reasoning و خروجی پرجزئیات در گروه‌ها

/reasoning، /verbose، و /trace می‌توانند reasoning داخلی، خروجی ابزار، یا diagnostics مربوط به plugin را افشا کنند که برای یک کانال عمومی در نظر گرفته نشده بود. در تنظیمات گروهی، آن‌ها را فقط اشکال‌زدایی تلقی کنید و خاموش نگه دارید مگر اینکه صریحاً به آن‌ها نیاز داشته باشید.

راهنما:

• در اتاق‌های عمومی، /reasoning، /verbose، و /trace را غیرفعال نگه دارید.
• اگر آن‌ها را فعال می‌کنید، فقط در پیام‌های مستقیم مورد اعتماد یا اتاق‌های کاملاً کنترل‌شده این کار را انجام دهید.
• به یاد داشته باشید: خروجی verbose و trace می‌تواند شامل آرگومان‌های ابزار، URLها، diagnostics مربوط به plugin، و داده‌هایی باشد که مدل دیده است.

# نمونه‌های سخت‌سازی پیکربندی

# مجوزهای فایل

config + state را روی میزبان Gateway خصوصی نگه دارید:

• ~/.openclaw/openclaw.json: 600 (فقط خواندن/نوشتن کاربر)
• ~/.openclaw: 700 (فقط کاربر)

openclaw doctor می‌تواند هشدار دهد و پیشنهاد کند این مجوزها سخت‌گیرانه‌تر شوند.

# قرارگیری در معرض شبکه (bind، پورت، firewall)

Gateway، WebSocket + HTTP را روی یک پورت واحد multiplex می‌کند:

• پیش‌فرض: 18789
• Config/flags/env: gateway.port, --port, OPENCLAW_GATEWAY_PORT

این سطح HTTP شامل Control UI و میزبان canvas است:

• Control UI (دارایی‌های SPA) (مسیر پایه پیش‌فرض /)
• میزبان canvas: /__openclaw__/canvas/ و /__openclaw__/a2ui/ (HTML/JS دلخواه؛ به‌عنوان محتوای نامطمئن تلقی شود)

اگر محتوای canvas را در یک مرورگر عادی بارگذاری می‌کنید، آن را مانند هر صفحه وب نامطمئن دیگری در نظر بگیرید:

• میزبان canvas را در معرض شبکه‌ها/کاربران نامطمئن قرار ندهید.
• محتوای canvas را با سطح‌های وب دارای امتیاز در یک origin مشترک قرار ندهید مگر اینکه پیامدها را کاملاً درک کرده باشید.

حالت bind کنترل می‌کند Gateway کجا گوش می‌دهد:

• gateway.bind: "loopback" (پیش‌فرض): فقط کلاینت‌های محلی می‌توانند وصل شوند.
• bindهای غیر loopback ("lan", "tailnet", "custom") سطح حمله را گسترش می‌دهند. فقط با احراز هویت Gateway (token/password مشترک یا یک proxy مورد اعتماد با پیکربندی درست) و firewall واقعی از آن‌ها استفاده کنید.

قواعد سرانگشتی:

• Tailscale Serve را به bindهای LAN ترجیح دهید (Serve، Gateway را روی loopback نگه می‌دارد، و Tailscale دسترسی را مدیریت می‌کند).
• اگر مجبورید به LAN bind کنید، پورت را با firewall به فهرست مجاز محدودی از IPهای مبدأ محدود کنید؛ آن را به‌طور گسترده port-forward نکنید.
• هرگز Gateway را بدون احراز هویت روی 0.0.0.0 در معرض قرار ندهید.

# انتشار پورت Docker با UFW

اگر OpenClaw را با Docker روی VPS اجرا می‌کنید، به یاد داشته باشید که پورت‌های container منتشرشده (-p HOST:CONTAINER یا Compose ports:) از طریق زنجیره‌های forwarding مربوط به Docker مسیر‌دهی می‌شوند، نه فقط قواعد INPUT میزبان.

برای همسو نگه داشتن ترافیک Docker با سیاست firewall خود، قواعد را در DOCKER-USER اعمال کنید (این زنجیره پیش از قواعد accept خود Docker ارزیابی می‌شود). در بسیاری از توزیع‌های مدرن، iptables/ip6tables از frontend iptables-nft استفاده می‌کنند و همچنان این قواعد را روی بک‌اند nftables اعمال می‌کنند.

نمونه حداقلی فهرست مجاز (IPv4):

# /etc/ufw/after.rules (append as its own *filter section)
*filter
:DOCKER-USER - [0:0]
-A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN
-A DOCKER-USER -s 127.0.0.0/8 -j RETURN
-A DOCKER-USER -s 10.0.0.0/8 -j RETURN
-A DOCKER-USER -s 172.16.0.0/12 -j RETURN
-A DOCKER-USER -s 192.168.0.0/16 -j RETURN
-A DOCKER-USER -s 100.64.0.0/10 -j RETURN
-A DOCKER-USER -p tcp --dport 80 -j RETURN
-A DOCKER-USER -p tcp --dport 443 -j RETURN
-A DOCKER-USER -m conntrack --ctstate NEW -j DROP
-A DOCKER-USER -j RETURN
COMMIT

IPv6 جدول‌های جداگانه دارد. اگر Docker IPv6 فعال است، سیاست متناظر را در /etc/ufw/after6.rules اضافه کنید.

از hardcode کردن نام interfaceهایی مانند eth0 در قطعه‌های مستندات پرهیز کنید. نام interfaceها در imageهای VPS متفاوت است (ens3, enp*, و غیره) و عدم تطابق می‌تواند ناخواسته باعث شود قاعده deny شما اعمال نشود.

اعتبارسنجی سریع پس از reload:

ufw reload
iptables -S DOCKER-USER
ip6tables -S DOCKER-USER
nmap -sT -p 1-65535 <public-ip> --open

پورت‌های خارجی مورد انتظار باید فقط همان‌هایی باشند که عمداً در معرض قرار می‌دهید (برای بیشتر راه‌اندازی‌ها: SSH + پورت‌های reverse proxy شما).

# کشف mDNS/Bonjour

وقتی plugin همراه bonjour فعال باشد، Gateway حضور خود را از طریق mDNS (_openclaw-gw._tcp روی پورت 5353) برای کشف دستگاه محلی broadcast می‌کند. در حالت کامل، این شامل رکوردهای TXT است که ممکن است جزئیات عملیاتی را افشا کنند:

• cliPath: مسیر کامل سیستم فایل به فایل اجرایی CLI (نام کاربری و محل نصب را آشکار می‌کند)
• sshPort: در دسترس بودن SSH روی میزبان را اعلام می‌کند
• displayName، lanHost: اطلاعات نام میزبان

ملاحظهٔ امنیت عملیاتی: پخش کردن جزئیات زیرساخت، شناسایی را برای هر کسی روی شبکهٔ محلی آسان‌تر می‌کند. حتی اطلاعات «بی‌ضرر» مثل مسیرهای سیستم فایل و در دسترس بودن SSH به مهاجمان کمک می‌کند محیط شما را نقشه‌برداری کنند.

توصیه‌ها:

1. Bonjour را غیرفعال نگه دارید مگر اینکه کشف در LAN لازم باشد. Bonjour روی میزبان‌های macOS به‌صورت خودکار شروع می‌شود و در جاهای دیگر opt-in است؛ URLهای مستقیم Gateway، Tailnet، SSH یا DNS-SD گسترده از چندپخشی محلی جلوگیری می‌کنند.

2. حالت کمینه (پیش‌فرض وقتی Bonjour فعال است، توصیه‌شده برای Gatewayهای در معرض دسترسی): فیلدهای حساس را از پخش‌های mDNS حذف کنید:

   {
     discovery: {
       mdns: { mode: "minimal" },
     },
   }
   

3. اگر می‌خواهید Plugin فعال بماند اما کشف دستگاه محلی متوقف شود، حالت mDNS را غیرفعال کنید:

   {
     discovery: {
       mdns: { mode: "off" },
     },
   }
   

4. حالت کامل (opt-in): cliPath + sshPort را در رکوردهای TXT وارد کنید:

   {
     discovery: {
       mdns: { mode: "full" },
     },
   }
   

5. متغیر محیطی (جایگزین): برای غیرفعال کردن mDNS بدون تغییر پیکربندی، OPENCLAW_DISABLE_BONJOUR=1 را تنظیم کنید.

وقتی Bonjour در حالت کمینه فعال است، Gateway برای کشف دستگاه به‌اندازهٔ کافی اطلاعات پخش می‌کند (role، gatewayPort، transport) اما cliPath و sshPort را حذف می‌کند. برنامه‌هایی که به اطلاعات مسیر CLI نیاز دارند می‌توانند به‌جای آن، از طریق اتصال احراز هویت‌شدهٔ وب‌سوکت آن را دریافت کنند.

# قفل کردن وب‌سوکت Gateway (احراز هویت محلی)

احراز هویت Gateway به‌صورت پیش‌فرض الزامی است. اگر هیچ مسیر احراز هویت Gateway معتبری پیکربندی نشده باشد، Gateway اتصال‌های وب‌سوکت را رد می‌کند (بسته در حالت خطا).

فرایند راه‌اندازی به‌صورت پیش‌فرض یک توکن تولید می‌کند (حتی برای loopback)، بنابراین کلاینت‌های محلی باید احراز هویت کنند.

یک توکن تنظیم کنید تا همهٔ کلاینت‌های WS مجبور به احراز هویت باشند:

{
  gateway: {
    auth: { mode: "token", token: "your-token" },
  },
}

Doctor می‌تواند یکی برای شما تولید کند: openclaw doctor --generate-gateway-token.

اختیاری: هنگام استفاده از wss://، TLS راه‌دور را با gateway.remote.tlsFingerprint pin کنید. متن سادهٔ ws:// به‌صورت پیش‌فرض فقط برای loopback است. برای مسیرهای شبکهٔ خصوصی مورد اعتماد، OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 را روی فرایند کلاینت به‌عنوان break-glass تنظیم کنید. این عمدا فقط محیط فرایند است، نه کلید پیکربندی openclaw.json. جفت‌سازی موبایل و مسیرهای دستی یا اسکن‌شدهٔ Gateway در Android سخت‌گیرانه‌تر هستند: cleartext برای loopback پذیرفته می‌شود، اما private-LAN، link-local، .local و نام‌های میزبان بدون نقطه باید از TLS استفاده کنند مگر اینکه صریحا مسیر cleartext شبکهٔ خصوصی مورد اعتماد را انتخاب کنید.

جفت‌سازی دستگاه محلی:

• جفت‌سازی دستگاه برای اتصال‌های مستقیم local loopback به‌صورت خودکار تأیید می‌شود تا کلاینت‌های همان میزبان روان کار کنند.
• OpenClaw همچنین یک مسیر self-connect محدود backend/container-local برای جریان‌های کمکی shared-secret مورد اعتماد دارد.
• اتصال‌های Tailnet و LAN، از جمله bindهای tailnet همان میزبان، برای جفت‌سازی راه‌دور تلقی می‌شوند و همچنان به تأیید نیاز دارند.
• شواهد forwarded-header روی یک درخواست loopback، محلی بودن loopback را رد صلاحیت می‌کند. تأیید خودکار metadata-upgrade دامنهٔ محدودی دارد. برای هر دو قاعده، جفت‌سازی Gateway را ببینید.

حالت‌های احراز هویت:

• gateway.auth.mode: "token": توکن bearer مشترک (توصیه‌شده برای بیشتر راه‌اندازی‌ها).
• gateway.auth.mode: "password": احراز هویت با گذرواژه (ترجیحا از طریق env تنظیم شود: OPENCLAW_GATEWAY_PASSWORD).
• gateway.auth.mode: "trusted-proxy": اعتماد به یک reverse proxy آگاه از هویت برای احراز هویت کاربران و ارسال هویت از طریق headerها (ببینید احراز هویت Trusted Proxy).

چک‌لیست چرخش (توکن/گذرواژه):

1. یک secret جدید تولید/تنظیم کنید (gateway.auth.token یا OPENCLAW_GATEWAY_PASSWORD).
2. Gateway را restart کنید (یا اگر برنامهٔ macOS ناظر Gateway است، برنامه را restart کنید).
3. هر کلاینت راه‌دور را به‌روزرسانی کنید (gateway.remote.token / .password روی ماشین‌هایی که Gateway را فراخوانی می‌کنند).
4. بررسی کنید که دیگر نتوانید با اعتبارنامه‌های قدیمی وصل شوید.

# headerهای هویت Tailscale Serve

وقتی gateway.auth.allowTailscale برابر true است (پیش‌فرض برای Serve)، OpenClaw headerهای هویت Tailscale Serve (tailscale-user-login) را برای احراز هویت Control UI/وب‌سوکت می‌پذیرد. OpenClaw هویت را با resolve کردن آدرس x-forwarded-for از طریق daemon محلی Tailscale (tailscale whois) و تطبیق آن با header تأیید می‌کند. این فقط برای درخواست‌هایی فعال می‌شود که به loopback برسند و x-forwarded-for، x-forwarded-proto و x-forwarded-host را همان‌طور که Tailscale تزریق کرده است شامل شوند. برای این مسیر بررسی هویت async، تلاش‌های ناموفق برای همان {scope, ip} قبل از ثبت شکست توسط محدودکننده، سریالی می‌شوند. بنابراین retryهای بد هم‌زمان از یک کلاینت Serve می‌توانند تلاش دوم را فورا قفل کنند، به‌جای اینکه مثل دو عدم‌تطابق ساده با هم race کنند. نقاط پایانی API HTTP (برای مثال /v1/*، /tools/invoke، و /api/channels/*) از احراز هویت identity-header Tailscale استفاده نمی‌کنند. آن‌ها همچنان از حالت احراز هویت HTTP پیکربندی‌شدهٔ gateway پیروی می‌کنند.

یادداشت مرزی مهم:

• احراز هویت bearer HTTP در Gateway عملا دسترسی اپراتوری همه‌یا‌هیچ است.
• اعتبارنامه‌هایی را که می‌توانند /v1/chat/completions، /v1/responses یا /api/channels/* را فراخوانی کنند، برای آن gateway به‌عنوان secretهای اپراتوری با دسترسی کامل در نظر بگیرید.
• روی سطح HTTP سازگار با OpenAI، احراز هویت bearer با shared-secret، scopeهای کامل اپراتور پیش‌فرض (operator.admin، operator.approvals، operator.pairing، operator.read، operator.talk.secrets، operator.write) و معناشناسی owner را برای نوبت‌های agent بازمی‌گرداند؛ مقادیر محدودتر x-openclaw-scopes آن مسیر shared-secret را کاهش نمی‌دهند.
• معناشناسی scope در هر درخواست روی HTTP فقط وقتی اعمال می‌شود که درخواست از یک حالت دارای هویت مانند احراز هویت trusted proxy یا gateway.auth.mode="none" روی یک ingress خصوصی بیاید.
• در آن حالت‌های دارای هویت، حذف x-openclaw-scopes به مجموعه scope پیش‌فرض معمول اپراتور fallback می‌کند؛ وقتی مجموعه scope محدودتری می‌خواهید، header را صریحا ارسال کنید.
• /tools/invoke از همان قاعدهٔ shared-secret پیروی می‌کند: احراز هویت bearer با token/password آنجا هم دسترسی کامل اپراتور تلقی می‌شود، در حالی که حالت‌های دارای هویت همچنان scopeهای اعلام‌شده را رعایت می‌کنند.
• این اعتبارنامه‌ها را با فراخوان‌های غیرقابل اعتماد به اشتراک نگذارید؛ برای هر مرز اعتماد، Gatewayهای جداگانه را ترجیح دهید.

فرض اعتماد: احراز هویت Serve بدون توکن فرض می‌کند میزبان gateway مورد اعتماد است. این را به‌عنوان محافظت در برابر فرایندهای خصمانهٔ همان میزبان در نظر نگیرید. اگر ممکن است کد محلی غیرقابل اعتماد روی میزبان gateway اجرا شود، gateway.auth.allowTailscale را غیرفعال کنید و احراز هویت shared-secret صریح را با gateway.auth.mode: "token" یا "password" الزامی کنید.

قاعدهٔ امنیتی: این headerها را از reverse proxy خودتان forward نکنید. اگر TLS را terminate می‌کنید یا جلوی gateway proxy می‌گذارید، gateway.auth.allowTailscale را غیرفعال کنید و به‌جای آن از احراز هویت shared-secret (gateway.auth.mode: "token" یا "password") یا احراز هویت Trusted Proxy استفاده کنید.

proxyهای مورد اعتماد:

• اگر TLS را جلوی Gateway terminate می‌کنید، gateway.trustedProxies را روی IPهای proxy خود تنظیم کنید.
• OpenClaw به x-forwarded-for (یا x-real-ip) از آن IPها اعتماد می‌کند تا IP کلاینت را برای بررسی‌های جفت‌سازی محلی و احراز هویت HTTP/بررسی‌های محلی تعیین کند.
• مطمئن شوید proxy شما x-forwarded-for را بازنویسی می‌کند و دسترسی مستقیم به پورت Gateway را مسدود می‌کند.

Tailscale و نمای کلی وب را ببینید.

# کنترل مرورگر از طریق میزبان node (توصیه‌شده)

اگر Gateway شما راه‌دور است اما مرورگر روی ماشین دیگری اجرا می‌شود، یک میزبان node روی ماشین مرورگر اجرا کنید و اجازه دهید Gateway کنش‌های مرورگر را proxy کند (ببینید ابزار مرورگر). جفت‌سازی node را مثل دسترسی مدیر در نظر بگیرید.

الگوی توصیه‌شده:

• Gateway و میزبان node را روی همان tailnet (Tailscale) نگه دارید.
• node را عامدانه pair کنید؛ اگر به مسیریابی proxy مرورگر نیاز ندارید، آن را غیرفعال کنید.

پرهیز کنید از:

• در معرض قرار دادن پورت‌های relay/control روی LAN یا اینترنت عمومی.
• Tailscale Funnel برای نقاط پایانی کنترل مرورگر (در معرض قرارگیری عمومی).

# secretهای روی دیسک

فرض کنید هر چیزی زیر ~/.openclaw/ (یا $OPENCLAW_STATE_DIR/) ممکن است شامل secret یا دادهٔ خصوصی باشد:

• openclaw.json: پیکربندی ممکن است شامل توکن‌ها (gateway، gateway راه‌دور)، تنظیمات provider و allowlistها باشد.
• credentials/**: اعتبارنامه‌های channel (مثال: اعتبارنامه‌های WhatsApp)، allowlistهای جفت‌سازی، importهای OAuth قدیمی.
• agents/<agentId>/agent/auth-profiles.json: کلیدهای API، پروفایل‌های توکن، توکن‌های OAuth و keyRef/tokenRef اختیاری.
• agents/<agentId>/agent/codex-home/**: حساب app-server مخصوص هر agent در Codex، پیکربندی، skills، plugins، وضعیت thread بومی، و diagnostics.
• secrets.json (اختیاری): payload secret مبتنی بر فایل که توسط providerهای SecretRef نوع file استفاده می‌شود (secrets.providers).
• agents/<agentId>/agent/auth.json: فایل سازگاری قدیمی. entryهای static api_key هنگام کشف scrub می‌شوند.
• agents/<agentId>/sessions/**: transcriptهای session (*.jsonl) + metadata مسیریابی (sessions.json) که می‌توانند پیام‌های خصوصی و خروجی ابزار را شامل شوند.
• بسته‌های Plugin همراه: Pluginهای نصب‌شده (به‌همراه node_modules/ آن‌ها).
• sandboxes/**: workspaceهای sandbox ابزار؛ می‌تواند کپی‌هایی از فایل‌هایی را که داخل sandbox می‌خوانید/می‌نویسید انباشته کند.

نکات سخت‌سازی:

• مجوزها را محدود نگه دارید (700 روی دایرکتوری‌ها، 600 روی فایل‌ها).
• روی میزبان gateway از رمزگذاری کامل دیسک استفاده کنید.
• اگر میزبان مشترک است، یک حساب کاربری OS اختصاصی برای Gateway را ترجیح دهید.

# فایل‌های .env در Workspace

OpenClaw فایل‌های .env محلی workspace را برای agentها و ابزارها load می‌کند، اما هرگز اجازه نمی‌دهد آن فایل‌ها کنترل‌های runtime gateway را بی‌صدا override کنند.

• هر کلیدی که با OPENCLAW_* شروع شود از فایل‌های .env غیرقابل اعتماد workspace مسدود می‌شود.
• تنظیمات endpoint مربوط به channel برای Matrix، Mattermost، IRC و Synology Chat نیز از overrideهای .env در workspace مسدود می‌شوند، بنابراین workspaceهای cloneشده نمی‌توانند ترافیک connector همراه را از طریق پیکربندی endpoint محلی redirect کنند. کلیدهای env مربوط به endpoint (مانند MATRIX_HOMESERVER، MATTERMOST_URL، IRC_HOST، SYNOLOGY_CHAT_INCOMING_URL) باید از محیط فرایند gateway یا env.shellEnv بیایند، نه از .env loadشده از workspace.
• block به‌صورت بسته در حالت خطا است: متغیر runtime-control جدیدی که در یک نسخهٔ آینده اضافه شود نمی‌تواند از یک .env commitشده یا تأمین‌شده توسط مهاجم به ارث برسد؛ کلید نادیده گرفته می‌شود و gateway مقدار خودش را نگه می‌دارد.
• متغیرهای محیطی مورد اعتماد فرایند/OS (shell خود gateway، واحد launchd/systemd، bundle برنامه) همچنان اعمال می‌شوند - این فقط load شدن فایل .env را محدود می‌کند.

چرا: فایل‌های .env در workspace اغلب کنار کد agent زندگی می‌کنند، تصادفا commit می‌شوند، یا توسط ابزارها نوشته می‌شوند. مسدود کردن کل پیشوند OPENCLAW_* یعنی افزودن یک flag جدید OPENCLAW_* در آینده هرگز نمی‌تواند به ارث‌بری بی‌صدای وضعیت workspace پس‌رفت کند.

# logها و transcriptها (redaction و retention)

logها و transcriptها حتی وقتی کنترل‌های دسترسی درست باشند می‌توانند اطلاعات حساس را لو بدهند:

• logهای Gateway ممکن است شامل خلاصه‌های ابزار، خطاها و URLها باشند.
• transcriptهای session می‌توانند شامل secretهای pasteشده، محتوای فایل، خروجی فرمان و linkها باشند.

توصیه‌ها:

• redaction مربوط به log و transcript را روشن نگه دارید (logging.redactSensitive: "tools"؛ پیش‌فرض).
• الگوهای سفارشی را برای محیط خود از طریق logging.redactPatterns اضافه کنید (توکن‌ها، نام‌های میزبان، URLهای داخلی).
• هنگام اشتراک‌گذاری diagnostics، به‌جای logهای خام، openclaw status --all را ترجیح دهید (قابل paste، secretها redacted شده‌اند).
• اگر به نگهداری طولانی نیاز ندارید، transcriptهای session و فایل‌های log قدیمی را prune کنید.

جزئیات: Logging

# DMها: جفت‌سازی به‌صورت پیش‌فرض

{
  channels: { whatsapp: { dmPolicy: "pairing" } },
}

# گروه‌ها: همه‌جا mention را الزامی کنید

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "groupChat": { "mentionPatterns": ["@openclaw", "@mybot"] }
      }
    ]
  }
}

در چت‌های گروهی، فقط زمانی پاسخ دهید که به‌صراحت منشن شده باشید.

# شماره‌های جداگانه (WhatsApp، Signal، Telegram)

برای کانال‌های مبتنی بر شماره تلفن، در نظر بگیرید AI خود را روی شماره تلفنی جدا از شماره شخصی‌تان اجرا کنید:

• شماره شخصی: مکالمه‌های شما خصوصی می‌مانند
• شماره بات: AI این موارد را با مرزبندی مناسب مدیریت می‌کند

# حالت فقط خواندنی (از طریق سندباکس و ابزارها)

می‌توانید با ترکیب موارد زیر یک پروفایل فقط خواندنی بسازید:

• agents.defaults.sandbox.workspaceAccess: "ro" (یا "none" برای نداشتن دسترسی به فضای کاری)
• فهرست‌های مجاز/غیرمجاز ابزار که write، edit، apply_patch، exec، process و غیره را مسدود می‌کنند.

گزینه‌های سخت‌سازی بیشتر:

• tools.exec.applyPatch.workspaceOnly: true (پیش‌فرض): تضمین می‌کند apply_patch حتی وقتی سندباکس خاموش است نتواند بیرون از دایرکتوری فضای کاری بنویسد/حذف کند. فقط زمانی آن را روی false بگذارید که عمداً می‌خواهید apply_patch فایل‌های بیرون از فضای کاری را لمس کند.
• tools.fs.workspaceOnly: true (اختیاری): مسیرهای read/write/edit/apply_patch و مسیرهای بارگذاری خودکار تصویر پرامپت بومی را به دایرکتوری فضای کاری محدود می‌کند (مفید است اگر امروز مسیرهای مطلق را مجاز کرده‌اید و یک محافظ واحد می‌خواهید).
• ریشه‌های فایل‌سیستم را محدود نگه دارید: برای فضاهای کاری agent/فضاهای کاری سندباکس، از ریشه‌های گسترده مثل دایرکتوری خانه خود پرهیز کنید. ریشه‌های گسترده می‌توانند فایل‌های محلی حساس (برای مثال state/config زیر ~/.openclaw) را در معرض ابزارهای فایل‌سیستم قرار دهند.

# خط مبنای امن (کپی/پیست)

یک پیکربندی «پیش‌فرض امن» که Gateway را خصوصی نگه می‌دارد، pairing در DM را الزامی می‌کند، و از بات‌های گروهی همیشه‌فعال پرهیز می‌کند:

{
  gateway: {
    mode: "local",
    bind: "loopback",
    port: 18789,
    auth: { mode: "token", token: "your-long-random-token" },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

اگر اجرای ابزار «به‌طور پیش‌فرض امن‌تر» هم می‌خواهید، برای هر agent غیرمالک یک سندباکس + منع ابزارهای خطرناک اضافه کنید (نمونه زیر در بخش «پروفایل‌های دسترسی برای هر agent» آمده است).

خط مبنای داخلی برای نوبت‌های agent مبتنی بر چت: فرستنده‌های غیرمالک نمی‌توانند از ابزارهای cron یا gateway استفاده کنند.

# سندباکس‌سازی (توصیه‌شده)

سند اختصاصی: سندباکس‌سازی

دو رویکرد مکمل:

• اجرای کامل Gateway در Docker (مرز کانتینر): Docker
• سندباکس ابزار (agents.defaults.sandbox، gateway میزبان + ابزارهای ایزوله‌شده در سندباکس؛ Docker بک‌اند پیش‌فرض است): سندباکس‌سازی

همچنین دسترسی فضای کاری agent داخل سندباکس را در نظر بگیرید:

• agents.defaults.sandbox.workspaceAccess: "none" (پیش‌فرض) فضای کاری agent را خارج از دسترس نگه می‌دارد؛ ابزارها در برابر یک فضای کاری سندباکس زیر ~/.openclaw/sandboxes اجرا می‌شوند
• agents.defaults.sandbox.workspaceAccess: "ro" فضای کاری agent را به‌صورت فقط خواندنی در /agent mount می‌کند (write/edit/apply_patch را غیرفعال می‌کند)
• agents.defaults.sandbox.workspaceAccess: "rw" فضای کاری agent را به‌صورت خواندن/نوشتن در /workspace mount می‌کند
• sandbox.docker.binds اضافی در برابر مسیرهای منبع نرمال‌سازی‌شده و canonicalized اعتبارسنجی می‌شوند. ترفندهای symlink والد و aliasهای canonical خانه همچنان fail closed می‌شوند اگر به ریشه‌های مسدودشده مثل /etc، /var/run، یا دایرکتوری‌های credential زیر خانه OS resolve شوند.

# محافظ واگذاری sub-agent

اگر ابزارهای session را مجاز می‌کنید، اجراهای sub-agent واگذارشده را به‌عنوان تصمیم مرزی دیگری در نظر بگیرید:

• sessions_spawn را منع کنید مگر اینکه agent واقعاً به واگذاری نیاز داشته باشد.
• agents.defaults.subagents.allowAgents و هر override مربوط به agents.list[].subagents.allowAgents در هر agent را به agentهای هدف شناخته‌شده و امن محدود نگه دارید.
• برای هر workflow که باید سندباکس‌شده بماند، sessions_spawn را با sandbox: "require" فراخوانی کنید (پیش‌فرض inherit است).
• sandbox: "require" وقتی runtime فرزند هدف سندباکس‌شده نباشد سریع fail می‌کند.

# خطرهای کنترل مرورگر

فعال‌کردن کنترل مرورگر به مدل توانایی هدایت یک مرورگر واقعی را می‌دهد. اگر آن پروفایل مرورگر از قبل sessionهای واردشده داشته باشد، مدل می‌تواند به آن حساب‌ها و داده‌ها دسترسی پیدا کند. پروفایل‌های مرورگر را وضعیت حساس تلقی کنید:

• یک پروفایل اختصاصی برای agent را ترجیح دهید (پروفایل پیش‌فرض openclaw).
• از اشاره دادن agent به پروفایل روزمره شخصی خود پرهیز کنید.
• کنترل مرورگر میزبان را برای agentهای سندباکس‌شده غیرفعال نگه دارید مگر اینکه به آن‌ها اعتماد دارید.
• API مستقل کنترل مرورگر loopback فقط احراز هویت shared-secret را می‌پذیرد (احراز هویت bearer با token Gateway یا password Gateway). این API هدرهای هویت trusted-proxy یا Tailscale Serve را مصرف نمی‌کند.
• دانلودهای مرورگر را ورودی غیرقابل اعتماد تلقی کنید؛ یک دایرکتوری دانلود ایزوله را ترجیح دهید.
• در صورت امکان، sync مرورگر/password managerها را در پروفایل agent غیرفعال کنید (دامنه اثر را کاهش می‌دهد).
• برای gatewayهای راه‌دور، فرض کنید «کنترل مرورگر» معادل «دسترسی operator» به هر چیزی است که آن پروفایل می‌تواند به آن برسد.
• Gateway و میزبان‌های node را فقط در tailnet نگه دارید؛ از در معرض قرار دادن پورت‌های کنترل مرورگر در LAN یا اینترنت عمومی پرهیز کنید.
• وقتی به مسیریابی proxy مرورگر نیاز ندارید، آن را غیرفعال کنید (gateway.nodes.browser.mode="off").
• حالت existing-session در Chrome MCP امن‌تر نیست؛ می‌تواند در هر چیزی که پروفایل Chrome آن میزبان به آن دسترسی دارد، مثل شما عمل کند.

# سیاست SSRF مرورگر (به‌صورت پیش‌فرض سخت‌گیرانه)

سیاست ناوبری مرورگر OpenClaw به‌صورت پیش‌فرض سخت‌گیرانه است: مقصدهای خصوصی/داخلی مسدود می‌مانند مگر اینکه صریحاً opt in کنید.

• پیش‌فرض: browser.ssrfPolicy.dangerouslyAllowPrivateNetwork تنظیم نشده است، بنابراین ناوبری مرورگر مقصدهای خصوصی/داخلی/special-use را مسدود نگه می‌دارد.
• alias قدیمی: browser.ssrfPolicy.allowPrivateNetwork همچنان برای سازگاری پذیرفته می‌شود.
• حالت opt-in: برای اجازه دادن به مقصدهای خصوصی/داخلی/special-use، browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true را تنظیم کنید.
• در حالت سخت‌گیرانه، برای استثناهای صریح از hostnameAllowlist (patternهایی مثل *.example.com) و allowedHostnames (استثناهای دقیق host، شامل نام‌های مسدودشده‌ای مثل localhost) استفاده کنید.
• ناوبری پیش از request بررسی می‌شود و پس از ناوبری، روی URL نهایی http(s) تا حد امکان دوباره بررسی می‌شود تا pivotهای مبتنی بر redirect کاهش یابد.

نمونه سیاست سخت‌گیرانه:

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"],
    },
  },
}

# پروفایل‌های دسترسی برای هر agent (چند-agent)

با routing چند-agent، هر agent می‌تواند سندباکس + سیاست ابزار خودش را داشته باشد: از این برای دادن دسترسی کامل، فقط خواندنی، یا بدون دسترسی به هر agent استفاده کنید. برای جزئیات کامل و قواعد تقدم، سندباکس و ابزارهای چند-Agent را ببینید.

موارد استفاده رایج:

• agent شخصی: دسترسی کامل، بدون سندباکس
• agent خانواده/کار: سندباکس‌شده + ابزارهای فقط خواندنی
• agent عمومی: سندباکس‌شده + بدون ابزارهای فایل‌سیستم/shell

# مثال: دسترسی کامل (بدون سندباکس)

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

# مثال: ابزارهای فقط خواندنی + فضای کاری فقط خواندنی

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "ro",
        },
        tools: {
          allow: ["read"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

# مثال: بدون دسترسی فایل‌سیستم/shell (پیام‌رسانی provider مجاز)

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "none",
        },
        // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools
        // to the current session + spawned subagent sessions, but you can clamp further if needed.
        // See `tools.sessions.visibility` in the configuration reference.
        tools: {
          sessions: { visibility: "tree" }, // self | tree | agent | all
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

# پاسخ به حادثه

اگر AI شما کار بدی انجام داد:

# مهار

1. متوقفش کنید: اپ macOS را متوقف کنید (اگر Gateway را supervisor می‌کند) یا پردازش openclaw gateway خود را terminate کنید.
2. در معرض بودن را ببندید: تا وقتی متوجه شوید چه اتفاقی افتاده، gateway.bind: "loopback" را تنظیم کنید (یا Tailscale Funnel/Serve را غیرفعال کنید).
3. دسترسی را freeze کنید: DM/گروه‌های پرخطر را به dmPolicy: "disabled" تغییر دهید / mention را الزامی کنید، و اگر entryهای allow-all با "*" داشتید آن‌ها را حذف کنید.

# چرخش (اگر secretها نشت کرده‌اند، compromise را فرض کنید)

1. احراز هویت Gateway (gateway.auth.token / OPENCLAW_GATEWAY_PASSWORD) را rotate کنید و restart کنید.
2. secretهای client راه‌دور (gateway.remote.token / .password) را روی هر دستگاهی که می‌تواند Gateway را فراخوانی کند rotate کنید.
3. credentialهای provider/API را rotate کنید (credentialهای WhatsApp، tokenهای Slack/Discord، کلیدهای model/API در auth-profiles.json، و مقدارهای payload secret رمزگذاری‌شده وقتی استفاده می‌شوند).

# حسابرسی

1. لاگ‌های Gateway را بررسی کنید: /tmp/openclaw/openclaw-YYYY-MM-DD.log (یا logging.file).
2. transcript(های) مرتبط را مرور کنید: ~/.openclaw/agents/<agentId>/sessions/*.jsonl.
3. تغییرهای اخیر پیکربندی را مرور کنید (هر چیزی که می‌توانسته دسترسی را گسترده‌تر کند: gateway.bind، gateway.auth، سیاست‌های dm/group، tools.elevated، تغییرهای plugin).
4. openclaw security audit --deep را دوباره اجرا کنید و تأیید کنید یافته‌های critical رفع شده‌اند.

# جمع‌آوری برای گزارش

• timestamp، OS میزبان gateway + نسخه OpenClaw
• transcript(های) session + یک tail کوتاه از log (پس از redaction)
• آنچه مهاجم فرستاد + آنچه agent انجام داد
• اینکه آیا Gateway فراتر از loopback در معرض بوده است یا نه (LAN/Tailscale Funnel/Serve)

# اسکن secret

CI هوک pre-commit با نام detect-private-key را روی repository اجرا می‌کند. اگر fail شد، key material کامیت‌شده را حذف یا rotate کنید، سپس به‌صورت محلی بازتولید کنید:

pre-commit run --all-files detect-private-key

# گزارش مسائل امنیتی

آسیب‌پذیری‌ای در OpenClaw پیدا کرده‌اید؟ لطفاً مسئولانه گزارش کنید:

1. ایمیل: [email protected]
2. تا زمان رفع، به‌صورت عمومی منتشر نکنید
3. به شما credit می‌دهیم (مگر اینکه ناشناس ماندن را ترجیح دهید)