Configuration Examples

每次在調整設定檔時，最怕的就是參數名稱對不上或是結構寫錯。你可能花了大把時間在查文件，卻發現範例程式碼已經過時，這種挫折感是每個開發者都遇過的痛。

為了讓你少走彎路，我們整理了符合目前 config schema 的範例，確保你在設定時能有準確的參考依據。

需要準備的東西

對於欄位細節的基礎了解
存取 Configuration 文件的權限

快速開始

你可以依照以下步驟快速檢核你的設定：

確認你的設定檔符合目前的 config schema 要求。
參考 Configuration 頁面中的每項欄位說明進行微調。

疑難排解

目前的範例已針對最新的 schema 優化。如果你在設定過程中遇到欄位定義不明的問題，請務必確認你參考的是 Configuration 中的最新欄位說明。

如果你在設定過程中遇到任何困難，可以隨時諮詢 AI Setup Assistant。

下一步

Configuration Reference

每次想幫自己弄個 AI 助理，光是搞定通訊軟體串接跟環境設定就讓人想放棄。你可能只是想要一個能直接在 WhatsApp 上對話的工具，而不是花一整天去研究複雜的 API 文件或伺服器架構。

OpenClaw 的設計就是為了讓你跳過那些瑣碎的步驟，直接進入重點。

What You’ll Need

在開始之前，請確保你準備好：

一個 WhatsApp 帳號（用於傳送訊息給機器人）
設定檔存放路徑 ~/.openclaw/

Quick Start

最簡配置

如果你想用最快的速度跑起來，只需要設定你的工作空間（workspace）以及允許傳送訊息給機器人的電話號碼。

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

將上面的內容儲存到 ~/.openclaw/openclaw.json。完成後，你就可以從該號碼傳送 WhatsApp 私訊 (DM) 給機器人了。

Troubleshooting

無法收到回應：請確認你的電話號碼已正確填入 allowFrom 陣列中，且包含正確的國際區碼。
路徑錯誤：確保 workspace 指定的目錄 ~/.openclaw/workspace 是你的系統帳號有權限存取與寫入的。

如果你在設定過程中遇到其他問題，歡迎詢問 AI Setup Assistant。

What’s Next

開發 AI Agent 最煩人的就是處理各種平台碎裂的設定。你可能早上還在調 Discord 的權限，下午就要處理 WhatsApp 的訊息排隊，還要擔心 API Key 噴掉或日誌太亂。

這份進階配置範例能幫你解決這些瑣事。我們使用 JSON5 格式，讓你可以在設定檔裡寫註釋，也不用再為了少一個逗號而報錯，讓你把精力花在打造 Agent 的邏輯上。

需要準備的東西

在開始之前，請確保你已經準備好以下資訊：

你的 API Key（例如 OpenRouter, Anthropic, OpenAI 或 Groq）
想要整合的頻道 Token（如 Telegram Bot Token, Discord Token 或 Slack App Token）
基礎的 Node.js 執行環境

快速開始

只要 5 分鐘，你就能建立一個功能完整的 Agent 執行環境：

建立設定檔：在你的專案目錄建立一個 config.json5。
複製範例：將下方的進階配置內容完整貼上。
填入 Token：搜尋 YOUR_TELEGRAM_BOT_TOKEN 等預留位置，填入你的實際金鑰。
啟動 OpenClaw：執行你的啟動指令並指向此設定檔。

{
  // 環境與 Shell 設定
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // 認證設定檔中繼資料 (敏感資訊儲存在 auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai-codex:default": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
      openai: ["openai:default"],
      "openai-codex": ["openai-codex:default"],
    },
  },

  // 身分識別
  identity: {
    name: "Samantha",
    theme: "helpful sloth",
    emoji: "🦥",
  },

  // 日誌記錄
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // 訊息格式
  messages: {
    messagePrefix: "[openclaw]",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
  },

  // 路由與隊列
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
      historyLimit: 50,
    },
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        slack: "collect",
        signal: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },

  // 工具集設定
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          // 可選的 CLI 備案 (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 行為
  session: {
    scope: "per-sender",
    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,
      rotateBytes: "10mb",
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // 頻道設定
  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: ["steipete"] },
      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 執行環境
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
      thinkingDefault: "low",
      verboseDefault: "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-5",
        target: "last",
        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",
        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,
        },
      },
    },
  },

  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: ["steipete"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // 自定義模型供應商
  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: {
    enabled: true,
    store: "~/.openclaw/cron/cron.json",
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    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: "./transforms/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 與網路設定
  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 },
  },

  技能: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

疑難排解

如果你在配置過程中遇到問題，可以檢查以下幾點：

Shell 指令超時：如果你的腳本執行太久，請調整 shellEnv.timeoutMs。
敏感資訊外洩：確認 redactSensitive 是否設定為 "tools" 以過濾日誌中的金鑰。
頻道沒反應：檢查各個頻道的 requireMention 設定，如果設為 true，你必須 @ 機器人它才會回覆。
Docker 權限問題：如果使用了 sandbox 模式，請確認 docker 的 user 設定與你的主機環境相符。

如果你遇到更複雜的配置難題，歡迎直接詢問我們的 AI Setup Assistant。

下一步

你是不是也遇過這種狀況：想讓機器人在多個通訊軟體上跑，但每個平台的 API 和權限設定都讓你頭大？或者當主要使用的 AI 模型突然連不上時，你的自動化流程就整個停擺。

這些常見的配置模式可以幫你解決這些痛點，讓你快速搞定多平台部署和模型備援，不用再從頭摸索複雜的 JSON 設定。

需要準備的東西

各通訊平台的存取憑證（如 Telegram botToken, Discord token 或 Slack botToken）
Anthropic 或 MiniMax 的 API Key
OAuth 認證資料（如果你使用訂閱版服務）
LM Studio（如果你打算跑本地模型）

快速開始

準備好你的配置文件（例如 config.json5）。
從下方挑選適合你的應用場景。
貼上你的 bot token 和 API Key。
啟動 OpenClaw 即可完成部署。

常用模式詳解

多平台設置

如果你想讓同一個 agent 同時在 WhatsApp、Telegram 和 Discord 上運作，可以使用這個配置。你可以針對不同平台設定不同的准入清單（allowlist）。

{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["yourname"] },
    },
  },
}

安全私訊模式（共享收件箱 / 多用戶 DM）

如果你的機器人會接收來自多個用戶的私訊（例如在 allowFrom 中有多個項目，或將 dmPolicy 設為 "open"），建議開啟 secure DM mode。這樣不同傳送者的私訊就不會共享同一個上下文對話紀錄。

{
  // 安全私訊模式（推薦用於多用戶或敏感的 DM agent）
  session: { dmScope: "per-channel-peer" },

  channels: {
    // 範例：WhatsApp 多用戶收件箱
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // 範例：Discord 多用戶收件箱
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["alice", "bob"] },
    },
  },
}

OAuth 與 API Key 備援機制

這個配置展示了如何優先使用 OAuth 訂閱帳號，當 OAuth 失效時自動切換到 API Key 模式，確保服務不中斷。

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-sonnet-4-5",
      fallbacks: ["anthropic/claude-opus-4-6"],
    },
  },
}

Anthropic 訂閱 + API Key，搭配 MiniMax 備援

當你對穩定性有極高要求時，除了內部的備援，還可以設定跨供應商的備援。例如當 Anthropic 服務完全不可用時，自動轉向 MiniMax。

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "user@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-opus-4-6",
      fallbacks: ["minimax/MiniMax-M2.1"],
    },
  },
}

工作機器人（限制存取權限）

如果你在公司環境部署機器人，通常需要關閉高階權限並限制頻道存取，確保安全性。

{
  identity: {
    name: "WorkBot",
    theme: "professional assistant",
  },
  agent: {
    workspace: "~/work-openclaw",
    elevated: { enabled: false },
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { allow: true, requireMention: true },
        "#general": { allow: true, requireMention: true },
      },
    },
  },
}

僅使用本地模型

對於注重隱私或想節省成本的開發者，可以透過 LM Studio 運行本地模型。

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "lmstudio/minimax-m2.1-gs32" },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.1-gs32",
            name: "MiniMax M2.1 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

想要針對你的特定需求調整配置嗎？試試我們的 AI Setup Assistant。

下一步

設定通訊 Gateway 時，最煩的就是明明照著文件寫了，結果訊息還是傳不出去。有時候只是一個小小的參數沒對齊，或是 ID 格式填錯，就得花大半天在那邊 debug，這種卡關的感覺真的很消磨開發熱情。

以下整理了幾個在配置時容易忽略的細節，幫你少走彎路。

需要準備的東西

已經準備好的 Gateway 配置文件
對應平台的 Provider 帳號資訊（如 WhatsApp）

快速開始

要在 5 分鐘內搞定這些細節，請跟著以下步驟檢查：

連動 dmPolicy 與 allowFrom：如果你將 dmPolicy 設定為 "open"，那麼對應的 allowFrom 清單中必須包含 "*"，否則權限會對不上。
核對 Provider ID 格式：每個平台的 ID 格式都長得不一樣。有些是手機號碼，有些是使用者 ID 或 Channel ID。請務必查看 Provider 文件來確認格式。
規劃選填區塊：你可以根據需求，在之後加入 web, browser, ui, discovery, canvasHost, talk, signal, imessage 等選填區塊。
查閱進階說明：如果需要更深入的設定，請參考 Providers 指南。

疑難排解

訊息無法正確接收或發送

請檢查你的 dmPolicy。如果設為 "open" 但 allowFrom 沒有包含 "*"，訊息會被系統擋掉。

Provider ID 報錯

這是最常見的問題。因為不同平台（如 WhatsApp 或 Signal）的 ID 規範不同，請回到 Troubleshooting 頁面確認你填入的 ID 是否符合該平台的格式要求。

有任何設定上的疑難雜症嗎？試試我們的 AI Setup Assistant 快速找答案。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。

Configuration Examples

需要準備的東西

快速開始

疑難排解

下一步

What You’ll Need

Quick Start

最簡配置

推薦入門配置

Troubleshooting

What’s Next

需要準備的東西

快速開始

疑難排解

下一步

需要準備的東西

快速開始

常用模式詳解

多平台設置

安全私訊模式（共享收件箱 / 多用戶 DM）

OAuth 與 API Key 備援機制

Anthropic 訂閱 + API Key，搭配 MiniMax 備援

工作機器人（限制存取權限）

僅使用本地模型

下一步

需要準備的東西

快速開始

疑難排解

訊息無法正確接收或發送

Provider ID 報錯

下一步

還是卡住了？