الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

مساعدات الإعداد للتعديلات غير التفاعلية في 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

​
المسارات

تستخدم المسارات ترميز النقاط أو الأقواس: 
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 لاشتراط تحليل JSON5. يظل --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
يطبع 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، وJSON بيانات اعتماد WhatsApp). راجع سطح بيانات اعتماد 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 ككائن) تجاوز التحقق من الأسطح غير المدعومة.
  • تُتخطى فحوصات SecretRef من نوع Exec افتراضياً أثناء التشغيل التجريبي لتجنب الآثار الجانبية للأوامر.
  • استخدم --allow-exec مع --dry-run للاشتراك في فحوصات SecretRef من نوع exec (قد ينفّذ هذا أوامر المزوّد).
  • --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", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "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: شكل الإعدادات بعد التغيير غير صالح؛ أصلح المسار/القيمة أو شكل كائن المزود/ref.
  • Config policy validation failed: unsupported SecretRef usage: انقل بيانات الاعتماد تلك مرة أخرى إلى إدخال نص عادي/سلسلة نصية، وأبقِ SecretRefs على الأسطح المدعومة فقط.
  • SecretRef assignment(s) could not be resolved: لا يمكن حاليًا حل المزود/ref المشار إليه (متغير بيئة مفقود، مؤشر ملف غير صالح، فشل مزود 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

Compare with docs

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

Apply targeted edits

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

Re-validate

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

Doctor for runtime issues

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

​
ذات صلة