مدیریت اسرار

OpenClaw از SecretRefهای افزایشی پشتیبانی می‌کند تا اعتبارنامه‌های پشتیبانی‌شده نیازی به ذخیره‌شدن به‌صورت متن ساده در پیکربندی نداشته باشند.

مدل زمان اجرا

• رازها هنگام فعال‌سازی، به‌صورت فوری و نه با تأخیر در مسیرهای درخواست، در یک اسنپ‌شات درون‌حافظه‌ای زمان اجرا resolve می‌شوند.
• راه‌اندازی سرد Gateway، خرابی قابل‌تلاش‌مجدد SecretRef را به یک مالک شناخته‌شدهٔ غیر Gateway محدود می‌کند، مشروط بر اینکه آن مالک از جداسازی پشتیبانی کند. کلاس‌های مالک نگاشت‌شده شامل ارائه‌دهندگان مدل و Skills، ارائه‌دهندگان رسانه/TTS/cron، پروفایل‌های احراز هویت واجد شرایط، حافظهٔ هر عامل، SSH سندباکس، حساب‌های کانال و مسیرهای Plugin اعلام‌شده در مانیفست هستند. Gateway راه‌اندازی می‌شود، مالک را به‌صورت پیکربندی‌شده اما در دسترس‌نبودنی ثبت می‌کند و یک هشدار افت عملکردِ سانسورشده منتشر می‌کند. احراز هویت ورودی Gateway، ارجاع‌ها یا مقادیر resolveشدهٔ دارای ساختار نامعتبر، مالکان fail-closed و ارجاع‌هایی که مالک زمان اجرای آن‌ها نگاشت نشده است، همچنان باعث شکست راه‌اندازی می‌شوند.
• بارگذاری مجدد، هر مالک نگاشت‌شده را مستقل اعتبارسنجی می‌کند و سپس یک اسنپ‌شات اتمی منتشر می‌کند. مالکان سالم تازه‌سازی می‌شوند. یک مالک واجد شرایطِ ناموفق، تنها وقتی آخرین مقدار سالم شناخته‌شدهٔ خود را حفظ می‌کند و stale می‌شود که هویت ارجاع‌ها، تعریف ارائه‌دهندگان و قرارداد کامل و غیرمحرمانهٔ مالک بدون تغییر مانده باشند؛ مالک ناموفقِ تغییرکرده یا جدید cold می‌شود. یک خرابی سخت‌گیرانه، بارگذاری مجدد را رد و اسنپ‌شات فعال را حفظ می‌کند.
• نقض خط‌مشی‌ها (برای مثال ترکیب پروفایل احراز هویت در حالت OAuth با ورودی SecretRef) پیش از تعویض زمان اجرا باعث شکست فعال‌سازی می‌شود.
• درخواست‌های زمان اجرا فقط اسنپ‌شات فعال درون‌حافظه‌ای را می‌خوانند. اعتبارنامه‌های SecretRef ارائه‌دهندهٔ مدل، تا زمان خروج از فرایند به‌صورت sentinelهای محلیِ فرایند از ذخیره‌سازی احراز هویت و گزینه‌های استریم عبور می‌کنند. مسیرهای تحویل خروجی (تحویل پاسخ/رشته در Discord و ارسال کنش در Telegram) نیز همین اسنپ‌شات را می‌خوانند و برای هر ارسال، ارجاع‌ها را دوباره resolve نمی‌کنند.

این کار اختلال ارائه‌دهندهٔ راز را از مسیرهای داغ درخواست دور نگه می‌دارد.

محافظت از ورودی Gateway، پیکربندی یا مقادیر resolveشدهٔ دارای ساختار نامعتبر، نقض خط‌مشی‌ها و مالکیت ناشناخته همچنان به‌صورت fail-closed عمل می‌کنند. مالکان جداشده هرگز به منبع اعتبارنامه‌ای با تقدم کمتر بازنمی‌گردند.

تزریق هنگام خروج (sentinelها)

برای اعتبارنامه‌های ارائه‌دهندهٔ مدل که بر SecretRef متکی هستند، OpenClaw هنگام resolve احراز هویت مدل یک sentinel مات و محلیِ فرایند ایجاد می‌کند. بنابراین ذخیره‌سازی احراز هویت، گزینه‌های استریم، پیکربندی SDK، گزارش‌ها، اشیای خطا و بیشتر بررسی‌های درونی زمان اجرا مقداری مانند oc-sent-v1-... را می‌بینند، نه اعتبارنامهٔ ارائه‌دهنده را. واکشی محافظت‌شدهٔ مدل و کاوش‌های سلامت مدیریت‌شدهٔ ارائه‌دهندهٔ محلی، بلافاصله پیش از خروج هر درخواست از فرایند، sentinelهای شناخته‌شده را در مقادیر URL و سرآیند جایگزین می‌کنند.

مقادیر ناشناخته با شکل sentinel پیش از هرگونه فعالیت شبکه‌ای به‌صورت fail-closed رد می‌شوند. OpenClaw به‌جای ارسال یک sentinel حل‌نشده به ارائه‌دهنده، از ارسال درخواست خودداری می‌کند. مقادیر راز resolveشده نیز به‌عنوان اقدامی دفاعی چندلایه، برای سانسور دقیق مقدار در گزارش‌ها ثبت می‌شوند.

آداپتورهای ارائه‌دهنده از آخرین نقطهٔ تزریقی که SDK آن‌ها پشتیبانی می‌کند استفاده می‌کنند:

• SDKهایی که گزینهٔ واکشی سفارشی دارند، واکشی محافظت‌شدهٔ OpenClaw را دریافت می‌کنند؛ بنابراین SDK، sentinel را حفظ می‌کند.
• SDKهایی که گزینهٔ واکشی سفارشی ندارند، sentinel را بلافاصله پیش از ساخت کلاینت باز می‌کنند. استریم‌های ارائه‌دهندهٔ متعلق به Plugin و هارنس‌های عامل در آخرین نقطهٔ تحویل متعلق به هسته آن را باز می‌کنند، زیرا این انتقال‌دهنده‌ها از واکشی محافظت‌شدهٔ OpenClaw استفاده نمی‌کنند.

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

برای غیرفعال‌کردن ساخت sentinel هنگام پاسخ‌گویی به رخداد یا عیب‌یابی سازگاری، OPENCLAW_SECRET_SENTINELS=off را تنظیم کنید (0 یا false نیز، بدون حساسیت به بزرگی و کوچکی حروف، پذیرفته می‌شوند). این کلید توقف، ثبت سانسور دقیق مقدار را غیرفعال نمی‌کند.

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

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

برای استقرارهای عملیاتی که فایل‌های قابل‌دسترسی برای عامل در دامنه قرار دارند، مهاجرت را فقط زمانی کامل در نظر بگیرید که همهٔ موارد زیر برقرار باشند:

• اعتبارنامه‌های پشتیبانی‌شده به‌جای مقادیر متن ساده از SecretRef استفاده کنند.
• باقی‌ماندهٔ قدیمیِ متن ساده از openclaw.json، auth-profiles.json، .env و فایل‌های models.json تولیدشده پاک شده باشد.
• openclaw secrets audit --check پس از مهاجرت پاک باشد.
• هر اعتبارنامهٔ پشتیبانی‌نشده یا در حال چرخشِ باقی‌مانده با جداسازی سیستم‌عامل، جداسازی کانتینر یا یک پروکسی اعتبارنامهٔ خارجی محافظت شود.

به همین دلیل، گردش‌کار ممیزی/پیکربندی/اعمال یک دروازهٔ مهاجرت امنیتی است، نه صرفاً یک ابزار کمکی برای سهولت کار.

پالایش سطح فعال

SecretRefها فقط در سطح‌هایی که عملاً فعال هستند اعتبارسنجی می‌شوند:

• سطح‌های فعال‌شده: خرابی‌های قابل‌تلاش‌مجدد برای مالکان نگاشت‌شده و قابل‌جداسازی، وارد وضعیت افت عملکرد cold یا stale می‌شوند. خرابی‌های سخت‌گیرانه، fail-closed، موردنیاز Gateway یا نگاشت‌نشده، راه‌اندازی/بارگذاری مجدد را مسدود می‌کنند.
• سطح‌های غیرفعال: ارجاع‌های resolveنشده راه‌اندازی/بارگذاری مجدد را مسدود نمی‌کنند؛ آن‌ها یک عیب‌یابی غیرکشندهٔ SECRETS_REF_IGNORED_INACTIVE_SURFACE منتشر می‌کنند.

عیب‌یابی سطح احراز هویت Gateway

وقتی یک SecretRef روی gateway.auth.token، gateway.auth.password، gateway.remote.token یا gateway.remote.password تنظیم شده باشد، راه‌اندازی/بارگذاری مجدد Gateway وضعیت سطح را با کد SECRETS_GATEWAY_AUTH_SURFACE ثبت می‌کند:

• active: این SecretRef بخشی از سطح مؤثر احراز هویت است و باید resolve شود.
• inactive: سطح احراز هویت دیگری اولویت دارد، یا احراز هویت راه‌دور غیرفعال/فعال‌نشده است.

ورودی گزارش شامل دلیلی است که خط‌مشی سطح فعال از آن استفاده کرده است.

پیش‌بررسی ارجاع در راه‌اندازی اولیه

در راه‌اندازی اولیهٔ تعاملی، انتخاب ذخیره‌سازی SecretRef پیش از ذخیره‌سازی، اعتبارسنجی پیش‌بررسی را اجرا می‌کند:

• ارجاع‌های محیطی: نام متغیر محیطی را اعتبارسنجی می‌کند و تأیید می‌کند که هنگام راه‌اندازی، مقداری غیرخالی قابل‌مشاهده است.
• ارجاع‌های ارائه‌دهنده (file یا exec): انتخاب ارائه‌دهنده را اعتبارسنجی می‌کند، id را resolve می‌کند و نوع مقدار resolveشده را بررسی می‌کند.
• گردش‌کار شروع سریع: وقتی gateway.auth.token از قبل یک SecretRef باشد، راه‌اندازی اولیه پیش از راه‌اندازی کاوش/داشبورد، با استفاده از همان دروازهٔ شکست سریع، آن را برای ارجاع‌های env، file و exec resolve می‌کند.

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

قرارداد SecretRef

یک شکل شیء در همه‌جا:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

پیکربندی ارائه‌دهنده

ارائه‌دهندگان را زیر secrets.providers تعریف کنید:

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // یا "singleValue"      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        args: ["--profile", "prod"],        passEnv: ["PATH", "VAULT_ADDR"],        jsonOnly: true,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },  },}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{"protocolVersion": 1,"values": {},"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }}

کلیدهای API مبتنی بر فایل

رشته‌های file:... را در بلوک env پیکربندی قرار ندهید. آن بلوک تحت‌اللفظی و غیرقابل‌بازنویسی است، بنابراین file:... هرگز در آن تفکیک نمی‌شود.

در عوض، در یکی از فیلدهای اعتبارنامه پشتیبانی‌شده از SecretRef فایل استفاده کنید:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

برای mode: "singleValue"، مقدار id در SecretRef برابر با "value" است. برای mode: "json"، از یک اشاره‌گر مطلق JSON مانند "/providers/xai/apiKey" استفاده کنید.

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

نمونه‌های یکپارچه‌سازی exec

برای راهنمای اختصاصی 1Password درباره حساب‌های سرویس، مهارت عامل همراه و عیب‌یابی، به 1Password مراجعه کنید.

{  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" },      },    },  },}

{  secrets: {    providers: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // برای باینری‌های دارای پیوند نمادین Homebrew الزامی است        trustedDirs: ["/opt/homebrew"],        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "vault_openai", id: "value" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`تجزیه درخواست ناموفق بود: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass با وضعیت ${result.status} خارج شد`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // برای باینری‌های دارای پیوند نمادین Homebrew الزامی است        trustedDirs: ["/opt/homebrew"],        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],        passEnv: ["SOPS_AGE_KEY_FILE"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "sops_openai", id: "value" },      },    },  },}

متغیرهای محیطی سرور MCP

متغیرهای محیطی سرور MCP که از طریق plugins.entries.acpx.config.mcpServers پیکربندی می‌شوند، SecretInput را می‌پذیرند و کلیدهای API و توکن‌ها را از پیکربندی متن ساده دور نگه می‌دارند:

{  plugins: {    entries: {      acpx: {        enabled: true,        config: {          mcpServers: {            github: {              command: "npx",              args: ["-y", "@modelcontextprotocol/server-github"],              env: {                GITHUB_PERSONAL_ACCESS_TOKEN: {                  source: "env",                  provider: "default",                  id: "MCP_GITHUB_PAT",                },              },            },          },        },      },    },  },}

مقادیر رشته‌ای متن ساده همچنان کار می‌کنند. ارجاع‌های الگوی محیطی مانند ${MCP_SERVER_API_KEY} و اشیای SecretRef هنگام فعال‌سازی Gateway و پیش از ایجاد فرایند سرور MCP تفکیک می‌شوند. همانند دیگر سطوح SecretRef، ارجاع‌های تفکیک‌نشده فقط زمانی فعال‌سازی را مسدود می‌کنند که Plugin ‏acpx عملاً فعال باشد.

اطلاعات احراز هویت SSH در sandbox

بک‌اند اصلی sandbox ‏ssh نیز از SecretRef برای اطلاعات احراز هویت SSH پشتیبانی می‌کند:

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        ssh: {          target: "user@gateway-host:22",          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

رفتار زمان اجرا:

• OpenClaw این ارجاع‌ها را هنگام فعال‌سازی سندباکس برطرف می‌کند، نه به‌صورت تنبل در هر فراخوانی SSH.
• مقادیر برطرف‌شده با مجوزهای محدودکنندهٔ فایل (0o600) در یک پوشهٔ موقت نوشته می‌شوند و در پیکربندی SSH تولیدشده به‌کار می‌روند.
• اگر بک‌اند مؤثر سندباکس ssh نباشد (یا حالت سندباکس off باشد)، این ارجاع‌ها غیرفعال می‌مانند و مانع راه‌اندازی نمی‌شوند.

سطح اعتبارنامهٔ پشتیبانی‌شده

اعتبارنامه‌های پشتیبانی‌شده و پشتیبانی‌نشدهٔ مرجع در سطح اعتبارنامهٔ SecretRef فهرست شده‌اند.

رفتار الزامی و تقدم

• فیلد بدون ارجاع: بدون تغییر.
• فیلد دارای ارجاع: هنگام فعال‌سازی در سطوح فعال الزامی است.
• اگر هم متن ساده و هم ارجاع وجود داشته باشند، در مسیرهای تقدم پشتیبانی‌شده ارجاع مقدم است.
• نشانگر ویرایش __OPENCLAW_REDACTED__ برای ویرایش/بازیابی داخلی پیکربندی رزرو شده است و به‌عنوان دادهٔ پیکربندی صریح ارسالی رد می‌شود.

سیگنال‌های هشدار و ممیزی:

• SECRETS_REF_OVERRIDES_PLAINTEXT (هشدار زمان اجرا)
• REF_SHADOWED (یافتهٔ ممیزی هنگامی که اعتبارنامه‌های auth-profiles.json بر ارجاع‌های openclaw.json مقدم باشند)

serviceAccount در Google Chat، JSON درون‌خطی یا یک SecretRef را می‌پذیرد. اگر فیلد مرجع تنظیم نشده باشد، Doctor فیلد هم‌سطح بازنشستهٔ serviceAccountRef را به این فیلد مرجع منتقل می‌کند.

محرک‌های فعال‌سازی

فعال‌سازی اسرار در موارد زیر اجرا می‌شود:

• راه‌اندازی (پیش‌بررسی به‌علاوهٔ فعال‌سازی نهایی)
• مسیر اعمال داغ بارگذاری مجدد پیکربندی
• مسیر بررسی راه‌اندازی مجدد در بارگذاری مجدد پیکربندی
• بارگذاری مجدد دستی از طریق secrets.reload
• پیش‌بررسی RPC نوشتن پیکربندی Gateway (config.set / config.apply / config.patch) که پیش از ماندگار کردن ویرایش‌ها، SecretRefهای سطح فعال را در محمولهٔ پیکربندی ارسالی اعتبارسنجی می‌کند

قرارداد فعال‌سازی:

• در صورت موفقیت، اسنپ‌شات به‌صورت اتمی جایگزین می‌شود.
• شکست سخت‌گیرانهٔ راه‌اندازی، راه‌اندازی Gateway را متوقف می‌کند.
• در راه‌اندازی سرد، شکست قابل‌تلاش‌مجدد در تفکیک برای یک مالک نگاشت‌شده، قابل‌جداسازی و غیر-Gateway ممکن است اسنپ‌شات را با همان مالک دقیقاً در وضعیت پیکربندی‌شده اما دردسترس‌نبودنی منتشر کند. درخواست‌ها برای آن مالک با SECRET_SURFACE_UNAVAILABLE شکست می‌خورند؛ پس از شکست یک ارجاع صریح، مالکان ارائه‌دهندهٔ مدل به اعتبارنامه‌های محیط یا نمایهٔ احراز هویت بازنمی‌گردند.
• بارگذاری مجدد و بررسی راه‌اندازی مجدد، مالکان نگاشت‌شدهٔ واجد شرایط را جدا می‌کنند. هویت‌های ارجاع تغییریافته‌نبوده با تعریف‌های ارائه‌دهندهٔ تغییریافته‌نبوده و قرارداد کامل و غیرمحرمانهٔ مالکِ تغییریافته‌نبوده، مقادیر دقیق آخرین وضعیت سالم خود را به‌صورت کهنه حفظ می‌کنند؛ ارجاع‌های تفکیک‌نشدهٔ تغییرکرده یا تازه پیکربندی‌شده فقط برای همان مالک به‌صورت سرد منتشر می‌شوند. شکست سخت‌گیرانهٔ بارگذاری مجدد، اسنپ‌شات فعال قبلی را حفظ می‌کند.
• config.set، config.apply و config.patch ارجاع‌های تفکیک‌نشدهٔ معتبر از نظر نحوی را برای مالکان قابل‌جداسازی می‌پذیرند و گزارش ویرایش‌شدهٔ degradedSecretOwners را بازمی‌گردانند. احراز هویت ورودی Gateway، پیکربندی یا مقادیر تفکیک‌شدهٔ نامعتبر از نظر ساختاری، نقض سیاست‌ها و مالکان ناشناخته همچنان پیش از تغییر دیسک رد می‌شوند.
• مالکان هم‌سطح سالم، حتی هنگامی که مالک دیگری سرد یا کهنه است، به‌طور عادی تفکیک و منتشر می‌شوند.
• ارائهٔ یک توکن صریح کانال برای هر فراخوانی به یک فراخوانی ابزار/تابع کمکی خروجی، فعال‌سازی SecretRef را تحریک نمی‌کند؛ نقاط فعال‌سازی همچنان راه‌اندازی، بارگذاری مجدد و secrets.reload صریح هستند.

سیگنال‌های تنزل و بازیابی

هنگامی که فعال‌سازی در زمان بارگذاری مجدد پس از یک وضعیت سالم شکست بخورد، OpenClaw وارد وضعیت تنزل‌یافتهٔ اسرار می‌شود و رویدادهای یک‌بارهٔ سیستمی و کدهای گزارش زیر را منتشر می‌کند:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

رفتار:

• تنزل‌یافته: مالکان سالم تازه‌سازی می‌شوند، مالکان کهنه آخرین وضعیت سالم را نگه می‌دارند و مالکان سرد دردسترس‌ناپذیر می‌مانند.
• بازیابی‌شده: پس از فعال‌سازی موفق بعدی یک بار منتشر می‌شود.
• شکست‌های مکرر در حالی که وضعیت از قبل تنزل‌یافته است، هشدار ثبت می‌کنند اما رویداد را دوباره منتشر نمی‌کنند.
• شکست سخت‌گیرانهٔ راه‌اندازی هرگز رویداد تنزل‌یافته منتشر نمی‌کند، زیرا زمان اجرا هیچ‌گاه فعال نشده است. راه‌اندازی موفق با مالکان سرد، تنزل مالک را ثبت می‌کند اما رویداد بارگذار مجدد منتشر نمی‌کند.
• شکست‌های محدود به ارجاع در راه‌اندازی و بارگذاری مجدد، برای هر مالک متأثر یک هشدار ساخت‌یافتهٔ SECRETS_DEGRADED منتشر می‌کنند. قطعی‌های محدود به ارائه‌دهنده به‌جای تکرار شکست ارائه‌دهنده برای هر مالک، یک هشدار SECRETS_PROVIDER_DEGRADED همراه با ارائه‌دهنده و فهرست کامل مالکان متأثر منتشر می‌کنند. هشدارها شامل دلیل ویرایش‌شده، وضعیت مالک cold یا stale و راهنمای تلاش مجدد openclaw secrets reload هستند. آن‌ها هرگز مقادیر تفکیک‌شده یا شناسه‌های SecretRef را شامل نمی‌شوند.
• openclaw doctor مالکان سرد و کهنه را همراه با مسیرهای پیکربندی متأثر، دلیل ویرایش‌شده و راهنمای تلاش مجدد فهرست می‌کند.

تفکیک مسیر فرمان

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

نکات دیگر:

• تازه‌سازی اسنپ‌شات پس از چرخش راز بک‌اند توسط openclaw secrets reload مدیریت می‌شود.
• روش RPC Gateway مورداستفادهٔ این مسیرهای فرمان: secrets.resolve.

جریان کاری ممیزی و پیکربندی

جریان پیش‌فرض اپراتور:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

تا زمانی که ممیزی مجدد پاک نشده است، مهاجرت را کامل تلقی نکنید. اگر ممیزی همچنان مقادیر متن سادهٔ ذخیره‌شده را گزارش کند، حتی هنگامی که APIهای زمان اجرا مقادیر ویرایش‌شده بازمی‌گردانند، خطر دسترسی عامل باقی می‌ماند.

اگر هنگام configure به‌جای اعمال، یک طرح را ذخیره می‌کنید، پیش از ممیزی مجدد آن طرح ذخیره‌شده را با openclaw secrets apply --from <plan-path> اعمال کنید.

openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

سیاست ایمنی یک‌طرفه

مدل ایمنی:

• پیش‌بررسی باید پیش از حالت نوشتن موفق شود.
• فعال‌سازی زمان اجرا پیش از ثبت اعتبارسنجی می‌شود.
• اعمال، فایل‌ها را با جایگزینی اتمی فایل به‌روزرسانی می‌کند و در صورت شکست، بازیابی را به‌صورت بهترین تلاش انجام می‌دهد.

نکات سازگاری احراز هویت قدیمی

برای اعتبارنامه‌های ایستا، زمان اجرا دیگر به ذخیره‌سازی قدیمی احراز هویت به‌صورت متن ساده وابسته نیست.

• منبع اعتبارنامهٔ زمان اجرا، اسنپ‌شات درون‌حافظه‌ای تفکیک‌شده است.
• ورودی‌های ایستای قدیمی api_key هنگام شناسایی پاک می‌شوند.
• رفتار سازگاری مرتبط با OAuth جدا باقی می‌ماند.

نکتهٔ رابط کاربری وب

پیکربندی برخی اجتماع‌های SecretInput در حالت ویرایشگر خام آسان‌تر از حالت فرم است.

مرتبط

• احراز هویت - راه‌اندازی احراز هویت
• CLI: اسرار - فرمان‌های CLI
• Vault SecretRefs - راه‌اندازی ارائه‌دهنده HashiCorp Vault
• متغیرهای محیطی - تقدم متغیرهای محیطی
• سطح اعتبارنامه SecretRef - سطح اعتبارنامه
• قرارداد طرح اعمال اسرار - جزئیات قرارداد طرح
• امنیت - وضعیت امنیتی