配置 🔧

OpenClaw 从 ~/.openclaw/openclaw.json（允许注释和尾随逗号）读取可选的 JSON5 配置。

如果文件缺失，OpenClaw 使用安全的默认值（嵌入式 Pi 智能体 + 每个发送者会话 + 工作区 ~/.openclaw/workspace）。通常只有以下情况才需要配置：

限制谁可以触发机器人（channels.whatsapp.allowFrom、channels.telegram.allowFrom 等）
控制群组允许列表 + 提及行为（channels.whatsapp.groups、channels.telegram.groups、channels.discord.guilds、agents.list[].groupChat）
自定义消息前缀（messages）
设置智能体的工作区（agents.defaults.workspace 或 agents.list[].workspace）
调整嵌入式智能体默认值（agents.defaults）和会话行为（session）
设置每个智能体的身份（agents.list[].identity）

配置新手？ 查看配置示例指南，了解带有详细解释的完整示例！

严格配置验证

OpenClaw 仅接受完全匹配模式的配置。未知键、格式错误的类型或无效值会导致网关拒绝启动以确保安全。

当验证失败时：

网关不会启动。
只允许诊断命令（例如：openclaw doctor、openclaw logs、openclaw health、openclaw status、openclaw service、openclaw help）。
运行 openclaw doctor 查看确切问题。
运行 openclaw doctor --fix（或 --yes）以应用迁移/修复。

除非你明确选择 --fix/--yes，否则 Doctor 永远不会写入更改。

模式 + UI 提示

网关通过 config.schema 公开配置的 JSON Schema 表示形式，供 UI 编辑器使用。控制 UI 从此模式渲染表单，并将原始 JSON编辑器作为紧急出口。

通道插件和扩展可以为它们的配置注册模式 + UI 提示，因此通道设置保持跨应用的模式驱动，无需硬编码表单。

提示（标签、分组、敏感字段）与模式一起提供，以便客户端可以渲染更好的表单，而无需硬编码配置知识。

应用 + 重启（RPC）

使用 config.apply 验证 + 写入完整配置并一步重启网关。它写入重启标记，并在网关恢复后 ping 最后活动的会话。

警告：config.apply 替换整个配置。如果你只想更改几个键，使用 config.patch 或 openclaw config set。保留 ~/.openclaw/openclaw.json 的备份。

参数：

raw（字符串）— 整个配置的 JSON5 有效载荷
baseHash（可选）— 来自 config.get 的配置哈希（当配置已存在时需要）
sessionKey（可选）— 最后活动会话键，用于唤醒 ping
note（可选）— 包含在重启标记中的备注
restartDelayMs（可选）— 重启前的延迟（默认 2000）

示例（通过 gateway call）：

bash

openclaw gateway call config.get --params '{}' # 捕获 payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

部分更新（RPC）

使用 config.patch 将部分更新合并到现有配置中，而不会覆盖无关键。它应用 JSON 合并补丁语义：

对象递归合并
null 删除键
数组替换像 config.apply 一样，它验证、写入配置、存储重启标记，并计划网关重启（当提供 sessionKey 时可选唤醒）。

参数：

raw（字符串）— 仅包含要更改的键的 JSON5 有效载荷
baseHash（必需）— 来自 config.get 的配置哈希
sessionKey（可选）— 最后活动会话键，用于唤醒 ping
note（可选）— 包含在重启标记中的备注
restartDelayMs（可选）— 重启前的延迟（默认 2000）

示例：

bash

openclaw gateway call config.get --params '{}' # 捕获 payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\n  channels: { telegram: { groups: { \"*\": { requireMention: false } } } }\n}\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

最小配置（推荐起点）

json5

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

使用以下命令构建默认镜像：

bash

scripts/sandbox-setup.sh

自聊天模式（推荐用于群组控制）

防止机器人响应 WhatsApp 群组中的 @-提及（仅响应特定文本触发器）：

json5

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] }
      }
    ]
  },
  channels: {
    whatsapp: {
      // 允许列表仅限 DMs；包含你自己的号码启用自聊天模式。
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  }
}

配置包含（`$include`）

使用 $include 指令将配置拆分为多个文件。这对于以下情况很有用：

组织大型配置（例如，每个客户端智能体定义）
跨环境共享通用设置
将敏感配置分开

基本用法

json5

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  
  // 包含单个文件（替换键的值）
  agents: { "$include": "./agents.json5" },
  
  // 包含多个文件（按顺序深度合并）
  broadcast: { 
    "$include": [
      "./clients/mueller.json5",
      "./clients/schmidt.json5"
    ]
  }
}

json5

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [
    { id: "main", workspace: "~/.openclaw/workspace" }
  ]
}

合并行为

单个文件：替换包含 $include 的对象
文件数组：按顺序深度合并文件（后面的文件覆盖前面的文件）
同级键：包含后合并同级键（覆盖包含的值）
同级键 + 数组/原始类型：不支持（包含的内容必须是对象）

json5

// 同级键覆盖包含的值
{
  "$include": "./base.json5",   // { a: 1, b: 2 }
  b: 99                          // 结果: { a: 1, b: 99 }
}

嵌套包含

被包含的文件本身可以包含 $include 指令（最多 10 层深度）：

json5

// clients/mueller.json5
{
  agents: { "$include": "./mueller/agents.json5" },
  broadcast: { "$include": "./mueller/broadcast.json5" }
}

路径解析

相对路径：相对于包含文件解析
绝对路径：按原样使用
父目录：../ 引用按预期工作

json5

{ "$include": "./sub/config.json5" }      // 相对
{ "$include": "/etc/openclaw/base.json5" } // 绝对
{ "$include": "../shared/common.json5" }   // 父目录

错误处理

文件缺失：显示包含已解析路径的清晰错误
解析错误：显示哪个包含文件失败
循环包含：检测并报告包含链

示例：多客户端法律设置

json5

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },
  
  // 通用智能体默认值
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" }
    },
    // 从所有客户端合并智能体列表
    list: { "$include": [
      "./clients/mueller/agents.json5",
      "./clients/schmidt/agents.json5"
    ]}
  },
  
  // 合并广播配置
  broadcast: { "$include": [
    "./clients/mueller/broadcast.json5",
    "./clients/schmidt/broadcast.json5"
  ]},
  
  channels: { whatsapp: { groupPolicy: "allowlist" } }
}

json5

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" }
]

json5

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "120363403215116621@g.us": ["mueller-transcribe", "mueller-docs"]
}

常用选项

环境变量 + `.env`

OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量。

此外，它加载：

当前工作目录中的 .env（如果存在）
全局回退 .env 来自 ~/.openclaw/.env（即 $OPENCLAW_STATE_DIR/.env）

两个 .env 文件都不会覆盖现有的环境变量。

你也可以在配置中提供内联环境变量。这些仅在进程环境缺少键时应用（相同的非覆盖规则）：

json5

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    }
  }
}

有关完整的优先级和来源，见/environment。

`env.shellEnv`（可选）

选择加入的便利：如果你启用了且尚未设置任何预期键，OpenClaw 运行你的登录 shell 并仅导入缺失的预期键（从不覆盖）。这有效地来源你的 shell 配置文件。

json5

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

环境变量等效项：

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

配置中的环境变量替换

你可以使用 ${VAR_NAME} 语法在任何配置字符串值中直接引用环境变量。变量在配置加载时、验证之前替换。

json5

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}"
      }
    }
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

规则：

仅匹配大写环境变量名：[A-Z_][A-Z0-9_]*
缺失或空的环境变量在配置加载时抛出错误
用 $${VAR} 转义以输出字面量 ${VAR}
适用于 $include（包含的文件也获得替换）

内联替换：

json5

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1"  // → "https://api.example.com/v1"
      }
    }
  }
}

认证存储（OAuth + API 密钥）

OpenClaw 存储每个智能体的认证配置文件（OAuth + API 密钥）在：

<agentDir>/auth-profiles.json（默认：~/.openclaw/agents/<agentId>/agent/auth-profiles.json）

另见：/concepts/oauth

传统 OAuth 导入：

~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json）

嵌入式 Pi 智能体在以下位置维护运行时缓存：

<agentDir>/auth.json（自动管理；不要手动编辑）

传统智能体目录（多智能体之前）：

~/.openclaw/agent/*（由 openclaw doctor 迁移到 ~/.openclaw/agents/<defaultAgentId>/agent/*）

覆盖：

OAuth 目录（传统仅导入）：OPENCLAW_OAUTH_DIR
智能体目录（默认智能体根覆盖）：OPENCLAW_AGENT_DIR（首选）、PI_CODING_AGENT_DIR（传统）

首次使用时，OpenClaw 将 oauth.json 条目导入 auth-profiles.json。

`auth`

认证配置文件的可选元数据。这不存储秘密；它将配置文件 ID 映射到提供商 + 模式（以及可选的电子邮件）并定义用于故障转移的提供商轮询顺序。

json5

{
  auth: {
    profiles: {
      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" }
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"]
    }
  }
}

`agents.list[].identity`

可选的每个智能体身份，用于默认值和 UX。这由 macOS 入职助手写入。

如果设置，OpenClaw 派生默认值（仅当你没有显式设置它们时）：

messages.ackReaction 来自活动智能体的 identity.emoji（回退到 👀）
agents.list[].groupChat.mentionPatterns 来自智能体的 identity.name/identity.emoji（所以"@Samantha" 在 Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp 的群组中工作）
identity.avatar 接受工作区相对图像路径或远程 URL/数据 URL。本地文件必须位于智能体工作区内。

identity.avatar 接受：

工作区相对路径（必须保持在智能体工作区内）
http(s) URL
data: URI

json5

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png"
        }
      }
    ]
  }
}

`wizard`

由 CLI 向导（onboard、configure、doctor）写入的元数据。

json5

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local"
  }
}

`logging`

默认日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log
如果你想要稳定路径，将 logging.file 设置为 /tmp/openclaw/openclaw.log。
控制台输出可以通过以下方式单独调整：
- logging.consoleLevel（默认 info，--verbose 时提升到 debug）
- logging.consoleStyle（pretty | compact | json）
工具摘要可以重化以避免泄露秘密：
- logging.redactSensitive（off | tools，默认：tools）
- logging.redactPatterns（正则表达式字符串数组；覆盖默认值）

json5

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // 示例：用你自己的规则覆盖默认值。
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
    ]
  }
}

`channels.whatsapp.dmPolicy`

控制 WhatsApp 直接聊天（DMs）的处理方式：

"pairing"（默认）：未知发送者获得配对码；所有者必须批准
"allowlist"：仅允许 channels.whatsapp.allowFrom 中的发送者（或配对允许存储）
"open"：允许所有入站 DMs（需要 channels.whatsapp.allowFrom 包含 "*"）
"disabled"：忽略所有入站 DMs

配对码在 1 小时后过期；机器人仅在创建新请求时发送配对码。挂起的 DM 配对请求默认上限为每个通道 3 个。

配对批准：

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

`channels.whatsapp.allowFrom`

可能触发 WhatsApp 自动回复的 E.164 电话号码允许列表（仅限 DMs）。如果为空且 channels.whatsapp.dmPolicy="pairing"，未知发送者将收到配对码。对于群组，使用 channels.whatsapp.groupPolicy + channels.whatsapp.groupAllowFrom。

json5

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // 可选出站块大小（字符）
      chunkMode: "length", // 可选分块模式（length | newline）
      mediaMaxMb: 50 // 可选入站媒体上限（MB）
    }
  }
}

`channels.whatsapp.sendReadReceipts`

控制入站 WhatsApp 消息是否标记为已读（蓝勾）。默认：true。

自聊天模式总是跳过已读回执，即使启用。

每账户覆盖：channels.whatsapp.accounts.<id>.sendReadReceipts。

json5

{
  channels: {
    whatsapp: { sendReadReceipts: false }
  }
}

`channels.whatsapp.accounts`（多账户）

在一个网关中运行多个 WhatsApp 账户：

json5

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // 可选；保持默认 ID 稳定
        personal: {},
        biz: {
          // 可选覆盖。默认：~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        }
      }
    }
  }
}

注意：

出站命令默认到账户 default（如果存在）；否则按排序的第一个配置账户 ID。
传统单账户 Baileys 认证目录由 openclaw doctor 迁移到 whatsapp/default。

`channels.telegram.accounts` / `channels.discord.accounts` / `channels.googlechat.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`

每个通道运行多个账户（每个账户有自己的 accountId 和可选的 name）：

json5

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

注意：

default 在省略 accountId 时使用（CLI + 路由）。
环境令牌仅适用于默认账户。
基础通道设置（组策略、提及门控等）适用于所有账户，除非每账户覆盖。
使用 bindings[].match.accountId 将每个账户路由到不同的 agents.defaults。

群组聊天提及门控（`agents.list[].groupChat` + `messages.groupChat`）

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

提及类型：

元数据提及：原生平台 @-提及（例如，WhatsApp 点击提及）。在自聊天模式中忽略（见 channels.whatsapp.allowFrom）。
文本模式：在 agents.list[].groupChat.mentionPatterns 中定义的正则表达式模式。无论自聊天模式如何，总是检查。
提及门控仅在提及检测可能时强制执行（原生提及或至少一个 mentionPattern）。

json5

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

messages.groupChat.historyLimit 设置群组历史上下文的全局默认值。通道可以用 channels.<channel>.historyLimit（或对于多账户的 channels.<channel>.accounts.*.historyLimit）覆盖。设置为 0 以禁用历史包装。

DM 历史限制

DM 对话使用智能体管理的基于会话的历史。你可以限制每个 DM 会话保留的用户轮次数量：

json5

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,  // 将 DM 会话限制为 30 个用户轮次
      dms: {
        "123456789": { historyLimit: 50 }  // 每用户覆盖（用户 ID）
      }
    }
  }
}

解析顺序：

每 DM 覆盖：channels.<provider>.dms[userId].historyLimit
提供商默认：channels.<provider>.dmHistoryLimit
无限制（保留所有历史）

支持的提供商：telegram、whatsapp、discord、slack、signal、imessage、msteams。

每智能体覆盖（设置时优先，即使 []）：

json5

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } }
    ]
  }
}

提及门控默认值位于每个通道（channels.whatsapp.groups、channels.telegram.groups、channels.imessage.groups、channels.discord.guilds）。设置 *.groups 时，它也充当群组允许列表；包含 "*" 以允许所有群组。

要仅响应特定文本触发器（忽略原生 @-提及）：

json5

{
  channels: {
    whatsapp: {
      // 包含你自己的号码以启用自聊天模式（忽略原生 @-提及）。
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // 仅这些文本模式将触发响应
          mentionPatterns: ["reisponde", "@clawd"]
        }
      }
    ]
  }
}

组策略（每个通道）

使用 channels.*.groupPolicy 控制是否完全接受群组/房间消息：

json5

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"]
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"]
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["user@org.com"]
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "GUILD_ID": {
          channels: { help: { allow: true } }
        }
      }
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } }
    }
  }
}

注意：

"open"：群组绕过允许列表；提及门控仍然适用。
"disabled"：阻止所有群组/房间消息。
"allowlist"：仅允许匹配的允许列表中的群组/房间。
channels.defaults.groupPolicy 在提供商的 groupPolicy 未设置时设置默认。
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams 使用 groupAllowFrom（回退：显式 allowFrom）。
Discord/Slack 使用通道允许列表（channels.discord.guilds.*.channels、channels.slack.channels）。
群组 DM（Discord/Slack）仍由 dm.groupEnabled + dm.groupChannels 控制。
默认是 groupPolicy: "allowlist"（除非被 channels.defaults.groupPolicy 覆盖）；如果没有配置允许列表，群组消息被阻止。

多智能体路由（`agents.list` + `bindings`）

在一个网关内运行多个隔离的智能体（单独的工作区、agentDir、会话）。入站消息通过绑定路由到智能体。

agents.list[]：每个智能体覆盖。
- id：稳定的智能体 ID（必需）。
- default：可选；当设置多个时，第一个获胜并记录警告。如果都未设置，列表中的第一个条目是默认智能体。
- name：智能体的显示名称。
- workspace：默认 ~/clawd-<agentId>（对于 main，回退到 agents.defaults.workspace）。
- agentDir：默认 ~/.openclaw/agents/<agentId>/agent。
- model：每个智能体默认模型，覆盖该智能体的 agents.defaults.model。
  - 字符串形式："provider/model"，仅覆盖 agents.defaults.model.primary
  - 对象形式：{ primary, fallbacks }（fallbacks 覆盖 agents.defaults.model.fallbacks；[] 禁用该智能体的全局回退）
- identity：每个智能体的名称/主题/emoji（用于提及模式 + 确认反应）。
- groupChat：每个智能体提及门控（mentionPatterns）。
- sandbox：每个智能体沙箱配置（覆盖 agents.defaults.sandbox）。
  - mode："off" | "non-main" | "all"
  - workspaceAccess："none" | "ro" | "rw"
  - scope："session" | "agent" | "shared"
  - workspaceRoot：自定义沙箱工作区根目录
  - docker：每个智能体 docker 覆盖（例如 image、network、env、setupCommand、限制；scope: "shared" 时忽略）
  - browser：每个智能体沙箱浏览器覆盖（scope: "shared" 时忽略）
  - prune：每个智能体沙箱修剪覆盖（scope: "shared" 时忽略）
- subagents：每个智能体子智能体默认值。
  - allowAgents：sessions_spawn 来自该智能体的允许智能体 ID 列表（["*"] = 允许任何；默认：仅相同智能体）
- tools：每个智能体工具限制（在沙箱工具策略之前应用）。
  - profile：基础工具配置文件（应用在 allow/deny 之前）
  - allow：允许的工具名称数组
  - deny：拒绝的工具名称数组（deny 获胜）
agents.defaults：共享智能体默认值（模型、工作区、沙箱等）。
bindings[]：将入站消息路由到 agentId。
- match.channel（必需）
- match.accountId（可选；* = 任何账户；省略 = 默认账户）
- match.peer（可选；{ kind: dm|group|channel, id }）
- match.guildId / match.teamId（可选；通道特定）

确定性匹配顺序：

match.peer
match.guildId
match.teamId
match.accountId（精确，无 peer/guild/team）
match.accountId: "*"（通道范围，无 peer/guild/team）
默认智能体（agents.list[].default，否则列表中的第一个，否则 "main"）

在每个匹配层级中，bindings 中第一个匹配的条目获胜。

每个智能体访问配置文件（多智能体）

每个智能体可以携带自己的沙箱 + 工具策略。使用它来混合访问级别在一个网关中：

完全访问（个人智能体）
只读工具 + 工作区
无文件系统访问（仅消息/会话工具）

见多智能体沙箱和工具了解优先级和额外示例。

完全访问（无沙箱）：

json5

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

只读工具 + 只读工作区：

json5

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/clawd-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"]
        }
      }
    ]
  }
}

无文件系统访问（启用消息/会话工具）：

json5

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/clawd-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"]
        }
      }
    ]
  }
}

示例：两个 WhatsApp 账户 → 两个智能体：

json5

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

`tools.agentToAgent`（可选）

智能体到智能体消息是选择加入的：

json5

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

`messages.queue`

控制入站消息在智能体运行已活动时的行为。

json5

{
  messages: {
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog (steer+backlog ok) | interrupt (queue=steer legacy)
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        imessage: "collect",
        webchat: "collect"
      }
    }
  }
}

`messages.inbound`

对来自同一发送者的快速入站消息进行去抖动，以便多个连续消息变成单个智能体轮次。去抖动按通道 + 对话范围，并使用最近的消息进行回复线程化/ID。

json5

{
  messages: {
    inbound: {
      debounceMs: 2000, // 0 禁用
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500
      }
    }
  }
}

注意：

去抖动批量纯文本消息；媒体/附件立即刷新。
控制命令（例如 /queue、/new）绕过去抖动以保持独立。

`commands`（聊天命令处理）

控制如何跨连接器启用聊天命令。

json5

{
  commands: {
    native: "auto",         // 在支持时注册原生命令（auto）
    text: true,             // 在聊天消息中解析斜杠命令
    bash: false,            // 允许 !（别名：/bash）（仅主机；需要 tools.elevated 允许列表）
    bashForegroundMs: 2000, // bash 前台窗口（0 立即后台）
    config: false,          // 允许 /config（写入磁盘）
    debug: false,           // 允许 /debug（运行时仅覆盖）
    restart: false,         // 允许 /restart + 网关工具重启操作
    useAccessGroups: true   // 对命令强制执行访问组允许列表/策略
  }
}

注意：

文本命令必须作为独立消息发送，并使用前导 /（无纯文本别名）。
commands.text: false 禁用聊天消息中的命令解析。
commands.native: "auto"（默认）开启 Discord/Telegram 的原生命令并保持 Slack 关闭；不支持的通道保持仅文本。
设置 commands.native: true|false 强制全部，或用 channels.discord.commands.native、channels.telegram.commands.native、channels.slack.commands.native（bool 或 "auto"）按通道覆盖。false 清除启动时 Discord/Telegram 上先前注册的命令；Slack 命令在 Slack 应用中管理。
channels.telegram.customCommands 添加额外的 Telegram 机器人菜单条目。名称标准化；与原生命令冲突被忽略。
commands.bash: true 启用 ! <cmd> 运行主机 shell 命令（/bash <cmd> 也作为别名工作）。需要 tools.elevated.enabled 并在 tools.elevated.allowFrom.<channel> 中允许发送者。
commands.bashForegroundMs 控制 bash 等待多长时间才后台。在 bash 作业运行时，新的 ! <cmd 请求被拒绝（一次一个）。
commands.config: true 启用 /config（读取/写入 openclaw.json）。
channels.<provider>.configWrites 阻止该通道启动的配置写入（包括超级群组 ID 迁移和 /config set|unset）。默认：true。
commands.debug: true 启用 /debug（运行时仅覆盖）。
commands.restart: true 启用 /restart 和网关工具重启操作。
commands.useAccessGroups: false 允许命令绕过访问组允许列表/策略。
斜杠命令和指令仅对授权发送者执行。授权来自通道允许列表/配对加上 commands.useAccessGroups（见配置和斜杠命令）。如果通道允许列表为空或包含 "*"，命令对该通道实际上开放。

`web`（WhatsApp Web 通道运行时）

WhatsApp 通过网关的 Web 通道（Baileys Web）运行。链接会话存在时自动启动。设置 web.enabled: false 默认保持关闭。

json5

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0
    }
  }
}

`channels.telegram`（机器人传输）

仅当 channels.telegram 配置部分存在时，OpenClaw 启动 Telegram。机器人令牌从 channels.telegram.botToken（或 channels.telegram.tokenFile）解析，TELEGRAM_BOT_TOKEN 作为默认账户的回退。设置 channels.telegram.enabled: false 禁用自动启动。多账户支持位于 channels.telegram.accounts（见上文多账户部分）。环境令牌仅适用于默认账户。设置 channels.telegram.configWrites: false 阻止 Telegram 启动的配置写入（包括超级群组 ID 迁移和 /config set|unset）。

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",                 // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"],         // 可选；"open" 需要 ["*"]
      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,                     // 包含最后 N 条群组消息作为上下文（0 禁用）
      replyToMode: "first",                 // off | first | all
      linkPreview: true,                   // 切换出站链接预览
      streamMode: "partial",               // off | partial | block（草稿流式传输；与块流式传输分开）
      draftChunk: {                        // 可选；仅用于 streamMode=block
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"       // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // 工具操作门（false 禁用）
      reactionNotifications: "own",   // off | own | all
      mediaMaxMb: 5,
      retry: {                             // 出站重试策略
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1
      },
      network: {                           // 传输覆盖
        autoSelectFamily: false
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook"
    }
  }
}

草稿流式传输说明：

使用 Telegram sendMessageDraft（草稿气泡，不是真实消息）。
需要私信主题（DMs 中的 message_thread_id；机器人已启用主题）。
/reasoning stream 将推理流式传输到草稿，然后发送最终答案。重试策略默认和行为记录在重试策略中。

`channels.discord`（机器人传输）

通过设置机器人令牌和可选门控配置 Discord 机器人：多账户支持位于 channels.discord.accounts（见上文多账户部分）。环境令牌仅适用于默认账户。

json5

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,                          // 钳制入站媒体大小
      allowBots: false,                       // 允许机器人作者消息
      actions: {                              // 工具操作门（false 禁用）
        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
      dm: {
        enabled: true,                        // 禁用所有 DMs 时为 false
        policy: "pairing",                    // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // 可选 DM 允许列表（"open" 需要 ["*"]）
        groupEnabled: false,                 // 启用群组 DMs
        groupChannels: ["clawd-dm"]          // 可选群组 DM 允许列表
      },
      guilds: {
        "123456789012345678": {               // 公会 ID（首选）或 slug
          slug: "friends-of-clawd",
          requireMention: false,              // 每公会默认
          reactionNotifications: "own",       // off | own | all | allowlist
          users: ["987654321098765432"],      // 可选每公会用户允许列表
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only."
            }
          }
        }
      },
      historyLimit: 20,                       // 包含最后 N 条公会消息作为上下文
      textChunkLimit: 2000,                   // 可选出站文本块大小（字符）
      chunkMode: "length",                    // 可选分块模式（length | newline）
      maxLinesPerMessage: 17,                 // 每条消息的软最大行数（Discord UI 裁剪）
      retry: {                                // 出站重试策略
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1
      }
    }
  }
}

仅当 channels.discord 配置部分存在时 OpenClaw 启动 Discord。令牌从 channels.discord.token 解析，DISCORD_BOT_TOKEN 作为默认账户的回退（除非 channels.discord.enabled 为 false）。在为 cron/CLI 命令指定发送目标时使用 user:<id>（DM）或 channel:<id>（公会通道）；裸数字 ID 是模糊的并被拒绝。公会 slug 是小写的，空格替换为 -；通道键使用 slug 后的通道名称（无前导 #）。优先使用公会 ID 作为键以避免重命名模糊性。

配置 🔧 ​

严格配置验证 ​

模式 + UI 提示 ​

应用 + 重启（RPC） ​

部分更新（RPC） ​

最小配置（推荐起点） ​

自聊天模式（推荐用于群组控制） ​

配置包含（$include） ​

基本用法 ​

合并行为 ​

嵌套包含 ​

路径解析 ​

错误处理 ​

示例：多客户端法律设置 ​

常用选项 ​

环境变量 + .env ​

env.shellEnv（可选） ​

配置中的环境变量替换 ​

认证存储（OAuth + API 密钥） ​

auth ​

agents.list[].identity ​

wizard ​

logging ​

channels.whatsapp.dmPolicy ​

channels.whatsapp.allowFrom ​

channels.whatsapp.sendReadReceipts ​

channels.whatsapp.accounts（多账户） ​

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts ​

群组聊天提及门控（agents.list[].groupChat + messages.groupChat） ​

DM 历史限制 ​

组策略（每个通道） ​

多智能体路由（agents.list + bindings） ​

每个智能体访问配置文件（多智能体） ​

tools.agentToAgent（可选） ​

messages.queue ​

messages.inbound ​

commands（聊天命令处理） ​

web（WhatsApp Web 通道运行时） ​

channels.telegram（机器人传输） ​

channels.discord（机器人传输） ​

配置 🔧

严格配置验证

模式 + UI 提示

应用 + 重启（RPC）

部分更新（RPC）

最小配置（推荐起点）

自聊天模式（推荐用于群组控制）

配置包含（`$include`）

基本用法

合并行为

嵌套包含

路径解析

错误处理

示例：多客户端法律设置

常用选项

环境变量 + `.env`

`env.shellEnv`（可选）

配置中的环境变量替换

认证存储（OAuth + API 密钥）

`auth`

`agents.list[].identity`

`wizard`

`logging`

`channels.whatsapp.dmPolicy`

`channels.whatsapp.allowFrom`

`channels.whatsapp.sendReadReceipts`

`channels.whatsapp.accounts`（多账户）

`channels.telegram.accounts` / `channels.discord.accounts` / `channels.googlechat.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`

群组聊天提及门控（`agents.list[].groupChat` + `messages.groupChat`）

DM 历史限制

组策略（每个通道）

多智能体路由（`agents.list` + `bindings`）

每个智能体访问配置文件（多智能体）

`tools.agentToAgent`（可选）

`messages.queue`

`messages.inbound`

`commands`（聊天命令处理）

`web`（WhatsApp Web 通道运行时）

`channels.telegram`（机器人传输）

`channels.discord`（机器人传输）