إدارة الأسرار

​

الأهداف ونموذج وقت التشغيل

• يتم الحل بشغف أثناء التفعيل، وليس بشكل كسول في مسارات الطلبات.
• يفشل بدء التشغيل سريعًا عندما يتعذر حل SecretRef نشط فعليًا.
• تستخدم إعادة التحميل تبديلًا ذريًا: نجاح كامل، أو الاحتفاظ بآخر لقطة معروفة وسليمة.
• تؤدي انتهاكات سياسة SecretRef (على سبيل المثال ملفات تعريف المصادقة بوضع OAuth المدمجة مع إدخال SecretRef) إلى فشل التفعيل قبل تبديل وقت التشغيل.
• تقرأ طلبات وقت التشغيل من اللقطة النشطة داخل الذاكرة فقط.
• بعد أول تفعيل/تحميل ناجح للتكوين، تستمر مسارات كود وقت التشغيل في قراءة تلك اللقطة النشطة داخل الذاكرة حتى تستبدلها إعادة تحميل ناجحة.
• تقرأ مسارات التسليم الصادرة أيضًا من تلك اللقطة النشطة (على سبيل المثال تسليم الردود/السلاسل في Discord وإرسال إجراءات Telegram)؛ ولا تعيد حل SecretRefs عند كل إرسال.

​

حد وصول الوكيل

• تستخدم بيانات الاعتماد المدعومة SecretRefs بدلًا من القيم النصية الصريحة
• تمت إزالة بقايا النص الصريح القديمة من openclaw.json و auth-profiles.json و.env وملفات models.json المولدة
• يكون openclaw secrets audit --check نظيفًا بعد الترحيل
• تكون أي بيانات اعتماد متبقية غير مدعومة أو دورية محمية بعزل نظام التشغيل أو عزل الحاوية أو وكيل بيانات اعتماد خارجي

​

تصفية السطح النشط

• الأسطح المفعلة: تمنع المراجع غير المحلولة بدء التشغيل/إعادة التحميل.
• الأسطح غير النشطة: لا تمنع المراجع غير المحلولة بدء التشغيل/إعادة التحميل.
• تصدر المراجع غير النشطة تشخيصات غير قاتلة بالرمز SECRETS_REF_IGNORED_INACTIVE_SURFACE.

​

تشخيصات سطح مصادقة Gateway

• active: يكون SecretRef جزءًا من سطح المصادقة الفعلي ويجب حله.
• inactive: يتم تجاهل SecretRef لوقت التشغيل هذا لأن سطح مصادقة آخر يفوز، أو لأن المصادقة البعيدة معطلة/غير نشطة.

​

فحص مرجع التهيئة المسبق

• مراجع البيئة: تتحقق من اسم متغير البيئة وتؤكد أن قيمة غير فارغة مرئية أثناء الإعداد.
• مراجع المزود (file أو exec): تتحقق من اختيار المزود، وتحل id، وتفحص نوع القيمة المحلولة.
• مسار إعادة استخدام البدء السريع: عندما يكون gateway.auth.token هو SecretRef بالفعل، تحله التهيئة قبل تمهيد الفحص/لوحة المعلومات (لمراجع env وfile وexec) باستخدام بوابة الفشل السريع نفسها.

​

عقد 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: {
      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 المدعومة بالملفات

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

​

أمثلة تكامل 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 node
const { 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 --check
openclaw 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

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

​

مواد مصادقة 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.
• تُكتب القيم المحلولة إلى ملفات مؤقتة بأذونات مقيّدة وتُستخدم في إعدادات SSH المولّدة.
• إذا لم تكن الواجهة الخلفية الفعالة لبيئة العزل هي ssh، تبقى هذه المراجع غير نشطة ولا تمنع بدء التشغيل.

​

سطح بيانات الاعتماد المدعوم

• سطح بيانات اعتماد SecretRef

​

السلوك المطلوب والأسبقية

• حقل بدون مرجع: بلا تغيير.
• حقل مع مرجع: مطلوب على الأسطح النشطة أثناء التفعيل.
• إذا وُجد كل من النص الصريح والمرجع، تكون الأسبقية للمرجع على مسارات الأسبقية المدعومة.
• قيمة التنقيح الحارسة __OPENCLAW_REDACTED__ محجوزة لتنقيح/استعادة الإعدادات داخليًا وتُرفض كبيانات إعدادات حرفية مُرسلة.

• SECRETS_REF_OVERRIDES_PLAINTEXT (تحذير وقت التشغيل)
• REF_SHADOWED (نتيجة تدقيق عندما تكون لبيانات اعتماد auth-profiles.json الأسبقية على مراجع openclaw.json)

• تكون الأسبقية لـ serviceAccountRef على serviceAccount النصي الصريح.
• تُتجاهل القيمة النصية الصريحة عند ضبط المرجع المجاور.

​

محفزات التفعيل

• بدء التشغيل (فحص تمهيدي إضافة إلى التفعيل النهائي)
• مسار تطبيق إعادة تحميل الإعدادات الساخن
• مسار فحص إعادة التشغيل عند إعادة تحميل الإعدادات
• إعادة التحميل اليدوية عبر secrets.reload
• الفحص التمهيدي لـ RPC كتابة إعدادات Gateway (config.set / config.apply / config.patch) للتحقق من قابلية حل SecretRef على السطح النشط ضمن حمولة الإعدادات المُرسلة قبل حفظ التعديلات

• يستبدل النجاح اللقطة بشكل ذري.
• يؤدي فشل بدء التشغيل إلى إيقاف بدء Gateway.
• يُبقي فشل إعادة التحميل في وقت التشغيل آخر لقطة سليمة معروفة.
• يرفض فشل الفحص التمهيدي لـ Write-RPC الإعدادات المُرسلة ويُبقي إعدادات القرص ولقطة وقت التشغيل النشطة بلا تغيير.
• لا يؤدي تقديم رمز قناة صريح لكل استدعاء إلى استدعاء مساعد/أداة صادرة إلى تشغيل تفعيل SecretRef؛ تبقى نقاط التفعيل هي بدء التشغيل، وإعادة التحميل، وsecrets.reload الصريح.

​

إشارات التدهور والتعافي

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• متدهور: يحتفظ وقت التشغيل بآخر لقطة سليمة معروفة.
• متعافٍ: يُصدر مرة واحدة بعد التفعيل الناجح التالي.
• تسجل الإخفاقات المتكررة أثناء التدهور تحذيرات لكنها لا تغرق الأحداث.
• لا يصدر فشل بدء التشغيل السريع أحداث تدهور لأن وقت التشغيل لم يصبح نشطًا قط.

​

حل مسار الأوامر

• يتولى openclaw secrets reload تحديث اللقطة بعد تدوير أسرار الواجهة الخلفية.
• طريقة Gateway RPC المستخدمة بواسطة مسارات الأوامر هذه: secrets.resolve.

​

سير عمل التدقيق والتهيئة

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

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

​

سياسة السلامة أحادية الاتجاه

• يجب أن ينجح فحص ما قبل التنفيذ قبل وضع الكتابة
• يتم التحقق من تنشيط وقت التشغيل قبل الالتزام
• يحدّث التطبيق الملفات باستخدام استبدال ملف ذري واستعادة بأفضل جهد عند الفشل

​

ملاحظات توافق المصادقة القديمة

• مصدر بيانات اعتماد وقت التشغيل هو اللقطة المحلولة في الذاكرة.
• يتم تنقيح إدخالات api_key الثابتة القديمة عند اكتشافها.
• يظل سلوك التوافق المرتبط بـ OAuth منفصلًا.

​

ملاحظة Web UI

​

ذات صلة

• المصادقة — إعداد المصادقة
• CLI: الأسرار — أوامر CLI
• متغيرات البيئة — أسبقية البيئة
• سطح بيانات اعتماد SecretRef — سطح بيانات الاعتماد
• عقد خطة تطبيق الأسرار — تفاصيل عقد الخطة
• الأمان — الوضع الأمني