本页是 ~/.openclaw/openclaw.json 的完整字段参考。养龙虾的时候遇到不知道该怎么配的字段，来这里查就对了。格式为 JSON5（支持注释和尾随逗号），所有字段均为可选——OpenClaw 在字段缺失时会使用安全默认值。任务导向的配置概览见配置文档。

配置参考

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

配置格式为 JSON5（支持注释和尾随逗号）。所有字段均为可选——缺失时 OpenClaw 使用安全默认值。

渠道（Channels）

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

DM 和群组访问策略

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

DM 策略	行为
`pairing`（默认）	未知发件人收到一次性配对码，需要所有者批准
`allowlist`	只允许 `allowFrom` 中的发件人（或已配对允许列表）
`open`	允许所有入站 DM（需要 `allowFrom: ["*"]`）
`disabled`	忽略所有入站 DM

群组策略	行为
`allowlist`（默认）	只允许配置的允许列表中的群组
`open`	绕过群组允许列表（提及门控仍然有效）
`disabled`	阻止所有群组/房间消息

channels.defaults.groupPolicy 设置提供商级 groupPolicy 未设置时的默认值。配对码有效期 1 小时。每个渠道最多 3 个待处理 DM 配对请求。

渠道模型覆盖

使用 channels.modelByChannel 将特定渠道 ID 固定到某个模型：

json5

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

渠道默认值与心跳

json5

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

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

json5

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true,
      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：

json5

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {},
      },
    },
  },
}

json5

{
  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 | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      proxy: "socks5://localhost:9050",
    },
  },
}

Bot token：channels.telegram.botToken，默认账号 env 回退为 TELEGRAM_BOT_TOKEN。
多账号配置时，建议显式设置 channels.telegram.defaultAccount，否则 openclaw doctor 会告警。
configWrites: false 阻止 Telegram 发起的配置写入。

Discord

json5

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      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 | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      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
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false,
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
    },
  },
}

Token：channels.discord.token，默认账号 env 回退为 DISCORD_BOT_TOKEN。
使用 user:<id>（DM）或 channel:<id>（公会频道）作为发送目标；不接受裸数字 ID。
maxLinesPerMessage（默认 17）：超过行数时拆分消息，即使字符数未超 2000。

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

Google Chat

json5

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

服务账号：内联（serviceAccount）或文件（serviceAccountFile），也支持 SecretRef（serviceAccountRef）。
Env 回退：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。

Slack

json5

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      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 | batched
      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,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

Socket 模式：需要 botToken 和 appToken（默认账号 env 回退：SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
HTTP 模式：需要 botToken 加 signingSecret。
使用 user:<id>（DM）或 channel:<id> 作为发送目标。

线程会话隔离： thread.historyScope 为 per-thread（默认）或共享 channel。thread.inheritParent 将父频道历史复制到新线程。

Mattermost

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

json5

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

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

Signal

json5

{
  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（推荐的 iMessage 方案）

BlueBubbles 是推荐的 iMessage 接入方式（插件支持，配置在 channels.bluebubbles）。

json5

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, 群组控制等
      // 详见 /openclaw/channels/bluebubbles
    },
  },
}

iMessage（直接模式）

OpenClaw 通过 stdio 启动 imsg rpc。不需要 daemon 或端口。

json5

{
  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"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

需要对 Messages DB 的完整磁盘访问权限。推荐用 chat_id:<id> 作为目标。

Matrix

Matrix 通过扩展支持，配置在 channels.matrix。

json5

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
        },
      },
    },
  },
}

Token 认证用 accessToken；密码认证用 userId + password。
channels.matrix.execApprovals 配置 Matrix 原生 exec 审批投递和审批者授权。

Microsoft Teams

Teams 通过扩展支持，配置在 channels.msteams。完整配置详见 Microsoft Teams。

多账号（所有渠道通用）

每个渠道可运行多个账号（各有独立 accountId）：

json5

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "主 bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "告警 bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

省略 accountId 时使用 default。
Env token 只适用于默认账号。
基础渠道设置应用于所有账号，除非每账号单独覆盖。

群聊提及门控

群消息默认需要提及（元数据提及或安全正则模式）。

json5

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

命令（聊天命令处理）

json5

{
  commands: {
    native: "auto", // 支持时注册原生命令
    text: true, // 解析聊天消息中的 /命令
    bash: false, // 允许 !（别名：/bash）
    bashForegroundMs: 2000,
    config: false, // 允许 /config
    debug: false, // 允许 /debug
    restart: false, // 允许 /restart + gateway 重启工具
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

Agent 默认值

`agents.defaults.workspace`

默认值：~/.openclaw/workspace。

json5

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

`agents.defaults.skills`

Agent 默认技能允许列表：

json5

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // 继承 github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换默认值
      { id: "locked-down", skills: [] }, // 无技能
    ],
  },
}

`agents.defaults.skipBootstrap`

禁用工作区 bootstrap 文件的自动创建（AGENTS.md、SOUL.md、TOOLS.md 等）。

`agents.defaults.contextInjection`

控制工作区 bootstrap 文件何时注入系统提示。默认："always"。

"continuation-skip"：安全续写轮次跳过 bootstrap 重注入，减少提示大小。

`agents.defaults.model`

json5

{
  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"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      params: { cacheRetention: "long" },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

内置别名速查表：

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

配置的别名总是优先于内置别名。

Z.AI GLM-4.x 模型默认自动启用思考模式，除非显式设置 --thinking off 或在 params 中设置。
Anthropic Claude 4.6 模型在未显式设置思考级别时默认用 adaptive 思考。

`agents.defaults.heartbeat`

心跳运行配置：

json5

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m 禁用
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        activeHours: { start: 8, end: 22, tz: "America/Los_Angeles" },
      },
    },
  },
}

Gateway 配置

`gateway.auth`

json5

{
  gateway: {
    auth: {
      mode: "token", // token | password | trusted-proxy | none
      token: "my-secret-token",
      password: "my-password",
      allowTailscale: true, // Tailscale 标识头满足 WebSocket/Control UI 认证
    },
  },
}

不要在配置文件中明文写 token；建议用 SecretRef 引用：

json5

{
  gateway: {
    auth: {
      token: { type: "env", source: "OPENCLAW_GATEWAY_TOKEN" },
    },
  },
}

`gateway.port` 和 `gateway.bind`

json5

{
  gateway: {
    port: 18789,
    bind: "loopback", // loopback | tailnet | lan | auto | custom
    bindHost: "0.0.0.0", // 仅 bind=custom 时使用
  },
}

`gateway.remote`

json5

{
  gateway: {
    mode: "remote", // local | remote
    remote: {
      url: "wss://gateway.example.com:18789",
      token: "my-remote-token",
    },
  },
}

工具配置

`tools.exec`

json5

{
  tools: {
    exec: {
      enabled: true,
      ask: "always", // never | on-request | always
      security: "standard", // standard | elevated-only | disabled
      allowFrom: {
        "*": ["*"],
        discord: ["user:123"],
      },
    },
  },
}

`tools.browser`

json5

{
  tools: {
    browser: {
      enabled: false, // 默认禁用
      viewport: { width: 1280, height: 800 },
      screenshotMaxDimension: 1200,
      executablePath: "/usr/bin/google-chrome",
    },
  },
}

`tools.web`

json5

{
  tools: {
    web: {
      enabled: true,
      maxBytes: 5242880, // 5MB
      timeout: 15000,
    },
  },
}

Cron 配置

json5

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

Hooks 配置

json5

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    internal: {
      enabled: true,
      entries: {
        "session-memory": { enabled: true },
        "command-logger": { enabled: false },
      },
    },
  },
}

插件配置

json5

{
  plugins: {
    load: {
      paths: ["/path/to/my-plugin"],
    },
    entries: {
      "my-plugin": {
        enabled: true,
        config: {
          // 插件特定配置
        },
      },
    },
  },
}

记忆配置

json5

{
  memory: {
    enabled: true,
    search: {
      provider: "auto", // auto | ollama | google | openai | none
      model: "ollama/nomic-embed-text",
    },
    index: {
      chunkSize: 500,
      chunkOverlap: 50,
    },
  },
}

记忆配置的完整参考见记忆配置文档。

常见问题

Q: 所有字段都必须填写吗？

A: 不用，所有字段均为可选。OpenClaw 有安全的默认值，通常你只需要填写渠道 token（如 channels.telegram.botToken）和基础 gateway 认证（gateway.auth.token）就能跑起来。

Q: 配置文件支持注释吗？

A: 支持。格式是 JSON5，可以用 // 或 /* */ 写注释，也支持尾随逗号。

Q: 修改配置后需要重启 Gateway 吗？

A: 大多数修改需要重启生效。运行 openclaw gateway restart 即可。某些配置（如 /config set 通过聊天修改）会自动触发重启。

配置参考 ​

渠道（Channels） ​

DM 和群组访问策略 ​

渠道模型覆盖 ​

渠道默认值与心跳 ​

WhatsApp ​

Telegram ​

Discord ​

Google Chat ​

Slack ​

Mattermost ​

Signal ​

BlueBubbles（推荐的 iMessage 方案） ​

iMessage（直接模式） ​

Matrix ​

Microsoft Teams ​

多账号（所有渠道通用） ​

群聊提及门控 ​

命令（聊天命令处理） ​

Agent 默认值 ​

agents.defaults.workspace ​

agents.defaults.skills ​

agents.defaults.skipBootstrap ​

agents.defaults.contextInjection ​

agents.defaults.model ​

agents.defaults.heartbeat ​

Gateway 配置 ​

gateway.auth ​

gateway.port 和 gateway.bind ​

gateway.remote ​

工具配置 ​

tools.exec ​

tools.browser ​

tools.web ​

Cron 配置 ​

Hooks 配置 ​

插件配置 ​

记忆配置 ​

常见问题 ​

配置参考

渠道（Channels）

DM 和群组访问策略

渠道模型覆盖

渠道默认值与心跳

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

BlueBubbles（推荐的 iMessage 方案）

iMessage（直接模式）

Matrix

Microsoft Teams

多账号（所有渠道通用）

群聊提及门控

命令（聊天命令处理）

Agent 默认值

`agents.defaults.workspace`

`agents.defaults.skills`

`agents.defaults.skipBootstrap`

`agents.defaults.contextInjection`

`agents.defaults.model`

`agents.defaults.heartbeat`

Gateway 配置

`gateway.auth`

`gateway.port` 和 `gateway.bind`

`gateway.remote`

工具配置

`tools.exec`

`tools.browser`

`tools.web`

Cron 配置

Hooks 配置

插件配置

记忆配置

常见问题