Gateway
أمثلة التكوين
الأمثلة أدناه متوافقة مع مخطط التهيئة الحالي. للاطلاع على المرجع الشامل وملاحظات كل حقل، راجع التهيئة.
البدء السريع
الحد الأدنى المطلق
{ agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } },}احفظه في ~/.openclaw/openclaw.json ويمكنك مراسلة الروبوت برسالة خاصة من ذلك الرقم.
إعداد البدء الموصى به
{ agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-sonnet-4-6" }, }, list: [ { id: "main", identity: { name: "Clawd", theme: "helpful assistant", emoji: "🦞", }, }, ], }, channels: { whatsapp: { allowFrom: ["+15555550123"], groups: { "*": { requireMention: true } }, }, }, messages: { visibleReplies: "automatic", groupChat: { visibleReplies: "message_tool", // default; use "automatic" for legacy room replies }, },}مثال موسّع (الخيارات الرئيسية)
يتيح لك JSON5 استخدام التعليقات والفواصل اللاحقة. يعمل JSON العادي أيضًا.
{ // Environment + shell env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, shellEnv: { enabled: true, timeoutMs: 15000, }, }, // Auth profile metadata (secrets live in auth-profiles.json) auth: { profiles: { "anthropic:default": { provider: "anthropic", mode: "api_key" }, "anthropic:work": { provider: "anthropic", mode: "api_key" }, "openai:default": { provider: "openai", mode: "api_key" }, "openai-codex:personal": { provider: "openai-codex", mode: "oauth" }, }, order: { anthropic: ["anthropic:default", "anthropic:work"], openai: ["openai:default"], "openai-codex": ["openai-codex:personal"], }, }, // Identity is per agent — set it on agents.list[].identity below. // Logging logging: { level: "info", file: "/tmp/openclaw/openclaw.log", consoleLevel: "info", consoleStyle: "pretty", redactSensitive: "tools", }, // Message formatting messages: { messagePrefix: "[openclaw]", visibleReplies: "automatic", responsePrefix: ">", ackReaction: "👀", ackReactionScope: "group-mentions", groupChat: { historyLimit: 50, visibleReplies: "message_tool", // normal final replies stay private in groups/channels }, queue: { mode: "steer", debounceMs: 500, cap: 20, drop: "summarize", byChannel: { whatsapp: "steer", telegram: "steer", discord: "steer", slack: "steer", signal: "steer", imessage: "steer", webchat: "steer", }, }, }, // Tooling tools: { media: { audio: { enabled: true, maxBytes: 20971520, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, // Optional CLI fallback (Whisper binary): // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] } ], timeoutSeconds: 120, }, video: { enabled: true, maxBytes: 52428800, models: [{ provider: "google", model: "gemini-3-flash-preview" }], }, }, }, // Session behavior session: { scope: "per-sender", dmScope: "per-channel-peer", // recommended for multi-user inboxes reset: { mode: "daily", atHour: 4, idleMinutes: 60, }, resetByChannel: { discord: { mode: "idle", idleMinutes: 10080 }, }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/default/sessions/sessions.json", maintenance: { mode: "warn", pruneAfter: "30d", maxEntries: 500, resetArchiveRetention: "30d", // duration or false maxDiskBytes: "500mb", // optional highWaterBytes: "400mb", // optional (defaults to 80% of maxDiskBytes) }, typingIntervalSeconds: 5, sendPolicy: { default: "allow", rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], }, }, // Channels channels: { whatsapp: { dmPolicy: "pairing", allowFrom: ["+15555550123"], groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true } }, }, telegram: { enabled: true, botToken: "YOUR_TELEGRAM_BOT_TOKEN", allowFrom: ["123456789"], groupPolicy: "allowlist", groupAllowFrom: ["123456789"], groups: { "*": { requireMention: true } }, }, discord: { enabled: true, token: "YOUR_DISCORD_BOT_TOKEN", dm: { enabled: true, allowFrom: ["123456789012345678"] }, guilds: { "123456789012345678": { slug: "friends-of-openclaw", requireMention: false, channels: { general: { allow: true }, help: { allow: true, requireMention: true }, }, }, }, }, slack: { enabled: true, botToken: "xoxb-REPLACE_ME", appToken: "xapp-REPLACE_ME", channels: { "#general": { allow: true, requireMention: true }, }, dm: { enabled: true, allowFrom: ["U123"] }, slashCommand: { enabled: true, name: "openclaw", sessionPrefix: "slack:slash", ephemeral: true, }, }, }, // Agent runtime agents: { defaults: { workspace: "~/.openclaw/workspace", userTimezone: "America/Chicago", model: { primary: "anthropic/claude-sonnet-4-6", fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"], }, imageModel: { primary: "openrouter/anthropic/claude-sonnet-4-6", }, models: { "anthropic/claude-opus-4-6": { alias: "opus" }, "anthropic/claude-sonnet-4-6": { alias: "sonnet" }, "openai/gpt-5.4": { alias: "gpt" }, }, skills: ["github", "weather"], // inherited by agents that omit list[].skills thinkingDefault: "low", verboseDefault: "off", toolProgressDetail: "explain", reasoningDefault: "off", elevatedDefault: "on", blockStreamingDefault: "off", blockStreamingBreak: "text_end", blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph", }, blockStreamingCoalesce: { idleMs: 1000, }, humanDelay: { mode: "natural", }, timeoutSeconds: 600, mediaMaxMb: 5, typingIntervalSeconds: 5, maxConcurrent: 3, heartbeat: { every: "30m", model: "anthropic/claude-sonnet-4-6", target: "last", directPolicy: "allow", // allow (default) | block to: "+15555550123", prompt: "HEARTBEAT", ackMaxChars: 300, }, memorySearch: { provider: "gemini", model: "gemini-embedding-001", remote: { apiKey: "${GEMINI_API_KEY}", }, extraPaths: ["../team-docs", "/srv/shared-notes"], }, sandbox: { mode: "non-main", scope: "session", // preferred over legacy perSession: true workspaceRoot: "~/.openclaw/sandboxes", docker: { image: "openclaw-sandbox:bookworm-slim", workdir: "/workspace", readOnlyRoot: true, tmpfs: ["/tmp", "/var/tmp", "/run"], network: "none", user: "1000:1000", }, browser: { enabled: false, }, }, }, list: [ { id: "main", default: true, identity: { name: "Samantha", theme: "helpful sloth", emoji: "🦥", }, // inherits defaults.skills -> github, weather groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, thinkingDefault: "high", // per-agent thinking override reasoningDefault: "on", // per-agent reasoning visibility fastModeDefault: false, // per-agent fast mode }, { id: "quick", skills: [], // no skills for this agent fastModeDefault: true, // this agent always runs fast thinkingDefault: "off", }, ], }, tools: { allow: ["exec", "process", "read", "write", "edit", "apply_patch"], deny: ["browser", "canvas"], exec: { backgroundMs: 10000, timeoutSec: 1800, cleanupMs: 1800000, }, elevated: { enabled: true, allowFrom: { whatsapp: ["+15555550123"], telegram: ["123456789"], discord: ["123456789012345678"], slack: ["U123"], signal: ["+15555550123"], imessage: ["[email protected]"], webchat: ["session:demo"], }, }, }, // Custom model providers models: { mode: "merge", providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", apiKey: "LITELLM_KEY", api: "openai-responses", authHeader: true, headers: { "X-Proxy-Region": "us-west" }, models: [ { id: "llama-3.1-8b", name: "Llama 3.1 8B", api: "openai-responses", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, maxTokens: 32000, }, ], }, }, }, // Cron jobs cron: { enabled: true, store: "~/.openclaw/cron/cron.json", maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000, }, }, // Webhooks hooks: { enabled: true, path: "/hooks", token: "shared-secret", presets: ["gmail"], transformsDir: "~/.openclaw/hooks/transforms", mappings: [ { id: "gmail-hook", match: { path: "gmail" }, action: "agent", wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}", textTemplate: "{{messages[0].snippet}}", deliver: true, channel: "last", to: "+15555550123", thinking: "low", timeoutSeconds: 300, transform: { module: "gmail.js", export: "transformGmail", }, }, ], gmail: { account: "[email protected]", label: "INBOX", 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" }, }, }, // Gateway + networking gateway: { mode: "local", port: 18789, bind: "loopback", controlUi: { enabled: true, basePath: "/openclaw" }, auth: { mode: "token", token: "gateway-token", allowTailscale: true, }, tailscale: { mode: "serve", resetOnExit: false }, remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" }, reload: { mode: "hybrid", debounceMs: 300 }, }, skills: { allowBundled: ["gemini", "peekaboo"], load: { extraDirs: ["~/Projects/agent-scripts/skills"], allowSymlinkTargets: ["~/Projects/agent-scripts/skills"], }, install: { preferBrew: true, nodeManager: "npm", // npm | pnpm | yarn | bun allowUploadedArchives: false, }, entries: { "image-lab": { enabled: true, apiKey: "GEMINI_KEY_HERE", env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, }, },}مستودع Skills شقيق مرتبط رمزياً
استخدم هذا عندما يحتوي جذر Skills مدمج على رابط رمزي إلى مستودع شقيق، على سبيل المثال ~/.agents/skills/manager -> ~/Projects/manager/skills.
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}- يفحص
extraDirsالمستودع الشقيق باعتباره جذر Skills صريحاً. - يتيح
allowSymlinkTargetsلمجلدات Skills المرتبطة رمزياً أن تُحل إلى جذر الهدف الحقيقي الموثوق هذا من دون السماح بأي إفلات عشوائي عبر الروابط الرمزية.
الأنماط الشائعة
خط أساس Skills مشترك مع تجاوز واحد
{ agents: { defaults: { workspace: "~/.openclaw/workspace", skills: ["github", "weather"], }, list: [ { id: "main", default: true }, { id: "docs", workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] }, ], },}agents.defaults.skillsهو خط الأساس المشترك.- يستبدل
agents.list[].skillsخط الأساس هذا لوكيل واحد. - استخدم
skills: []عندما ينبغي ألا يرى الوكيل أي Skills.
إعداد متعدد المنصات
{ agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] }, telegram: { enabled: true, botToken: "YOUR_TOKEN", allowFrom: ["123456789"], }, discord: { enabled: true, token: "YOUR_TOKEN", dm: { allowFrom: ["123456789012345678"] }, }, },}الموافقة التلقائية لشبكة Node الموثوقة
أبقِ إقران الأجهزة يدويًا ما لم تكن تتحكم في مسار الشبكة. بالنسبة إلى مختبر مخصص أو شبكة فرعية ضمن tailnet، يمكنك تفعيل الموافقة التلقائية على جهاز Node عند أول استخدام باستخدام CIDR أو عناوين IP دقيقة:
{ gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, }, },}يبقى هذا معطلاً عند عدم ضبطه. لا ينطبق إلا على إقران جديد لـ role: node دون
نطاقات مطلوبة. لا يزال عملاء المشغّل/المتصفح وترقيات الدور أو النطاق أو البيانات الوصفية أو
المفتاح العام تتطلب موافقة يدوية.
وضع DM الآمن (صندوق وارد مشترك / رسائل DM متعددة المستخدمين)
إذا كان بإمكان أكثر من شخص مراسلة برنامجك عبر DM (إدخالات متعددة في allowFrom، أو موافقات إقران لعدة أشخاص، أو dmPolicy: "open")، ففعّل وضع DM الآمن حتى لا تشارك رسائل DM من مرسلين مختلفين سياقًا واحدًا افتراضيًا:
{ // Secure DM mode (recommended for multi-user or sensitive DM agents) session: { dmScope: "per-channel-peer" }, channels: { // Example: WhatsApp multi-user inbox whatsapp: { dmPolicy: "allowlist", allowFrom: ["+15555550123", "+15555550124"], }, // Example: Discord multi-user inbox discord: { enabled: true, token: "YOUR_DISCORD_BOT_TOKEN", dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] }, }, },}بالنسبة إلى Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC، يكون تفويض المرسل قائمًا على المعرّف أولاً افتراضيًا.
لا تفعّل المطابقة المباشرة القابلة للتغيير للاسم/البريد الإلكتروني/اللقب باستخدام dangerouslyAllowNameMatching: true الخاص بكل قناة إلا إذا كنت تقبل هذا الخطر صراحةً.
مفتاح Anthropic API + احتياط MiniMax
{ auth: { profiles: { "anthropic:api": { provider: "anthropic", mode: "api_key", }, }, order: { anthropic: ["anthropic:api"], }, }, models: { providers: { minimax: { baseUrl: "https://api.minimax.io/anthropic", api: "anthropic-messages", apiKey: "${MINIMAX_API_KEY}", }, }, }, agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-opus-4-6", fallbacks: ["minimax/MiniMax-M2.7"], }, }, },}بوت العمل (وصول مقيّد)
{ agents: { defaults: { workspace: "~/work-openclaw", elevatedDefault: "off", }, list: [ { id: "main", identity: { name: "WorkBot", theme: "professional assistant", }, }, ], }, channels: { slack: { enabled: true, botToken: "xoxb-...", channels: { "#engineering": { allow: true, requireMention: true }, "#general": { allow: true, requireMention: true }, }, }, },}النماذج المحلية فقط
{ agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "lmstudio/my-local-model" }, }, }, models: { mode: "merge", providers: { lmstudio: { baseUrl: "http://127.0.0.1:1234/v1", apiKey: "lmstudio", api: "openai-responses", models: [ { id: "my-local-model", name: "Local Model", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 196608, maxTokens: 8192, }, ], }, }, },}نصائح
- إذا ضبطت
dmPolicy: "open"، فيجب أن تتضمن قائمةallowFromالمطابقة"*". - تختلف معرّفات المزوّدين (أرقام الهواتف، معرّفات المستخدمين، معرّفات القنوات). استخدم وثائق المزوّد لتأكيد التنسيق.
- أقسام اختيارية لإضافتها لاحقًا:
web،browser،ui،discovery،plugins،talk،signal،imessage. - راجع المزوّدون واستكشاف الأخطاء وإصلاحها للحصول على ملاحظات إعداد أعمق.