Gateway
مرجع التكوين
مرجع إعدادات النواة لـ ~/.openclaw/openclaw.json. للحصول على نظرة عامة موجّهة بالمهام، راجع التهيئة.
يغطي أسطح إعدادات OpenClaw الرئيسية ويربط إلى الخارج عندما يكون لدى نظام فرعي مرجعه الأعمق الخاص. توجد فهارس الأوامر المملوكة للقنوات وPlugins ومفاتيح الذاكرة العميقة/QMD في صفحاتها الخاصة بدلا من هذه الصفحة.
حقيقة الكود:
- يطبع
openclaw config schemaمخطط JSON الحي المستخدم للتحقق وControl UI، مع دمج بيانات التعريف المجمعة/الخاصة بـPlugin/القناة عند توفرها - يعيد
config.schema.lookupعقدة مخطط واحدة محددة النطاق بالمسار لأدوات التنقيب التفصيلي - يتحقق
pnpm config:docs:check/pnpm config:docs:genمن تجزئة خط أساس وثائق الإعدادات مقابل سطح المخطط الحالي
مسار بحث الوكيل: استخدم إجراء أداة gateway المسمى config.schema.lookup للحصول على
وثائق وقيود دقيقة على مستوى الحقل قبل التحرير. استخدم
التهيئة للإرشادات الموجهة بالمهام وهذه الصفحة
لخريطة الحقول الأوسع، والقيم الافتراضية، والروابط إلى مراجع الأنظمة الفرعية.
مراجع عميقة مخصصة:
- مرجع تهيئة الذاكرة لـ
agents.defaults.memorySearch.*وmemory.qmd.*وmemory.citationsوإعدادات dreaming ضمنplugins.entries.memory-core.config.dreaming - أوامر الشرطة المائلة لفهرس الأوامر الحالي المدمج + المجمع
- صفحات القناة/Plugin المالكة لأسطح الأوامر الخاصة بالقنوات
تنسيق الإعدادات هو JSON5 (يسمح بالتعليقات + الفواصل اللاحقة). كل الحقول اختيارية - يستخدم OpenClaw قيما افتراضية آمنة عند حذفها.
القنوات
انتقلت مفاتيح إعدادات كل قناة إلى صفحة مخصصة - راجع
التهيئة - القنوات لـ channels.*،
بما في ذلك Slack وDiscord وTelegram وWhatsApp وMatrix وiMessage وقنوات
مجمعة أخرى (المصادقة، التحكم في الوصول، تعدد الحسابات، بوابة الإشارات).
افتراضيات الوكيل، وتعدد الوكلاء، والجلسات، والرسائل
انتقلت إلى صفحة مخصصة - راجع التهيئة - الوكلاء من أجل:
agents.defaults.*(مساحة العمل، النموذج، التفكير، heartbeat، الذاكرة، الوسائط، Skills، sandbox)multiAgent.*(توجيه تعدد الوكلاء والارتباطات)session.*(دورة حياة الجلسة، Compaction، التشذيب)messages.*(تسليم الرسائل، TTS، عرض markdown)talk.*(وضع Talk)talk.consultThinkingLevel: تجاوز مستوى التفكير لتشغيل وكيل OpenClaw الكامل خلف استشارات Control UI Talk الفوريةtalk.consultFastMode: تجاوز لمرة واحدة لوضع السرعة لاستشارات Control UI Talk الفوريةtalk.speechLocale: معرف لغة BCP 47 اختياري للتعرف على الكلام في Talk على iOS/macOStalk.silenceTimeoutMs: عند عدم تعيينه، يحتفظ Talk بنافذة التوقف الافتراضية للمنصة قبل إرسال النص (700 ms on macOS and Android, 900 ms on iOS)talk.realtime.consultRouting: مسار احتياطي لترحيل Gateway لنصوص Talk الفورية النهائية التي تتجاوزopenclaw_agent_consult
الأدوات والمزودون المخصصون
انتقلت سياسة الأدوات، والمفاتيح التجريبية، وإعدادات الأدوات المدعومة بالمزود، وإعداد المزود المخصص / عنوان URL الأساسي إلى صفحة مخصصة - راجع التهيئة - الأدوات والمزودون المخصصون.
النماذج
توجد تعريفات المزودين، وقوائم السماح للنماذج، وإعداد المزود المخصص في
التهيئة - الأدوات والمزودون المخصصون.
يمتلك جذر models أيضا سلوك فهرس النماذج العام.
{ models: { // Optional. Default: true. Requires a Gateway restart when changed. pricing: { enabled: false }, },}models.mode: سلوك فهرس المزود (mergeأوreplace).models.providers: خريطة المزودين المخصصين المفهرسة حسب معرف المزود.models.providers.*.localService: مدير عمليات اختياري عند الطلب لخوادم النماذج المحلية. يفحص OpenClaw نقطة نهاية الصحة المهيأة، ويبدأcommandالمطلق عند الحاجة، وينتظر الجاهزية، ثم يرسل طلب النموذج. راجع خدمات النماذج المحلية.models.pricing.enabled: يتحكم في تمهيد التسعير الخلفي الذي يبدأ بعد أن تصل العمليات الجانبية والقنوات إلى مسار جاهزية Gateway. عندfalse، يتجاوز Gateway جلب فهارس أسعار OpenRouter وLiteLLM؛ وتظل قيمmodels.providers.*.models[].costالمهيأة تعمل لتقديرات التكلفة المحلية.
MCP
توجد تعريفات خوادم MCP التي يديرها OpenClaw ضمن mcp.servers وتستهلكها
OpenClaw المضمنة ومحولات وقت التشغيل الأخرى. تدير أوامر openclaw mcp list و
show وset وunset هذه الكتلة دون الاتصال بالخادم
الهدف أثناء تحرير الإعدادات.
{ mcp: { // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction. sessionIdleTtlMs: 600000, servers: { docs: { command: "npx", args: ["-y", "@modelcontextprotocol/server-fetch"], }, remote: { url: "https://example.com/mcp", transport: "streamable-http", // streamable-http | sse timeout: 20, connectTimeout: 5, supportsParallelToolCalls: true, headers: { Authorization: "Bearer ${MCP_REMOTE_TOKEN}", }, auth: "oauth", oauth: { scope: "docs.read", }, sslVerify: true, clientCert: "/path/to/client.crt", clientKey: "/path/to/client.key", toolFilter: { include: ["search_*"], exclude: ["admin_*"], }, // Optional Codex app-server projection controls. codex: { agents: ["main"], defaultToolsApprovalMode: "approve", // auto | prompt | approve }, }, }, },}mcp.servers: تعريفات خوادم MCP مسماة من نوع stdio أو بعيدة لأوقات التشغيل التي تعرض أدوات MCP المهيأة. تستخدم الإدخالات البعيدةtransport: "streamable-http"أوtransport: "sse"؛ أماtype: "http"فهو اسم مستعار أصيل في CLI تقومopenclaw mcp setوopenclaw doctor --fixبتطبيعه إلى حقلtransportالقياسي.mcp.servers.<name>.enabled: عيّنه إلىfalseللاحتفاظ بتعريف خادم محفوظ مع استبعاده من اكتشاف MCP المضمن في OpenClaw وإسقاط الأدوات.mcp.servers.<name>.timeout/requestTimeoutMs: مهلة طلب MCP لكل خادم بالثواني أو المللي ثانية.mcp.servers.<name>.connectTimeout/connectionTimeoutMs: مهلة الاتصال لكل خادم بالثواني أو المللي ثانية.mcp.servers.<name>.supportsParallelToolCalls: تلميح تزامن اختياري للمحولات التي يمكنها اختيار ما إذا كانت ستصدر استدعاءات أدوات MCP متوازية.mcp.servers.<name>.auth: عيّنه إلى"oauth"لخوادم MCP عبر HTTP التي تتطلب OAuth. شغّلopenclaw mcp login <name>لتخزين الرموز ضمن حالة OpenClaw.mcp.servers.<name>.oauth: تجاوزات اختيارية لنطاق OAuth، وعنوان URL لإعادة التوجيه، وعنوان URL لبيانات تعريف العميل.mcp.servers.<name>.sslVerifyوclientCertوclientKey: عناصر تحكم HTTP TLS للنقاط النهائية الخاصة وTLS المتبادل.mcp.servers.<name>.toolFilter: اختيار أدوات اختياري لكل خادم. يحدincludeأدوات MCP المكتشفة إلى الأسماء المطابقة؛ ويخفيexcludeالأسماء المطابقة. الإدخالات هي أسماء أدوات MCP دقيقة أو أنماط*بسيطة. تولد الخوادم التي لديها موارد أو مطالبات أيضا أسماء أدوات مساعدة (resources_list،resources_read،prompts_list،prompts_get)، وتستخدم تلك الأسماء المرشح نفسه.mcp.servers.<name>.codex: عناصر تحكم اختيارية لإسقاط خادم تطبيق Codex. هذه الكتلة هي بيانات تعريف OpenClaw لسلاسل خادم تطبيق Codex فقط؛ ولا تؤثر في جلسات ACP، أو إعدادات حزمة Codex العامة، أو محولات وقت التشغيل الأخرى. يحدcodex.agentsغير الفارغ الخادم إلى معرفات وكلاء OpenClaw المدرجة. ترفض عملية التحقق من الإعدادات قوائم الوكلاء المحددة النطاق الفارغة أو الخالية أو غير الصالحة ويحذفها مسار إسقاط وقت التشغيل بدلا من أن تصبح عامة. يصدرcodex.defaultToolsApprovalModeقيمة Codex الأصليةdefault_tools_approval_modeلذلك الخادم. يزيل OpenClaw كتلةcodexقبل تمرير إعداداتmcp_serversالأصلية إلى Codex. احذف الكتلة لإبقاء الخادم مسقطا لكل وكيل خادم تطبيق Codex مع سلوك موافقة MCP الافتراضي في Codex.mcp.sessionIdleTtlMs: مدة TTL للخمول لأوقات تشغيل MCP المجمعة محددة النطاق بالجلسة. تطلب عمليات التشغيل المضمنة لمرة واحدة تنظيف نهاية التشغيل؛ وتمثل مدة TTL هذه خط الرجوع للجلسات طويلة العمر والمستدعين المستقبليين.- تطبق التغييرات ضمن
mcp.*فوريا عبر التخلص من أوقات تشغيل MCP المخزنة مؤقتا للجلسة. يعيد اكتشاف/استخدام الأداة التالي إنشاءها من الإعدادات الجديدة، لذلك تزال إدخالاتmcp.serversالمحذوفة فورا بدلا من انتظار مدة TTL للخمول. - يراعي اكتشاف وقت التشغيل أيضا إشعارات تغيير قائمة أدوات MCP عبر إسقاط الفهرس المخزن مؤقتا لتلك الجلسة. تحصل الخوادم التي تعلن موارد أو مطالبات على أدوات مساعدة لسرد/قراءة الموارد وسرد/جلب المطالبات. توقف إخفاقات استدعاء الأدوات المتكررة الخادم المتأثر مؤقتا قبل محاولة استدعاء آخر.
راجع MCP و واجهات CLI الخلفية لسلوك وقت التشغيل.
Skills
{ skills: { allowBundled: ["gemini", "peekaboo"], load: { extraDirs: ["~/Projects/agent-scripts/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, install: { preferBrew: true, nodeManager: "npm", // npm | pnpm | yarn | bun allowUploadedArchives: false, }, workshop: { allowSymlinkTargetWrites: false, }, entries: { "image-lab": { apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, sag: { enabled: false }, }, },}allowBundled: قائمة سماح اختيارية لـ Skills المجمعة فقط (لا تتأثر Skills المدارة/الخاصة بمساحة العمل).load.extraDirs: جذور Skills مشتركة إضافية (أدنى أولوية).load.allowSymlinkTargets: جذور أهداف حقيقية موثوقة يمكن أن تحل إليها الروابط الرمزية الخاصة بـ Skills عندما يكون الرابط خارج جذر المصدر المهيأ.workshop.allowSymlinkTargetWrites: يسمح لتطبيق Skill Workshop بالكتابة عبر أهداف الروابط الرمزية الموثوقة مسبقا (الافتراضي: false).install.preferBrew: عند true، يفضل مثبتات Homebrew عندما يكونbrewمتاحا قبل الرجوع إلى أنواع مثبتات أخرى.install.nodeManager: تفضيل مثبت Node لمواصفاتmetadata.openclaw.install(npm|pnpm|yarn|bun).install.allowUploadedArchives: السماح لعملاء Gateway الموثوقين من نوعoperator.adminبتثبيت أرشيفات zip خاصة ممرحلة عبرskills.upload.*(الافتراضي: false). هذا لا يفعل إلا مسار الأرشيفات المرفوعة؛ ولا تتطلبه عمليات التثبيت العادية من ClawHub.- يعطل
entries.<skillKey>.enabled: falseSkill حتى إن كانت مجمعة/مثبتة. entries.<skillKey>.apiKey: تسهيل لـ Skills التي تعلن متغير env أساسيا (سلسلة نصية صريحة أو كائن SecretRef).
Plugins
{ plugins: { enabled: true, allow: ["voice-call"], deny: [], load: { paths: ["~/Projects/oss/voice-call-plugin"], }, entries: { "voice-call": { enabled: true, hooks: { allowPromptInjection: false, }, config: { provider: "twilio" }, }, }, },}- تُحمَّل من أدلة الحزم أو الحِزم ضمن
~/.openclaw/extensionsو<workspace>/.openclaw/extensions، إضافةً إلى الملفات أو الأدلة المدرجة فيplugins.load.paths. - ضع ملفات Plugin المستقلة في
plugins.load.paths؛ تتجاهل جذور الامتدادات المكتشفة تلقائيًا ملفات.jsو.mjsو.tsذات المستوى الأعلى حتى لا تمنع سكربتات المساعدة في تلك الجذور بدء التشغيل. - يقبل الاكتشاف Plugins OpenClaw الأصلية إضافةً إلى حِزم Codex وحِزم Claude المتوافقة، بما في ذلك حِزم Claude ذات التخطيط الافتراضي بلا بيان.
- تتطلب تغييرات الإعدادات إعادة تشغيل Gateway.
allow: قائمة سماح اختيارية (لا تُحمَّل إلا Plugins المدرجة). تتغلبdeny.plugins.entries.<id>.apiKey: حقل ملاءمة لمفتاح API على مستوى Plugin (عندما يدعمه Plugin).plugins.entries.<id>.env: خريطة متغيرات بيئة مقيّدة بنطاق Plugin.plugins.entries.<id>.hooks.allowPromptInjection: عندما تكونfalse، يحظر القلبbefore_prompt_buildويتجاهل الحقول التي تعدّل الموجّه منbefore_agent_startالقديم، مع الحفاظ علىmodelOverrideوproviderOverrideالقديمين. ينطبق ذلك على خطّافات Plugin الأصلية وأدلة الخطّافات المدعومة التي توفرها الحِزم.plugins.entries.<id>.hooks.allowConversationAccess: عندما تكونtrue، يمكن لـ Plugins غير المضمّنة والموثوقة قراءة محتوى المحادثة الخام من الخطّافات الموصوفة نوعيًا مثلllm_inputوllm_outputوbefore_model_resolveوbefore_agent_replyوbefore_agent_runوbefore_agent_finalizeوagent_end.plugins.entries.<id>.subagent.allowModelOverride: ثق صراحةً بهذا Plugin ليطلب تجاوزاتproviderوmodelلكل تشغيل في عمليات subagent الخلفية.plugins.entries.<id>.subagent.allowedModels: قائمة سماح اختيارية لأهدافprovider/modelالقانونية لتجاوزات subagent الموثوقة. استخدم"*"فقط عندما تريد عمدًا السماح بأي نموذج.plugins.entries.<id>.llm.allowModelOverride: ثق صراحةً بهذا Plugin ليطلب تجاوزات النموذج لـapi.runtime.llm.complete.plugins.entries.<id>.llm.allowedModels: قائمة سماح اختيارية لأهدافprovider/modelالقانونية لتجاوزات إكمال LLM الخاصة بـ Plugin الموثوق. استخدم"*"فقط عندما تريد عمدًا السماح بأي نموذج.plugins.entries.<id>.llm.allowAgentIdOverride: ثق صراحةً بهذا Plugin لتشغيلapi.runtime.llm.completeمقابل معرّف وكيل غير افتراضي.plugins.entries.<id>.config: كائن إعدادات يعرّفه Plugin (يُتحقّق منه عبر مخطط Plugin OpenClaw الأصلي عند توفره).- توجد إعدادات حساب/تشغيل Plugin القناة ضمن
channels.<id>ويجب أن تصفها بياناتchannelConfigsالوصفية في بيان Plugin المالك، لا سجل خيارات مركزي في OpenClaw.
إعدادات Plugin حاضنة Codex
يمتلك Plugin المضمّن codex إعدادات حاضنة خادم تطبيق Codex الأصلية ضمن
plugins.entries.codex.config. راجع
مرجع حاضنة Codex للاطلاع على سطح الإعدادات الكامل
وحاضنة Codex للاطلاع على نموذج التشغيل.
ينطبق codexPlugins فقط على الجلسات التي تختار حاضنة Codex الأصلية.
ولا يفعّل Plugins Codex لعمليات تشغيل مزود OpenClaw أو ارتباطات محادثة ACP
أو أي حاضنة غير Codex.
{ plugins: { entries: { codex: { enabled: true, config: { codexPlugins: { enabled: true, allow_destructive_actions: true, plugins: { "google-calendar": { enabled: true, marketplaceName: "openai-curated", pluginName: "google-calendar", allow_destructive_actions: false, }, }, }, }, }, }, },}plugins.entries.codex.config.codexPlugins.enabled: يفعّل دعم Plugin/التطبيق الأصلي لحاضنة Codex. الافتراضي:false.plugins.entries.codex.config.codexPlugins.allow_destructive_actions: سياسة الإجراءات التدميرية الافتراضية لاستدعاءات تطبيق Plugin المُرحّلة. استخدمtrueلقبول مخططات موافقة Codex الآمنة دون مطالبة، وfalseلرفضها، و"auto"لتوجيه الموافقات التي يتطلبها Codex عبر موافقات Plugin في OpenClaw، أو"ask"للمطالبة بكل إجراء كتابة/تدمير خاص بـ Plugin دون موافقة دائمة. يمسح وضع"ask"تجاوزات موافقة Codex الدائمة لكل أداة للتطبيق المتأثر ويختار مراجع الموافقات البشري لذلك التطبيق قبل بدء سلسلة Codex. الافتراضي:true.plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: يفعّل إدخال Plugin مُرحّلًا عندما يكونcodexPlugins.enabledالعام صحيحًا أيضًا. الافتراضي:trueللإدخالات الصريحة.plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: هوية سوق مستقرة. يدعم V1 فقط"openai-curated".plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: هوية Plugin Codex مستقرة من الترحيل، مثل"google-calendar".plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: تجاوز الإجراءات التدميرية لكل Plugin. عند حذفه، تُستخدم قيمةallow_destructive_actionsالعامة. تقبل القيمة الخاصة بكل Plugin السياسات نفسها:trueأوfalseأو"auto"أو"ask".
كل تطبيق Plugin مُقبَل يستخدم "ask" يوجّه طلبات موافقة ذلك التطبيق
إلى المراجع البشري. تحتفظ التطبيقات الأخرى وموافقات السلسلة غير التطبيقية
بالمراجع المضبوط لها، لذلك لا ترث سياسات Plugin المختلطة سلوك "ask".
codexPlugins.enabled هو توجيه التفعيل العام. إدخالات Plugin الصريحة
التي يكتبها الترحيل هي مجموعة التثبيت الدائم وأهلية الإصلاح.
plugins["*"] غير مدعوم، ولا يوجد مفتاح install، وقيم
marketplacePath المحلية ليست حقول إعدادات عمدًا لأنها خاصة بالمضيف.
تُخزَّن فحوص جاهزية app/list مؤقتًا لمدة ساعة واحدة وتُحدَّث
بشكل غير متزامن عند التقادم. تُحتسب إعدادات تطبيق سلسلة Codex عند إنشاء
جلسة حاضنة Codex، لا في كل دور؛ استخدم /new أو /reset أو إعادة تشغيل
Gateway بعد تغيير إعدادات Plugin الأصلية.
plugins.entries.firecrawl.config.webFetch: إعدادات مزود جلب الويب Firecrawl.apiKey: مفتاح API اختياري لـ Firecrawl لحدود أعلى (يقبل SecretRef). يعود إلىplugins.entries.firecrawl.config.webSearch.apiKeyأوtools.web.fetch.firecrawl.apiKeyالقديم أو متغير البيئةFIRECRAWL_API_KEY.baseUrl: عنوان URL الأساسي لـ API Firecrawl (الافتراضي:https://api.firecrawl.dev؛ يجب أن تستهدف تجاوزات الاستضافة الذاتية نقاط نهاية خاصة/داخلية).onlyMainContent: استخرج المحتوى الرئيسي فقط من الصفحات (الافتراضي:true).maxAgeMs: أقصى عمر لذاكرة التخزين المؤقت بالمللي ثانية (الافتراضي:172800000/ يومان).timeoutSeconds: مهلة طلب الكشط بالثواني (الافتراضي:60).
plugins.entries.xai.config.xSearch: إعدادات xAI X Search (بحث Grok على الويب).enabled: فعّل مزود X Search.model: نموذج Grok المراد استخدامه للبحث (مثل"grok-4-1-fast").
plugins.entries.memory-core.config.dreaming: إعدادات Dreaming للذاكرة. راجع Dreaming للمراحل والعتبات.enabled: مفتاح Dreaming الرئيسي (الافتراضيfalse).frequency: وتيرة Cron لكل مسح Dreaming كامل ("0 3 * * *"افتراضيًا).model: تجاوز اختياري لنموذج subagent الخاص بـ Dream Diary. يتطلبplugins.entries.memory-core.subagent.allowModelOverride: true؛ اقرنه بـallowedModelsلتقييد الأهداف. أخطاء عدم توفر النموذج تعيد المحاولة مرة واحدة باستخدام نموذج الجلسة الافتراضي؛ ولا تعود إخفاقات الثقة أو قائمة السماح بصمت.- سياسة المراحل والعتبات تفاصيل تنفيذية (وليست مفاتيح إعدادات موجهة للمستخدم).
- توجد إعدادات الذاكرة الكاملة في مرجع إعدادات الذاكرة:
agents.defaults.memorySearch.*memory.backendmemory.citationsmemory.qmd.*plugins.entries.memory-core.config.dreaming
- يمكن لـ Plugins حِزم Claude المفعّلة أيضًا المساهمة بإعدادات OpenClaw الافتراضية المضمّنة من
settings.json؛ يطبق OpenClaw هذه كإعدادات وكيل منقّاة، لا كتصحيحات خام لإعدادات OpenClaw. plugins.slots.memory: اختر معرّف Plugin الذاكرة النشط، أو"none"لتعطيل Plugins الذاكرة.plugins.slots.contextEngine: اختر معرّف Plugin محرك السياق النشط؛ يكون الافتراضي"legacy"ما لم تثبّت محركًا آخر وتختاره.
راجع Plugins.
الالتزامات
يتحكم commitments في ذاكرة المتابعة المستنتجة: يستطيع OpenClaw اكتشاف عمليات التحقق من أدوار المحادثة وتسليمها عبر عمليات Heartbeat.
commitments.enabled: فعّل استخراج LLM المخفي والتخزين وتسليم Heartbeat لالتزامات المتابعة المستنتجة. الافتراضي:false.commitments.maxPerDay: الحد الأقصى لالتزامات المتابعة المستنتجة المُسلّمة لكل جلسة وكيل خلال يوم متحرك. الافتراضي:3.
راجع الالتزامات المستنتجة.
المتصفح
{ browser: { enabled: true, evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, tabCleanup: { enabled: true, idleMinutes: 120, maxTabsPerSession: 8, sweepMinutes: 5, }, profiles: { openclaw: { cdpPort: 18800, color: "#FF4500" }, work: { cdpPort: 18801, color: "#0066CC", executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", }, user: { driver: "existing-session", attachOnly: true, color: "#00AA00" }, brave: { driver: "existing-session", attachOnly: true, userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser", color: "#FB542B", }, remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }, }, color: "#FF4500", // headless: false, // noSandbox: false, // extraArgs: [], // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", // attachOnly: false, },}- يعطّل
evaluateEnabled: falseكلًا منact:evaluateوwait --fn. - يستعيد
tabCleanupعلامات تبويب الوكيل الأساسي المتتبعة بعد مدة الخمول أو عندما تتجاوز الجلسة حدّها الأقصى. اضبطidleMinutes: 0أوmaxTabsPerSession: 0من أجل تعطيل أوضاع التنظيف الفردية هذه. - يكون
ssrfPolicy.dangerouslyAllowPrivateNetworkمعطّلًا عند عدم ضبطه، لذلك يظل تنقّل المتصفح صارمًا افتراضيًا. - اضبط
ssrfPolicy.dangerouslyAllowPrivateNetwork: trueفقط عندما تثق عمدًا بتنقّل المتصفح عبر الشبكة الخاصة. - في الوضع الصارم، تخضع نقاط نهاية ملفات تعريف CDP البعيدة (
profiles.*.cdpUrl) لحظر الشبكة الخاصة نفسه أثناء فحوصات قابلية الوصول/الاكتشاف. - يظل
ssrfPolicy.allowPrivateNetworkمدعومًا كاسم بديل قديم. - في الوضع الصارم، استخدم
ssrfPolicy.hostnameAllowlistوssrfPolicy.allowedHostnamesللاستثناءات الصريحة. - ملفات التعريف البعيدة مخصصة للإرفاق فقط (التشغيل/الإيقاف/إعادة الضبط معطلة).
- يقبل
profiles.*.cdpUrlالقيمhttp://وhttps://وws://وwss://. استخدم HTTP(S) عندما تريد من OpenClaw اكتشاف/json/version؛ واستخدم WS(S) عندما يزوّدك الموفّر بعنوان URL مباشر لـ DevTools WebSocket. - ينطبق
remoteCdpTimeoutMsوremoteCdpHandshakeTimeoutMsعلى قابلية الوصول إلى CDP البعيد وattachOnly، إضافة إلى طلبات فتح علامات التبويب. تحتفظ ملفات تعريف الاسترجاع المُدارة بإعدادات CDP المحلية الافتراضية. - إذا كانت خدمة CDP المُدارة خارجيًا قابلة للوصول عبر الاسترجاع، فاضبط
attachOnly: trueلذلك الملف التعريفي؛ وإلا فسيعامل OpenClaw منفذ الاسترجاع كملف تعريف متصفح محلي مُدار وقد يبلّغ عن أخطاء ملكية المنفذ المحلي. - تستخدم ملفات تعريف
existing-sessionChrome MCP بدلًا من CDP ويمكنها الإرفاق على المضيف المحدد أو عبر عقدة متصفح متصلة. - يمكن لملفات تعريف
existing-sessionضبطuserDataDirلاستهداف ملف تعريف متصفح محدد قائم على Chromium مثل Brave أو Edge. - يمكن لملفات تعريف
existing-sessionضبطcdpUrlعندما يكون Chrome قيد التشغيل بالفعل خلف نقطة نهاية اكتشاف DevTools HTTP(S) أو نقطة نهاية WS(S) مباشرة. في ذلك الوضع يمرّر OpenClaw نقطة النهاية إلى Chrome MCP بدلًا من استخدام الاتصال التلقائي؛ يتم تجاهلuserDataDirلوسائط تشغيل Chrome MCP. - تحتفظ ملفات تعريف
existing-sessionبحدود مسار Chrome MCP الحالية: إجراءات مدفوعة باللقطات/المراجع بدلًا من الاستهداف بمحددات CSS، وخطافات رفع ملف واحد، بلا تجاوزات لمهلة الحوارات، وبلاwait --load networkidle، وبلاresponsebodyأو تصدير PDF أو اعتراض التنزيلات أو إجراءات الدُفعات. - تعيّن ملفات تعريف
openclawالمحلية المُدارةcdpPortوcdpUrlتلقائيًا؛ اضبطcdpUrlصراحةً فقط لملفات تعريف CDP البعيدة أو إرفاق نقطة نهاية existing-session. - يمكن لملفات التعريف المحلية المُدارة ضبط
executablePathلتجاوزbrowser.executablePathالعام لذلك الملف التعريفي. استخدم هذا لتشغيل ملف تعريف واحد في Chrome وآخر في Brave. - تستخدم ملفات التعريف المحلية المُدارة
browser.localLaunchTimeoutMsلاكتشاف Chrome CDP HTTP بعد بدء العملية وbrowser.localCdpReadyTimeoutMsلجاهزية websocket الخاص بـCDP بعد التشغيل. ارفع هذه القيم على المضيفين الأبطأ حيث يبدأ Chrome بنجاح لكن فحوصات الجاهزية تتسابق مع بدء التشغيل. يجب أن تكون كلتا القيمتين أعدادًا صحيحة موجبة حتى120000مللي ثانية؛ تُرفض قيم الإعدادات غير الصالحة. - ترتيب الاكتشاف التلقائي: المتصفح الافتراضي إذا كان قائمًا على Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
- يقبل كل من
browser.executablePathوbrowser.profiles.<name>.executablePathالقيمتين~و~/...لدليل المنزل في نظام التشغيل لديك قبل تشغيل Chromium. يتم أيضًا توسيع علامة التلدة فيuserDataDirلكل ملف تعريف في ملفات تعريفexisting-session. - خدمة التحكم: الاسترجاع فقط (المنفذ مشتق من
gateway.port، الافتراضي18791). - يضيف
extraArgsأعلام تشغيل إضافية إلى بدء تشغيل Chromium المحلي (على سبيل المثال--disable-gpu، أو ضبط حجم النافذة، أو أعلام التصحيح).
واجهة المستخدم
{ ui: { seamColor: "#FF4500", assistant: { name: "OpenClaw", avatar: "CB", // emoji, short text, image URL, or data URI }, },}seamColor: لون تمييز لزخرفة واجهة مستخدم التطبيق الأصلية (تلوين فقاعة Talk Mode، وما إلى ذلك).assistant: تجاوز هوية Control UI. يعود إلى هوية الوكيل النشط عند عدم ضبطه.
Gateway
{ gateway: { mode: "local", // local | remote port: 18789, bind: "loopback", auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, windowMs: 60000, lockoutMs: 300000, exemptLoopback: true, }, }, tailscale: { mode: "off", // off | serve | funnel resetOnExit: false, }, controlUi: { enabled: true, basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, remote: { url: "ws://127.0.0.1:18789", transport: "ssh", // ssh | direct token: "your-token", // password: "your-password", }, trustedProxies: ["10.0.0.1"], // Optional. Default false. allowRealIpFallback: false, nodes: { pairing: { // Optional. Default unset/disabled. autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, allowCommands: ["canvas.navigate"], denyCommands: ["system.run"], }, tools: { // Additional /tools/invoke HTTP denies deny: ["browser"], // Remove tools from the default HTTP deny list for owner/admin callers allow: ["gateway"], }, push: { apns: { relay: { baseUrl: "https://relay.example.com", timeoutMs: 10000, }, }, }, },}Gateway field details
mode:local(تشغيل Gateway) أوremote(الاتصال بـ Gateway بعيد). يرفض Gateway البدء ما لم تكن القيمةlocal.port: منفذ واحد متعدد الاستخدامات لـ WS + HTTP. الأولوية:--port>OPENCLAW_GATEWAY_PORT>gateway.port>18789.bind:auto، أوloopback(الافتراضي)، أوlan(0.0.0.0)، أوtailnet(عنوان IP الخاص بـ Tailscale فقط)، أوcustom.- أسماء bind المستعارة القديمة: استخدم قيم وضع bind في
gateway.bind(auto،loopback،lan،tailnet،custom)، وليس أسماء المضيف المستعارة (0.0.0.0،127.0.0.1،localhost،::،::1). - ملاحظة Docker: يستمع bind الافتراضي
loopbackعلى127.0.0.1داخل الحاوية. مع شبكة Docker الجسرية (-p 18789:18789)، تصل الحركة عبرeth0، لذلك لا يمكن الوصول إلى Gateway. استخدم--network host، أو اضبطbind: "lan"(أوbind: "custom"معcustomBindHost: "0.0.0.0") للاستماع على كل الواجهات. - المصادقة: مطلوبة افتراضيا. تتطلب عمليات bind غير loopback مصادقة Gateway. عمليا، يعني ذلك رمزا/كلمة مرور مشتركة أو وكيلا عكسيا مدركا للهوية مع
gateway.auth.mode: "trusted-proxy". ينشئ معالج الإعداد الأولي رمزا افتراضيا. - إذا تم تكوين كل من
gateway.auth.tokenوgateway.auth.password(بما في ذلك SecretRefs)، فاضبطgateway.auth.modeصراحة علىtokenأوpassword. تفشل تدفقات بدء التشغيل وتثبيت/إصلاح الخدمة عندما يكون كلاهما مكوّنا ويكون الوضع غير مضبوط. gateway.auth.mode: "none": وضع صريح بلا مصادقة. استخدمه فقط لإعدادات local loopback موثوقة؛ وهذا غير معروض عمدا في مطالبات الإعداد الأولي.gateway.auth.mode: "trusted-proxy": فوّض مصادقة المتصفح/المستخدم إلى وكيل عكسي مدرك للهوية، وثق بترويسات الهوية منgateway.trustedProxies(راجع مصادقة الوكيل الموثوق). يتوقع هذا الوضع افتراضيا مصدر وكيل غير loopback؛ وتتطلب الوكلاء العكسيون عبر loopback على المضيف نفسه ضبطا صريحا لـgateway.auth.trustedProxy.allowLoopback = true. يمكن للمتصلين الداخليين على المضيف نفسه استخدامgateway.auth.passwordكبديل محلي مباشر؛ ويظلgateway.auth.tokenمتنافيا مع وضع trusted-proxy.gateway.auth.allowTailscale: عندما تكونtrue، يمكن لترويسات هوية Tailscale Serve استيفاء مصادقة واجهة التحكم/WebSocket (يتم التحقق عبرtailscale whois). لا تستخدم نقاط نهاية HTTP API مصادقة ترويسة Tailscale تلك؛ بل تتبع وضع مصادقة HTTP المعتاد في Gateway بدلا من ذلك. يفترض هذا التدفق بلا رمز أن مضيف Gateway موثوق. القيمة الافتراضية هيtrueعندما تكونtailscale.mode = "serve".gateway.auth.rateLimit: محدد اختياري لمحاولات المصادقة الفاشلة. يطبّق لكل عنوان IP عميل ولكل نطاق مصادقة (يتم تتبع shared-secret وdevice-token بشكل مستقل). تعيد المحاولات المحظورة429+Retry-After.- على مسار واجهة التحكم غير المتزامن في Tailscale Serve، تتم تسلسلة المحاولات الفاشلة لنفس
{scope, clientIp}قبل كتابة الفشل. لذلك يمكن للمحاولات السيئة المتزامنة من العميل نفسه أن تفعّل المحدد في الطلب الثاني بدلا من أن تمر كلتاهما كتعارضات عادية. - القيمة الافتراضية لـ
gateway.auth.rateLimit.exemptLoopbackهيtrue؛ اضبطها علىfalseعندما تريد عمدا تقييد حركة localhost أيضا (لإعدادات الاختبار أو نشر الوكيل الصارم). - تتم دائما خنق محاولات مصادقة WS من مصدر المتصفح مع تعطيل إعفاء loopback (دفاع معمق ضد هجمات القوة الغاشمة على localhost من المتصفح).
- على loopback، تُعزل عمليات القفل هذه الصادرة من المتصفح لكل قيمة
Originمطبّعة، لذلك لا تؤدي الإخفاقات المتكررة من مصدر localhost واحد تلقائيا إلى قفل مصدر مختلف. tailscale.mode:serve(tailnet فقط، bind عبر loopback) أوfunnel(عام، يتطلب المصادقة).tailscale.serviceName: اسم خدمة Tailscale اختياري لوضع Serve، مثلsvc:openclaw. عند ضبطه، يمرره OpenClaw إلىtailscale serve --serviceحتى يمكن عرض واجهة التحكم عبر خدمة مسماة بدلا من اسم مضيف الجهاز. يجب أن تستخدم القيمة تنسيق اسم خدمة Tailscalesvc:<dns-label>؛ ويبلغ بدء التشغيل عن عنوان URL المشتق للخدمة.tailscale.preserveFunnel: عندما تكونtrueوtailscale.mode = "serve"، يتحقق OpenClaw منtailscale funnel statusقبل إعادة تطبيق Serve عند بدء التشغيل ويتخطاه إذا كان مسار Funnel مكوّنا خارجيا يغطي منفذ Gateway بالفعل. الافتراضيfalse.controlUi.allowedOrigins: قائمة سماح صريحة لمصدر المتصفح لاتصالات Gateway WebSocket. مطلوبة لمصادر المتصفح العامة غير loopback. يتم قبول تحميلات واجهة المستخدم الخاصة من نفس المصدر عبر LAN/Tailnet من loopback أو RFC1918/link-local أو.localأو.ts.netأو مضيفي Tailscale CGNAT من دون تمكين بديل ترويسة Host.controlUi.chatMessageMaxWidth: عرض أقصى اختياري لرسائل دردشة واجهة التحكم المجمعة. يقبل قيم عرض CSS مقيّدة مثل960pxو82%وmin(1280px, 82%)وcalc(100% - 2rem).controlUi.dangerouslyAllowHostHeaderOriginFallback: وضع خطر يفعّل بديل مصدر ترويسة Host لعمليات النشر التي تعتمد عمدا على سياسة مصدر ترويسة Host.remote.transport:ssh(الافتراضي) أوdirect(ws/wss). بالنسبة إلىdirect، يجب أن تكونremote.urlهيwss://للمضيفين العامين؛ ولا يُقبل النص الصريحws://إلا لـ loopback وLAN وlink-local و.localو.ts.netومضيفي Tailscale CGNAT.remote.remotePort: منفذ Gateway على مضيف SSH البعيد. الافتراضي18789؛ استخدم هذا عندما يختلف منفذ النفق المحلي عن منفذ Gateway البعيد.remote.sshHostKeyPolicy: سياسة مفتاح مضيف نفق SSH على macOS.strictهي القيمة الافتراضية وتتطلب مفتاحا موثوقا مسبقا.opensshهو قبول صريح لاستخدام تكوين OpenSSH الفعّال للأسماء المستعارة المُدارة؛ راجع إعدادات SSH المطابقة للمستخدم والنظام قبل استخدامه. يعيد تطبيق macOS وconfigure-remoteضبط هذه السياسة إلىstrictعند تغيير الأهداف ما لم يتم قبولها صراحة مرة أخرى.gateway.remote.token/.passwordهي حقول بيانات اعتماد العميل البعيد. لا تكوّن مصادقة Gateway بحد ذاتها.gateway.push.apns.relay.baseUrl: عنوان URL أساسي عبر HTTPS لمرحل APNs الخارجي المستخدم بعد أن تنشر إصدارات iOS المدعومة بالمرحل التسجيلات إلى Gateway. تستخدم إصدارات App Store العامة مرحل OpenClaw المستضاف. يجب أن تطابق عناوين URL للمرحل المخصص مسار بناء/نشر iOS منفصلا عمدا يشير عنوان URL للمرحل فيه إلى ذلك المرحل.gateway.push.apns.relay.timeoutMs: مهلة إرسال Gateway إلى المرحل بالمللي ثانية. الافتراضي10000.- تُفوّض التسجيلات المدعومة بالمرحل إلى هوية Gateway محددة. يجلب تطبيق iOS المقترن
gateway.identity.get، ويدرج تلك الهوية في تسجيل المرحل، ويمرر منحة إرسال محددة بنطاق التسجيل إلى Gateway. لا يمكن لـ Gateway آخر إعادة استخدام ذلك التسجيل المخزن. OPENCLAW_APNS_RELAY_BASE_URL/OPENCLAW_APNS_RELAY_TIMEOUT_MS: تجاوزات env مؤقتة لتكوين المرحل أعلاه.OPENCLAW_APNS_RELAY_ALLOW_HTTP=true: منفذ هروب للتطوير فقط لعناوين URL لمرحل HTTP عبر loopback. يجب أن تبقى عناوين URL لمرحل الإنتاج على HTTPS.gateway.handshakeTimeoutMs: مهلة مصافحة Gateway WebSocket قبل المصادقة بالمللي ثانية. الافتراضي:15000. يأخذOPENCLAW_HANDSHAKE_TIMEOUT_MSالأولوية عند ضبطه. زِد هذه القيمة على المضيفين المحمّلين أو ضعيفي الطاقة حيث يمكن للعملاء المحليين الاتصال بينما لا يزال إحماء بدء التشغيل يستقر.gateway.channelHealthCheckMinutes: الفاصل الزمني لمراقب صحة القناة بالدقائق. اضبط0لتعطيل عمليات إعادة تشغيل مراقب الصحة عالميا. الافتراضي:5.gateway.channelStaleEventThresholdMinutes: حد المقبس القديم بالدقائق. أبقِ هذه القيمة أكبر من أو مساوية لـgateway.channelHealthCheckMinutes. الافتراضي:30.gateway.channelMaxRestartsPerHour: الحد الأقصى لعمليات إعادة تشغيل مراقب الصحة لكل قناة/حساب في ساعة متحركة. الافتراضي:10.channels.<provider>.healthMonitor.enabled: تعطيل اختياري لكل قناة لعمليات إعادة تشغيل مراقب الصحة مع إبقاء المراقب العالمي مفعلا.channels.<provider>.accounts.<accountId>.healthMonitor.enabled: تجاوز لكل حساب للقنوات متعددة الحسابات. عند ضبطه، يأخذ الأولوية على تجاوز مستوى القناة.- يمكن لمسارات استدعاء Gateway المحلية استخدام
gateway.remote.*كبديل فقط عندما تكونgateway.auth.*غير مضبوطة. - إذا تم تكوين
gateway.auth.token/gateway.auth.passwordصراحة عبر SecretRef ولم يتم حلها، يفشل الحل بإغلاق آمن (من دون إخفاء ببديل بعيد). trustedProxies: عناوين IP للوكلاء العكسيين الذين ينهون TLS أو يحقنون ترويسات العميل المُمررة. أدرج فقط الوكلاء الذين تتحكم بهم. تظل إدخالات loopback صالحة لإعدادات الوكيل على المضيف نفسه/الاكتشاف المحلي (مثل Tailscale Serve أو وكيل عكسي محلي)، لكنها لا تجعل طلبات loopback مؤهلة لـgateway.auth.mode: "trusted-proxy".allowRealIpFallback: عندما تكونtrue، يقبل GatewayX-Real-IPإذا كانX-Forwarded-Forمفقودا. الافتراضيfalseلسلوك الفشل المغلق.gateway.nodes.pairing.autoApproveCidrs: قائمة سماح CIDR/IP اختيارية للموافقة التلقائية على إقران جهاز عقدة لأول مرة من دون نطاقات مطلوبة. تكون معطلة عند عدم ضبطها. لا يوافق هذا تلقائيا على إقران المشغل/المتصفح/واجهة التحكم/دردشة الويب، ولا يوافق تلقائيا على ترقيات الدور أو النطاق أو البيانات الوصفية أو المفتاح العام.gateway.nodes.allowCommands/gateway.nodes.denyCommands: تشكيل سماح/منع عالمي لأوامر العقد المعلنة بعد الإقران وتقييم قائمة سماح المنصة. استخدمallowCommandsلقبول أوامر العقد الخطرة مثلcamera.snapوcamera.clipوscreen.record؛ يزيلdenyCommandsأمرا حتى لو كان افتراض المنصة أو سماح صريح سيتضمنه بخلاف ذلك. بعد أن تغير عقدة قائمة أوامرها المعلنة، ارفض إقران ذلك الجهاز وأعد الموافقة عليه حتى يخزن Gateway لقطة الأوامر المحدثة.gateway.tools.deny: أسماء أدوات إضافية محظورة لـ HTTPPOST /tools/invoke(توسع قائمة المنع الافتراضية).gateway.tools.allow: إزالة أسماء أدوات من قائمة منع HTTP الافتراضية للمتصلين المالكين/المسؤولين. لا يرفع هذا المتصلين الحاملين لهويةoperator.writeإلى وصول مالك/مسؤول؛ تظلcronوgatewayوnodesغير متاحة للمتصلين غير المالكين حتى عند إدراجها في قائمة السماح.
نقاط نهاية متوافقة مع OpenAI
- RPC إداري عبر HTTP: معطل افتراضيا باعتباره Plugin
admin-http-rpc. فعّل Plugin لتسجيلPOST /api/v1/admin/rpc. راجع RPC إداري عبر HTTP. - Chat Completions: معطلة افتراضيا. فعّلها باستخدام
gateway.http.endpoints.chatCompletions.enabled: true. - Responses API:
gateway.http.endpoints.responses.enabled. - تقوية إدخال URL في Responses:
gateway.http.endpoints.responses.maxUrlPartsgateway.http.endpoints.responses.files.urlAllowlistgateway.http.endpoints.responses.images.urlAllowlistتُعامل قوائم السماح الفارغة كأنها غير مضبوطة؛ استخدمgateway.http.endpoints.responses.files.allowUrl=falseو/أوgateway.http.endpoints.responses.images.allowUrl=falseلتعطيل جلب URL.
- ترويسة تقوية استجابة اختيارية:
gateway.http.securityHeaders.strictTransportSecurity(اضبطها فقط لمصادر HTTPS التي تتحكم بها؛ راجع مصادقة الوكيل الموثوق)
عزل متعدد المثيلات
شغّل عدة Gateways على مضيف واحد بمنافذ ومجلدات حالة فريدة:
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \OPENCLAW_STATE_DIR=~/.openclaw-a \openclaw gateway --port 19001أعلام ملائمة: --dev (يستخدم ~/.openclaw-dev + المنفذ 19001)، و--profile <name> (يستخدم ~/.openclaw-<name>).
راجع عدة Gateways.
gateway.tls
{ gateway: { tls: { enabled: false, autoGenerate: false, certPath: "/etc/openclaw/tls/server.crt", keyPath: "/etc/openclaw/tls/server.key", caPath: "/etc/openclaw/tls/ca-bundle.crt", }, },}enabled: يفعّل إنهاء TLS عند مستمع Gateway (HTTPS/WSS) (الافتراضي:false).autoGenerate: ينشئ تلقائيا زوج شهادة/مفتاح موقّعا ذاتيا محليا عندما لا يتم تكوين ملفات صريحة؛ للاستخدام المحلي/التطوير فقط.certPath: مسار نظام الملفات إلى ملف شهادة TLS.keyPath: مسار نظام الملفات إلى ملف المفتاح الخاص لـ TLS؛ أبقه مقيّدا بالأذونات.caPath: مسار اختياري لحزمة CA للتحقق من العميل أو سلاسل الثقة المخصصة.
gateway.reload
{ gateway: { reload: { mode: "hybrid", // off | restart | hot | hybrid debounceMs: 500, deferralTimeoutMs: 300000, }, },}mode: يتحكم في كيفية تطبيق تعديلات الإعدادات أثناء التشغيل."off": تجاهل التعديلات المباشرة؛ تتطلب التغييرات إعادة تشغيل صريحة."restart": أعد تشغيل عملية Gateway دائمًا عند تغيير الإعدادات."hot": طبّق التغييرات داخل العملية من دون إعادة التشغيل."hybrid"(الافتراضي): جرّب إعادة التحميل الساخنة أولًا؛ وارجع إلى إعادة التشغيل إذا لزم الأمر.
debounceMs: نافذة منع التكرار بالمللي ثانية قبل تطبيق تغييرات الإعدادات (عدد صحيح غير سالب).deferralTimeoutMs: الحد الأقصى الاختياري للوقت بالمللي ثانية لانتظار العمليات الجارية قبل فرض إعادة تشغيل أو إعادة تحميل ساخنة للقناة. احذفه لاستخدام الانتظار المحدود الافتراضي (300000)؛ واضبطه على0للانتظار إلى أجل غير مسمى وتسجيل تحذيرات دورية عن العناصر التي لا تزال معلّقة.
الخطافات
{ hooks: { enabled: true, token: "shared-secret", path: "/hooks", maxBodyBytes: 262144, defaultSessionKey: "hook:ingress", allowRequestSessionKey: true, allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"], allowedAgentIds: ["hooks", "main"], presets: ["gmail"], transformsDir: "~/.openclaw/hooks/transforms", mappings: [ { match: { path: "gmail" }, action: "agent", agentId: "hooks", wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", }, ], },}المصادقة: Authorization: Bearer <token> أو x-openclaw-token: <token>.
تُرفض رموز الخطافات في سلسلة الاستعلام.
ملاحظات التحقق والسلامة:
- يتطلب
hooks.enabled=trueقيمة غير فارغة فيhooks.token. - يجب أن يكون
hooks.tokenمختلفًا عن مصادقة السر المشترك النشطة في Gateway (gateway.auth.token/OPENCLAW_GATEWAY_TOKENأوgateway.auth.password/OPENCLAW_GATEWAY_PASSWORD)؛ تسجّل عملية بدء التشغيل تحذيرًا أمنيًا غير قاتل عندما تكتشف إعادة الاستخدام. - يضع
openclaw security auditعلامة على إعادة استخدام مصادقة الخطاف/Gateway باعتبارها نتيجة حرجة، بما في ذلك مصادقة كلمة مرور Gateway المقدمة فقط وقت التدقيق (--auth password --password <password>). شغّلopenclaw doctor --fixلتدويرhooks.tokenمُعاد استخدامه ومخزّن، ثم حدّث مرسلي الخطافات الخارجيين لاستخدام رمز الخطاف الجديد. - لا يمكن أن يكون
hooks.pathهو/؛ استخدم مسارًا فرعيًا مخصصًا مثل/hooks. - إذا كان
hooks.allowRequestSessionKey=true، فقيّدhooks.allowedSessionKeyPrefixes(على سبيل المثال["hook:"]). - إذا كان تعيين أو إعداد مسبق يستخدم
sessionKeyمُمَوْضَعًا بقالب، فاضبطhooks.allowedSessionKeyPrefixesوhooks.allowRequestSessionKey=true. لا تتطلب مفاتيح التعيين الثابتة هذا الاشتراك الصريح.
نقاط النهاية:
POST /hooks/wake→{ text, mode?: "now"|"next-heartbeat" }POST /hooks/agent→{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }- لا يُقبل
sessionKeyمن حمولة الطلب إلا عندما يكونhooks.allowRequestSessionKey=true(الافتراضي:false).
- لا يُقبل
POST /hooks/<name>→ يُحل عبرhooks.mappings- تُعامَل قيم
sessionKeyفي التعيين المعروضة من القوالب كقيم مقدمة خارجيًا وتتطلب أيضًاhooks.allowRequestSessionKey=true.
- تُعامَل قيم
تفاصيل التعيين
- يطابق
match.pathالمسار الفرعي بعد/hooks(مثلًا/hooks/gmail→gmail). - يطابق
match.sourceحقل حمولة للمسارات العامة. - تقرأ القوالب مثل
{{messages[0].subject}}من الحمولة. - يمكن أن يشير
transformإلى وحدة JS/TS تُرجع إجراء خطاف. - يجب أن يكون
transform.moduleمسارًا نسبيًا ويبقى داخلhooks.transformsDir(تُرفض المسارات المطلقة والتنقل خارج المسار). - أبقِ
hooks.transformsDirضمن~/.openclaw/hooks/transforms؛ تُرفض أدلة Skills في مساحة العمل. إذا أبلغopenclaw doctorأن هذا المسار غير صالح، فانقل وحدة التحويل إلى دليل تحويلات الخطافات أو أزلhooks.transformsDir. - يوجّه
agentIdإلى وكيل محدد؛ تعود المعرّفات غير المعروفة إلى الوكيل الافتراضي. allowedAgentIds: يقيّد توجيه الوكيل الفعّال، بما في ذلك مسار الوكيل الافتراضي عند حذفagentId(*أو الحذف = السماح للجميع،[]= رفض الجميع).defaultSessionKey: مفتاح جلسة ثابت اختياري لتشغيلات وكيل الخطاف دونsessionKeyصريح.allowRequestSessionKey: اسمح لمستدعي/hooks/agentومفاتيح جلسات التعيين المدفوعة بالقوالب بتعيينsessionKey(الافتراضي:false).allowedSessionKeyPrefixes: قائمة سماح اختيارية بالبادئات لقيمsessionKeyالصريحة (الطلب + التعيين)، مثل["hook:"]. تصبح مطلوبة عندما يستخدم أي تعيين أو إعداد مسبقsessionKeyمُمَوْضَعًا بقالب.- يرسل
deliver: trueالرد النهائي إلى قناة؛ وتكون قيمةchannelالافتراضية هيlast. - يتجاوز
modelنموذج LLM لتشغيل هذا الخطاف (يجب أن يكون مسموحًا به إذا تم تعيين كتالوج النماذج).
تكامل Gmail
- يستخدم إعداد Gmail المسبق المضمّن
sessionKey: "hook:gmail:{{messages[0].id}}". - إذا أبقيت ذلك التوجيه لكل رسالة، فاضبط
hooks.allowRequestSessionKey: trueوقيّدhooks.allowedSessionKeyPrefixesلتطابق مساحة أسماء Gmail، على سبيل المثال["hook:", "hook:gmail:"]. - إذا كنت تحتاج إلى
hooks.allowRequestSessionKey: false، فتجاوز الإعداد المسبق باستخدامsessionKeyثابت بدلًا من الافتراضي المُمَوْضَع بقالب.
{ hooks: { gmail: { account: "openclaw@gmail.com", topic: "projects/<project-id>/topics/gog-gmail-watch", subscription: "gog-gmail-watch-push", pushToken: "shared-push-token", hookUrl: "http://127.0.0.1:18789/hooks/gmail", includeBody: true, maxBytes: 20000, renewEveryMinutes: 720, serve: { bind: "127.0.0.1", port: 8788, path: "/" }, tailscale: { mode: "funnel", path: "/gmail-pubsub" }, model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", thinking: "off", }, },}- يبدأ Gateway تلقائيًا تشغيل
gog gmail watch serveعند الإقلاع عند تكوينه. اضبطOPENCLAW_SKIP_GMAIL_WATCHER=1للتعطيل. - لا تشغّل
gog gmail watch serveمنفصلًا إلى جانب Gateway.
مضيف Plugin اللوحة
{ plugins: { entries: { canvas: { config: { host: { root: "~/.openclaw/workspace/canvas", liveReload: true, // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, }, }, }, },}- يقدّم HTML/CSS/JS قابلة لتحرير الوكيل وA2UI عبر HTTP تحت منفذ Gateway:
http://<gateway-host>:<gateway.port>/__openclaw__/canvas/http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
- محلي فقط: أبقِ
gateway.bind: "loopback"(الافتراضي). - ربط غير local loopback: تتطلب مسارات اللوحة مصادقة Gateway (رمز/كلمة مرور/وكيل موثوق)، مثل أسطح HTTP الأخرى في Gateway.
- لا ترسل WebViews في Node عادةً ترويسات المصادقة؛ بعد إقران عقدة واتصالها، يعلن Gateway عناوين URL للقدرات ضمن نطاق العقدة للوصول إلى اللوحة/A2UI.
- ترتبط عناوين URL للقدرات بجلسة WS النشطة للعقدة وتنتهي صلاحيتها بسرعة. لا يُستخدم fallback المستند إلى IP.
- يحقن عميل إعادة التحميل المباشر في HTML المقدّم.
- ينشئ تلقائيًا ملف
index.htmlمبدئيًا عندما يكون فارغًا. - يقدّم A2UI أيضًا عند
/__openclaw__/a2ui/. - تتطلب التغييرات إعادة تشغيل Gateway.
- عطّل إعادة التحميل المباشرة للأدلة الكبيرة أو أخطاء
EMFILE.
الاكتشاف
mDNS (Bonjour)
{ discovery: { mdns: { mode: "minimal", // minimal | full | off }, },}minimal(الافتراضي عند تمكين Pluginbonjourالمضمّن): احذفcliPath+sshPortمن سجلات TXT.full: ضمّنcliPath+sshPort؛ لا يزال إعلان البث المتعدد على LAN يتطلب تمكين Pluginbonjourالمضمّن.off: امنع إعلان البث المتعدد على LAN دون تغيير تمكين Plugin.- يبدأ Plugin
bonjourالمضمّن تلقائيًا على مضيفي macOS ويكون اختياريًا على Linux وWindows ونشرات Gateway ضمن الحاويات. - يكون اسم المضيف افتراضيًا اسم مضيف النظام عندما يكون تسمية DNS صالحة، مع الرجوع إلى
openclaw. تجاوزه باستخدامOPENCLAW_MDNS_HOSTNAME.
واسع النطاق (DNS-SD)
{ discovery: { wideArea: { enabled: true }, },}يكتب منطقة DNS-SD أحادية البث ضمن ~/.openclaw/dns/. للاكتشاف عبر الشبكات، اقرنه بخادم DNS (يوصى بـ CoreDNS) + Tailscale split DNS.
الإعداد: openclaw dns setup --apply.
البيئة
env (متغيرات البيئة المضمّنة)
{ env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, shellEnv: { enabled: true, timeoutMs: 15000, }, },}- لا تُطبَّق متغيرات البيئة المضمّنة إلا إذا كانت بيئة العملية تفتقد المفتاح.
- ملفات
.env: ملف.envفي CWD +~/.openclaw/.env(لا يتجاوز أي منهما المتغيرات الموجودة). shellEnv: يستورد المفاتيح المتوقعة المفقودة من ملف تعريف صدفة تسجيل الدخول.- راجع البيئة لمعرفة أسبقية كاملة.
استبدال متغيرات البيئة
ارجع إلى متغيرات البيئة في أي سلسلة إعدادات باستخدام ${VAR_NAME}:
{ gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" }, },}- الأسماء ذات الأحرف الكبيرة فقط مطابقة:
[A-Z_][A-Z0-9_]*. - تؤدي المتغيرات المفقودة/الفارغة إلى خطأ عند تحميل الإعدادات.
- اخرجها باستخدام
$${VAR}للحصول على${VAR}حرفية. - يعمل مع
$include.
الأسرار
مراجع الأسرار إضافية: لا تزال قيم النص الصريح تعمل.
SecretRef
استخدم شكل كائن واحد:
{ source: "env" | "file" | "exec", provider: "default", id: "..." }التحقق:
- نمط
provider:^[a-z][a-z0-9_-]{0,63}$ - نمط معرف
source: "env":^[A-Z][A-Z0-9_]{0,127}$ - معرف
source: "file": مؤشر JSON مطلق (على سبيل المثال"/providers/openai/apiKey") - نمط معرف
source: "exec":^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$(يدعم محددات على نمط AWS مثلsecret#json_key) - يجب ألا تحتوي معرفات
source: "exec"على مقاطع مسار مفصولة بشرطة مائلة.أو..(على سبيل المثال يُرفضa/../b)
سطح بيانات الاعتماد المدعوم
- المصفوفة القانونية: سطح بيانات اعتماد SecretRef
- تستهدف
secrets applyمسارات بيانات اعتمادopenclaw.jsonالمدعومة. - تُضمّن مراجع
auth-profiles.jsonفي حل وقت التشغيل وتغطية التدقيق.
إعدادات موفري الأسرار
{ secrets: { providers: { default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", mode: "json", timeoutMs: 5000, }, vault: { source: "exec", command: "/usr/local/bin/openclaw-vault-resolver", passEnv: ["PATH", "VAULT_ADDR"], }, }, defaults: { env: "default", file: "filemain", exec: "vault", }, },}ملاحظات:
- يدعم موفر
fileالوضعينmode: "json"وmode: "singleValue"(يجب أن يكونidهو"value"في وضع singleValue). - تفشل مسارات موفرَي الملفات والتنفيذ بشكل مغلق عندما لا يكون التحقق من Windows ACL متاحًا. اضبط
allowInsecurePath: trueفقط للمسارات الموثوقة التي لا يمكن التحقق منها. - يتطلب موفر
execمسارcommandمطلقًا ويستخدم حمولات البروتوكول عبر stdin/stdout. - افتراضيًا، تُرفض مسارات أوامر الروابط الرمزية. اضبط
allowSymlinkCommand: trueللسماح بمسارات الروابط الرمزية أثناء التحقق من مسار الهدف المحلول. - إذا تم تكوين
trustedDirs، فتنطبق عملية التحقق من الدليل الموثوق على مسار الهدف المحلول. - تكون بيئة ابن
execفي حدّها الأدنى افتراضيًا؛ مرّر المتغيرات المطلوبة صراحةً باستخدامpassEnv. - تُحل مراجع الأسرار وقت التفعيل إلى لقطة داخل الذاكرة، ثم تقرأ مسارات الطلب اللقطة فقط.
- ينطبق ترشيح السطح النشط أثناء التفعيل: تتسبب المراجع غير المحلولة على الأسطح الممكّنة في فشل بدء التشغيل/إعادة التحميل، بينما تُتخطى الأسطح غير النشطة مع تشخيصات.
تخزين المصادقة
{ auth: { profiles: { "anthropic:default": { provider: "anthropic", mode: "api_key" }, "anthropic:work": { provider: "anthropic", mode: "api_key" }, "openai:personal": { provider: "openai", mode: "oauth" }, }, order: { anthropic: ["anthropic:default", "anthropic:work"], openai: ["openai:personal"], }, },}- تُخزَّن ملفات التعريف لكل وكيل في
<agentDir>/auth-profiles.json. - يدعم
auth-profiles.jsonمراجع على مستوى القيمة (keyRefلـapi_key، وtokenRefلـtoken) لأوضاع بيانات الاعتماد الثابتة. - خرائط
auth-profiles.jsonالمسطحة القديمة مثل{ "provider": { "apiKey": "..." } }ليست تنسيقًا لوقت التشغيل؛ يعيدopenclaw doctor --fixكتابتها إلى ملفات تعريف مفاتيح API قياسية بصيغةprovider:defaultمع نسخة احتياطية.legacy-flat.*.bak. - ملفات التعريف بوضع OAuth (
auth.profiles.<id>.mode = "oauth") لا تدعم بيانات اعتماد ملف تعريف المصادقة المدعومة بـ SecretRef. - تأتي بيانات اعتماد وقت التشغيل الثابتة من لقطات محلولة في الذاكرة؛ وتُزال إدخالات
auth.jsonالثابتة القديمة عند اكتشافها. - يستورد OAuth القديم من
~/.openclaw/credentials/oauth.json. - راجع OAuth.
- سلوك وقت تشغيل الأسرار وأدوات
audit/configure/apply: إدارة الأسرار.
auth.cooldowns
{ auth: { cooldowns: { billingBackoffHours: 5, billingBackoffHoursByProvider: { anthropic: 3, openai: 8 }, billingMaxHours: 24, authPermanentBackoffMinutes: 10, authPermanentMaxMinutes: 60, failureWindowHours: 24, overloadedProfileRotations: 1, overloadedBackoffMs: 0, rateLimitedProfileRotations: 1, }, },}billingBackoffHours: مدة التراجع الأساسية بالساعات عندما يفشل ملف تعريف بسبب أخطاء فوترة/رصيد غير كافٍ حقيقية (الافتراضي:5). قد يظل نص الفوترة الصريح يصل إلى هنا حتى في استجابات401/403، لكن مطابقات النص الخاصة بالمزوّد تبقى محددة النطاق بالمزوّد الذي يملكها (مثل OpenRouterKey limit exceeded). تبقى رسائل HTTP402القابلة لإعادة المحاولة الخاصة بنافذة الاستخدام أو حد إنفاق المؤسسة/مساحة العمل ضمن مسارrate_limitبدلًا من ذلك.billingBackoffHoursByProvider: تجاوزات اختيارية لكل مزوّد لساعات تراجع الفوترة.billingMaxHours: الحد الأقصى بالساعات لنمو تراجع الفوترة الأُسّي (الافتراضي:24).authPermanentBackoffMinutes: مدة التراجع الأساسية بالدقائق لإخفاقاتauth_permanentعالية الثقة (الافتراضي:10).authPermanentMaxMinutes: الحد الأقصى بالدقائق لنمو تراجعauth_permanent(الافتراضي:60).failureWindowHours: نافذة متحركة بالساعات تُستخدم لعدادات التراجع (الافتراضي:24).overloadedProfileRotations: الحد الأقصى لتدويرات ملف تعريف المصادقة لدى المزوّد نفسه عند أخطاء التحميل الزائد قبل الانتقال إلى بديل النموذج (الافتراضي:1). تقع هنا أشكال انشغال المزوّد مثلModelNotReadyException.overloadedBackoffMs: تأخير ثابت قبل إعادة محاولة تدوير مزوّد/ملف تعريف محمّل زائدًا (الافتراضي:0).rateLimitedProfileRotations: الحد الأقصى لتدويرات ملف تعريف المصادقة لدى المزوّد نفسه عند أخطاء حد المعدل قبل الانتقال إلى بديل النموذج (الافتراضي:1). تشمل حاوية حد المعدل هذه نصوصًا مشكلة بحسب المزوّد مثلToo many concurrent requestsوThrottlingExceptionوconcurrency limit reachedوworkers_ai ... quota limit exceededوresource exhausted.
التسجيل
{ logging: { level: "info", file: "/tmp/openclaw/openclaw.log", consoleLevel: "info", consoleStyle: "pretty", // pretty | compact | json redactSensitive: "tools", // off | tools redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"], },}- ملف السجل الافتراضي:
/tmp/openclaw/openclaw-YYYY-MM-DD.log. - اضبط
logging.fileلمسار ثابت. - يرتفع
consoleLevelإلىdebugعند استخدام--verbose. maxFileBytes: أقصى حجم لملف السجل النشط بالبايت قبل التدوير (عدد صحيح موجب؛ الافتراضي:104857600= 100 ميغابايت). يحتفظ OpenClaw بما يصل إلى خمسة أرشيفات مرقمة بجانب الملف النشط.redactSensitive/redactPatterns: إخفاء بأفضل جهد لمخرجات وحدة التحكم، وسجلات الملفات، وسجلات OTLP، ونصوص نسخ جلسات العمل المحفوظة. يعطّلredactSensitive: "off"سياسة السجل/النص العامة هذه فقط؛ ما زالت أسطح أمان الواجهة/الأدوات/التشخيصات تحجب الأسرار قبل الإرسال.
التشخيصات
{ diagnostics: { enabled: true, flags: ["telegram.*"], stuckSessionWarnMs: 30000, stuckSessionAbortMs: 300000, memoryPressureSnapshot: false, otel: { enabled: false, endpoint: "https://otel-collector.example.com:4318", tracesEndpoint: "https://traces.example.com/v1/traces", metricsEndpoint: "https://metrics.example.com/v1/metrics", logsEndpoint: "https://logs.example.com/v1/logs", protocol: "http/protobuf", // http/protobuf | grpc headers: { "x-tenant-id": "my-org" }, serviceName: "openclaw-gateway", traces: true, metrics: true, logs: false, logsExporter: "otlp", sampleRate: 1.0, flushIntervalMs: 5000, captureContent: { enabled: false, inputMessages: false, outputMessages: false, toolInputs: false, toolOutputs: false, systemPrompt: false, toolDefinitions: false, }, }, cacheTrace: { enabled: false, filePath: "~/.openclaw/logs/cache-trace.jsonl", includeMessages: true, includePrompt: true, includeSystem: true, }, },}enabled: مفتاح عام لمخرجات القياس والتتبّع (الافتراضي:true).flags: مصفوفة من سلاسل العلامات التي تفعّل مخرجات سجل موجّهة (تدعم أحرف البدل مثل"telegram.*"أو"*").stuckSessionWarnMs: عتبة عمر عدم التقدم بالمللي ثانية لتصنيف جلسات المعالجة طويلة التشغيل على أنهاsession.long_runningأوsession.stalledأوsession.stuck. تعيد الردود والأدوات والحالة والكتل وتقدم ACP ضبط المؤقت؛ وتتراجع تشخيصاتsession.stuckالمتكررة ما دامت بلا تغيير.stuckSessionAbortMs: عتبة عمر عدم التقدم بالمللي ثانية قبل أن يصبح العمل النشط المتعثر مؤهلًا للتصريف بالإيقاف من أجل التعافي. عند عدم ضبطها، يستخدم OpenClaw نافذة التشغيل المضمنة الموسعة الأكثر أمانًا، وهي 5 دقائق على الأقل و3 أضعافstuckSessionWarnMs.memoryPressureSnapshot: تلتقط لقطة استقرار منقحة قبل نفاد الذاكرة عندما يصل ضغط الذاكرة إلىcritical(الافتراضي:false). اضبطها علىtrueلإضافة فحص/كتابة ملف حزمة الاستقرار مع إبقاء أحداث ضغط الذاكرة العادية.otel.enabled: يفعّل خط أنابيب تصدير OpenTelemetry (الافتراضي:false). للتكوين الكامل، وفهرس الإشارات، ونموذج الخصوصية، راجع تصدير OpenTelemetry.otel.endpoint: عنوان URL للمجمّع لتصدير OTel.otel.tracesEndpoint/otel.metricsEndpoint/otel.logsEndpoint: نقاط نهاية OTLP اختيارية خاصة بالإشارة. عند ضبطها، تتجاوزotel.endpointلتلك الإشارة فقط.otel.protocol:"http/protobuf"(الافتراضي) أو"grpc".otel.headers: ترويسات بيانات وصفية إضافية لـ HTTP/gRPC تُرسل مع طلبات تصدير OTel.otel.serviceName: اسم الخدمة لسمات المورد.otel.traces/otel.metrics/otel.logs: تفعيل تصدير التتبّع أو المقاييس أو السجلات.otel.logsExporter: وجهة تصدير السجلات:"otlp"(الافتراضي)، أو"stdout"لكائن JSON واحد لكل سطر stdout، أو"both".otel.sampleRate: معدل أخذ عينات التتبّع0-1.otel.flushIntervalMs: فاصل تفريغ القياسات الدورية بالمللي ثانية.otel.captureContent: التقاط اختياري للمحتوى الخام لسمات مقطع OTEL. يكون معطلًا افتراضيًا. تلتقط القيمة المنطقيةtrueمحتوى الرسائل/الأدوات غير النظامي؛ ويتيح لك شكل الكائن تفعيلinputMessagesوoutputMessagesوtoolInputsوtoolOutputsوsystemPromptوtoolDefinitionsصراحةً.OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: متغير بيئة لتفعيل أحدث شكل تجريبي لمقاطع استدلال GenAI، بما في ذلك أسماء المقاطع{gen_ai.operation.name} {gen_ai.request.model}، ونوع المقطعCLIENT، وgen_ai.provider.nameبدلًا منgen_ai.systemالقديم. افتراضيًا تحتفظ المقاطع بـopenclaw.model.callوgen_ai.systemللتوافق؛ وتستخدم مقاييس GenAI سمات دلالية محدودة.OPENCLAW_OTEL_PRELOADED=1: متغير بيئة للمضيفين الذين سجّلوا مسبقًا SDK OpenTelemetry عامًا. عندها يتخطى OpenClaw بدء/إيقاف SDK المملوك للـ Plugin مع إبقاء مستمعي التشخيص نشطين.OTEL_EXPORTER_OTLP_TRACES_ENDPOINTوOTEL_EXPORTER_OTLP_METRICS_ENDPOINTوOTEL_EXPORTER_OTLP_LOGS_ENDPOINT: متغيرات بيئة لنقاط نهاية خاصة بالإشارة تُستخدم عندما يكون مفتاح التكوين المطابق غير مضبوط.cacheTrace.enabled: تسجيل لقطات تتبّع الذاكرة المخبئية للتشغيلات المضمنة (الافتراضي:false).cacheTrace.filePath: مسار إخراج JSONL لتتبّع الذاكرة المخبئية (الافتراضي:$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).cacheTrace.includeMessages/includePrompt/includeSystem: التحكم فيما يُضمَّن في مخرجات تتبّع الذاكرة المخبئية (كلها افتراضيًا:true).
التحديث
{ update: { channel: "stable", // stable | beta | dev checkOnStart: true, auto: { enabled: false, stableDelayHours: 6, stableJitterHours: 12, betaCheckIntervalHours: 1, }, },}channel: قناة الإصدار لتثبيتات npm/git -"stable"أو"beta"أو"dev".checkOnStart: التحقق من تحديثات npm عند بدء Gateway (الافتراضي:true).auto.enabled: تفعيل التحديث التلقائي في الخلفية لتثبيتات الحزم (الافتراضي:false).auto.stableDelayHours: الحد الأدنى للتأخير بالساعات قبل التطبيق التلقائي لقناة stable (الافتراضي:6؛ الحد الأقصى:168).auto.stableJitterHours: نافذة انتشار إضافية بالساعات لطرح قناة stable (الافتراضي:12؛ الحد الأقصى:168).auto.betaCheckIntervalHours: عدد مرات تشغيل فحوصات قناة beta بالساعات (الافتراضي:1؛ الحد الأقصى:24).
ACP
{ acp: { enabled: true, dispatch: { enabled: true }, backend: "acpx", defaultAgent: "main", allowedAgents: ["main", "ops"], maxConcurrentSessions: 10, stream: { coalesceIdleMs: 50, maxChunkChars: 1000, repeatSuppression: true, deliveryMode: "live", // live | final_only hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph maxOutputChars: 50000, maxSessionUpdateChars: 500, }, runtime: { ttlMinutes: 30, }, },}enabled: بوابة ميزة ACP العامة (الافتراضي:true؛ اضبطها علىfalseلإخفاء إمكانات إرسال ACP والإنشاء).dispatch.enabled: بوابة مستقلة لإرسال دور جلسة ACP (الافتراضي:true). اضبطها علىfalseلإبقاء أوامر ACP متاحة مع حظر التنفيذ.backend: معرّف الواجهة الخلفية الافتراضي لوقت تشغيل ACP (يجب أن يطابق Plugin وقت تشغيل ACP مسجلًا). ثبّت Plugin الواجهة الخلفية أولًا، وإذا كانplugins.allowمضبوطًا، فأدرج معرّف Plugin الواجهة الخلفية (مثلacpx) وإلا فلن تُحمَّل واجهة ACP الخلفية.defaultAgent: معرّف الوكيل الهدف الاحتياطي لـ ACP عندما لا تحدد عمليات الإنشاء هدفًا صريحًا.allowedAgents: قائمة سماح لمعرّفات الوكلاء المسموح بها لجلسات وقت تشغيل ACP؛ تعني القيمة الفارغة عدم وجود قيد إضافي.maxConcurrentSessions: الحد الأقصى لجلسات ACP النشطة في الوقت نفسه.stream.coalesceIdleMs: نافذة تفريغ الخمول بالمللي ثانية للنص المتدفق.stream.maxChunkChars: الحد الأقصى لحجم المقطع قبل تقسيم إسقاط الكتلة المتدفقة.stream.repeatSuppression: كتم أسطر الحالة/الأداة المتكررة لكل دور (الافتراضي:true).stream.deliveryMode: يبث"live"تدريجيًا؛ ويخزّن"final_only"مؤقتًا حتى أحداث نهاية الدور.stream.hiddenBoundarySeparator: الفاصل قبل النص المرئي بعد أحداث الأدوات المخفية (الافتراضي:"paragraph").stream.maxOutputChars: الحد الأقصى لأحرف مخرجات المساعد المسقطة لكل دور ACP.stream.maxSessionUpdateChars: الحد الأقصى للأحرف لأسطر حالة/تحديث ACP المسقطة.stream.tagVisibility: سجل لأسماء الوسوم إلى تجاوزات رؤية منطقية للأحداث المتدفقة.runtime.ttlMinutes: مدة TTL للخمول بالدقائق لعاملَي جلسات ACP قبل أن يصبحوا مؤهلين للتنظيف.runtime.installCommand: أمر تثبيت اختياري للتشغيل عند تهيئة بيئة وقت تشغيل ACP.
CLI
{ cli: { banner: { taglineMode: "off", // random | default | off }, },}- يتحكم
cli.banner.taglineModeفي نمط العبارة التعريفية للشعار:"random"(الافتراضي): عبارات طريفة/موسمية متناوبة."default": عبارة محايدة ثابتة (All your chats, one OpenClaw.)."off": بلا نص عبارة تعريفية (يبقى عنوان الشعار/الإصدار ظاهرًا).
- لإخفاء الشعار بالكامل (وليس العبارات التعريفية فقط)، اضبط env
OPENCLAW_HIDE_BANNER=1.
المعالج
بيانات وصفية تكتبها تدفقات الإعداد الموجّهة في CLI (onboard، configure، doctor):
{ wizard: { lastRunAt: "2026-01-01T00:00:00.000Z", lastRunVersion: "2026.1.4", lastRunCommit: "abc1234", lastRunCommand: "configure", lastRunMode: "local", securityAcknowledgedAt: "2026-01-01T00:00:00.000Z", },}الهوية
راجع حقول هوية agents.list ضمن إعدادات الوكيل الافتراضية.
الجسر (قديم، تمت إزالته)
لم تعد الإصدارات الحالية تتضمن جسر TCP. تتصل العُقد عبر Gateway WebSocket. لم تعد مفاتيح bridge.* جزءًا من مخطط الإعدادات (يفشل التحقق حتى تُزال؛ يمكن لـ openclaw doctor --fix حذف المفاتيح غير المعروفة).
إعدادات الجسر القديمة (مرجع تاريخي)
{"bridge": { "enabled": true, "port": 18790, "bind": "tailnet", "tls": { "enabled": true, "autoGenerate": true }}}Cron
{ cron: { enabled: true, maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth sessionRetention: "24h", // duration string or false runLog: { maxBytes: "2mb", // default 2_000_000 bytes keepLines: 2000, // default 2000 }, },}sessionRetention: مدة الاحتفاظ بجلسات تشغيل Cron المعزولة المكتملة قبل تنقيتها منsessions.json. يتحكم أيضًا في تنظيف نصوص Cron المؤرشفة المحذوفة. الافتراضي:24h؛ اضبطه علىfalseللتعطيل.runLog.maxBytes: مقبول للتوافق مع سجلات تشغيل Cron القديمة المدعومة بالملفات. الافتراضي:2_000_000بايت.runLog.keepLines: أحدث صفوف سجل التشغيل في SQLite المحتفظ بها لكل مهمة. الافتراضي:2000.webhookToken: رمز حامل يُستخدم لتسليم POST عبر Cron Webhook (delivery.mode = "webhook")، وإذا حُذف فلن يُرسل ترويس مصادقة.webhook: عنوان URL احتياطي قديم ومهمل لـ Webhook (http/https) يستخدمهopenclaw doctor --fixلترحيل المهام المخزنة التي لا تزال تحتوي علىnotify: true؛ يستخدم تسليم وقت التشغيلdelivery.mode="webhook"لكل مهمة معdelivery.to، أوdelivery.completionDestinationعند الحفاظ على تسليم الإعلان.
cron.retry
{ cron: { retry: { maxAttempts: 3, backoffMs: [30000, 60000, 300000], retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"], }, },}maxAttempts: الحد الأقصى لإعادات محاولة مهام Cron عند الأخطاء العابرة (الافتراضي:3؛ النطاق:0-10).backoffMs: مصفوفة تأخيرات التراجع بالمللي ثانية لكل محاولة إعادة (الافتراضي:[30000, 60000, 300000]؛ من 1 إلى 10 مُدخلات).retryOn: أنواع الأخطاء التي تطلق إعادة المحاولة -"rate_limit"،"overloaded"،"network"،"timeout"،"server_error". احذفها لإعادة محاولة جميع الأنواع العابرة.
تبقى المهام أحادية التنفيذ مفعّلة حتى تُستنفد محاولات الإعادة، ثم تُعطّل مع الاحتفاظ بحالة الخطأ النهائية. تستخدم المهام المتكررة سياسة إعادة المحاولة نفسها للأخطاء العابرة للتشغيل مجددًا بعد التراجع قبل خانتها المجدولة التالية؛ أما الأخطاء الدائمة أو استنفاد إعادات المحاولة العابرة فتعود إلى الجدول المتكرر العادي مع تراجع الخطأ.
cron.failureAlert
{ cron: { failureAlert: { enabled: false, after: 3, cooldownMs: 3600000, includeSkipped: false, mode: "announce", accountId: "main", }, },}enabled: تفعيل تنبيهات الفشل لمهام Cron (الافتراضي:false).after: عدد الإخفاقات المتتالية قبل إطلاق تنبيه (عدد صحيح موجب، الحد الأدنى:1).cooldownMs: الحد الأدنى بالمللي ثانية بين التنبيهات المتكررة للمهمة نفسها (عدد صحيح غير سالب).includeSkipped: احتساب عمليات التشغيل المتخطاة المتتالية ضمن عتبة التنبيه (الافتراضي:false). تُتتبّع عمليات التشغيل المتخطاة بشكل منفصل ولا تؤثر في تراجع أخطاء التنفيذ.mode: وضع التسليم - يرسل"announce"عبر رسالة قناة؛ وينشر"webhook"إلى Webhook المُعد.accountId: حساب اختياري أو معرف قناة اختياري لتحديد نطاق تسليم التنبيه.
cron.failureDestination
{ cron: { failureDestination: { mode: "announce", channel: "last", to: "channel:C1234567890", accountId: "main", }, },}- الوجهة الافتراضية لإشعارات فشل Cron عبر جميع المهام.
mode:"announce"أو"webhook"؛ يكون الافتراضي"announce"عند توفر بيانات هدف كافية.channel: تجاوز القناة لتسليم الإعلان. يعيد"last"استخدام آخر قناة تسليم معروفة.to: هدف إعلان صريح أو عنوان URL لـ Webhook. مطلوب لوضع Webhook.accountId: تجاوز حساب اختياري للتسليم.- يتجاوز
delivery.failureDestinationلكل مهمة هذا الافتراضي العام. - عندما لا تُعيَّن وجهة فشل عامة ولا لكل مهمة، تعود المهام التي تُسلَّم بالفعل عبر
announceإلى هدف الإعلان الأساسي ذلك عند الفشل. - لا يُدعم
delivery.failureDestinationإلا لمهامsessionTarget="isolated"ما لم يكنdelivery.modeالأساسي للمهمة هو"webhook".
راجع مهام Cron. تُتتبّع تنفيذات Cron المعزولة بوصفها مهام خلفية.
متغيرات قالب نموذج الوسائط
عناصر نائبة للقالب تُوسَّع في tools.media.models[].args:
| المتغير | الوصف |
|---|---|
{{Body}} |
نص الرسالة الواردة الكامل |
{{RawBody}} |
النص الخام (بلا أغلفة السجل/المرسل) |
{{BodyStripped}} |
النص بعد إزالة إشارات المجموعات |
{{From}} |
معرّف المرسل |
{{To}} |
معرّف الوجهة |
{{MessageSid}} |
معرّف رسالة القناة |
{{SessionId}} |
UUID الجلسة الحالية |
{{IsNewSession}} |
"true" عند إنشاء جلسة جديدة |
{{MediaUrl}} |
عنوان URL زائف للوسائط الواردة |
{{MediaPath}} |
مسار الوسائط المحلي |
{{MediaType}} |
نوع الوسائط (صورة/صوت/مستند/…) |
{{Transcript}} |
نص تفريغ الصوت |
{{Prompt}} |
مطالبة الوسائط المحلولة لإدخالات CLI |
{{MaxChars}} |
الحد الأقصى المحلول لأحرف الإخراج لإدخالات CLI |
{{ChatType}} |
"direct" أو "group" |
{{GroupSubject}} |
موضوع المجموعة (بأفضل جهد) |
{{GroupMembers}} |
معاينة أعضاء المجموعة (بأفضل جهد) |
{{SenderName}} |
اسم عرض المرسل (بأفضل جهد) |
{{SenderE164}} |
رقم هاتف المرسل (بأفضل جهد) |
{{Provider}} |
تلميح المزوّد (whatsapp، telegram، discord، إلخ) |
تضمينات الإعدادات ($include)
قسّم الإعدادات إلى ملفات متعددة:
// ~/.openclaw/openclaw.json{ gateway: { port: 18789 }, agents: { $include: "./agents.json5" }, broadcast: { $include: ["./clients/mueller.json5", "./clients/schmidt.json5"], },}سلوك الدمج:
- ملف واحد: يستبدل الكائن الحاوي.
- مصفوفة ملفات: تُدمج بعمق بالترتيب (اللاحق يتجاوز السابق).
- المفاتيح الشقيقة: تُدمج بعد التضمينات (تتجاوز القيم المضمنة).
- التضمينات المتداخلة: حتى 10 مستويات عمق.
- المسارات: تُحل نسبةً إلى الملف الذي يضمّنها، لكن يجب أن تبقى داخل دليل الإعدادات الأعلى (
dirnameلـopenclaw.json). يُسمح بالصيغ المطلقة/../فقط عندما تظل تُحل داخل ذلك الحد. يجب ألا تحتوي المسارات على بايتات null ويجب أن تكون أقصر بصرامة من 4096 حرفًا قبل الحل وبعده. - عمليات الكتابة المملوكة لـ OpenClaw التي تغيّر قسمًا واحدًا فقط من المستوى الأعلى ومدعومًا بتضمين ملف واحد تكتب عبر ذلك الملف المضمن. على سبيل المثال، يحدّث
plugins installالقيمةplugins: { $include: "./plugins.json5" }فيplugins.json5ويتركopenclaw.jsonكما هو. - تضمينات الجذر، ومصفوفات التضمين، والتضمينات ذات التجاوزات الشقيقة للقراءة فقط بالنسبة إلى عمليات الكتابة المملوكة لـ OpenClaw؛ تفشل تلك الكتابات بإغلاق محكم بدل تسطيح الإعدادات.
- الأخطاء: رسائل واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية، وتنسيق المسار غير الصالح، والطول الزائد.
ذات صلة: الإعدادات · أمثلة الإعدادات · Doctor