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", // فعالسازی اختیاری؛ خروجی قابل مشاهده به message(action=send) نیاز دارد unmentionedInbound: "room_event", }, },}نمونهٔ گسترشیافته (گزینههای اصلی)
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:personal": { provider: "openai", mode: "oauth" }, }, order: { anthropic: ["anthropic:default", "anthropic:work"], openai: ["openai:personal", "openai:default"], }, }, // 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", // opt in for shared rooms with tool-reliable models unmentionedInbound: "room_event", }, queue: { mode: "followup", debounceMs: 500, cap: 20, drop: "summarize", byChannel: { whatsapp: "followup", telegram: "followup", discord: "collect", slack: "collect", signal: "followup", imessage: "followup", webchat: "followup", }, }, }, // Tooling tools: { media: { audio: { enabled: true, maxBytes: 20971520, models: [ { provider: "openai", model: "gpt-4o-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/main/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: { enabled: true }, help: { enabled: true, requireMention: true }, }, }, }, }, slack: { enabled: true, botToken: "xoxb-REPLACE_ME", appToken: "xapp-REPLACE_ME", channels: { "#general": { enabled: 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: ["user@example.com"], 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/jobs.json", maxConcurrentRuns: 8, // default; 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: "openclaw@gmail.com", 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-host.ts.net: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 دارای پیوند نمادین اجازه میدهد بدون مجازکردن خروج دلخواه پیوندهای نمادین، به ریشهٔ مقصد واقعی و مورداعتماد وارد شوند.- برای اینکه Skill Workshop بتواند از طریق همان مقصد مورداعتماد پیوند نمادین عملیات نوشتن را انجام دهد،
مقدار
skills.workshop.allowSymlinkTargetWrites: trueرا تنظیم کنید.
الگوهای رایج
خط مبنای مشترک 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
بدون دامنههای درخواستی اعمال میشود. کلاینتهای اپراتور/مرورگر و ارتقای نقش، دامنه، فراداده یا
کلید عمومی همچنان به تأیید دستی نیاز دارند.
حالت امن پیام خصوصی (صندوق ورودی مشترک / پیامهای خصوصی چندکاربره)
اگر بیش از یک نفر میتواند به ربات شما پیام خصوصی بفرستد (چند ورودی در allowFrom، تأیید جفتسازی برای چند نفر، یا dmPolicy: "open")، حالت امن پیام خصوصی را فعال کنید تا پیامهای خصوصی فرستندگان مختلف بهطور پیشفرض یک زمینهٔ مشترک نداشته باشند:
{ // 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/Google Chat/IRC/Mattermost/Microsoft Teams/Slack، مجوزدهی فرستنده بهطور پیشفرض ابتدا بر اساس شناسه انجام میشود.
تطبیق مستقیم نام/ایمیل/نام مستعارِ تغییرپذیر را با dangerouslyAllowNameMatching: true در هر کانال فقط زمانی فعال کنید که صراحتاً این خطر را میپذیرید.
کلید API Anthropic و جایگزین 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": { enabled: true, requireMention: true }, "#general": { enabled: 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. - برای نکات عمیقتر دربارهٔ راهاندازی، ارائهدهندگان و عیبیابی را ببینید.