مدیریت اسرار

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

اهداف و مدل runtime

Secrets به یک snapshot runtime درون‌حافظه‌ای resolve می‌شوند.

• Resolution در زمان activation با اشتیاق انجام می‌شود، نه به‌صورت lazy در مسیرهای درخواست.
• Startup وقتی یک SecretRef عملا فعال resolve نشود، سریع fail می‌شود.
• Reload از swap اتمیک استفاده می‌کند: موفقیت کامل، یا حفظ آخرین snapshot سالم شناخته‌شده.
• نقض‌های policy مربوط به SecretRef (برای مثال auth profileهای حالت OAuth همراه با ورودی SecretRef) پیش از swap runtime باعث fail شدن activation می‌شوند.
• درخواست‌های runtime فقط از snapshot فعال درون‌حافظه‌ای می‌خوانند.
• پس از نخستین activation/load موفق پیکربندی، مسیرهای کد runtime تا زمانی که یک reload موفق آن را swap کند، همان snapshot فعال درون‌حافظه‌ای را می‌خوانند.
• مسیرهای تحویل خروجی نیز از همان snapshot فعال می‌خوانند (برای مثال تحویل پاسخ/thread در Discord و ارسال action در Telegram)؛ آن‌ها SecretRefs را در هر ارسال دوباره resolve نمی‌کنند.

این کار قطعی‌های secret-provider را از مسیرهای داغ درخواست دور نگه می‌دارد.

مرز دسترسی agent

SecretRefs از ماندگار شدن اعتبارنامه‌ها در پیکربندی پشتیبانی‌شده و سطح‌های model تولیدشده جلوگیری می‌کنند، اما مرز ایزولاسیون فرایند نیستند. اگر یک اعتبارنامه‌ی متن ساده روی دیسک در مسیری باقی بماند که agent بتواند آن را بخواند، agent می‌تواند با استفاده از ابزارهای file یا shell برای بررسی آن فایل، redaction سطح API را دور بزند.

برای استقرارهای production که فایل‌های قابل‌دسترسی برای agent در scope هستند، مهاجرت SecretRef را فقط وقتی کامل بدانید که همه‌ی موارد زیر درست باشند:

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

به همین دلیل workflow مربوط به audit/configure/apply یک gate مهاجرت امنیتی است، نه فقط یک helper برای راحتی.

فیلتر کردن سطح فعال

SecretRefs فقط روی سطح‌های عملا فعال validate می‌شوند.

• سطح‌های enabled: refهای resolveنشده startup/reload را block می‌کنند.
• سطح‌های inactive: refهای resolveنشده startup/reload را block نمی‌کنند.
• refهای inactive diagnosticهای غیرکشنده با کد SECRETS_REF_IGNORED_INACTIVE_SURFACE منتشر می‌کنند.

Diagnosticهای سطح auth در Gateway

وقتی یک SecretRef روی gateway.auth.token، gateway.auth.password، gateway.remote.token، یا gateway.remote.password پیکربندی شود، startup/reload مربوط به Gateway وضعیت سطح را صریحا log می‌کند:

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

این ورودی‌ها با SECRETS_GATEWAY_AUTH_SURFACE log می‌شوند و شامل دلیلی هستند که policy سطح فعال استفاده کرده است، تا بتوانید ببینید چرا یک اعتبارنامه active یا inactive در نظر گرفته شده است.

Preflight مرجع onboarding

وقتی onboarding در حالت تعاملی اجرا می‌شود و شما ذخیره‌سازی SecretRef را انتخاب می‌کنید، OpenClaw پیش از ذخیره‌سازی preflight validation اجرا می‌کند:

• refهای env: نام env var را validate می‌کند و تایید می‌کند که یک مقدار غیرخالی هنگام setup قابل مشاهده است.
• refهای provider (file یا exec): انتخاب provider را validate می‌کند، id را resolve می‌کند، و نوع مقدار resolveشده را بررسی می‌کند.
• مسیر استفاده‌ی دوباره‌ی quickstart: وقتی gateway.auth.token از قبل SecretRef باشد، onboarding آن را پیش از probe/dashboard bootstrap (برای refهای env، file، و exec) با همان gate fail-fast resolve می‌کند.

اگر validation fail شود، onboarding خطا را نشان می‌دهد و اجازه می‌دهد دوباره تلاش کنید.

قرارداد SecretRef

همه‌جا از یک شکل object استفاده کنید:

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

پیکربندی provider

providerها را زیر secrets.providers تعریف کنید:

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // or "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",    },    resolution: {      maxProviderConcurrency: 4,      maxRefsPerProvider: 512,      maxBatchBytes: 262144,    },  },}

{ "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": { "message": "not found" } }}

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

stringهای file:... را در block env پیکربندی قرار ندهید. block env literal و non-overriding است، بنابراین file:... resolve نمی‌شود.

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

{  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 pointer مطلق مانند "/providers/xai/apiKey" استفاده کنید.

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

نمونه‌های integration مربوط به exec

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        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, // required for Homebrew symlinked binaries        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(`Failed to parse request: ${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 exited ${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, // required for Homebrew symlinked binaries        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، resolve می‌شوند. مانند دیگر سطوح SecretRef، ارجاع‌های resolveنشده فقط زمانی فعال‌سازی را مسدود می‌کنند که Plugin acpx عملاً فعال باشد.

مواد احراز هویت SSH برای sandbox

backend اصلی 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 این ارجاع‌ها را هنگام فعال‌سازی sandbox resolve می‌کند، نه به‌صورت تنبل هنگام هر فراخوانی SSH.
• مقادیر resolveشده در فایل‌های موقت با مجوزهای محدودکننده نوشته می‌شوند و در پیکربندی SSH تولیدشده استفاده می‌شوند.
• اگر backend مؤثر sandbox برابر ssh نباشد، این ارجاع‌ها غیرفعال می‌مانند و راه‌اندازی را مسدود نمی‌کنند.

سطح credential پشتیبانی‌شده

credentialهای canonical پشتیبانی‌شده و پشتیبانی‌نشده در اینجا فهرست شده‌اند:

• سطح credential SecretRef

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

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

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

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

رفتار سازگاری Google Chat:

• serviceAccountRef بر serviceAccount متن ساده تقدم دارد.
• وقتی ارجاع sibling تنظیم شده باشد، مقدار متن ساده نادیده گرفته می‌شود.

triggerهای فعال‌سازی

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

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

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

• موفقیت snapshot را به‌صورت اتمی تعویض می‌کند.
• شکست راه‌اندازی، راه‌اندازی Gateway را لغو می‌کند.
• شکست بازبارگذاری زمان اجرا، آخرین snapshot خوب شناخته‌شده را نگه می‌دارد.
• شکست preflight مربوط به Write-RPC، پیکربندی ارسالی را رد می‌کند و هم پیکربندی دیسک و هم snapshot فعال زمان اجرا را بدون تغییر نگه می‌دارد.
• ارائه یک توکن کانال صریح برای هر فراخوانی به helper/tool خروجی، فعال‌سازی SecretRef را trigger نمی‌کند؛ نقاط فعال‌سازی همان راه‌اندازی، بازبارگذاری، و secrets.reload صریح باقی می‌مانند.

سیگنال‌های degraded و recovered

وقتی فعال‌سازی هنگام بازبارگذاری پس از یک وضعیت سالم شکست بخورد، OpenClaw وارد وضعیت degraded secrets می‌شود.

رویداد یک‌باره سیستم و کدهای لاگ:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

رفتار:

• degraded: زمان اجرا آخرین snapshot خوب شناخته‌شده را نگه می‌دارد.
• recovered: یک بار پس از فعال‌سازی موفق بعدی emit می‌شود.
• شکست‌های تکراری در حالی که سیستم از قبل degraded است هشدارها را لاگ می‌کنند اما رویدادها را اسپم نمی‌کنند.
• fail-fast راه‌اندازی رویدادهای degraded را emit نمی‌کند، چون زمان اجرا هرگز فعال نشده بود.

resolution مسیر فرمان

مسیرهای فرمان می‌توانند از طریق RPC snapshot Gateway به resolution پشتیبانی‌شده SecretRef opt in کنند.

دو رفتار کلی وجود دارد:

نکته‌های دیگر:

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

جریان کاری audit و configure

جریان پیش‌فرض operator:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

مهاجرت را تا زمانی که re-audit پاک نیست کامل تلقی نکنید. اگر audit هنوز مقادیر plaintext در حالت ذخیره‌شده گزارش می‌کند، ریسک دسترسی agent همچنان وجود دارد حتی وقتی APIهای runtime مقادیر redacted برمی‌گردانند.

اگر هنگام configure به‌جای اعمال، یک plan ذخیره می‌کنید، آن plan ذخیره‌شده را پیش از re-audit با 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

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

مدل ایمنی:

• preflight باید پیش از حالت write موفق شود
• فعال‌سازی runtime پیش از commit اعتبارسنجی می‌شود
• apply فایل‌ها را با جایگزینی اتمیک فایل و restore در حد best-effort هنگام شکست به‌روزرسانی می‌کند

نکته‌های سازگاری auth legacy

برای credentialهای static، runtime دیگر به ذخیره‌سازی auth legacy به‌صورت plaintext وابسته نیست.

• منبع credential در runtime همان snapshot درون‌حافظه‌ای resolveشده است.
• ورودی‌های static legacy از نوع api_key هنگام کشف پاک‌سازی می‌شوند.
• رفتار سازگاری مرتبط با OAuth جدا باقی می‌ماند.

نکتهٔ Web UI

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

مرتبط

• احراز هویت — راه‌اندازی auth
• CLI: secrets — فرمان‌های CLI
• متغیرهای محیطی — precedence محیط
• سطح credential در SecretRef — سطح credential
• قرارداد Secrets Apply Plan — جزئیات قرارداد plan
• امنیت — وضعیت امنیتی