配置参考

~/.openclaw/openclaw.json 中可用的所有字段。面向任务的概览见配置文档。

配置格式为 JSON5（允许注释和尾逗号）。所有字段均为可选——省略时 OpenClaw 使用安全默认值。

---

渠道

每个渠道在其配置节存在时自动启动（除非 enabled: false）。

DM 和群组访问

所有渠道支持 DM 策略和群组策略：

DM 策略	行为
pairing（默认）	未知发送者收到一次性配对码；所有者必须批准
allowlist	只允许 allowFrom 中的发送者（或已配对的 allow store）
open	允许所有入站 DM（需要 allowFrom: ["*"]）
disabled	忽略所有入站 DM

群组策略	行为
allowlist（默认）	只允许匹配已配置 allowlist 的群组
open	绕过群组 allowlist（提及门控仍适用）
disabled	阻止所有群组/房间消息

注意： channels.defaults.groupPolicy 在提供商的 groupPolicy 未设置时设置默认值。 配对码 1 小时后过期。每个渠道最多 3 个待处理的 DM 配对请求。 如果提供商块完全缺失（channels.<provider> 不存在），运行时群组策略回退到 allowlist（fail-closed），并发出启动警告。

按渠道覆盖模型

使用 channels.modelByChannel 将特定渠道 ID 固定到某个模型。值接受 provider/model 或配置的模型别名。渠道映射在会话没有模型覆盖时生效（例如通过 /model 设置）。

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

渠道默认值和心跳

使用 channels.defaults 跨提供商共享群组策略和心跳行为：

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy：提供商级别 groupPolicy 未设置时的后备群组策略。
• channels.defaults.heartbeat.showOk：在心跳输出中包含健康的渠道状态。
• channels.defaults.heartbeat.showAlerts：在心跳输出中包含降级/错误状态。
• channels.defaults.heartbeat.useIndicator：渲染紧凑的指示器样式心跳输出。

WhatsApp

WhatsApp 通过 Gateway 的 web 渠道（Baileys Web）运行。存在已链接会话时自动启动。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 蓝勾（自聊模式下为 false）
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

多账户 WhatsApp 示例：

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

• 出站命令默认使用 default 账户（如果存在）；否则使用第一个配置的账户 id（按排序）。
• 可选的 channels.whatsapp.defaultAccount 在匹配已配置账户 id 时覆盖该后备默认账户选择。
• 旧版单账户 Baileys auth 目录由 openclaw doctor 迁移到 whatsapp/default。
• 每账户覆盖：channels.whatsapp.accounts.<id>.sendReadReceipts、channels.whatsapp.accounts.<id>.dmPolicy、channels.whatsapp.accounts.<id>.allowFrom。

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress（默认：off；显式启用以避免预览编辑速率限制）
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Bot token：channels.telegram.botToken 或 channels.telegram.tokenFile（普通文件；拒绝符号链接），默认账户 env 后备为 TELEGRAM_BOT_TOKEN。
• 可选的 channels.telegram.defaultAccount 在匹配已配置账户 id 时覆盖默认账户选择。
• 在多账户设置（2+ 个账户 id）中，设置明确的默认账户（channels.telegram.defaultAccount 或 channels.telegram.accounts.default）以避免后备路由；openclaw doctor 在缺失或无效时发出警告。
• configWrites: false 阻止 Telegram 发起的配置写入（超级群组 ID 迁移、/config set|unset）。
• Telegram 流预览使用 sendMessage + editMessageText（在直聊和群聊中均有效）。
• 重试策略：见重试策略。

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false,
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

• Token：channels.discord.token，默认账户 env 后备为 DISCORD_BOT_TOKEN。
• 使用 user:<id>（DM）或 channel:<id>（guild 频道）作为发送目标；裸数字 ID 被拒绝。
• Guild slug 为小写，空格替换为 -；频道键使用 slug 名称（无 #）。优先使用 guild ID。
• maxLinesPerMessage（默认 17）即使在 2000 字符以内也会分割高内容消息。
• channels.discord.streaming 是规范的流模式键。旧版 streamMode 和布尔 streaming 值会自动迁移。

反应通知模式： off（无）、own（bot 消息，默认）、all（所有消息）、allowlist（来自所有消息的 guilds.<id>.users）。

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• 服务账户 JSON：内联（serviceAccount）或基于文件（serviceAccountFile）。
• 也支持服务账户 SecretRef（serviceAccountRef）。
• Env 后备：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
• 使用 spaces/<spaceId> 或 users/<userId> 作为发送目标。

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: "partial", // off | partial | block | progress
      nativeStreaming: true,
      mediaMaxMb: 20,
    },
  },
}

• Socket 模式需要 botToken 和 appToken（默认账户 env 后备：SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
• HTTP 模式需要 botToken 加 signingSecret（根级或每账户）。
• 使用 user:<id>（DM）或 channel:<id> 作为发送目标。

Mattermost

Mattermost 以插件形式提供：openclaw plugins install @openclaw/mattermost。

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

聊天模式：oncall（@提及时响应，默认）、onmessage（每条消息）、onchar（以触发前缀开头的消息）。

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123",
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own",
      reactionAllowlist: ["+15551234567"],
      historyLimit: 50,
    },
  },
}

BlueBubbles

BlueBubbles 是推荐的 iMessage 路径（插件支持，在 channels.bluebubbles 下配置）。

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl、password、webhookPath、群组控制和高级操作：
      // 见 /openclaw/channels/bluebubbles
    },
  },
}

完整 BlueBubbles 渠道配置见 BlueBubbles。

iMessage

OpenClaw 通过 imsg rpc（stdio 上的 JSON-RPC）运行。不需要守护进程或端口。

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• 需要 Messages DB 的完全磁盘访问权限。
• 优先使用 chat_id:<id> 目标。使用 imsg chats --limit 20 列出聊天。
• cliPath 可以指向 SSH 包装器；设置 remoteHost（host 或 user@host）用于 SCP 附件获取。

Microsoft Teams

Microsoft Teams 以扩展形式支持，在 channels.msteams 下配置。

完整 Teams 配置（凭证、webhook、DM/群组策略、每团队/每频道覆盖）见 Microsoft Teams。

IRC

IRC 以扩展形式支持，在 channels.irc 下配置。

完整 IRC 渠道配置（主机/端口/TLS/频道/allowlist/提及门控）见 IRC。

多账户（所有渠道）

每个渠道运行多个账户（每个都有自己的 accountId）：

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• 省略 accountId 时使用 default（CLI + 路由）。
• Env token 只适用于 default 账户。
• 基础渠道设置适用于所有账户，除非每账户覆盖。
• 使用 bindings[].match.accountId 将每个账户路由到不同的 agent。

其他扩展渠道

许多扩展渠道配置为 channels.<id>，在专属渠道页面中有文档（例如飞书、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 完整渠道索引见渠道。

群聊提及门控

群组消息默认需要提及（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

---

Agent 默认值

agents.defaults.workspace

默认值：~/.openclaw/workspace。

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
• models：已配置的模型目录，同时作为 /model 命令的 allowlist。每个条目可包含 alias（快捷方式）和 params（提供商特定，例如 temperature、maxTokens、cacheRetention）。
• maxConcurrent：跨会话的最大并行 agent 运行数（每个会话仍然序列化）。默认：1。

内置别名简写（仅在模型在 agents.defaults.models 中时适用）：

别名	模型
opus	anthropic/claude-opus-4-6
sonnet	anthropic/claude-sonnet-4-6
gpt	openai/gpt-5.4
gpt-mini	openai/gpt-5-mini
gemini	google/gemini-3.1-pro-preview
gemini-flash	google/gemini-3-flash-preview
gemini-flash-lite	google/gemini-3.1-flash-lite-preview

你配置的别名总是优先于默认值。

agents.defaults.heartbeat

周期性心跳运行。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m 禁用
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        lightContext: false,
        isolatedSession: false,
        session: "main",
        to: "+15555550123",
        directPolicy: "allow",
        target: "none",
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

• isolatedSession：为 true 时，每次心跳运行在新会话中，无之前的对话历史。与 cron sessionTarget: "isolated" 使用相同的隔离模式。将每次心跳的 token 成本从约 10 万降低到约 2-5K。
• 心跳运行完整的 agent 轮次——较短的间隔消耗更多 token。

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict",
        postCompactionSections: ["Session Startup", "Red Lines"],
        model: "openrouter/anthropic/claude-sonnet-4-6",
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

agents.defaults.sandbox

可选的嵌入式 agent 沙盒。完整指南见沙盒。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
}

构建镜像：

scripts/sandbox-setup.sh           # 主沙盒镜像
scripts/sandbox-browser-setup.sh   # 可选浏览器镜像

agents.list（每 agent 覆盖）

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        model: "anthropic/claude-opus-4-6",
        thinkingDefault: "high",
        reasoningDefault: "on",
        fastModeDefault: false,
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

---

多 Agent 路由

在一个 Gateway 内运行多个隔离的 agent。见多 Agent。

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

绑定匹配字段

• type（可选）：普通路由用 route（缺省类型默认为 route），持久 ACP 会话绑定用 acp
• match.channel（必填）
• match.accountId（可选；* = 任意账户；省略 = 默认账户）
• match.peer（可选；{ kind: direct|group|channel, id }）
• match.guildId / match.teamId（可选；渠道特定）

确定性匹配顺序：

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId（精确，无 peer/guild/team）
5. match.accountId: "*"（渠道范围）
6. 默认 agent

---

会话

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000,
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d",
      maxDiskBytes: "500mb",
      highWaterBytes: "400mb",
    },
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

---

消息

{
  messages: {
    responsePrefix: "🦞", // 或 "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 禁用
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

---

工具

工具 profile

tools.profile 在 tools.allow/tools.deny 之前设置基础 allowlist：

Profile	包含
minimal	仅 session_status
coding	group:fs、group:runtime、group:sessions、group:memory、image
messaging	group:messaging、sessions_list、sessions_history、sessions_send、session_status
full	无限制（与未设置相同）

工具组

组	工具
group:runtime	exec、process
group:fs	read、write、edit、apply_patch
group:sessions	sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
group:memory	memory_search、memory_get
group:web	web_search、web_fetch
group:ui	browser、canvas
group:automation	cron、gateway
group:messaging	message
group:nodes	nodes
group:openclaw	所有内置工具（不含提供商插件）

tools.elevated

控制提升（主机）exec 访问：

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
    },
  },
}

tools.media

配置入站媒体理解（图片/音频/视频）：

{
  tools: {
    media: {
      concurrency: 2,
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

---

自定义提供商和 Base URL

OpenClaw 使用 pi-coding-agent 模型目录。通过 models.providers 添加自定义提供商：

{
  models: {
    mode: "merge", // merge（默认）| replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

---

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

---

插件

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-extension"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• 从 ~/.openclaw/extensions、<workspace>/.openclaw/extensions 以及 plugins.load.paths 加载。
• 配置更改需要重启 Gateway。
• allow：可选的 allowlist（只加载列出的插件）。deny 优先。

见插件。

---

浏览器

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
    },
    color: "#FF4500",
  },
}

---

Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
    },
    trustedProxies: ["10.0.0.1"],
    allowRealIpFallback: false,
    tools: {
      deny: ["browser"],
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

• port：WS + HTTP 的单一多路复用端口。优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。
• bind：auto、loopback（默认）、lan（0.0.0.0）、tailnet（仅 Tailscale IP）或 custom。
• Docker 注意：默认 loopback 绑定在容器内监听 127.0.0.1。使用 Docker 桥接网络（-p 18789:18789）时，流量到达 eth0，Gateway 无法访问。使用 --network host，或设置 bind: "lan" 以监听所有接口。
• 认证：默认需要。非 loopback 绑定需要共享 token/密码。Onboarding 向导默认生成 token。

多实例隔离

在一台主机上运行多个 Gateway，使用唯一端口和状态目录：

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

便捷标志：--dev（使用 ~/.openclaw-dev + 端口 19001）、--profile <name>（使用 ~/.openclaw-<name>）。

---

Hooks

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    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.2-mini",
      },
    ],
  },
}

认证：Authorization: Bearer <token> 或 x-openclaw-token: <token>。

端点：

• POST /hooks/wake
• POST /hooks/agent
• POST /hooks/<name> → 通过 hooks.mappings 解析

---

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

见 Cron 任务。

---

日志

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

---

配置文件包含（$include）

将配置拆分为多个文件：

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

合并行为：

• 单个文件：替换包含的对象。
• 文件数组：按顺序深度合并（后者覆盖前者）。
• 同级键：在 include 后合并（覆盖 include 的值）。
• 嵌套 include：最多 10 层深。
• 路径：相对于包含文件解析，但必须保持在顶层配置目录（openclaw.json 的 dirname）内。

---

相关：配置 · 配置示例 · Doctor