OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

الإعدادات

مساعدات غير تفاعلية لملف openclaw.json: جلب قيمة أو تعيينها أو ترقيعها أو إلغاء تعيينها حسب المسار، أو طباعة المخطط، أو التحقق من الصحة، أو طباعة مسار الملف النشط. شغّل openclaw config من دون أمر فرعي لفتح المعالج الإرشادي نفسه الذي يفتحه openclaw configure.

خيارات الجذر

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> مرشّح قابل للتكرار لقسم الإعداد الإرشادي عند تشغيل openclaw config من دون أمر فرعي.

الأقسام الإرشادية: workspace وmodel وweb وgateway وdaemon وchannels وplugins وskills وhealth.

أمثلة

bash
openclaw config fileopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config get browser.executablePathopenclaw 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 --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw config validate --json

المسارات

ترميز بالنقاط أو الأقواس. ضع مسارات الأقواس بين علامتَي اقتباس في أمثلة الصدفة حتى لا يوسّع zsh النمط [0]:

bash
openclaw config get agents.defaults.workspaceopenclaw config get 'agents.list[0].id'openclaw config get agents.listopenclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

config get

يقرأ قيمة من لقطة الإعدادات المنقّحة (لا تُطبع الأسرار مطلقًا). يطبع --json القيمة الأولية بصيغة JSON؛ وإلا فتُطبع السلاسل والأرقام والقيم المنطقية مباشرة، بينما تُطبع الكائنات والمصفوفات بصيغة JSON منسّقة.

bash
openclaw config get browser.executablePathopenclaw config get agents.defaults.model --json

config file

يطبع مسار ملف الإعدادات النشط، المحسوم من OPENCLAW_CONFIG_PATH أو الموقع الافتراضي. يشير المسار إلى ملف عادي، وليس رابطًا رمزيًا؛ راجع سلامة الكتابة.

config schema

يطبع مخطط JSON المُنشأ لملف openclaw.json إلى المخرج القياسي.

ما يتضمنه
  • مخطط إعدادات الجذر الحالي، إضافة إلى حقل سلسلة $schema في الجذر لأدوات المحرر.
  • بيانات توثيق الحقلين title وdescription التي تستخدمها واجهة التحكم.
  • ترث عُقد الكائنات المتداخلة وأحرف البدل (*) وعناصر المصفوفة ([]) بيانات title وdescription نفسها عند وجود توثيق مطابق للحقول.
  • ترث فروع anyOf وoneOf وallOf بيانات التوثيق نفسها أيضًا.
  • بيانات مخطط وصفية مباشرة للـ Plugin والقناة بأفضل جهد ممكن عندما يمكن تحميل بيانات وقت التشغيل.
  • مخطط احتياطي نظيف حتى عندما تكون الإعدادات الحالية غير صالحة.
استدعاء RPC المرتبط بوقت التشغيل

يعيد config.schema.lookup مسار إعدادات واحدًا بعد تسويته، مع عقدة مخطط سطحية (title وdescription وtype وenum وconst والحدود الشائعة)، وبيانات تلميحات واجهة المستخدم المطابقة، وملخصات الأبناء المباشرين. استخدمه للتعمق ضمن نطاق المسار في واجهة التحكم أو في العملاء المخصصين.

bash
openclaw config schemaopenclaw config schema > openclaw.schema.json

config validate

يتحقق من صحة الإعدادات الحالية مقابل المخطط النشط من دون تشغيل Gateway.

bash
openclaw config validateopenclaw config validate --json

القيم

تُحلّل القيم بصيغة JSON5 متى أمكن؛ وإلا فتُعامل بوصفها سلاسل أولية. استخدم --strict-json لفرض JSON القياسي من دون الرجوع إلى السلاسل (وعندئذ يُرفض بناء الجملة الخاص بـ JSON5 فقط، مثل التعليقات أو الفواصل الختامية أو المفاتيح غير الموضوعة بين علامتَي اقتباس). يُعد --json اسمًا بديلًا قديمًا لـ --strict-json في config set.

bash
openclaw config set agents.defaults.heartbeat.every "0m"openclaw config set gateway.port 19001 --strict-jsonopenclaw config set channels.whatsapp.groups '["*"]' --strict-json

يطبع config get <path> --json القيمة الأولية بصيغة JSON بدلًا من نص منسّق للطرفية.

استخدم --merge عند إضافة إدخالات إلى هذه الخرائط:

bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

استخدم --replace فقط عندما يُراد عمدًا أن تصبح القيمة المقدمة هي القيمة الكاملة للهدف.

أوضاع config set

وضع القيمة

bash
openclaw config set <path> <value>

وضع إنشاء SecretRef

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

وضع إنشاء المزوّد

يستهدف مسارات secrets.providers.<alias> فقط:

bash
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-timeout-ms 5000

الوضع الدفعي

bash
openclaw config set --batch-json '[  {    "path": "secrets.providers.default",    "provider": { "source": "env" }  },  {    "path": "channels.discord.token",    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }  }]'
bash
openclaw config set --batch-file ./config-set.batch.json --dry-run

يستخدم التحليل الدفعي دائمًا حمولة الدفعة (--batch-json/--batch-file) بوصفها مصدر الحقيقة؛ ولا يغيّر --strict-json أو --json سلوك التحليل الدفعي.

يعمل وضع المسار/القيمة بصيغة JSON أيضًا مباشرة مع SecretRefs والمزوّدين:

bash
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-source env)
  • --provider-allowlist &lt;ENV_VAR&gt; (قابل للتكرار)
مزوّد الملفات (--provider-source file)
  • --provider-path <path> (مطلوب)
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
مزوّد التنفيذ (--provider-source exec)
  • --provider-command <path> (مطلوب)
  • --provider-arg <arg> (قابل للتكرار)
  • --provider-no-output-timeout-ms <ms>
  • --provider-max-output-bytes <bytes>
  • --provider-json-only
  • --provider-env &lt;KEY=VALUE&gt; (قابل للتكرار)
  • --provider-pass-env &lt;ENV_VAR&gt; (قابل للتكرار)
  • --provider-trusted-dir <path> (قابل للتكرار)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command

مثال على مزوّد تنفيذ محصّن:

bash
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

config patch

الصق أو مرّر عبر أنبوب ترقيعًا للإعدادات بصيغة JSON5 بدلًا من تشغيل العديد من أوامر config set المعتمدة على المسار. تُدمج الكائنات بشكل متكرر؛ وتستبدل المصفوفات والقيم القياسية الهدف؛ وتحذف null المسار الهدف.

bash
openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config patch --file ./openclaw.patch.json5

مرّر ترقيعًا عبر الإدخال القياسي لبرامج الإعداد النصية البعيدة:

bash
ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

مثال على ترقيع:

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.6-sol" },      models: {        "openai/gpt-5.6-sol": { params: { fastMode: true } },      },    },  },}

استخدم --replace-path <path> عندما يجب أن يصبح أحد الكائنات أو المصفوفات مساويًا تمامًا للقيمة المقدمة بدلًا من ترقيعه بشكل متكرر:

bash
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

يشغّل --dry-run فحوصات المخطط وقابلية حل SecretRef من دون كتابة. تُتخطى SecretRefs المدعومة بالتنفيذ افتراضيًا أثناء التشغيل التجريبي؛ أضف --allow-exec عندما تريد عمدًا أن ينفّذ التشغيل التجريبي أوامر المزوّد.

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

يتحقق --dry-run من صحة التغييرات من دون الكتابة إلى openclaw.json. وهو متاح مع config set وconfig patch وconfig unset.

bash
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.
  • يُجرى التحقق من السياسة على الإعداد الكامل بعد التغيير، لذا لا يمكن لعمليات الكتابة إلى الكائن الأب (مثل تعيين hooks ككائن) تجاوز التحقق من الأسطح غير المدعومة.
  • تُتخطى فحوصات SecretRef من نوع exec افتراضيًا لتجنب الآثار الجانبية للأوامر؛ مرّر --allow-exec للاشتراك فيها (قد يؤدي ذلك إلى تنفيذ أوامر المزوّد). لا يعمل --allow-exec إلا مع التشغيل التجريبي، ويُصدر خطأ عند استخدامه من دون --dry-run.
حقول --dry-run --json
  • ok: ما إذا نجح التشغيل التجريبي
  • operations: عدد عمليات التعيين التي جرى تقييمها
  • checks: ما إذا أُجريت فحوصات المخطط/قابلية الحل
  • checks.resolvabilityComplete: ما إذا اكتملت فحوصات قابلية الحل (تكون false عند تخطي مراجع exec)
  • refsChecked: عدد المراجع التي جرى حلها فعليًا أثناء التشغيل التجريبي
  • skippedExecRefs: عدد مراجع exec التي جرى تخطيها لأن --allow-exec لم يكن معيّنًا
  • errors: إخفاقات منظّمة للمسار المفقود أو المخطط أو قابلية الحل عندما تكون ok=false

بنية مخرجات JSON

json5
{  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, // موجود لأخطاء قابلية الحل    },  ],}

مثال على النجاح

json
{  "ok": true,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0}

مثال على الإخفاق

json
{  "ok": false,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0,  "errors": [    {      "kind": "resolvability",      "message": "خطأ: متغير البيئة \"MISSING_TEST_SECRET\" غير معيّن.",      "ref": "env:default:MISSING_TEST_SECRET"    }  ]}
إذا فشل التشغيل التجريبي
  • 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): أعد التشغيل باستخدام --allow-exec إذا كنت تحتاج إلى التحقق من قابلية حل exec.
  • في وضع الدُفعات، أصلح الإدخالات الفاشلة وأعد تشغيل --dry-run قبل الكتابة.

تطبيق التغييرات

بعد كل عملية ناجحة من config set أو config patch أو config unset، تطبع CLI أحد التلميحات الثلاثة التالية لتعرف ما إذا كان Gateway يحتاج إلى إعادة تشغيل:

التلميح المعنى
Restart the gateway to apply. يحتاج المسار الذي جرى تغييره إلى إعادة تشغيل كاملة.
Change will apply without restarting the gateway. يلتقطه إعادة التحميل الفوري تلقائيًا.
No gateway restart needed. لم يتغير شيء ذو صلة بوقت التشغيل.

تتطلب عمليات الكتابة إلى plugins.entries (أو أي مسار فرعي له) إعادة تشغيل دائمًا، لأن CLI لا يمكنها إثبات تحميل بيانات إعادة التحميل الوصفية لكل Plugin.

أمان الكتابة

يتحقق openclaw config set وغيره من أدوات كتابة الإعداد المملوكة لـ OpenClaw من صحة الإعداد الكامل بعد التغيير قبل حفظه على القرص. إذا فشلت الحمولة الجديدة في التحقق من صحة المخطط أو بدت كاستبدال هدّام، يُترك الإعداد النشط دون تغيير، وتُحفظ الحمولة المرفوضة بجانبه باسم openclaw.json.rejected.*.

فضّل الكتابة عبر CLI للتعديلات الصغيرة:

bash
openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate

إذا رُفضت عملية كتابة، فافحص الحمولة المحفوظة وأصلح بنية الإعداد الكاملة:

bash
CONFIG="$(openclaw config file)"ls -lt "$CONFIG".rejected.* 2>/dev/null | headopenclaw config validate

لا تزال الكتابة المباشرة عبر المحرر مسموحة، لكن Gateway الجاري يعاملها على أنها غير موثوقة حتى تجتاز التحقق. تؤدي التعديلات المباشرة غير الصالحة إلى فشل بدء التشغيل أو يتخطاها إعادة التحميل الفوري؛ ولا يعيد Gateway كتابة openclaw.json. شغّل openclaw doctor --fix لإصلاح الإعداد ذي البادئات/المستبدل أو لاستعادة آخر نسخة سليمة معروفة. راجع استكشاف أخطاء Gateway وإصلاحها.

يُحجز استرداد الملف بالكامل لإصلاح doctor. وتظل تغييرات مخطط Plugin أو عدم توافق minHostVersion ظاهرة بوضوح بدلًا من التراجع عن إعدادات مستخدم غير مرتبطة، مثل إعدادات النماذج أو المزوّدين أو ملفات تعريف المصادقة أو القنوات أو إتاحة Gateway أو الأدوات أو الذاكرة أو المتصفح أو cron.

حلقة الإصلاح

بعد نجاح openclaw config validate، استخدم TUI المحلي ليقارن وكيل مضمّن الإعداد النشط بالوثائق بينما تتحقق من كل تغيير من الطرفية نفسها:

bash
openclaw chat

داخل TUI، يؤدي الرمز ! في البداية إلى تشغيل أمر shell محلي حرفيًا (بعد مطالبة تأكيد لمرة واحدة في كل جلسة):

text
!openclaw config file!openclaw docs gateway auth token secretref!openclaw config validate!openclaw doctor

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

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

  • تطبيق تعديلات محددة

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

  • إعادة التحقق

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

  • استخدام doctor لمشكلات وقت التشغيل

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

    • ذو صلة

    Was this useful?
    On this page

    On this page