الانتقال إلى المحتوى الرئيسي
مساعدات إعدادات للتعديلات غير التفاعلية في openclaw.json: الحصول/التعيين/التصحيح/إلغاء التعيين/الملف/المخطط/التحقق من القيم حسب المسار وطباعة ملف الإعدادات النشط. شغّلها دون أمر فرعي لفتح معالج التهيئة (مثل openclaw configure).
عند تعيين OPENCLAW_NIX_MODE=1، يتعامل OpenClaw مع openclaw.json باعتباره غير قابل للتغيير. تظل الأوامر للقراءة فقط مثل config get وconfig file وconfig schema وconfig validate تعمل، لكن أوامر كتابة الإعدادات ترفض التنفيذ. ينبغي للوكلاء تعديل مصدر Nix الخاص بالتثبيت بدلا من ذلك؛ وبالنسبة لتوزيعة nix-openclaw الرسمية، استخدم البدء السريع في nix-openclaw واضبط القيم ضمن programs.openclaw.config أو instances.<name>.config.

​
خيارات الجذر

​
--section <section>
string
مرشح قسم إعداد موجه قابل للتكرار عند تشغيل openclaw config دون أمر فرعي.
الأقسام الموجهة المدعومة: workspace وmodel وweb وgateway وdaemon وchannels وplugins وskills وhealth.

​
أمثلة

openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

​
config schema

اطبع مخطط JSON المولّد لـ openclaw.json إلى stdout بصيغة JSON.
  • مخطط إعدادات الجذر الحالي، إضافة إلى حقل سلسلة $schema جذري لأدوات المحرر.
  • بيانات تعريف توثيقية للحقلين title وdescription تستخدمها واجهة Control UI.
  • ترث عقد الكائنات المتداخلة وحرف البدل (*) وعناصر المصفوفة ([]) بيانات تعريف title / description نفسها عند وجود توثيق مطابق للحقل.
  • ترث فروع anyOf / oneOf / allOf بيانات التعريف التوثيقية نفسها أيضا عند وجود توثيق مطابق للحقل.
  • بيانات تعريف مخطط Plugin + قناة مباشرة بأفضل جهد عندما يمكن تحميل بيانات manifest وقت التشغيل.
  • مخطط احتياطي نظيف حتى عندما تكون الإعدادات الحالية غير صالحة.
يعيد config.schema.lookup مسار إعدادات واحدا مطبّعا مع عقدة مخطط سطحية (title وdescription وtype وenum وconst والحدود الشائعة)، وبيانات تعريف تلميح واجهة مستخدم مطابقة، وملخصات الأبناء المباشرين. استخدمه للتنقل التفصيلي محدود المسار في Control UI أو العملاء المخصصين.
openclaw config schema
مرّره عبر أنبوب إلى ملف عندما تريد فحصه أو التحقق منه باستخدام أدوات أخرى: 
openclaw config schema > openclaw.schema.json

​
المسارات

تستخدم المسارات ترميز النقاط أو الأقواس. ضع مسارات ترميز الأقواس بين علامات اقتباس في أمثلة shell حتى لا توسع shells مثل zsh القيمة [0] كنمط glob قبل أن يتلقى OpenClaw المسار: 
openclaw config get agents.defaults.workspace
openclaw config get 'agents.list[0].id'
استخدم فهرس قائمة الوكلاء لاستهداف وكيل محدد: 
openclaw config get agents.list
openclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

​
القيم

تُحلل القيم كـ JSON5 عندما يكون ذلك ممكنا؛ وإلا فتُعامل كسلاسل. استخدم --strict-json لطلب تحليل JSON قياسي دون رجوع إلى السلاسل. يظل --json مدعوما كاسم بديل قديم لـ --strict-json. 
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
عند تفعيل --strict-json، تُرفض صياغة JSON5 فقط مثل التعليقات أو الفواصل اللاحقة أو مفاتيح الكائنات غير المقتبسة. احذف --strict-json لتحليل قيم JSON5 مع الرجوع إلى السلسلة الخام. يطبع config get <path> --json القيمة الخام بصيغة JSON بدلا من نص منسق للطرفية.
يستبدل إسناد الكائن المسار الهدف افتراضيا. ترفض مسارات الخرائط/القوائم المحمية التي تحتفظ عادة بمدخلات يضيفها المستخدم، مثل agents.defaults.models وmodels.providers وmodels.providers.<id>.models وplugins.entries وauth.profiles، عمليات الاستبدال التي قد تزيل مدخلات موجودة ما لم تمرر --replace.
استخدم --merge عند إضافة مدخلات إلى تلك الخرائط: 
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
استخدم --replace فقط عندما تريد عمدا أن تصبح القيمة المقدمة هي القيمة الهدف الكاملة.

​
أوضاع config set

يدعم openclaw config set أربعة أنماط إسناد: 
openclaw config set <path> <value>
تُرفض تعيينات SecretRef على الأسطح غير المدعومة والقابلة للتغيير وقت التشغيل (مثل hooks.token وcommands.ownerDisplaySecret ورموز Webhook ربط سلاسل Discord وبيانات اعتماد WhatsApp بصيغة JSON). راجع سطح بيانات اعتماد SecretRef.
يستخدم تحليل الدُفعات دائما حمولة الدُفعة (--batch-json/--batch-file) كمصدر الحقيقة. لا يغير --strict-json / --json سلوك تحليل الدُفعات.

​
config patch

استخدم config patch عندما تريد لصق أو تمرير تصحيح له شكل الإعدادات بدلا من تشغيل العديد من أوامر config set المعتمدة على المسارات. يكون الإدخال كائن JSON5. تُدمج الكائنات تكراريا، وتستبدل المصفوفات والقيم القياسية القيمة الهدف، وتحذف null المسار الهدف. 
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5
يمكنك أيضا تمرير تصحيح عبر stdin، وهذا مفيد لنصوص الإعداد عن بُعد: 
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
مثال تصحيح: 
{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      groupPolicy: "open",
      requireMention: false,
    },
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
      dmPolicy: "disabled",
      dm: { enabled: false },
      groupPolicy: "allowlist",
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
استخدم --replace-path <path> عندما يجب أن يصبح كائن أو مصفوفة واحدة القيمة المقدمة بالضبط بدلا من تصحيحها تكراريا: 
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
يشغّل --dry-run فحوصات المخطط وقابلية حل SecretRef دون كتابة. تُتخطى SecretRefs المدعومة بـ exec افتراضيا أثناء التشغيل التجريبي؛ أضف --allow-exec عندما تريد عمدا أن ينفذ التشغيل التجريبي أوامر المزوّد. يبقى وضع مسار/قيمة JSON مدعوما لكل من SecretRefs والمزوّدين: 
openclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

openclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
  --strict-json

​
علامات منشئ المزوّد

يجب أن تستخدم أهداف منشئ المزوّد secrets.providers.<alias> كمسار.
  • --provider-source <env|file|exec>
  • --provider-timeout-ms <ms> (file, exec)
  • --provider-allowlist <ENV_VAR> (قابل للتكرار)
  • --provider-path <path> (مطلوب)
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
  • --provider-command <path> (مطلوب)
  • --provider-arg <arg> (قابل للتكرار)
  • --provider-no-output-timeout-ms <ms>
  • --provider-max-output-bytes <bytes>
  • --provider-json-only
  • --provider-env <KEY=VALUE> (قابل للتكرار)
  • --provider-pass-env <ENV_VAR> (قابل للتكرار)
  • --provider-trusted-dir <path> (قابل للتكرار)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command
مثال لمزوّد exec محصّن: 
openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

​
تشغيل تجريبي

استخدم --dry-run للتحقق من التغييرات دون الكتابة إلى openclaw.json. 
openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run \
  --json

openclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec
  • وضع المنشئ: يشغّل فحوصات قابلية حل SecretRef للمراجع/المزوّدين الذين تغيّروا.
  • وضع JSON (--strict-json أو --json أو وضع الدُفعات): يشغّل التحقق من المخطط بالإضافة إلى فحوصات قابلية حل SecretRef.
  • يعمل التحقق من السياسة أيضًا لأسطح أهداف SecretRef المعروفة بأنها غير مدعومة.
  • تقيّم فحوصات السياسة التهيئة الكاملة بعد التغيير، لذلك لا يمكن لعمليات الكتابة على الكائن الأب (على سبيل المثال تعيين hooks ككائن) تجاوز التحقق من الأسطح غير المدعومة.
  • يتم تخطي فحوصات Exec SecretRef افتراضيًا أثناء التشغيل التجريبي لتجنب الآثار الجانبية للأوامر.
  • استخدم --allow-exec مع --dry-run للاشتراك في فحوصات Exec SecretRef (قد يؤدي ذلك إلى تنفيذ أوامر المزوّد).
  • --allow-exec مخصص للتشغيل التجريبي فقط ويُظهر خطأ إذا استُخدم بدون --dry-run.
يطبع --dry-run --json تقريرًا قابلًا للقراءة آليًا:
  • ok: ما إذا كان التشغيل التجريبي قد نجح
  • operations: عدد التعيينات التي تم تقييمها
  • checks: ما إذا كانت فحوصات المخطط/قابلية الحل قد شُغّلت
  • checks.resolvabilityComplete: ما إذا كانت فحوصات قابلية الحل قد اكتملت (false عند تخطي مراجع exec)
  • refsChecked: عدد المراجع التي تم حلها فعليًا أثناء التشغيل التجريبي
  • skippedExecRefs: عدد مراجع exec التي تم تخطيها لأن --allow-exec لم يكن معيّنًا
  • errors: إخفاقات منظمة للمسار المفقود أو المخطط أو قابلية الحل عندما تكون ok=false

​
شكل إخراج JSON

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder" | "unset", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "missing-path" | "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}
  • config schema validation failed: شكل التهيئة بعد التغيير غير صالح؛ أصلح المسار/القيمة أو شكل كائن المزوّد/المرجع.
  • Config policy validation failed: unsupported SecretRef usage: انقل بيانات الاعتماد هذه مرة أخرى إلى إدخال نص عادي/سلسلة نصية، وأبقِ SecretRefs على الأسطح المدعومة فقط.
  • SecretRef assignment(s) could not be resolved: لا يمكن حاليًا حل المزوّد/المرجع المشار إليه (متغير بيئة مفقود، مؤشر ملف غير صالح، فشل مزوّد exec، أو عدم تطابق بين المزوّد/المصدر).
  • Dry run note: skipped <n> exec SecretRef resolvability check(s): تخطى التشغيل التجريبي مراجع exec؛ أعد التشغيل باستخدام --allow-exec إذا كنت تحتاج إلى التحقق من قابلية حل exec.
  • في وضع الدُفعات، أصلح الإدخالات الفاشلة وأعد تشغيل --dry-run قبل الكتابة.

​
أمان الكتابة

يتحقق openclaw config set وكتّاب التهيئة الآخرون المملوكون لـ OpenClaw من التهيئة الكاملة بعد التغيير قبل حفظها على القرص. إذا فشل الحمولة الجديدة في التحقق من المخطط أو بدت كاستبدال هدّام، تُترك التهيئة النشطة كما هي وتُحفظ الحمولة المرفوضة بجانبها باسم openclaw.json.rejected.*.
يجب أن يكون مسار التهيئة النشطة ملفًا عاديًا. تخطيطات openclaw.json ذات الروابط الرمزية غير مدعومة للكتابة؛ استخدم OPENCLAW_CONFIG_PATH للإشارة مباشرة إلى الملف الحقيقي بدلًا من ذلك.
فضّل الكتابة عبر CLI للتعديلات الصغيرة: 
openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate
إذا رُفضت كتابة، افحص الحمولة المحفوظة وأصلح شكل التهيئة الكامل: 
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate
لا تزال الكتابة المباشرة بالمحرر مسموحة، لكن Gateway الجاري يعتبرها غير موثوقة حتى يتم التحقق منها. تؤدي التعديلات المباشرة غير الصالحة إلى فشل بدء التشغيل أو يتم تخطيها بواسطة إعادة التحميل الساخنة؛ لا يعيد Gateway كتابة openclaw.json. شغّل openclaw doctor --fix لإصلاح التهيئة ذات البادئات/المستبدلة بشكل خاطئ أو لاستعادة آخر نسخة جيدة معروفة. راجع استكشاف أخطاء Gateway وإصلاحها. استعادة الملف بالكامل مخصصة لإصلاح doctor. تبقى تغييرات مخطط Plugin أو انحراف minHostVersion واضحة بدلًا من التراجع عن إعدادات المستخدم غير المرتبطة مثل النماذج والمزوّدين وملفات تعريف المصادقة والقنوات وتعرّض Gateway والأدوات والذاكرة والمتصفح أو تهيئة cron.

​
الأوامر الفرعية

  • config file: اطبع مسار ملف التهيئة النشطة (المحلول من OPENCLAW_CONFIG_PATH أو الموقع الافتراضي). يجب أن يسمّي المسار ملفًا عاديًا، وليس رابطًا رمزيًا.
أعد تشغيل gateway بعد التعديلات.

​
التحقق

تحقق من التهيئة الحالية مقابل المخطط النشط بدون بدء Gateway. 
openclaw config validate
openclaw config validate --json
بعد أن ينجح openclaw config validate، يمكنك استخدام TUI المحلي لجعل وكيل مضمّن يقارن التهيئة النشطة بالوثائق أثناء تحققك من كل تغيير من الطرفية نفسها:
إذا كان التحقق يفشل بالفعل، فابدأ بـ openclaw configure أو openclaw doctor --fix. لا يتجاوز openclaw chat حارس التهيئة غير الصالحة.
openclaw chat
ثم داخل TUI: 
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
حلقة الإصلاح المعتادة:
1

المقارنة مع الوثائق

اطلب من الوكيل مقارنة التهيئة الحالية لديك بصفحة الوثائق ذات الصلة واقتراح أصغر إصلاح.
2

تطبيق تعديلات موجهة

طبّق تعديلات موجهة باستخدام openclaw config set أو openclaw configure.
3

إعادة التحقق

أعد تشغيل openclaw config validate بعد كل تغيير.
4

Doctor لمشكلات وقت التشغيل

إذا نجح التحقق لكن وقت التشغيل لا يزال غير سليم، فشغّل openclaw doctor أو openclaw doctor --fix للحصول على مساعدة في الترحيل والإصلاح.

​
ذو صلة