配置参考

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

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

频道

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

私聊和群组访问

所有频道都支持私聊策略和群组策略：

说明： channels.defaults.groupPolicy 在提供商的 groupPolicy 未设置时作为默认值。 配对码 1 小时后过期。每个频道的待处理私聊配对请求上限为 3 个。 如果提供商配置块完全缺失（channels.<provider> 不存在），运行时群组策略回退到 allowlist（失败关闭）并在启动时发出警告。

频道模型覆盖

用 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: fallback group policy when a provider-level groupPolicy is unset.
• channels.defaults.heartbeat.showOk: include healthy channel statuses in heartbeat output.
• channels.defaults.heartbeat.showAlerts: include degraded/error statuses in heartbeat output.
• channels.defaults.heartbeat.useIndicator: render compact indicator-style heartbeat output.

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, // blue ticks (false in self-chat mode)
      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,
    },
  },
}

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

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 (default: 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 or channels.telegram.tokenFile (regular file only; symlinks rejected), with TELEGRAM_BOT_TOKEN as fallback for the default account.
• Optional channels.telegram.defaultAccount overrides default account selection when it matches a configured account id.
• In multi-account setups (2+ account ids), set an explicit default (channels.telegram.defaultAccount or channels.telegram.accounts.default) to avoid fallback routing; openclaw doctor warns when this is missing or invalid.
• configWrites: false blocks Telegram-initiated config writes (supergroup ID migrations, /config set|unset).
• Top-level bindings[] entries with type: "acp" configure persistent ACP bindings for forum topics (use canonical chatId:topic:topicId in match.peer.id). Field semantics are shared in ACP Agents.
• Telegram stream previews use sendMessage + editMessageText (works in direct and group chats).
• Retry policy: see Retry policy.

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 (progress maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, with DISCORD_BOT_TOKEN as fallback for the default account.
• Direct outbound calls that provide an explicit Discord token use that token for the call; account retry/policy settings still come from the selected account in the active runtime snapshot.
• Optional channels.discord.defaultAccount overrides default account selection when it matches a configured account id.
• Use user:<id> (DM) or channel:<id> (guild channel) for delivery targets; bare numeric IDs are rejected.
• Guild slugs are lowercase with spaces replaced by -; channel keys use the slugged name (no #). Prefer guild IDs.
• Bot-authored messages are ignored by default. allowBots: true enables them; use allowBots: "mentions" to only accept bot messages that mention the bot (own messages still filtered).
• channels.discord.guilds.<id>.ignoreOtherMentions (and channel overrides) drops messages that mention another user or role but not the bot (excluding @everyone/@here).
• maxLinesPerMessage (default 17) splits tall messages even when under 2000 chars.
• channels.discord.threadBindings controls Discord thread-bound routing:
  • enabled: Discord override for thread-bound session features (/focus, /unfocus, /agents, /session idle, /session max-age, and bound delivery/routing)
  • idleHours: Discord override for inactivity auto-unfocus in hours (0 disables)
  • maxAgeHours: Discord override for hard max age in hours (0 disables)
  • spawnSubagentSessions: opt-in switch for sessions_spawn({ thread: true }) auto thread creation/binding
• Top-level bindings[] entries with type: "acp" configure persistent ACP bindings for channels and threads (use channel/thread id in match.peer.id). Field semantics are shared in ACP Agents.
• channels.discord.ui.components.accentColor sets the accent color for Discord components v2 containers.
• channels.discord.voice enables Discord voice channel conversations and optional auto-join + TTS overrides.
• channels.discord.voice.daveEncryption and channels.discord.voice.decryptionFailureTolerance pass through to @discordjs/voice DAVE options (true and 24 by default).
• OpenClaw additionally attempts voice receive recovery by leaving/rejoining a voice session after repeated decrypt failures.
• channels.discord.streaming is the canonical stream mode key. Legacy streamMode and boolean streaming values are auto-migrated.
• channels.discord.autoPresence maps runtime availability to bot presence (healthy => online, degraded => idle, exhausted => dnd) and allows optional status text overrides.
• channels.discord.dangerouslyAllowNameMatching re-enables mutable name/tag matching (break-glass compatibility mode).

Reaction notification modes: off (none), own (bot’s messages, default), all (all messages), allowlist (from guilds.<id>.users on all messages).

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

• Service account JSON: inline (serviceAccount) or file-based (serviceAccountFile).
• Service account SecretRef is also supported (serviceAccountRef).
• Env fallbacks: GOOGLE_CHAT_SERVICE_ACCOUNT or GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Use spaces/<spaceId> or users/<userId> for delivery targets.
• channels.googlechat.dangerouslyAllowNameMatching re-enables mutable email principal matching (break-glass compatibility mode).

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 (preview mode)
      nativeStreaming: true, // use Slack native streaming API when streaming=partial
      mediaMaxMb: 20,
    },
  },
}

• Socket mode requires both botToken and appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN for default account env fallback).
• HTTP mode requires botToken plus signingSecret (at root or per-account).
• configWrites: false blocks Slack-initiated config writes.
• Optional channels.slack.defaultAccount overrides default account selection when it matches a configured account id.
• channels.slack.streaming is the canonical stream mode key. Legacy streamMode and boolean streaming values are auto-migrated.
• Use user:<id> (DM) or channel:<id> for delivery targets.

Reaction notification modes: off, own (default), all, allowlist (from reactionAllowlist).

Thread session isolation: thread.historyScope is per-thread (default) or shared across channel. thread.inheritParent copies parent channel transcript to new threads.

• typingReaction adds a temporary reaction to the inbound Slack message while a reply is running, then removes it on completion. Use a Slack emoji shortcode such as "hourglass_flowing_sand".

Mattermost

Mattermost ships as a plugin: 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, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

Chat modes: oncall (respond on @-mention, default), onmessage (every message), onchar (messages starting with trigger prefix).

When Mattermost native commands are enabled:

• commands.callbackPath must be a path (for example /api/channels/mattermost/command), not a full URL.
• commands.callbackUrl must resolve to the OpenClaw gateway endpoint and be reachable from the Mattermost server.
• For private/tailnet/internal callback hosts, Mattermost may require ServiceSettings.AllowedUntrustedInternalConnections to include the callback host/domain. Use host/domain values, not full URLs.
• channels.mattermost.configWrites: allow or deny Mattermost-initiated config writes.
• channels.mattermost.requireMention: require @mention before replying in channels.
• Optional channels.mattermost.defaultAccount overrides default account selection when it matches a configured account id.

Signal

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

Reaction notification modes: off, own (default), all, allowlist (from reactionAllowlist).

• channels.signal.account: pin channel startup to a specific Signal account identity.
• channels.signal.configWrites: allow or deny Signal-initiated config writes.
• Optional channels.signal.defaultAccount overrides default account selection when it matches a configured account id.

BlueBubbles

BlueBubbles is the recommended iMessage path (plugin-backed, configured under channels.bluebubbles).

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• Core key paths covered here: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• Optional channels.bluebubbles.defaultAccount overrides default account selection when it matches a configured account id.
• Full BlueBubbles channel configuration is documented in BlueBubbles.

iMessage

OpenClaw spawns imsg rpc (JSON-RPC over stdio). No daemon or port required.

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

• Optional channels.imessage.defaultAccount overrides default account selection when it matches a configured account id.

• Requires Full Disk Access to the Messages DB.

• Prefer chat_id:<id> targets. Use imsg chats --limit 20 to list chats.

• cliPath can point to an SSH wrapper; set remoteHost (host or user@host) for SCP attachment fetching.

• attachmentRoots and remoteAttachmentRoots restrict inbound attachment paths (default: /Users/*/Library/Messages/Attachments).

• SCP uses strict host-key checking, so ensure the relay host key already exists in ~/.ssh/known_hosts.

• channels.imessage.configWrites: allow or deny iMessage-initiated config writes.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Microsoft Teams

Microsoft Teams is extension-backed and configured under channels.msteams.

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• Core key paths covered here: channels.msteams, channels.msteams.configWrites.
• Full Teams config (credentials, webhook, DM/group policy, per-team/per-channel overrides) is documented in Microsoft Teams.

IRC

IRC is extension-backed and configured under channels.irc.

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "[email protected]",
      },
    },
  },
}

• Core key paths covered here: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• Optional channels.irc.defaultAccount overrides default account selection when it matches a configured account id.
• Full IRC channel configuration (host/port/TLS/channels/allowlists/mention gating) is documented in IRC.

Multi-account (all channels)

Run multiple accounts per channel (each with its own accountId):

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

• default is used when accountId is omitted (CLI + routing).
• Env tokens only apply to the default account.
• Base channel settings apply to all accounts unless overridden per account.
• Use bindings[].match.accountId to route each account to a different agent.
• If you add a non-default account via openclaw channels add (or channel onboarding) while still on a single-account top-level channel config, OpenClaw moves account-scoped top-level single-account values into channels.<channel>.accounts.default first so the original account keeps working.
• Existing channel-only bindings (no accountId) keep matching the default account; account-scoped bindings remain optional.
• openclaw doctor --fix also repairs mixed shapes by moving account-scoped top-level single-account values into accounts.default when named accounts exist but default is missing.

Other extension channels

Many extension channels are configured as channels.<id> and documented in their dedicated channel pages (for example Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, and Twitch). See the full channel index: Channels.

Group chat mention gating

Group messages default to require mention (metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, Google Chat, and iMessage group chats.

Mention types:

• Metadata mentions: Native platform @-mentions. Ignored in WhatsApp self-chat mode.
• Text patterns: Regex patterns in agents.list[].groupChat.mentionPatterns. Always checked.
• Mention gating is enforced only when detection is possible (native mentions or at least one pattern).

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

messages.groupChat.historyLimit sets the global default. Channels can override with channels.<channel>.historyLimit (or per-account). Set 0 to disable.

DM history limits

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

Resolution: per-DM override → provider default → no limit (all retained).

Supported: telegram, whatsapp, discord, slack, signal, imessage, msteams.

Self-chat mode

Include your own number in allowFrom to enable self-chat mode (ignores native @-mentions, only responds to text patterns):

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

Commands (chat command handling)

{
  commands: {
    native: "auto", // register native commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    debug: false, // allow /debug
    restart: false, // allow /restart + gateway restart tool
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

Agent 默认值

agents.defaults.workspace

默认值：~/.openclaw/workspace。

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

agents.defaults.repoRoot

可选的仓库根目录，显示在系统提示的 Runtime 行中。未设置时 OpenClaw 从工作区向上自动检测。

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

agents.defaults.skipBootstrap

禁用工作区引导文件的自动创建（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md）。

{
  agents: { defaults: { skipBootstrap: true } },
}

agents.defaults.bootstrapMaxChars

每个工作区引导文件在截断前的最大字符数。默认：20000。

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

agents.defaults.bootstrapTotalMaxChars

所有工作区引导文件注入的最大总字符数。默认：150000。

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

agents.defaults.bootstrapPromptTruncationWarning

控制引导上下文被截断时 Agent 可见的警告文本。 默认："once"。

• "off"：不在系统提示中注入警告文本。
• "once"：每个唯一的截断签名只注入一次警告（推荐）。
• "always"：存在截断时每次运行都注入警告。

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

agents.defaults.imageMaxDimensionPx

发送给提供商之前，转录/工具图片块中最长边的最大像素值。 默认：1200。

较低的值通常能减少截图密集运行的视觉 token 消耗和请求 payload 大小。 较高的值保留更多视觉细节。

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

agents.defaults.userTimezone

系统提示上下文中的时区（不影响消息时间戳）。回退到主机时区。

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

agents.defaults.timeFormat

系统提示中的时间格式。默认：auto（操作系统偏好）。

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.5": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.5"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      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: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • String form sets only the primary model.
  • Object form sets primary plus ordered failover models.
• imageModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • Used by the image tool path as its vision-model config.
  • Also used as fallback routing when the selected/default model cannot accept image input.
• pdfModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • Used by the pdf tool for model routing.
  • If omitted, the PDF tool falls back to imageModel, then to best-effort provider defaults.
• pdfMaxBytesMb: default PDF size limit for the pdf tool when maxBytesMb is not passed at call time.
• pdfMaxPages: default maximum pages considered by extraction fallback mode in the pdf tool.
• model.primary: format provider/model (e.g. anthropic/claude-opus-4-6). If you omit the provider, OpenClaw assumes anthropic (deprecated).
• models: the configured model catalog and allowlist for /model. Each entry can include alias (shortcut) and params (provider-specific, for example temperature, maxTokens, cacheRetention, context1m).
• params merge precedence (config): agents.defaults.models["provider/model"].params is the base, then agents.list[].params (matching agent id) overrides by key.
• Config writers that mutate these fields (for example /models set, /models set-image, and fallback add/remove commands) save canonical object form and preserve existing fallback lists when possible.
• maxConcurrent: max parallel agent runs across sessions (each session still serialized). Default: 1.

Built-in alias shorthands (only apply when the model is in agents.defaults.models):

Your configured aliases always win over defaults.

Z.AI GLM-4.x models automatically enable thinking mode unless you set --thinking off or define agents.defaults.models["zai/<model>"].params.thinking yourself. Z.AI models enable tool_stream by default for tool call streaming. Set agents.defaults.models["zai/<model>"].params.tool_stream to false to disable it. Anthropic Claude 4.6 models default to adaptive thinking when no explicit thinking level is set.

agents.defaults.cliBackends

可选的 CLI 后端，用于纯文本回退运行（无工具调用）。API 提供商失败时可作为备用。

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI 后端以文本为主；工具始终禁用。
• 设置 sessionArg 时支持会话。
• imageArg 接受文件路径时支持图片透传。

agents.defaults.heartbeat

周期性心跳运行。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

• every: duration string (ms/s/m/h). Default: 30m.
• suppressToolErrorWarnings: when true, suppresses tool error warning payloads during heartbeat runs.
• directPolicy: direct/DM delivery policy. allow (default) permits direct-target delivery. block suppresses direct-target delivery and emits reason=dm-blocked.
• lightContext: when true, heartbeat runs use lightweight bootstrap context and keep only HEARTBEAT.md from workspace bootstrap files.
• Per-agent: set agents.list[].heartbeat. When any agent defines heartbeat, only those agents run heartbeats.
• Heartbeats run full agent turns — shorter intervals burn more tokens.

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-5", // optional compaction-only model override
        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.",
        },
      },
    },
  },
}

• mode: default or safeguard (chunked summarization for long histories). See Compaction.
• identifierPolicy: strict (default), off, or custom. strict prepends built-in opaque identifier retention guidance during compaction summarization.
• identifierInstructions: optional custom identifier-preservation text used when identifierPolicy=custom.
• postCompactionSections: optional AGENTS.md H2/H3 section names to re-inject after compaction. Defaults to ["Session Startup", "Red Lines"]; set [] to disable reinjection. When unset or explicitly set to that default pair, older Every Session/Safety headings are also accepted as a legacy fallback.
• model: optional provider/model-id override for compaction summarization only. Use this when the main session should keep one model but compaction summaries should run on another; when unset, compaction uses the session’s primary model.
• memoryFlush: silent agentic turn before auto-compaction to store durable memories. Skipped when workspace is read-only.

agents.defaults.contextPruning

Prunes old tool results from in-memory context before sending to the LLM. Does not modify session history on disk.

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

See Session Pruning for behavior details.

Block streaming

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
}

• Non-Telegram channels require explicit *.blockStreaming: true to enable block replies.
• Channel overrides: channels.<channel>.blockStreamingCoalesce (and per-account variants). Signal/Slack/Discord/Google Chat default minChars: 1500.
• humanDelay: randomized pause between block replies. natural = 800–2500ms. Per-agent override: agents.list[].humanDelay.

See Streaming for behavior + chunking details.

Typing indicators

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Defaults: instant for direct chats/mentions, message for unmentioned group chats.
• Per-session overrides: session.typingMode, session.typingIntervalSeconds.

See Typing Indicators.

agents.defaults.sandbox

可选的 Docker 沙箱，用于内嵌 Agent。完整指南见 Sandboxing。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        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,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

构建镜像：

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

agents.list（按 Agent 覆盖）

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: stable agent id (required).
• default: when multiple are set, first wins (warning logged). If none set, first list entry is default.
• model: string form overrides primary only; object form { primary, fallbacks } overrides both ([] disables global fallbacks). Cron jobs that only override primary still inherit default fallbacks unless you set fallbacks: [].
• params: per-agent stream params merged over the selected model entry in agents.defaults.models. Use this for agent-specific overrides like cacheRetention, temperature, or maxTokens without duplicating the whole model catalog.
• runtime: optional per-agent runtime descriptor. Use type: "acp" with runtime.acp defaults (agent, backend, mode, cwd) when the agent should default to ACP harness sessions.
• identity.avatar: workspace-relative path, http(s) URL, or data: URI.
• identity derives defaults: ackReaction from emoji, mentionPatterns from name/emoji.
• subagents.allowAgents: allowlist of agent ids for sessions_spawn (["*"] = any; default: same agent only).
• Sandbox inheritance guard: if the requester session is sandboxed, sessions_spawn rejects targets that would run unsandboxed.

多 Agent 路由

在一个 Gateway 内运行多个隔离的 Agent。见 Multi-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 (optional): route for normal routing (missing type defaults to route), acp for persistent ACP conversation bindings.
• match.channel (required)
• match.accountId (optional; * = any account; omitted = default account)
• match.peer (optional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (optional; channel-specific)
• acp (optional; only for type: "acp"): { mode, label, cwd, backend }

Deterministic match order:

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exact, no peer/guild/team)
5. match.accountId: "*" (channel-wide)
6. Default agent

Within each tier, the first matching bindings entry wins.

For type: "acp" entries, OpenClaw resolves by exact conversation identity (match.channel + account + match.peer.id) and does not use the route binding tier order above.

按 Agent 访问配置

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

See Multi-Agent Sandbox & Tools for precedence details.

会话

{
  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, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

消息

{
  messages: {
    responsePrefix: "🦞", // or "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 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

响应前缀

Per-channel/account overrides: channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix.

Resolution (most specific wins): account → channel → global. "" disables and stops cascade. "auto" derives [{identity.name}].

Template variables:

Variables are case-insensitive. {think} is an alias for {thinkingLevel}.

确认反应

• Defaults to active agent’s identity.emoji, otherwise "👀". Set "" to disable.
• Per-channel overrides: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Resolution order: account → channel → messages.ackReaction → identity fallback.
• Scope: group-mentions (default), group-all, direct, all.
• removeAckAfterReply: removes ack after reply (Slack/Discord/Telegram/Google Chat only).

入站防抖

将同一发送者的快速纯文本消息合并为单个 Agent 轮次。媒体/附件立即刷新。控制命令绕过防抖。

TTS（文本转语音）

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• auto controls auto-TTS. /tts off|always|inbound|tagged overrides per session.
• summaryModel overrides agents.defaults.model.primary for auto-summary.
• modelOverrides is enabled by default; modelOverrides.allowProvider defaults to false (opt-in).
• API keys fall back to ELEVENLABS_API_KEY/XI_API_KEY and OPENAI_API_KEY.
• openai.baseUrl overrides the OpenAI TTS endpoint. Resolution order is config, then OPENAI_TTS_BASE_URL, then https://api.openai.com/v1.
• When openai.baseUrl points to a non-OpenAI endpoint, OpenClaw treats it as an OpenAI-compatible TTS server and relaxes model/voice validation.

Talk

Defaults for Talk mode (macOS/iOS/Android).

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17",
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• Voice IDs fall back to ELEVENLABS_VOICE_ID or SAG_VOICE_ID.
• apiKey and providers.*.apiKey accept plaintext strings or SecretRef objects.
• ELEVENLABS_API_KEY fallback applies only when no Talk API key is configured.
• voiceAliases lets Talk directives use friendly names.
• silenceTimeoutMs controls how long Talk mode waits after user silence before it sends the transcript. Unset keeps the platform default pause window (700 ms on macOS and Android, 900 ms on iOS).

工具

工具配置

tools.profile sets a base allowlist before tools.allow/tools.deny:

Local onboarding defaults new local configs to tools.profile: "coding" when unset (existing explicit profiles are preserved).

工具组

tools.allow / tools.deny

全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 * 通配符。即使 Docker 沙箱关闭也生效。

{
  tools: { deny: ["browser", "canvas"] },
}

tools.byProvider

进一步限制特定提供商或模型的工具。顺序：基础配置 → 提供商配置 → allow/deny。

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

tools.elevated

控制提权（宿主机）exec 访问：

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

• Per-agent override (agents.list[].tools.elevated) can only further restrict.
• /elevated on|off|ask|full stores state per session; inline directives apply to single message.
• Elevated exec runs on the host, bypasses sandboxing.

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.2"],
      },
    },
  },
}

tools.loopDetection

Tool-loop safety checks are disabled by default. Set enabled: true to activate detection. Settings can be defined globally in tools.loopDetection and overridden per-agent at agents.list[].tools.loopDetection.

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

• historySize: max tool-call history retained for loop analysis.
• warningThreshold: repeating no-progress pattern threshold for warnings.
• criticalThreshold: higher repeating threshold for blocking critical loops.
• globalCircuitBreakerThreshold: hard stop threshold for any no-progress run.
• detectors.genericRepeat: warn on repeated same-tool/same-args calls.
• detectors.knownPollNoProgress: warn/block on known poll tools (process.poll, command_status, etc.).
• detectors.pingPong: warn/block on alternating no-progress pair patterns.
• If warningThreshold >= criticalThreshold or criticalThreshold >= globalCircuitBreakerThreshold, validation fails.

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // or BRAVE_API_KEY env
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        userAgent: "custom-ua",
      },
    },
  },
}

tools.media

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

{
  tools: {
    media: {
      concurrency: 2,
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        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" }],
      },
    },
  },
}

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

tools.sessions

Controls which sessions can be targeted by the session tools (sessions_list, sessions_history, sessions_send).

Default: tree (current session + sessions spawned by it, such as subagents).

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

Notes:

• self: only the current session key.
• tree: current session + sessions spawned by the current session (subagents).
• agent: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).
• all: any session. Cross-agent targeting still requires tools.agentToAgent.
• Sandbox clamp: when the current session is sandboxed and agents.defaults.sandbox.sessionToolsVisibility="spawned", visibility is forced to tree even if tools.sessions.visibility="all".

tools.sessions_spawn

Controls inline attachment support for sessions_spawn.

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}

Notes:

• Attachments are only supported for runtime: "subagent". ACP runtime rejects them.
• Files are materialized into the child workspace at .openclaw/attachments/<uuid>/ with a .manifest.json.
• Attachment content is automatically redacted from transcript persistence.
• Base64 inputs are validated with strict alphabet/padding checks and a pre-decode size guard.
• File permissions are 0700 for directories and 0600 for files.
• Cleanup follows the cleanup policy: delete always removes attachments; keep retains them only when retainOnSessionKeep: true.

tools.subagents

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.5",
        maxConcurrent: 1,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

• model: default model for spawned sub-agents. If omitted, sub-agents inherit the caller’s model.
• runTimeoutSeconds: default timeout (seconds) for sessions_spawn when the tool call omits runTimeoutSeconds. 0 means no timeout.
• Per-subagent tool policy: tools.subagents.tools.allow / tools.subagents.tools.deny.

自定义提供商和 base URL

OpenClaw 使用 pi-coding-agent 模型目录。通过配置中的 models.providers 或 ~/.openclaw/agents/<agentId>/agent/models.json 添加自定义提供商。

{
  models: {
    mode: "merge", // merge (default) | 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,
          },
        ],
      },
    },
  },
}

• Use authHeader: true + headers for custom auth needs.
• Override agent config root with OPENCLAW_AGENT_DIR (or PI_CODING_AGENT_DIR).
• Merge precedence for matching provider IDs:
  • Non-empty agent models.json baseUrl values win.
  • Non-empty agent apiKey values win only when that provider is not SecretRef-managed in current config/auth-profile context.
  • SecretRef-managed provider apiKey values are refreshed from source markers (ENV_VAR_NAME for env refs, secretref-managed for file/exec refs) instead of persisting resolved secrets.
  • SecretRef-managed provider header values are refreshed from source markers (secretref-env:ENV_VAR_NAME for env refs, secretref-managed for file/exec refs).
  • Empty or missing agent apiKey/baseUrl fall back to models.providers in config.
  • Matching model contextWindow/maxTokens use the higher value between explicit config and implicit catalog values.
  • Use models.mode: "replace" when you want config to fully rewrite models.json.
  • Marker persistence is source-authoritative: markers are written from the active source config snapshot (pre-resolution), not from resolved runtime secret values.

提供商字段详情

• models.mode: provider catalog behavior (merge or replace).
• models.providers: custom provider map keyed by provider id.
• models.providers.*.api: request adapter (openai-completions, openai-responses, anthropic-messages, google-generative-ai, etc).
• models.providers.*.apiKey: provider credential (prefer SecretRef/env substitution).
• models.providers.*.auth: auth strategy (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: for Ollama + openai-completions, inject options.num_ctx into requests (default: true).
• models.providers.*.authHeader: force credential transport in the Authorization header when required.
• models.providers.*.baseUrl: upstream API base URL.
• models.providers.*.headers: extra static headers for proxy/tenant routing.
• models.providers.*.models: explicit provider model catalog entries.
• models.providers.*.models.*.compat.supportsDeveloperRole: optional compatibility hint. For api: "openai-completions" with a non-empty non-native baseUrl (host not api.openai.com), OpenClaw forces this to false at runtime. Empty/omitted baseUrl keeps default OpenAI behavior.
• models.bedrockDiscovery: Bedrock auto-discovery settings root.
• models.bedrockDiscovery.enabled: turn discovery polling on/off.
• models.bedrockDiscovery.region: AWS region for discovery.
• models.bedrockDiscovery.providerFilter: optional provider-id filter for targeted discovery.
• models.bedrockDiscovery.refreshInterval: polling interval for discovery refresh.
• models.bedrockDiscovery.defaultContextWindow: fallback context window for discovered models.
• models.bedrockDiscovery.defaultMaxTokens: fallback max output tokens for discovered models.

提供商示例

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
        ],
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-6" },
      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} },
    },
  },
}

{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.5" },
      models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi-coding/k2p5" },
      models: { "kimi-coding/k2p5": { alias: "Kimi K2.5" } },
    },
  },
}

{
  env: { SYNTHETIC_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "hf:MiniMaxAI/MiniMax-M2.5",
            name: "MiniMax M2.5",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536,
          },
        ],
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.5" },
      models: {
        "minimax/MiniMax-M2.5": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.5",
            name: "MiniMax M2.5",
            reasoning: true,
            input: ["text"],
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

技能

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn
    },
    entries: {
      "nano-banana-pro": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled: optional allowlist for bundled skills only (managed/workspace skills unaffected).
• entries.<skillKey>.enabled: false disables a skill even if bundled/installed.
• entries.<skillKey>.apiKey: convenience for skills declaring a primary env var (plaintext string or SecretRef object).

插件

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

• Loaded from ~/.openclaw/extensions, <workspace>/.openclaw/extensions, plus plugins.load.paths.
• Config changes require a gateway restart.
• allow: optional allowlist (only listed plugins load). deny wins.
• plugins.entries.<id>.apiKey: plugin-level API key convenience field (when supported by the plugin).
• plugins.entries.<id>.env: plugin-scoped env var map.
• plugins.entries.<id>.hooks.allowPromptInjection: when false, core blocks before_prompt_build and ignores prompt-mutating fields from legacy before_agent_start, while preserving legacy modelOverride and providerOverride.
• plugins.entries.<id>.config: plugin-defined config object (validated by plugin schema).
• plugins.slots.memory: pick the active memory plugin id, or "none" to disable memory plugins.
• plugins.slots.contextEngine: pick the active context engine plugin id; defaults to "legacy" unless you install and select another engine.
• plugins.installs: CLI-managed install metadata used by openclaw plugins update.
  • Includes source, spec, sourcePath, installPath, version, resolvedName, resolvedVersion, resolvedSpec, integrity, shasum, resolvedAt, installedAt.
  • Treat plugins.installs.* as managed state; prefer CLI commands over manual edits.

See Plugins.

浏览器

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "chrome",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // relayBindHost: "0.0.0.0", // only when the extension relay must be reachable across namespaces (for example WSL2)
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• evaluateEnabled: false disables act:evaluate and wait --fn.
• ssrfPolicy.dangerouslyAllowPrivateNetwork defaults to true when unset (trusted-network model).
• Set ssrfPolicy.dangerouslyAllowPrivateNetwork: false for strict public-only browser navigation.
• ssrfPolicy.allowPrivateNetwork remains supported as a legacy alias.
• In strict mode, use ssrfPolicy.hostnameAllowlist and ssrfPolicy.allowedHostnames for explicit exceptions.
• Remote profiles are attach-only (start/stop/reset disabled).
• Auto-detect order: default browser if Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary.
• Control service: loopback only (port derived from gateway.port, default 18791).
• extraArgs appends extra launch flags to local Chromium startup (for example --disable-gpu, window sizing, or debug flags).
• relayBindHost changes where the Chrome extension relay listens. Leave unset for loopback-only access; set an explicit non-loopback bind address such as 0.0.0.0 only when the relay must cross a namespace boundary (for example WSL2) and the host network is already trusted.

UI

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor: accent color for native app UI chrome (Talk Mode bubble tint, etc.).
• assistant: Control UI identity override. Falls back to active agent identity.

Gateway 网关

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

OpenAI 兼容端点

• Chat Completions: disabled by default. Enable with gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Responses URL-input hardening:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist
• Optional response hardening header:
  • gateway.http.securityHeaders.strictTransportSecurity (set only for HTTPS origins you control; see Trusted Proxy Auth)

多实例隔离

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

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

Convenience flags: --dev (uses ~/.openclaw-dev + port 19001), --profile <name> (uses ~/.openclaw-<name>).

See Multiple Gateways.

Hooks（Webhook）

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

Auth: Authorization: Bearer <token> or x-openclaw-token: <token>.

Endpoints:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • sessionKey from request payload is accepted only when hooks.allowRequestSessionKey=true (default: false).
• POST /hooks/<name> → resolved via hooks.mappings

Gmail 集成

{
  hooks: {
    gmail: {
      account: "[email protected]",
      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" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• Gateway auto-starts gog gmail watch serve on boot when configured. Set OPENCLAW_SKIP_GMAIL_WATCHER=1 to disable.
• Don’t run a separate gog gmail watch serve alongside the Gateway.

Canvas 主机

{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    liveReload: true,
    // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
  },
}

• Serves agent-editable HTML/CSS/JS and A2UI over HTTP under the Gateway port:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Local-only: keep gateway.bind: "loopback" (default).
• Non-loopback binds: canvas routes require Gateway auth (token/password/trusted-proxy), same as other Gateway HTTP surfaces.
• Node WebViews typically don’t send auth headers; after a node is paired and connected, the Gateway advertises node-scoped capability URLs for canvas/A2UI access.
• Capability URLs are bound to the active node WS session and expire quickly. IP-based fallback is not used.
• Injects live-reload client into served HTML.
• Auto-creates starter index.html when empty.
• Also serves A2UI at /__openclaw__/a2ui/.
• Changes require a gateway restart.
• Disable live reload for large directories or EMFILE errors.

发现

mDNS（Bonjour）

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal (default): omit cliPath + sshPort from TXT records.
• full: include cliPath + sshPort.
• Hostname defaults to openclaw. Override with OPENCLAW_MDNS_HOSTNAME.

广域（DNS-SD）

{
  discovery: {
    wideArea: { enabled: true },
  },
}

Writes a unicast DNS-SD zone under ~/.openclaw/dns/. For cross-network discovery, pair with a DNS server (CoreDNS recommended) + Tailscale split DNS.

Setup: openclaw dns setup --apply.

环境变量

env（内联环境变量）

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• Inline env vars are only applied if the process env is missing the key.
• .env files: CWD .env + ~/.openclaw/.env (neither overrides existing vars).
• shellEnv: imports missing expected keys from your login shell profile.
• See Environment for full precedence.

环境变量替换

在任何配置字符串中用 ${VAR_NAME} 引用环境变量：

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• Only uppercase names matched: [A-Z_][A-Z0-9_]*.
• Missing/empty vars throw an error at config load.
• Escape with $${VAR} for a literal ${VAR}.
• Works with $include.

密钥

Secret refs 是增量的：明文值仍然有效。

SecretRef

使用以下对象格式：

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Validation:

• provider pattern: ^[a-z][a-z0-9_-]{0,63}$
• source: "env" id pattern: ^[A-Z][A-Z0-9_]{0,127}$
• source: "file" id: absolute JSON pointer (for example "/providers/openai/apiKey")
• source: "exec" id pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• source: "exec" ids must not contain . or .. slash-delimited path segments (for example a/../b is rejected)

支持的凭证路径

• Canonical matrix: SecretRef Credential Surface
• secrets apply targets supported openclaw.json credential paths.
• auth-profiles.json refs are included in runtime resolution and audit coverage.

密钥提供者配置

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}