واجهة بيانات اعتماد SecretRef

تحدد هذه الصفحة السطح القياسي لبيانات اعتماد SecretRef: أي حقول بيانات الاعتماد تقبل SecretRef (مرجعًا مدعومًا بمتغيرات البيئة/ملف/تنفيذ) بدلًا من قيمة سر خام.

النطاق:

• ضمن النطاق: بيانات الاعتماد التي يقدّمها المستخدم حصرًا، والتي لا ينشئها OpenClaw ولا يدوّرها.
• خارج النطاق: بيانات الاعتماد التي تُنشأ أو تُدوّر في وقت التشغيل، ومواد تحديث OAuth، والآثار الشبيهة بالجلسات.

تُنشأ القوائم أدناه من سجل الأهداف المصدري وتُفحص مقابل docs/reference/secretref-user-supplied-credentials-matrix.json في CI؛ لا تعدّل الإدخالات يدويًا.

بيانات الاعتماد المدعومة

أهداف openclaw.json ‏(secrets configure + secrets apply + secrets audit)

• models.providers.*.apiKey
• models.providers.*.headers.*
• models.providers.*.request.auth.token
• models.providers.*.request.auth.value
• models.providers.*.request.headers.*
• models.providers.*.request.proxy.tls.ca
• models.providers.*.request.proxy.tls.cert
• models.providers.*.request.proxy.tls.key
• models.providers.*.request.proxy.tls.passphrase
• models.providers.*.request.tls.ca
• models.providers.*.request.tls.cert
• models.providers.*.request.tls.key
• models.providers.*.request.tls.passphrase
• skills.entries.*.apiKey
• agents.defaults.memorySearch.remote.apiKey
• agents.list[].tts.providers.*.apiKey
• agents.list[].memorySearch.remote.apiKey
• talk.providers.*.apiKey
• talk.realtime.providers.*.apiKey
• messages.tts.providers.*.apiKey
• tools.web.fetch.firecrawl.apiKey
• plugins.entries.acpx.config.mcpServers.*.env.*
• plugins.entries.brave.config.webSearch.apiKey
• plugins.entries.codex.config.appServer.authToken
• plugins.entries.codex.config.appServer.headers.*
• plugins.entries.exa.config.webSearch.apiKey
• plugins.entries.google-meet.config.realtime.providers.*.apiKey
• plugins.entries.google.config.webSearch.apiKey
• plugins.entries.xai.config.webSearch.apiKey
• plugins.entries.moonshot.config.webSearch.apiKey
• plugins.entries.perplexity.config.webSearch.apiKey
• plugins.entries.firecrawl.config.webSearch.apiKey
• plugins.entries.minimax.config.webSearch.apiKey
• plugins.entries.tavily.config.webSearch.apiKey
• plugins.entries.parallel.config.webSearch.apiKey
• plugins.entries.voice-call.config.realtime.providers.*.apiKey
• plugins.entries.voice-call.config.streaming.providers.*.apiKey
• plugins.entries.voice-call.config.tts.providers.*.apiKey
• plugins.entries.voice-call.config.twilio.authToken
• tools.web.search.*.apiKey
• tools.web.search.apiKey
• gateway.auth.password
• gateway.auth.token
• gateway.remote.token
• gateway.remote.password
• cron.webhookToken
• channels.telegram.botToken
• channels.telegram.webhookSecret
• channels.telegram.accounts.*.botToken
• channels.telegram.accounts.*.webhookSecret
• channels.slack.botToken
• channels.slack.appToken
• channels.slack.relay.authToken
• channels.slack.userToken
• channels.slack.signingSecret
• channels.slack.accounts.*.botToken
• channels.slack.accounts.*.appToken
• channels.slack.accounts.*.relay.authToken
• channels.slack.accounts.*.userToken
• channels.slack.accounts.*.signingSecret
• channels.sms.authToken
• channels.sms.accounts.*.authToken
• channels.clickclack.token
• channels.clickclack.accounts.*.token
• channels.discord.token
• channels.discord.pluralkit.token
• channels.discord.voice.tts.providers.*.apiKey
• channels.discord.accounts.*.token
• channels.discord.accounts.*.pluralkit.token
• channels.discord.accounts.*.voice.tts.providers.*.apiKey
• channels.irc.password
• channels.irc.nickserv.password
• channels.irc.accounts.*.password
• channels.irc.accounts.*.nickserv.password
• channels.feishu.appSecret
• channels.feishu.encryptKey
• channels.feishu.verificationToken
• channels.feishu.accounts.*.appSecret
• channels.feishu.accounts.*.encryptKey
• channels.feishu.accounts.*.verificationToken
• channels.qqbot.clientSecret
• channels.qqbot.accounts.*.clientSecret
• channels.msteams.appPassword
• channels.mattermost.botToken
• channels.mattermost.accounts.*.botToken
• channels.matrix.accessToken
• channels.matrix.password
• channels.matrix.accounts.*.accessToken
• channels.matrix.accounts.*.password
• channels.nextcloud-talk.botSecret
• channels.nextcloud-talk.apiPassword
• channels.nextcloud-talk.accounts.*.botSecret
• channels.nextcloud-talk.accounts.*.apiPassword
• channels.zalo.botToken
• channels.zalo.webhookSecret
• channels.zalo.accounts.*.botToken
• channels.zalo.accounts.*.webhookSecret
• channels.googlechat.serviceAccount عبر serviceAccountRef الشقيق (استثناء توافق)
• channels.googlechat.accounts.*.serviceAccount عبر serviceAccountRef الشقيق (استثناء توافق)

أهداف auth-profiles.json ‏(secrets configure + secrets apply + secrets audit)

• profiles.*.keyRef ‏(type: "api_key"؛ غير مدعوم عند auth.profiles.<id>.mode = "oauth")
• profiles.*.tokenRef ‏(type: "token"؛ غير مدعوم عند auth.profiles.<id>.mode = "oauth")

ملاحظات:

• تتطلب أهداف خطة ملف تعريف المصادقة agentId؛ تستهدف إدخالات الخطة profiles.*.key / profiles.*.token وتكتب المراجع الشقيقة (keyRef / tokenRef). تُضمَّن مراجع ملف تعريف المصادقة في حل وقت التشغيل وتغطية التدقيق.
• في openclaw.json، يجب أن تستخدم SecretRefs كائنات منظّمة مثل {"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}. تُرفض سلاسل علامات secretref-env:<ENV_VAR> القديمة في مسارات بيانات اعتماد SecretRef؛ شغّل openclaw doctor --fix لترحيل العلامات الصالحة.
• حارس سياسة OAuth: لا يمكن دمج auth.profiles.<id>.mode = "oauth" مع مدخلات SecretRef لذلك الملف التعريفي. يفشل بدء التشغيل/إعادة التحميل وحل ملف تعريف المصادقة مبكرًا عند انتهاك هذه السياسة.
• بالنسبة إلى موفري النماذج المُدارة بواسطة SecretRef، تحتفظ إدخالات agents/*/agent/models.json المُنشأة بعلامات غير سرية (وليس قيم الأسرار المحلولة) لأسطح apiKey/الترويسة. يستند الاحتفاظ بالعلامات إلى المصدر بوصفه المرجع المعتمد: يكتب OpenClaw العلامات من لقطة إعدادات المصدر النشطة (قبل الحل)، وليس من قيم أسرار وقت التشغيل المحلولة.
• بالنسبة إلى بحث الويب: في وضع الموفّر الصريح (عند تعيين tools.web.search.provider)، لا يكون نشطًا إلا مفتاح الموفّر المحدد. وفي الوضع التلقائي (عند عدم تعيين tools.web.search.provider)، لا يكون نشطًا إلا أول مفتاح موفّر يُحل وفق ترتيب الأولوية، وتُعامل مراجع الموفّرين غير المحددين على أنها غير نشطة إلى أن تُحدد. تظل مسارات موفّر tools.web.search.* القديمة قابلة للحل خلال فترة التوافق، لكن سطح SecretRef القياسي هو plugins.entries.<plugin>.config.webSearch.*.

بيانات الاعتماد غير المدعومة

بيانات الاعتماد هذه من فئات تُنشأ أو تُدوّر أو تحمل جلسات أو تستمر عبر OAuth، ولذلك لا تتوافق مع حل SecretRef الخارجي المخصص للقراءة فقط:

• commands.ownerDisplaySecret
• hooks.token
• hooks.gmail.pushToken
• hooks.mappings[].sessionKey
• auth-profiles.oauth.*
• channels.discord.threadBindings.webhookToken
• channels.discord.accounts.*.threadBindings.webhookToken
• channels.whatsapp.creds.json
• channels.whatsapp.accounts.*.creds.json

ذو صلة

• إدارة الأسرار
• دلالات بيانات اعتماد المصادقة