配置 🔧

• ✦限制谁可以触发机器人（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）

初次接触配置？ 请查阅配置示例指南，获取带有详细说明的完整示例！

严格配置验证

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

Schema + UI 提示

应用 + 重启（RPC）

• ✦raw（字符串）— 整个配置的 JSON5 负载
• ✦baseHash（可选）— 来自 config.get 的配置哈希（当配置已存在时为必需）
• ✦sessionKey（可选）— 最后活跃会话的键，用于唤醒 ping
• ✦note（可选）— 包含在重启哨兵中的备注
• ✦restartDelayMs（可选）— 重启前的延迟（默认 2000）

bash
openclaw gateway call config.get --params '{}' # capture 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）

• ✦对象递归合并
• ✦null 删除键
• ✦数组替换 与 config.apply 类似，它会验证、写入配置、存储重启哨兵，并调度 Gateway 网关重启（当提供 sessionKey 时可选择唤醒）。

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

bash
openclaw gateway call config.get --params '{}' # capture 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

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

json5
{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      // 白名单仅适用于私聊；包含你自己的号码可启用自聊天模式。
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

配置包含（$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 }
}

嵌套包含

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

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

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

env.shellEnv（可选）

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

• ✦OPENCLAW_LOAD_SHELL_ENV=1
• ✦OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

配置中的环境变量替换

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 密钥）

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

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

• ✦<agentDir>/auth.json（自动管理；请勿手动编辑）

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

• ✦OAuth 目录（仅旧版导入）：OPENCLAW_OAUTH_DIR
• ✦智能体目录（默认智能体根目录覆盖）：OPENCLAW_AGENT_DIR（推荐）、PI_CODING_AGENT_DIR（旧版）

auth

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

• ✦messages.ackReaction 来自活跃智能体的 identity.emoji（回退到 👀）
• ✦agents.list[].groupChat.mentionPatterns 来自智能体的 identity.name/identity.emoji（因此 "@Samantha" 在 Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp 的群组中均可使用）
• ✦identity.avatar 接受工作区相对图片路径或远程 URL/data URL。本地文件必须位于智能体工作区内。

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

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

wizard

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

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

• ✦openclaw pairing list whatsapp
• ✦openclaw pairing approve whatsapp <code>

channels.whatsapp.allowFrom

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

channels.whatsapp.sendReadReceipts

json5
{
  channels: {
    whatsapp: { sendReadReceipts: false },
  },
}

channels.whatsapp.accounts（多账号）

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

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

• ✦省略 accountId 时使用 default（CLI + 路由）。
• ✦环境变量 token 仅适用于默认账号。
• ✦基础渠道设置（群组策略、提及门控等）适用于所有账号，除非在每个账号中单独覆盖。
• ✦使用 bindings[].match.accountId 将每个账号路由到不同的 agents.defaults。

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

• ✦元数据提及：原生平台 @提及（例如 WhatsApp 点按提及）。在 WhatsApp 自聊天模式中被忽略（参见 channels.whatsapp.allowFrom）。
• ✦文本模式：在 agents.list[].groupChat.mentionPatterns 中定义的正则模式。无论自聊天模式如何始终检查。
• ✦提及门控仅在可以检测提及时执行（原生提及或至少一个 mentionPattern）。

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

私聊历史限制

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

1. ✦每私聊覆盖：channels.<provider>.dms[userId].historyLimit
2. ✦提供商默认值：channels.<provider>.dmHistoryLimit
3. ✦无限制（保留所有历史）

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

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

群组策略（按渠道）

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）。
• ✦群组私聊（Discord/Slack）仍由 dm.groupEnabled + dm.groupChannels 控制。
• ✦默认为 groupPolicy: "allowlist"（除非被 channels.defaults.groupPolicy 覆盖）；如果未配置白名单，群组消息将被阻止。

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

• ✦agents.list[]：每智能体覆盖。
  • ✦id：稳定的智能体 id（必需）。
  • ✦default：可选；当设置多个时，第一个获胜并记录警告。 如果未设置，列表中的第一个条目为默认智能体。
  • ✦name：智能体的显示名称。
  • ✦workspace：默认 ~/.openclaw/workspace-<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：每智能体的名称/主题/表情（用于提及模式 + 确认反应）。
  • ✦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（可选；渠道特定）

1. ✦match.peer
2. ✦match.guildId
3. ✦match.teamId
4. ✦match.accountId（精确匹配，无 peer/guild/team）
5. ✦match.accountId: "*"（渠道范围，无 peer/guild/team）
6. ✦默认智能体（agents.list[].default，否则第一个列表条目，否则 "main"）

每智能体访问配置（多智能体）

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

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

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

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

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

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 + gateway 重启工具
    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 控制由该渠道发起的配置变更（默认：true）。适用于 /config set|unset 以及提供商特定的自动迁移（Telegram 超级群组 ID 变更、Slack 频道 ID 变更）。
• ✦commands.debug: true 启用 /debug（仅运行时覆盖）。
• ✦commands.restart: true 启用 /restart 和 gateway 工具重启动作。
• ✦commands.useAccessGroups: false 允许命令绕过访问组白名单/策略。
• ✦斜杠命令和指令仅对已授权发送者有效。授权来自渠道白名单/配对以及 commands.useAccessGroups。

web（WhatsApp Web 渠道运行时）

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

channels.telegram（机器人传输）

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
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

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

channels.discord（机器人传输）

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, // 设为 false 时禁用所有私聊
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // 可选私聊白名单（"open" 需要 ["*"]）
        groupEnabled: false, // 启用群组私聊
        groupChannels: ["openclaw-dm"], // 可选群组私聊白名单
      },
      guilds: {
        "123456789012345678": {
          // 服务器 id（推荐）或 slug
          slug: "friends-of-openclaw",
          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,
      },
    },
  },
}

• ✦off：无反应事件。
• ✦own：机器人自身消息上的反应（默认）。
• ✦all：所有消息上的所有反应。
• ✦allowlist：guilds.<id>.users 中的用户在所有消息上的反应（空列表禁用）。 出站文本按 channels.discord.textChunkLimit（默认 2000）分块。设置 channels.discord.chunkMode="newline" 在长度分块前按空行（段落边界）分割。Discord 客户端可能裁剪过高的消息，因此 channels.discord.maxLinesPerMessage（默认 17）即使在 2000 字符以内也会分割长多行回复。 重试策略默认值和行为记录在重试策略中。

channels.googlechat（Chat API webhook）

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", // pairing | allowlist | open | disabled
        allowFrom: ["users/1234567890"], // 可选；"open" 需要 ["*"]
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• ✦服务账号 JSON 可以内联（serviceAccount）或基于文件（serviceAccountFile）。
• ✦默认账号的环境变量回退：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
• ✦audienceType + audience 必须与 Chat 应用的 webhook 认证配置匹配。
• ✦设置投递目标时使用 spaces/<spaceId> 或 users/<userId|email>。

channels.slack（socket 模式）

json5
{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["U123", "U456", "*"], // 可选；"open" 需要 ["*"]
        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, // 包含最近 N 条频道/群组消息作为上下文（0 禁用）
      allowBots: false,
      reactionNotifications: "own", // off | own | all | allowlist
      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,
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20,
    },
  },
}

• ✦off：无反应事件。
• ✦own：机器人自身消息上的反应（默认）。
• ✦all：所有消息上的所有反应。
• ✦allowlist：channels.slack.reactionAllowlist 中的用户在所有消息上的反应（空列表禁用）。

• ✦channels.slack.thread.historyScope 控制线程历史是按线程（thread，默认）还是跨频道共享（channel）。
• ✦channels.slack.thread.inheritParent 控制新线程会话是否继承父频道的记录（默认：false）。

channels.mattermost（机器人 token）

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

• ✦oncall（默认）：仅在被 @提及时响应频道消息。
• ✦onmessage：响应每条频道消息。
• ✦onchar：当消息以触发前缀开头时响应（channels.mattermost.oncharPrefixes，默认 [">", "!"]）。

• ✦默认私聊：channels.mattermost.dmPolicy="pairing"（未知发送者收到配对码）。
• ✦公开私聊：channels.mattermost.dmPolicy="open" 加上 channels.mattermost.allowFrom=["*"]。
• ✦群组：channels.mattermost.groupPolicy="allowlist" 为默认值（提及门控）。使用 channels.mattermost.groupAllowFrom 限制发送者。

channels.signal（signal-cli）

json5
{
  channels: {
    signal: {
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50, // 包含最近 N 条群消息作为上下文（0 禁用）
    },
  },
}

• ✦off：无反应事件。
• ✦own：机器人自身消息上的反应（默认）。
• ✦all：所有消息上的所有反应。
• ✦allowlist：channels.signal.reactionAllowlist 中的用户在所有消息上的反应（空列表禁用）。

channels.imessage（imsg CLI）

json5
{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host", // 使用 SSH 包装器时通过 SCP 获取远程附件
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50, // 包含最近 N 条群消息作为上下文（0 禁用）
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• ✦需要对消息数据库的完全磁盘访问权限。
• ✦首次发送时会提示请求消息自动化权限。
• ✦建议使用 chat_id:<id> 目标。使用 imsg chats --limit 20 列出聊天。
• ✦channels.imessage.cliPath 可以指向包装脚本（例如 ssh 到另一台运行 imsg rpc 的 Mac）；使用 SSH 密钥避免密码提示。
• ✦对于远程 SSH 包装器，设置 channels.imessage.remoteHost 以便在启用 includeAttachments 时通过 SCP 获取附件。

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

agents.defaults.workspace

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

agents.defaults.repoRoot

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

agents.defaults.skipBootstrap

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

agents.defaults.bootstrapMaxChars

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

agents.defaults.userTimezone

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

agents.defaults.timeFormat

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

messages

json5
{
  messages: {
    responsePrefix: "🦞", // 或 "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false,
  },
}

模板变量

json5
{
  messages: {
    responsePrefix: "[{model} | think:{thinkingLevel}]",
  },
}

• ✦group-mentions（默认）：仅在群组/房间要求提及且机器人被提及时
• ✦group-all：所有群组/房间消息
• ✦direct：仅私聊消息
• ✦all：所有消息

messages.tts

json5
{
  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",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• ✦messages.tts.auto 控制自动 TTS（off、always、inbound、tagged）。
• ✦/tts off|always|inbound|tagged 设置每会话的自动模式（覆盖配置）。
• ✦messages.tts.enabled 为旧版；doctor 会将其迁移为 messages.tts.auto。
• ✦prefsPath 存储本地覆盖（提供商/限制/摘要）。
• ✦maxTextLength 是 TTS 输入的硬上限；摘要会被截断以适应。
• ✦summaryModel 覆盖自动摘要的 agents.defaults.model.primary。
  • ✦接受 provider/model 或来自 agents.defaults.models 的别名。
• ✦modelOverrides 启用模型驱动的覆盖如 [[tts:...]] 标签（默认开启）。
• ✦/tts limit 和 /tts summary 控制每用户的摘要设置。
• ✦apiKey 值回退到 ELEVENLABS_API_KEY/XI_API_KEY 和 OPENAI_API_KEY。
• ✦elevenlabs.baseUrl 覆盖 ElevenLabs API 基础 URL。
• ✦elevenlabs.voiceSettings 支持 stability/similarityBoost/style（0..1）、 useSpeakerBoost 和 speed（0.5..2.0）。

talk

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

agents.defaults

• ✦alias（可选的模型快捷方式，例如 /opus）。
• ✦params（可选的提供商特定 API 参数，传递给模型请求）。

json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5-20250929": {
          params: { temperature: 0.6 },
        },
        "openai/gpt-5.2": {
          params: { maxTokens: 8192 },
        },
      },
    },
  },
}

• ✦设置 --thinking off，或
• ✦自行定义 agents.defaults.models["zai/<model>"].params.thinking。

• ✦opus -> anthropic/claude-opus-4-5
• ✦sonnet -> anthropic/claude-sonnet-4-5
• ✦gpt -> openai/gpt-5.2
• ✦gpt-mini -> openai/gpt-5-mini
• ✦gemini -> google/gemini-3-pro-preview
• ✦gemini-flash -> google/gemini-3-flash-preview

json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["minimax/MiniMax-M2.1"],
      },
    },
  },
}

agents.defaults.cliBackends（CLI 回退）

• ✦CLI 后端以文本为主；工具始终禁用。
• ✦设置 sessionArg 时支持会话；会话 id 按后端持久化。
• ✦对于 claude-cli，默认值已内置。如果 PATH 不完整（launchd/systemd），请覆盖命令路径。

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

json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4.7": {
          alias: "GLM",
          params: {
            thinking: {
              type: "enabled",
              clear_thinking: false,
            },
          },
        },
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free",
        ],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        target: "last",
      },
      maxConcurrent: 3,
      subagents: {
        model: "minimax/MiniMax-M2.1",
        maxConcurrent: 1,
        archiveAfterMinutes: 60,
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000,
      },
      contextTokens: 200000,
    },
  },
}

agents.defaults.contextPruning（工具结果裁剪）

• ✦不触及用户/助手消息。
• ✦保护最后 keepLastAssistants 条助手消息（该点之后的工具结果不会被裁剪）。
• ✦保护引导前缀（第一条用户消息之前的内容不会被裁剪）。
• ✦模式：
  • ✦adaptive：当估计的上下文比率超过 softTrimRatio 时，软裁剪过大的工具结果（保留头尾）。 然后当估计的上下文比率超过 hardClearRatio 且有足够的可裁剪工具结果量（minPrunableToolChars）时，硬清除最旧的符合条件的工具结果。
  • ✦aggressive：始终用 hardClear.placeholder 替换截止点之前符合条件的工具结果（不做比率检查）。

• ✦软裁剪：仅针对过大的工具结果。保留开头 + 结尾，在中间插入 ...。
  • ✦之前：toolResult("…很长的输出…")
  • ✦之后：toolResult("HEAD…\n...\n…TAIL\n\n[Tool result trimmed: …]")
• ✦硬清除：用占位符替换整个工具结果。
  • ✦之前：toolResult("…很长的输出…")
  • ✦之后：toolResult("[Old tool result content cleared]")

• ✦目前包含图像块的工具结果会被跳过（不会被裁剪/清除）。
• ✦估计的"上下文比率"基于字符（近似值），不是精确的 token 数。
• ✦如果会话尚未包含至少 keepLastAssistants 条助手消息，则跳过裁剪。
• ✦在 aggressive 模式下，hardClear.enabled 被忽略（符合条件的工具结果始终被替换为 hardClear.placeholder）。

json5
{
  agents: { defaults: { contextPruning: { mode: "adaptive" } } },
}

json5
{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

• ✦keepLastAssistants：3
• ✦softTrimRatio：0.3（仅 adaptive）
• ✦hardClearRatio：0.5（仅 adaptive）
• ✦minPrunableToolChars：50000（仅 adaptive）
• ✦softTrim：{ maxChars: 4000, headChars: 1500, tailChars: 1500 }（仅 adaptive）
• ✦hardClear：{ enabled: true, placeholder: "[Old tool result content cleared]" }

json5
{
  agents: { defaults: { contextPruning: { mode: "aggressive" } } },
}

json5
{
  agents: {
    defaults: {
      contextPruning: {
        mode: "adaptive",
        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]" },
        // 可选：限制裁剪仅针对特定工具（deny 优先；支持 "*" 通配符）
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

agents.defaults.compaction（预留空间 + 记忆刷新）

• ✦memoryFlush.enabled：true
• ✦memoryFlush.softThresholdTokens：4000
• ✦memoryFlush.prompt / memoryFlush.systemPrompt：带 NO_REPLY 的内置默认值
• ✦注意：当会话工作区为只读时跳过记忆刷新（agents.defaults.sandbox.workspaceAccess: "ro" 或 "none"）。

json5
{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard",
        reserveTokensFloor: 24000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• ✦agents.defaults.blockStreamingDefault："on"/"off"（默认 off）。
• ✦渠道覆盖：*.blockStreaming（及每账号变体）强制分块流式传输开/关。 非 Telegram 渠道需要显式设置 *.blockStreaming: true 来启用块回复。
• ✦agents.defaults.blockStreamingBreak："text_end" 或 "message_end"（默认：text_end）。
• ✦agents.defaults.blockStreamingChunk：流式块的软分块。默认 800–1200 字符，优先段落分隔（\n\n），然后换行，然后句子。 示例：

  json5
  {
    agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } },
  }
  

• ✦agents.defaults.blockStreamingCoalesce：发送前合并流式块。 默认为 { idleMs: 1000 }，从 blockStreamingChunk 继承 minChars， maxChars 上限为渠道文本限制。Signal/Slack/Discord/Google Chat 默认 minChars: 1500，除非被覆盖。 渠道覆盖：channels.whatsapp.blockStreamingCoalesce、channels.telegram.blockStreamingCoalesce、 channels.discord.blockStreamingCoalesce、channels.slack.blockStreamingCoalesce、channels.mattermost.blockStreamingCoalesce、 channels.signal.blockStreamingCoalesce、channels.imessage.blockStreamingCoalesce、channels.msteams.blockStreamingCoalesce、 channels.googlechat.blockStreamingCoalesce （及每账号变体）。
• ✦agents.defaults.humanDelay：第一条之后块回复之间的随机延迟。 模式：off（默认）、natural（800–2500ms）、custom（使用 minMs/maxMs）。 每智能体覆盖：agents.list[].humanDelay。 示例：

  json5
  {
    agents: { defaults: { humanDelay: { mode: "natural" } } },
  }
  

  参见 /concepts/streaming 了解行为 + 分块细节。

• ✦agents.defaults.typingMode："never" | "instant" | "thinking" | "message"。私聊/提及默认为 instant，未被提及的群聊默认为 message。
• ✦session.typingMode：每会话的模式覆盖。
• ✦agents.defaults.typingIntervalSeconds：输入信号刷新频率（默认：6s）。
• ✦session.typingIntervalSeconds：每会话的刷新间隔覆盖。 参见 /concepts/typing-indicators 了解行为细节。

• ✦every：持续时间字符串（ms、s、m、h）；默认单位分钟。默认： 30m。设为 0m 禁用。
• ✦model：可选的心跳运行覆盖模型（provider/model）。
• ✦includeReasoning：为 true 时，心跳也会传递单独的 Reasoning: 消息（与 /reasoning on 相同形式）。默认：false。
• ✦session：可选的会话键，控制心跳在哪个会话中运行。默认：main。
• ✦to：可选的收件人覆盖（渠道特定 id，例如 WhatsApp 的 E.164，Telegram 的聊天 id）。
• ✦target：可选的投递渠道（last、whatsapp、telegram、discord、slack、msteams、signal、imessage、none）。默认：last。
• ✦prompt：可选的心跳内容覆盖（默认：Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.）。覆盖值按原样发送；如果仍需读取文件，请包含 Read HEARTBEAT.md 行。
• ✦ackMaxChars：HEARTBEAT_OK 之后投递前允许的最大字符数（默认：300）。

• ✦设置 agents.list[].heartbeat 为特定智能体启用或覆盖心跳设置。
• ✦如果任何智能体条目定义了 heartbeat，仅那些智能体运行心跳；默认值 成为那些智能体的共享基线。

• ✦backgroundMs：自动后台化前的时间（ms，默认 10000）
• ✦timeoutSec：超过此运行时间后自动终止（秒，默认 1800）
• ✦cleanupMs：完成的会话在内存中保留多久（ms，默认 1800000）
• ✦notifyOnExit：后台执行退出时加入系统事件 + 请求心跳（默认 true）
• ✦applyPatch.enabled：启用实验性 apply_patch（仅 OpenAI/OpenAI Codex；默认 false）
• ✦applyPatch.allowModels：可选的模型 id 白名单（例如 gpt-5.2 或 openai/gpt-5.2） 注意：applyPatch 仅在 tools.exec 下。

• ✦tools.web.search.enabled（默认：有密钥时为 true）
• ✦tools.web.search.apiKey（推荐：通过 openclaw configure --section web 设置，或使用 BRAVE_API_KEY 环境变量）
• ✦tools.web.search.maxResults（1–10，默认 5）
• ✦tools.web.search.timeoutSeconds（默认 30）
• ✦tools.web.search.cacheTtlMinutes（默认 15）
• ✦tools.web.fetch.enabled（默认 true）
• ✦tools.web.fetch.maxChars（默认 50000）
• ✦tools.web.fetch.timeoutSeconds（默认 30）
• ✦tools.web.fetch.cacheTtlMinutes（默认 15）
• ✦tools.web.fetch.userAgent（可选覆盖）
• ✦tools.web.fetch.readability（默认 true；禁用后仅使用基本 HTML 清理）
• ✦tools.web.fetch.firecrawl.enabled（默认：设置了 API 密钥时为 true）
• ✦tools.web.fetch.firecrawl.apiKey（可选；默认为 FIRECRAWL_API_KEY）
• ✦tools.web.fetch.firecrawl.baseUrl（默认 https://api.firecrawl.dev）
• ✦tools.web.fetch.firecrawl.onlyMainContent（默认 true）
• ✦tools.web.fetch.firecrawl.maxAgeMs（可选）
• ✦tools.web.fetch.firecrawl.timeoutSeconds（可选）

• ✦tools.media.models：共享模型列表（按能力标记；在每能力列表之后使用）。
• ✦tools.media.concurrency：最大并发能力运行数（默认 2）。
• ✦tools.media.image / tools.media.audio / tools.media.video：
  • ✦enabled：选择退出开关（配置了模型时默认为 true）。
  • ✦prompt：可选的提示覆盖（图片/视频自动附加 maxChars 提示）。
  • ✦maxChars：最大输出字符数（图片/视频默认 500；音频未设置）。
  • ✦maxBytes：发送的最大媒体大小（默认：图片 10MB，音频 20MB，视频 50MB）。
  • ✦timeoutSeconds：请求超时（默认：图片 60s，音频 60s，视频 120s）。
  • ✦language：可选的音频提示。
  • ✦attachments：附件策略（mode、maxAttachments、prefer）。
  • ✦scope：可选的门控（第一个匹配获胜），带 match.channel、match.chatType 或 match.keyPrefix。
  • ✦models：有序的模型条目列表；失败或超大媒体回退到下一个条目。
• ✦每个 models[] 条目：
  • ✦提供商条目（type: "provider" 或省略）：
    • ✦provider：API 提供商 id（openai、anthropic、google/gemini、groq 等）。
    • ✦model：模型 id 覆盖（图片必需；音频提供商默认为 gpt-4o-mini-transcribe/whisper-large-v3-turbo，视频默认为 gemini-3-flash-preview）。
    • ✦profile / preferredProfile：认证配置文件选择。
  • ✦CLI 条目（type: "cli"）：
    • ✦command：要运行的可执行文件。
    • ✦args：模板化参数（支持 {{MediaPath}}、{{Prompt}}、{{MaxChars}} 等）。
  • ✦capabilities：可选的能力列表（image、audio、video）用于门控共享条目。省略时的默认值：openai/anthropic/minimax → image，google → image+audio+video，groq → audio。
  • ✦prompt、maxChars、maxBytes、timeoutSeconds、language 可在每个条目中覆盖。

json5
{
  tools: {
    media: {
      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" }],
      },
    },
  },
}

• ✦model：生成的子智能体的默认模型（字符串或 { primary, fallbacks }）。如果省略，子智能体继承调用者的模型，除非按智能体或按调用覆盖。
• ✦maxConcurrent：最大并发子智能体运行数（默认 1）
• ✦archiveAfterMinutes：N 分钟后自动归档子智能体会话（默认 60；设为 0 禁用）
• ✦每子智能体工具策略：tools.subagents.tools.allow / tools.subagents.tools.deny（deny 优先）

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

json5
{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

json5
{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

json5
{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

json5
{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

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

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

• ✦enabled：允许提升模式（默认 true）
• ✦allowFrom：每渠道白名单（空 = 禁用）
  • ✦whatsapp：E.164 号码
  • ✦telegram：聊天 id 或用户名
  • ✦discord：用户 id 或用户名（省略时回退到 channels.discord.dm.allowFrom）
  • ✦signal：E.164 号码
  • ✦imessage：句柄/聊天 id
  • ✦webchat：会话 id 或用户名

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

json5
{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          elevated: { enabled: false },
        },
      },
    ],
  },
}

• ✦tools.elevated 是全局基线。agents.list[].tools.elevated 只能进一步限制（两者都必须允许）。
• ✦/elevated on|off|ask|full 按会话键存储状态；内联指令仅应用于单条消息。
• ✦提升的 exec 在主机上运行并绕过沙箱。
• ✦工具策略仍然适用；如果 exec 被拒绝，则无法使用提升。

agents.defaults.sandbox

• ✦scope："agent"（每个智能体一个容器 + 工作区）
• ✦基于 Debian bookworm-slim 的镜像
• ✦智能体工作区访问：workspaceAccess: "none"（默认）
  • ✦"none"：在 ~/.openclaw/sandboxes 下使用每范围的沙箱工作区
• ✦"ro"：将沙箱工作区保持在 /workspace，智能体工作区以只读方式挂载到 /agent（禁用 write/edit/apply_patch）
  • ✦"rw"：将智能体工作区以读写方式挂载到 /workspace
• ✦自动清理：空闲超过 24h 或存在超过 7d
• ✦工具策略：仅允许 exec、process、read、write、edit、apply_patch、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status（deny 优先）
  • ✦通过 tools.sandbox.tools 配置，通过 agents.list[].tools.sandbox.tools 进行每智能体覆盖
  • ✦沙箱策略中支持工具组简写：group:runtime、group:fs、group:sessions、group:memory（参见沙箱 vs 工具策略 vs 提升）
• ✦可选的沙箱浏览器（Chromium + CDP，noVNC 观察器）
• ✦加固旋钮：network、user、pidsLimit、memory、cpus、ulimits、seccompProfile、apparmorProfile

json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared（agent 为默认）
        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",
          // 每智能体覆盖（多智能体）：agents.list[].sandbox.docker.*
          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: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"],
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          containerPrefix: "openclaw-sbx-browser-",
          cdpPort: 9222,
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          allowedControlUrls: ["http://10.0.0.42:18791"],
          allowedControlHosts: ["browser.lab.local", "10.0.0.42"],
          allowedControlPorts: [18791],
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24, // 0 禁用空闲清理
          maxAgeDays: 7, // 0 禁用最大存活时间清理
        },
      },
    },
  },
  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"],
      },
    },
  },
}

bash
scripts/sandbox-setup.sh

bash
scripts/sandbox-browser-setup.sh

• ✦allowedControlUrls：target: "custom" 允许的精确控制 URL。
• ✦allowedControlHosts：允许的主机名（仅主机名，无端口）。
• ✦allowedControlPorts：允许的端口（默认：http=80，https=443）。 默认：所有白名单未设置（无限制）。allowHostControl 默认为 false。

models（自定义提供商 + 基础 URL）

• ✦默认行为：合并（保留现有提供商，按名称覆盖）
• ✦设为 models.mode: "replace" 覆盖文件内容

json5
{
  agents: {
    defaults: {
      model: { primary: "custom-proxy/llama-3.1-8b" },
      models: {
        "custom-proxy/llama-3.1-8b": {},
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions",
        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,
          },
        ],
      },
    },
  },
}

OpenCode Zen（多模型代理）

• ✦模型引用使用 opencode/<modelId>（示例：opencode/claude-opus-4-5）。
• ✦如果你通过 agents.defaults.models 启用白名单，请添加你计划使用的每个模型。
• ✦快捷方式：openclaw onboard --auth-choice opencode-zen。

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

Z.AI（GLM-4.7）— 提供商别名支持

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

• ✦z.ai/* 和 z-ai/* 是接受的别名，规范化为 zai/*。
• ✦如果缺少 ZAI_API_KEY，对 zai/* 的请求将在运行时因认证错误失败。
• ✦示例错误：No API key found for provider "zai".
• ✦Z.AI 的通用 API 端点是 https://api.z.ai/api/paas/v4。GLM 编码 请求使用专用编码端点 https://api.z.ai/api/coding/paas/v4。 内置的 zai 提供商使用编码端点。如果你需要通用 端点，请在 models.providers 中定义自定义提供商并覆盖基础 URL （参见上方自定义提供商部分）。
• ✦在文档/配置中使用假占位符；切勿提交真实 API 密钥。

Moonshot AI（Kimi）

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

• ✦在环境中设置 MOONSHOT_API_KEY 或使用 openclaw onboard --auth-choice moonshot-api-key。
• ✦模型引用：moonshot/kimi-k2.5。
• ✦如需中国端点，使用 https://api.moonshot.cn/v1。

Kimi Coding

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

• ✦在环境中设置 KIMI_API_KEY 或使用 openclaw onboard --auth-choice kimi-code-api-key。
• ✦模型引用：kimi-coding/k2p5。

Synthetic（Anthropic 兼容）

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

• ✦设置 SYNTHETIC_API_KEY 或使用 openclaw onboard --auth-choice synthetic-api-key。
• ✦模型引用：synthetic/hf:MiniMaxAI/MiniMax-M2.1。
• ✦基础 URL 应省略 /v1，因为 Anthropic 客户端会自动附加。

本地模型（LM Studio）— 推荐设置

MiniMax M2.1

json5
{
  agent: {
    model: { primary: "minimax/MiniMax-M2.1" },
    models: {
      "anthropic/claude-opus-4-5": { alias: "Opus" },
      "minimax/MiniMax-M2.1": { alias: "Minimax" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.1",
            name: "MiniMax M2.1",
            reasoning: false,
            input: ["text"],
            // 定价：如需精确费用跟踪，请在 models.json 中更新。
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• ✦设置 MINIMAX_API_KEY 环境变量或使用 openclaw onboard --auth-choice minimax-api。
• ✦可用模型：MiniMax-M2.1（默认）。
• ✦如需精确费用跟踪，请在 models.json 中更新定价。

Cerebras（GLM 4.6 / 4.7）

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

• ✦Cerebras 使用 cerebras/zai-glm-4.7；Z.AI 直连使用 zai/glm-4.7。
• ✦在环境或配置中设置 CEREBRAS_API_KEY。

• ✦支持的 API：openai-completions、openai-responses、anthropic-messages、 google-generative-ai
• ✦对于自定义认证需求使用 authHeader: true + headers。
• ✦如果你希望 models.json 存储在其他位置，请使用 OPENCLAW_AGENT_DIR（或 PI_CODING_AGENT_DIR）覆盖智能体配置根目录（默认：~/.openclaw/agents/main/agent）。

session

json5
{
  session: {
    scope: "per-sender",
    dmScope: "main",
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      dm: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    // 默认已按智能体存储在 ~/.openclaw/agents/<agentId>/sessions/sessions.json
    // 你可以使用 {agentId} 模板进行覆盖：
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    // 私聊折叠到 agent:<agentId>:<mainKey>（默认："main"）。
    mainKey: "main",
    agentToAgent: {
      // 请求者/目标之间的最大乒乓回复轮次（0–5）。
      maxPingPongTurns: 5,
    },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

• ✦mainKey：私聊桶键（默认："main"）。当你想"重命名"主私聊线程而不更改 agentId 时有用。
  • ✦沙箱说明：agents.defaults.sandbox.mode: "non-main" 使用此键检测主会话。任何不匹配 mainKey 的会话键（群组/频道）都会被沙箱化。
• ✦dmScope：私聊会话如何分组（默认："main"）。
  • ✦main：所有私聊共享主会话以保持连续性。
  • ✦per-peer：按发送者 id 跨渠道隔离私聊。
  • ✦per-channel-peer：按渠道 + 发送者隔离私聊（推荐用于多用户收件箱）。
  • ✦per-account-channel-peer：按账号 + 渠道 + 发送者隔离私聊（推荐用于多账号收件箱）。
• ✦identityLinks：将规范 id 映射到提供商前缀的对等方，以便在使用 per-peer、per-channel-peer 或 per-account-channel-peer 时同一人跨渠道共享私聊会话。
  • ✦示例：alice: ["telegram:123456789", "discord:987654321012345678"]。
• ✦reset：主重置策略。默认为 Gateway 网关主机上本地时间凌晨 4:00 每日重置。
  • ✦mode：daily 或 idle（当存在 reset 时默认：daily）。
  • ✦atHour：本地小时（0-23）作为每日重置边界。
  • ✦idleMinutes：滑动空闲窗口（分钟）。当 daily + idle 都配置时，先到期的获胜。
• ✦resetByType：dm、group 和 thread 的每会话覆盖。
  • ✦如果你只设置了旧版 session.idleMinutes 而没有任何 reset/resetByType，OpenClaw 保持仅空闲模式以向后兼容。
• ✦heartbeatIdleMinutes：可选的心跳检查空闲覆盖（启用时每日重置仍然适用）。
• ✦agentToAgent.maxPingPongTurns：请求者/目标之间的最大回复轮次（0–5，默认 5）。
• ✦sendPolicy.default：无规则匹配时的 allow 或 deny 回退。
• ✦sendPolicy.rules[]：按 channel、chatType（direct|group|room）或 keyPrefix（例如 cron:）匹配。第一个 deny 获胜；否则 allow。

skills（Skills 配置）

• ✦allowBundled：可选的仅内置Skills 白名单。如果设置，仅那些内置 Skills 符合条件（管理/工作区 Skills 不受影响）。
• ✦load.extraDirs：额外要扫描的 Skills 目录（最低优先级）。
• ✦install.preferBrew：可用时优先使用 brew 安装程序（默认：true）。
• ✦install.nodeManager：node 安装偏好（npm | pnpm | yarn，默认：npm）。
• ✦entries.<skillKey>：每 Skills 配置覆盖。

• ✦enabled：设为 false 禁用 Skills，即使它是内置/已安装的。
• ✦env：为智能体运行注入的环境变量（仅在尚未设置时）。
• ✦apiKey：对于声明了主环境变量的 Skills 的可选便利字段（例如 nano-banana-pro → GEMINI_API_KEY）。

json5
{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

plugins（扩展）

• ✦enabled：插件加载的主开关（默认：true）。
• ✦allow：可选的插件 id 白名单；设置后仅加载列出的插件。
• ✦deny：可选的插件 id 拒绝列表（deny 优先）。
• ✦load.paths：要加载的额外插件文件或目录（绝对路径或 ~）。
• ✦entries.<pluginId>：每插件覆盖。
  • ✦enabled：设为 false 禁用。
  • ✦config：插件特定的配置对象（如果提供，由插件验证）。

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

browser（OpenClaw 管理的浏览器）

• ✦enabled：true
• ✦evaluateEnabled：true（设为 false 禁用 act:evaluate 和 wait --fn）
• ✦控制服务：仅 local loopback（端口从 gateway.port 派生，默认 18791）
• ✦CDP URL：http://127.0.0.1:18792（控制服务 + 1，旧版单配置文件）
• ✦配置文件颜色：#FF4500（龙虾橙）
• ✦注意：控制服务器由运行中的 Gateway 网关（OpenClaw.app 菜单栏或 openclaw gateway）启动。
• ✦自动检测顺序：如果为 Chromium 内核则使用默认浏览器；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。

json5
{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖
    defaultProfile: "chrome",
    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,
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false, // 将远程 CDP 隧道到 localhost 时设为 true
  },
}

ui（外观）

json5
{
  ui: {
    seamColor: "#FF4500", // 十六进制（RRGGBB 或 #RRGGBB）
    // 可选：控制台 UI 助手身份覆盖。
    // 如果未设置，控制台 UI 使用活跃智能体的身份（配置或 IDENTITY.md）。
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // 表情、短文本，或图片 URL/data URI
    },
  },
}

gateway（Gateway 网关服务器模式 + 绑定）

• ✦mode：未设置（视为"不自动启动"）
• ✦bind：loopback
• ✦port：18789（WS + HTTP 单端口）

json5
{
  gateway: {
    mode: "local", // 或 "remote"
    port: 18789, // WS + HTTP 多路复用
    bind: "loopback",
    // controlUi: { enabled: true, basePath: "/openclaw" }
    // auth: { mode: "token", token: "your-token" } // token 控制 WS + 控制台 UI 访问
    // tailscale: { mode: "off" | "serve" | "funnel" }
  },
}

• ✦gateway.controlUi.basePath 设置控制台 UI 提供服务的 URL 前缀。
• ✦示例："/ui"、"/openclaw"、"/apps/openclaw"。
• ✦默认：根路径（/）（不变）。
• ✦gateway.controlUi.root 设置控制台 UI 资产的文件系统根目录（默认：dist/control-ui）。
• ✦gateway.controlUi.allowInsecureAuth 允许在省略设备身份时对控制台 UI 进行仅 token 认证（通常通过 HTTP）。默认：false。建议使用 HTTPS（Tailscale Serve）或 127.0.0.1。
• ✦gateway.controlUi.dangerouslyDisableDeviceAuth 禁用控制台 UI 的设备身份检查（仅 token/密码）。默认：false。仅用于紧急情况。

• ✦控制台 UI
• ✦Web 概述
• ✦Tailscale
• ✦远程访问

• ✦gateway.trustedProxies：在 Gateway 网关前面终止 TLS 的反向代理 IP 列表。
• ✦当连接来自这些 IP 之一时，OpenClaw 使用 x-forwarded-for（或 x-real-ip）来确定客户端 IP，用于本地配对检查和 HTTP 认证/本地检查。
• ✦仅列出你完全控制的代理，并确保它们覆盖传入的 x-forwarded-for。

• ✦openclaw gateway 拒绝启动，除非 gateway.mode 设为 local（或你传递了覆盖标志）。
• ✦gateway.port 控制用于 WebSocket + HTTP（控制台 UI、hooks、A2UI）的单一多路复用端口。
• ✦OpenAI Chat Completions 端点：默认禁用；通过 gateway.http.endpoints.chatCompletions.enabled: true 启用。
• ✦优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789。
• ✦默认需要 Gateway 网关认证（token/密码或 Tailscale Serve 身份）。非 local loopback 绑定需要共享 token/密码。
• ✦新手引导向导默认生成 gateway token（即使在 local loopback 上）。
• ✦gateway.remote.token 仅用于远程 CLI 调用；它不启用本地 gateway 认证。gateway.token 被忽略。

• ✦gateway.auth.mode 设置握手要求（token 或 password）。未设置时，假定 token 认证。
• ✦gateway.auth.token 存储 token 认证的共享 token（同一机器上的 CLI 使用）。
• ✦当设置了 gateway.auth.mode 时，仅接受该方法（加上可选的 Tailscale 头部）。
• ✦gateway.auth.password 可在此设置，或通过 OPENCLAW_GATEWAY_PASSWORD（推荐）。
• ✦gateway.auth.allowTailscale 允许 Tailscale Serve 身份头部 （tailscale-user-login）在请求通过 local loopback 到达且带有 x-forwarded-for、 x-forwarded-proto 和 x-forwarded-host 时满足认证。OpenClaw 在接受之前 通过 tailscale whois 解析 x-forwarded-for 地址来验证身份。为 true 时， Serve 请求不需要 token/密码；设为 false 要求显式凭据。当 tailscale.mode = "serve" 且认证模式不是 password 时默认为 true。
• ✦gateway.tailscale.mode: "serve" 使用 Tailscale Serve（仅 tailnet，local loopback 绑定）。
• ✦gateway.tailscale.mode: "funnel" 公开暴露仪表板；需要认证。
• ✦gateway.tailscale.resetOnExit 在关闭时重置 Serve/Funnel 配置。

• ✦gateway.remote.url 设置 gateway.mode = "remote" 时 CLI 调用的默认 Gateway 网关 WebSocket URL。
• ✦gateway.remote.transport 选择 macOS 远程传输（ssh 默认，direct 用于 ws/wss）。使用 direct 时，gateway.remote.url 必须为 ws:// 或 wss://。ws://host 默认端口 18789。
• ✦gateway.remote.token 提供远程调用的 token（不需要认证时留空）。
• ✦gateway.remote.password 提供远程调用的密码（不需要认证时留空）。

• ✦OpenClaw.app 监视 ~/.openclaw/openclaw.json，当 gateway.mode 或 gateway.remote.url 变更时实时切换模式。
• ✦如果 gateway.mode 未设置但 gateway.remote.url 已设置，macOS 应用将其视为远程模式。
• ✦当你在 macOS 应用中更改连接模式时，它会将 gateway.mode（以及远程模式下的 gateway.remote.url + gateway.remote.transport）写回配置文件。

json5
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

json5
{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "wss://gateway.example.ts.net",
      token: "your-token",
    },
  },
}

gateway.reload（配置热重载）

• ✦hybrid（默认）：安全更改热应用；关键更改重启 Gateway 网关。
• ✦hot：仅应用热安全更改；需要重启时记录日志。
• ✦restart：任何配置更改都重启 Gateway 网关。
• ✦off：禁用热重载。

json5
{
  gateway: {
    reload: {
      mode: "hybrid",
      debounceMs: 300,
    },
  },
}

热重载矩阵（文件 + 影响）

• ✦~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）

• ✦hooks（webhook 认证/路径/映射）+ hooks.gmail（Gmail 监视器重启）
• ✦browser（浏览器控制服务器重启）
• ✦cron（cron 服务重启 + 并发更新）
• ✦agents.defaults.heartbeat（心跳运行器重启）
• ✦web（WhatsApp Web 渠道重启）
• ✦telegram、discord、signal、imessage（渠道重启）
• ✦agent、models、routing、messages、session、whatsapp、logging、skills、ui、talk、identity、wizard（动态读取）

• ✦gateway（端口/绑定/认证/控制台 UI/tailscale）
• ✦bridge（旧版）
• ✦discovery
• ✦canvasHost
• ✦plugins
• ✦任何未知/不支持的配置路径（为安全默认重启）

多实例隔离

• ✦OPENCLAW_CONFIG_PATH（每实例配置）
• ✦OPENCLAW_STATE_DIR（会话/凭据）
• ✦agents.defaults.workspace（记忆）
• ✦gateway.port（每实例唯一）

• ✦openclaw --dev … → 使用 ~/.openclaw-dev + 端口从基础 19001 偏移
• ✦openclaw --profile <name> … → 使用 ~/.openclaw-<name>（端口通过配置/环境变量/标志）

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

hooks（Gateway 网关 webhook）

• ✦enabled：false
• ✦path：/hooks
• ✦maxBodyBytes：262144（256 KB）

json5
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.2-mini",
      },
    ],
  },
}

• ✦Authorization: Bearer <token> 或
• ✦x-openclaw-token: <token> 或
• ✦?token=<token>

• ✦POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• ✦POST /hooks/agent → { message, name?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
• ✦POST /hooks/<name> → 通过 hooks.mappings 解析

• ✦match.path 匹配 /hooks 之后的子路径（例如 /hooks/gmail → gmail）。
• ✦match.source 匹配负载字段（例如 { source: "gmail" }），以便使用通用的 /hooks/ingest 路径。
• ✦{{messages[0].subject}} 等模板从负载中读取。
• ✦transform 可以指向返回 hook 动作的 JS/TS 模块。
• ✦deliver: true 将最终回复发送到渠道；channel 默认为 last（回退到 WhatsApp）。
• ✦如果没有先前的投递路由，请显式设置 channel + to（Telegram/Discord/Google Chat/Slack/Signal/iMessage/MS Teams 必需）。
• ✦model 覆盖此 hook 运行的 LLM（provider/model 或别名；如果设置了 agents.defaults.models 则必须被允许）。

json5
{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      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" },

      // 可选：为 Gmail hook 处理使用更便宜的模型
      // 在认证/速率限制/超时时回退到 agents.defaults.model.fallbacks，然后 primary
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      // 可选：Gmail hook 的默认思考级别
      thinking: "off",
    },
  },
}

• ✦hooks.gmail.model 指定用于 Gmail hook 处理的模型（默认为会话主模型）。
• ✦接受 provider/model 引用或来自 agents.defaults.models 的别名。
• ✦在认证/速率限制/超时时回退到 agents.defaults.model.fallbacks，然后 agents.defaults.model.primary。
• ✦如果设置了 agents.defaults.models，请将 hooks 模型包含在白名单中。
• ✦启动时，如果配置的模型不在模型目录或白名单中，会发出警告。
• ✦hooks.gmail.thinking 设置 Gmail hook 的默认思考级别，被每 hook 的 thinking 覆盖。

• ✦如果 hooks.enabled=true 且 hooks.gmail.account 已设置，Gateway 网关在启动时 启动 gog gmail watch serve 并自动续期监视。
• ✦设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 禁用自动启动（用于手动运行）。
• ✦避免在 Gateway 网关旁边单独运行 gog gmail watch serve；它会 因 listen tcp 127.0.0.1:8788: bind: address already in use 而失败。

canvasHost（LAN/tailnet Canvas 文件服务器 + 实时重载）

• ✦提供 canvasHost.root 下的文件
• ✦向提供的 HTML 注入微型实时重载客户端
• ✦监视目录并通过 /__openclaw__/ws 的 WebSocket 端点广播重载
• ✦目录为空时自动创建起始 index.html（以便你立即看到内容）
• ✦同时在 /__openclaw__/a2ui/ 提供 A2UI，并作为 canvasHostUrl 通告给节点 （节点始终使用它来访问 Canvas/A2UI）

• ✦配置：canvasHost: { liveReload: false }

json5
{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    port: 18793,
    liveReload: true,
  },
}

• ✦配置：canvasHost: { enabled: false }
• ✦环境变量：OPENCLAW_SKIP_CANVAS_HOST=1

bridge（旧版 TCP 桥接，已移除）

• ✦Gateway 网关可以为节点（iOS/Android）暴露简单的 TCP 桥接，通常在端口 18790。

• ✦enabled：true
• ✦port：18790
• ✦bind：lan（绑定到 0.0.0.0）

• ✦lan：0.0.0.0（可通过任何接口访问，包括 LAN/Wi‑Fi 和 Tailscale）
• ✦tailnet：仅绑定到机器的 Tailscale IP（推荐用于跨地域访问）
• ✦loopback：127.0.0.1（仅本地）
• ✦auto：如果存在 tailnet IP 则优先使用，否则 lan

• ✦bridge.tls.enabled：为桥接连接启用 TLS（启用时仅 TLS）。
• ✦bridge.tls.autoGenerate：当无证书/密钥时生成自签名证书（默认：true）。
• ✦bridge.tls.certPath / bridge.tls.keyPath：桥接证书 + 私钥的 PEM 路径。
• ✦bridge.tls.caPath：可选的 PEM CA 捆绑包（自定义根证书或未来的 mTLS）。

json5
{
  bridge: {
    enabled: true,
    port: 18790,
    bind: "tailnet",
    tls: {
      enabled: true,
      // 省略时使用 ~/.openclaw/bridge/tls/bridge-{cert,key}.pem。
      // certPath: "~/.openclaw/bridge/tls/bridge-cert.pem",
      // keyPath: "~/.openclaw/bridge/tls/bridge-key.pem"
    },
  },
}

discovery.mdns（Bonjour / mDNS 广播模式）

• ✦minimal（默认）：从 TXT 记录中省略 cliPath + sshPort
• ✦full：在 TXT 记录中包含 cliPath + sshPort
• ✦off：完全禁用 mDNS 广播
• ✦主机名：默认为 openclaw（通告 openclaw.local）。通过 OPENCLAW_MDNS_HOSTNAME 覆盖。

json5
{
  discovery: { mdns: { mode: "minimal" } },
}

discovery.wideArea（广域 Bonjour / 单播 DNS‑SD）

• ✦在 Gateway 网关主机上运行 DNS 服务器，为你选择的域名提供服务（推荐 CoreDNS）
• ✦Tailscale split DNS，使客户端通过 Gateway 网关 DNS 服务器解析该域名

bash
openclaw dns setup --apply

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

模板变量

Cron（Gateway 网关调度器）

json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
  },
}