Gateway

نمونه‌های پیکربندی

نمونه‌های زیر با شِمای پیکربندی فعلی هماهنگ هستند. برای مرجع جامع و توضیحات مربوط به هر فیلد، به پیکربندی مراجعه کنید.

شروع سریع

حداقل مطلق

json5
{  agents: { defaults: { workspace: "~/.openclaw/workspace" } },  channels: { whatsapp: { allowFrom: ["+15555550123"] } },}

آن را در ~/.openclaw/openclaw.json ذخیره کنید؛ سپس می‌توانید از آن شماره به ربات پیام خصوصی بفرستید.

پیکربندی آغازین پیشنهادی

json5
{  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 معمولی نیز قابل استفاده است.

json5
{  // 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.

json5
{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}
  • extraDirs مخزن هم‌رده را به‌عنوان یک ریشهٔ صریح Skills پویش می‌کند.
  • allowSymlinkTargets به پوشه‌های Skills دارای پیوند نمادین اجازه می‌دهد بدون مجازکردن خروج دلخواه پیوندهای نمادین، به ریشهٔ مقصد واقعی و مورداعتماد وارد شوند.
  • برای اینکه Skill Workshop بتواند از طریق همان مقصد مورداعتماد پیوند نمادین عملیات نوشتن را انجام دهد، مقدار skills.workshop.allowSymlinkTargetWrites: true را تنظیم کنید.

الگوهای رایج

خط مبنای مشترک Skills با یک بازنویسی

json5
{  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: [] استفاده کنید.

راه‌اندازی چندسکویی

json5
{  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 دقیق فعال کنید:

json5
{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],      },    },  },}

اگر تنظیم نشود، همچنان غیرفعال می‌ماند. این قابلیت فقط برای جفت‌سازی جدید role: node بدون دامنه‌های درخواستی اعمال می‌شود. کلاینت‌های اپراتور/مرورگر و ارتقای نقش، دامنه، فراداده یا کلید عمومی همچنان به تأیید دستی نیاز دارند.

حالت امن پیام خصوصی (صندوق ورودی مشترک / پیام‌های خصوصی چندکاربره)

اگر بیش از یک نفر می‌تواند به ربات شما پیام خصوصی بفرستد (چند ورودی در allowFrom، تأیید جفت‌سازی برای چند نفر، یا dmPolicy: "open"حالت امن پیام خصوصی را فعال کنید تا پیام‌های خصوصی فرستندگان مختلف به‌طور پیش‌فرض یک زمینهٔ مشترک نداشته باشند:

json5
{  // 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

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

ربات کاری (دسترسی محدود)

json5
{  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 },      },    },  },}

فقط مدل‌های محلی

json5
{  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.
  • برای نکات عمیق‌تر دربارهٔ راه‌اندازی، ارائه‌دهندگان و عیب‌یابی را ببینید.

مرتبط

Was this useful?
On this page

On this page