مرجع الإعدادات

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 config schema مخطط JSON Schema الحي المستخدم للتحقق وواجهة Control UI، مع دمج بيانات الحزم/الـ plugin/القنوات الوصفية عند توفرها
• يعيد config.schema.lookup عقدة مخطط واحدة محددة بالمسار لأدوات التعمق
• يتحقق pnpm config:docs:check / pnpm config:docs:gen من تجزئة خط أساس وثائق الإعدادات مقابل سطح المخطط الحالي

• مرجع تكوين الذاكرة لـ agents.defaults.memorySearch.* وmemory.qmd.* وmemory.citations وتكوين dreaming ضمن plugins.entries.memory-core.config.dreaming
• أوامر Slash لكتالوج الأوامر الحالي المدمج + المحزم
• صفحات القنوات/الـ plugin المالكة لأسطح الأوامر الخاصة بالقنوات

​

القنوات

​

القيم الافتراضية للوكلاء، وتعدد الوكلاء، والجلسات، والرسائل

• agents.defaults.* (مساحة العمل، النموذج، التفكير، heartbeat، الذاكرة، الوسائط، Skills، صندوق العزل)
• 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/macOS
  • talk.silenceTimeoutMs: عند عدم تعيينه، يحتفظ Talk بنافذة التوقف الافتراضية للمنصة قبل إرسال النص (700 ms on macOS and Android, 900 ms on iOS)

​

الأدوات والمزودون المخصصون

​

النماذج

{
  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: {
    // 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
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
      },
    },
  },
}

• mcp.servers: تعريفات خوادم MCP مسماة بنمط stdio أو بعيدة لبيئات التشغيل التي تعرض أدوات MCP المكوّنة. تستخدم الإدخالات البعيدة transport: "streamable-http" أو transport: "sse"؛ وtype: "http" اسم مستعار أصلي للـ CLI يقوم openclaw mcp set و openclaw doctor --fix بتطبيعه إلى حقل transport القياسي.
• mcp.sessionIdleTtlMs: مدة TTL للخمول لبيئات تشغيل MCP المحزمة المحددة بنطاق الجلسة. تطلب التشغيلات المضمنة لمرة واحدة التنظيف عند نهاية التشغيل؛ وتكون مدة TTL هذه هي حد الأمان للجلسات طويلة العمر والمستدعين المستقبليين.
• تُطبّق التغييرات ضمن mcp.* فورًا عبر التخلص من بيئات تشغيل MCP المخزنة للجلسات. يعيد اكتشاف/استخدام الأداة التالي إنشاءها من الإعدادات الجديدة، لذلك تُزال إدخالات mcp.servers المحذوفة فورًا بدلًا من انتظار مدة TTL للخمول.

​

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,
    },
    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 الرمزية عندما يكون الرابط خارج جذر المصدر المكوّن له.
• 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: false يعطل skill حتى لو كانت محزمة/مثبتة.
• entries.<skillKey>.apiKey: تسهيل للـ skills التي تعلن متغير بيئة أساسيًا (سلسلة نصية صريحة أو كائن SecretRef).

​

Plugins

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    bundledDiscovery: "allowlist",
    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.
• يقبل الاكتشاف plugins OpenClaw الأصلية إضافة إلى حزم Codex المتوافقة وحزم Claude، بما في ذلك حزم Claude ذات التخطيط الافتراضي بلا manifest.
• تتطلب تغييرات الإعدادات إعادة تشغيل gateway.
• allow: قائمة سماح اختيارية (تُحمّل plugins المدرجة فقط). تكون أولوية deny أعلى.
• bundledDiscovery: القيمة الافتراضية هي "allowlist" للإعدادات الجديدة، بحيث إن وجود plugins.allow غير فارغة يقيّد أيضًا plugins المزودين المحزمة، بما في ذلك مزودي تشغيل بحث الويب. يكتب Doctor القيمة "compat" لإعدادات قوائم السماح القديمة المرحّلة للحفاظ على سلوك مزودي الحزم الحالي حتى تختار الاشتراك.
• 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 لكل تشغيل لتشغيلات الوكلاء الفرعيين في الخلفية.
• plugins.entries.<id>.subagent.allowedModels: قائمة سماح اختيارية لأهداف provider/model القياسية لتجاوزات الوكيل الفرعي الموثوقة. استخدم "*" فقط عندما تريد عمدًا السماح بأي نموذج.
• 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 الوصفية في manifest الخاصة بالـ plugin المالك، لا سجل خيارات OpenClaw مركزي.

​

إعدادات Codex harness plugin

{
  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/app الأصلي لحزمة Codex. الافتراضي: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: سياسة إجراءات التدمير الافتراضية لاستدعاءات تطبيقات Plugin المرحّلة. الافتراضي: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: يفعّل إدخال Plugin مرحّلاً عندما يكون codexPlugins.enabled العام مضبوطاً أيضاً على true. الافتراضي: true للإدخالات الصريحة.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: هوية سوق ثابتة. يدعم V1 فقط "openai-curated".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: هوية Codex Plugin ثابتة من الترحيل، مثل "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: تجاوز إجراءات التدمير لكل Plugin. عند حذفه، تُستخدم قيمة allow_destructive_actions العامة.

• plugins.entries.firecrawl.config.webFetch: إعدادات موفر جلب الويب Firecrawl.
  • apiKey: مفتاح Firecrawl API (يقبل SecretRef). يعود إلى plugins.entries.firecrawl.config.webSearch.apiKey أو tools.web.fetch.firecrawl.apiKey القديم أو متغير البيئة FIRECRAWL_API_KEY.
  • baseUrl: عنوان URL الأساسي لـ Firecrawl API (الافتراضي: 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: تجاوز اختياري لنموذج الوكيل الفرعي Dream Diary. يتطلب plugins.entries.memory-core.subagent.allowModelOverride: true؛ اقرنه مع allowedModels لتقييد الأهداف. تُعاد محاولة أخطاء عدم توفر النموذج مرة واحدة باستخدام نموذج الجلسة الافتراضي؛ إخفاقات الثقة أو قائمة السماح لا تعود احتياطياً بصمت.
  • سياسة المراحل والعتبات هي تفاصيل تنفيذية (وليست مفاتيح إعدادات ظاهرة للمستخدم).
• توجد إعدادات الذاكرة الكاملة في مرجع إعدادات الذاكرة:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• يمكن أيضاً لـ plugins حزمة Claude المفعّلة المساهمة بإعدادات Pi افتراضية مضمّنة من settings.json؛ يطبق OpenClaw هذه كإعدادات وكيل منقّاة، وليس كتصحيحات إعدادات OpenClaw خام.
• plugins.slots.memory: اختر معرّف Plugin الذاكرة النشط، أو "none" لتعطيل plugins الذاكرة.
• plugins.slots.contextEngine: اختر معرّف Plugin محرك السياق النشط؛ تكون القيمة الافتراضية "legacy" ما لم تثبّت وتحدد محركاً آخر.

​

الالتزامات

• 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 بالإضافة إلى طلبات فتح الألسنة. تحتفظ ملفات تعريف loopback المُدارة بإعدادات CDP المحلية الافتراضية.
• إذا كانت خدمة CDP مُدارة خارجياً وقابلة للوصول عبر loopback، فاضبط attachOnly: true لذلك الملف الشخصي؛ وإلا يعامل OpenClaw منفذ loopback كملف تعريف متصفح محلي مُدار وقد يبلغ عن أخطاء ملكية المنفذ المحلي.
• تستخدم ملفات تعريف existing-session Chrome MCP بدلاً من CDP ويمكنها الاتصال على المضيف المحدد أو عبر عقدة متصفح متصلة.
• يمكن لملفات تعريف existing-session ضبط userDataDir لاستهداف ملف تعريف متصفح محدد قائم على Chromium مثل Brave أو Edge.
• تحتفظ ملفات تعريف existing-session بحدود مسار Chrome MCP الحالية: إجراءات مدفوعة باللقطات/المراجع بدلاً من استهداف محددات CSS، وخطافات تحميل ملف واحد، ولا توجد تجاوزات مهلة للحوار، ولا wait --load networkidle، ولا responsebody، أو تصدير PDF، أو اعتراض التنزيل، أو إجراءات دفعية.
• تُعيّن ملفات تعريف openclaw المحلية المُدارة cdpPort وcdpUrl تلقائياً؛ اضبط cdpUrl صراحةً فقط لـ CDP البعيد.
• يمكن لملفات التعريف المحلية المُدارة ضبط executablePath لتجاوز browser.executablePath العام لذلك الملف الشخصي. استخدم هذا لتشغيل ملف تعريف في Chrome وآخر في Brave.
• تستخدم ملفات التعريف المحلية المُدارة browser.localLaunchTimeoutMs لاكتشاف HTTP الخاص بـ Chrome CDP بعد بدء العملية وbrowser.localCdpReadyTimeoutMs لجاهزية websocket الخاصة بـ CDP بعد الإطلاق. ارفعها على المضيفات الأبطأ حيث يبدأ Chrome بنجاح لكن فحوص الجاهزية تتسابق مع بدء التشغيل. يجب أن تكون كلتا القيمتين أعداداً صحيحة موجبة حتى 120000 مللي ثانية؛ تُرفض قيم الإعدادات غير الصالحة.
• ترتيب الاكتشاف التلقائي: المتصفح الافتراضي إذا كان قائماً على Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• يقبل كل من browser.executablePath وbrowser.profiles.<name>.executablePath ~ و~/... لدليل المنزل في نظام التشغيل لديك قبل تشغيل Chromium. يتم أيضاً توسيع التلدة في userDataDir لكل ملف تعريف على ملفات تعريف existing-session.
• خدمة التحكم: loopback فقط (المنفذ مشتق من 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: تجاوز هوية واجهة التحكم. يعود إلى هوية الوكيل النشط.

​

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://gateway.tailnet: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
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

​

نقاط النهاية المتوافقة مع OpenAI

• إكمالات الدردشة: معطلة افتراضيًا. فعّلها باستخدام gateway.http.endpoints.chatCompletions.enabled: true.
• واجهة Responses API: gateway.http.endpoints.responses.enabled.
• تقوية إدخال عناوين URL في Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.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 التي تتحكم بها؛ راجع مصادقة الوكيل الموثوق)

​

عزل المثيلات المتعددة

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

​

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",
      },
    ],
  },
}

• يتطلب hooks.enabled=true قيمة غير فارغة في hooks.token.
• يجب أن يكون hooks.token مختلفًا عن gateway.auth.token؛ تُرفض إعادة استخدام رمز Gateway.
• لا يمكن أن يكون 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.

​

تكامل 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" (الافتراضي).
• الارتباطات غير loopback: تتطلب مسارات اللوحة مصادقة Gateway (رمز/كلمة مرور/وكيل موثوق)، مثل أسطح HTTP الأخرى في Gateway.
• لا ترسل Node WebViews عادةً رؤوس المصادقة؛ بعد إقران node واتصالها، يعلن Gateway عن عناوين URL للقدرات محددة النطاق للـ node للوصول إلى اللوحة/A2UI.
• ترتبط عناوين URL للقدرات بجلسة WS النشطة الخاصة بـ node وتنتهي صلاحيتها بسرعة. لا يُستخدم الرجوع المستند إلى IP.
• يحقن عميل إعادة التحميل الحي في HTML المقدّم.
• ينشئ تلقائيًا ملف index.html بادئًا عندما يكون فارغًا.
• يقدم أيضًا A2UI عند /__openclaw__/a2ui/.
• تتطلب التغييرات إعادة تشغيل Gateway.
• عطّل إعادة التحميل الحي للأدلة الكبيرة أو أخطاء EMFILE.

​

الاكتشاف

​

mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal (الافتراضي عندما يكون Plugin bonjour المضمن ممكّنًا): يحذف cliPath + sshPort من سجلات TXT.
• full: يتضمن cliPath + sshPort؛ ما زال إعلان البث المتعدد عبر LAN يتطلب تمكين Plugin bonjour المضمن.
• off: يمنع إعلان البث المتعدد عبر LAN دون تغيير تمكين Plugin.
• يبدأ Plugin bonjour المضمن تلقائيًا على مضيفي macOS ويكون اختياريًا على Linux وWindows ونشرات Gateway المعبأة في حاويات.
• يكون اسم المضيف افتراضيًا هو اسم مضيف النظام عندما يكون تسمية DNS صالحة، مع الرجوع إلى openclaw. تجاوزه باستخدام OPENCLAW_MDNS_HOSTNAME.

​

النطاق الواسع (DNS-SD)

{
  discovery: {
    wideArea: { enabled: true },
  },
}

​

البيئة

​

env (متغيرات بيئة مضمنة)

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• لا تُطبّق متغيرات البيئة المضمنة إلا إذا كانت بيئة العملية تفتقد المفتاح.
• ملفات .env: ملف .env في CWD + ~/.openclaw/.env (لا يتجاوز أي منهما المتغيرات الموجودة).
• shellEnv: يستورد المفاتيح المتوقعة المفقودة من ملف تعريف صدفة تسجيل الدخول لديك.
• راجع البيئة لمعرفة أسبقية الإعدادات الكاملة.

​

استبدال متغيرات البيئة

{
  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}$
• يجب ألا تحتوي معرّفات 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).
• تفشل مسارات موفرَي file وexec بإغلاق آمن عندما لا يتوفر التحقق من Windows ACL. عيّن allowInsecurePath: true فقط للمسارات الموثوقة التي لا يمكن التحقق منها.
• يتطلب موفر exec مسار command مطلقًا ويستخدم حمولات البروتوكول عبر stdin/stdout.
• افتراضيًا، تُرفض مسارات أوامر symlink. عيّن allowSymlinkCommand: true للسماح بمسارات symlink مع التحقق من مسار الهدف بعد الحل.
• إذا تم إعداد trustedDirs، ينطبق فحص الدليل الموثوق على مسار الهدف بعد الحل.
• تكون بيئة العملية الفرعية لـ exec بالحد الأدنى افتراضيًا؛ مرّر المتغيرات المطلوبة صراحةً باستخدام passEnv.
• تُحل مراجع الأسرار عند وقت التنشيط إلى لقطة داخل الذاكرة، ثم تقرأ مسارات الطلب اللقطة فقط.
• ينطبق ترشيح السطح النشط أثناء التنشيط: تفشل المراجع غير المحلولة على الأسطح الممكّنة في بدء التشغيل/إعادة التحميل، بينما يتم تخطي الأسطح غير النشطة مع تشخيصات.

​

تخزين المصادقة

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      "openai-codex": ["openai-codex: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، لكن مطابقات النص الخاصة بالمزوّد تبقى محصورة في نطاق المزوّد الذي يملكها (مثل OpenRouter Key limit exceeded). تبقى رسائل نافذة استخدام HTTP 402 القابلة لإعادة المحاولة أو رسائل حد إنفاق المؤسسة/مساحة العمل في مسار 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: 600000,

    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,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: 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 نافذة تشغيل مضمّن ممتدة أكثر أمانًا لا تقل عن 10 دقائق و5 أضعاف stuckSessionWarnMs.
• 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.sampleRate: معدل أخذ عينات التتبع 0-1.
• otel.flushIntervalMs: فاصل تفريغ القياسات الدورية بالمللي ثانية.
• otel.captureContent: التقاط اختياري للمحتوى الخام لسمات امتداد OTEL. يكون معطلًا افتراضيًا. يلتقط Boolean true محتوى الرسائل/الأدوات غير النظامي؛ أما صيغة الكائن فتتيح لك تفعيل inputMessages وoutputMessages وtoolInputs وtoolOutputs وsystemPrompt صراحةً.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: مفتاح تبديل بيئة لسمات مزوّد امتدادات GenAI التجريبية الأحدث. تحتفظ الامتدادات افتراضيًا بسمة 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": بلا نص عبارة (مع استمرار عرض عنوان/إصدار اللافتة).
• لإخفاء اللافتة بالكامل (وليس العبارات فقط)، عيّن متغير البيئة OPENCLAW_HIDE_BANNER=1.

​

المعالج

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

​

الهوية

​

الجسر (قديم، مُزال)

{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

​

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // 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/runs/<jobId>.jsonl) قبل التقليم. الافتراضي: 2_000_000 بايت.
• runLog.keepLines: أحدث الأسطر المحتفَظ بها عند تشغيل تقليم سجل التشغيل. الافتراضي: 2000.
• webhookToken: رمز الحامل المستخدم لتسليم POST الخاص بـ Cron Webhook (delivery.mode = "webhook")، وإذا أُغفل فلن يُرسل ترويس مصادقة.
• webhook: عنوان URL قديم ومهمل لـ Webhook احتياطي (http/https) يُستخدم فقط للمهام المخزنة التي لا تزال تحتوي على notify: true.

​

cron.retry

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

• maxAttempts: الحد الأقصى لإعادة المحاولة لمهام التشغيل لمرة واحدة عند حدوث أخطاء عابرة (الافتراضي: 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".

​

متغيرات قالب نموذج الوسائط

​

تضمينات الإعداد ($include)

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

• ملف واحد: يستبدل الكائن الحاوي.
• مصفوفة ملفات: تُدمج دمجًا عميقًا بالترتيب (اللاحق يتجاوز السابق).
• المفاتيح الشقيقة: تُدمج بعد التضمينات (تتجاوز القيم المضمّنة).
• التضمينات المتداخلة: حتى 10 مستويات عمق.
• المسارات: تُحل نسبةً إلى الملف الذي يجري التضمين، لكن يجب أن تبقى داخل دليل الإعداد ذي المستوى الأعلى (dirname لـ openclaw.json). لا تُسمح صيغ المسارات المطلقة/../ إلا عندما تظل تُحل داخل ذلك الحد.
• عمليات الكتابة المملوكة لـ OpenClaw التي تغيّر قسمًا واحدًا فقط من المستوى الأعلى مدعومًا بتضمين ملف واحد تكتب عبره إلى ذلك الملف المضمّن. على سبيل المثال، يحدّث plugins install القسم plugins: { $include: "./plugins.json5" } في plugins.json5 ويترك openclaw.json دون تغيير.
• تضمينات الجذر، ومصفوفات التضمين، والتضمينات ذات التجاوزات الشقيقة تكون للقراءة فقط لعمليات الكتابة المملوكة لـ OpenClaw؛ تفشل تلك الكتابات بإغلاق آمن بدل تسطيح الإعداد.
• الأخطاء: رسائل واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية.

​

ذو صلة

• الإعداد
• أمثلة الإعداد