配置

每个渠道在 channels.<provider> 下都有自己的配置部分。请查看专用渠道页面了解设置步骤：

• WhatsApp - channels.whatsapp
• Telegram - channels.telegram
• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• Microsoft Teams - channels.msteams
• Slack - channels.slack
• Signal - channels.signal
• iMessage - channels.imessage
• Mattermost - channels.mattermost

所有渠道共享相同的私信策略模式：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}

设置主模型和可选回退模型：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models 定义模型目录，并作为 /model 的允许列表。
• 使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 添加允许列表条目，而不移除现有模型。会移除条目的普通替换会被拒绝，除非你传入 --replace。
• 模型引用使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
• agents.defaults.imageMaxDimensionPx 控制转录/工具图片缩放（默认 1200）；较低的值通常会在截图密集的运行中减少视觉 token 用量。
• 请参阅 Models CLI 了解如何在聊天中切换模型，并参阅 Model Failover 了解身份验证轮换和回退行为。
• 对于自定义/自托管提供商，请参阅参考中的自定义提供商。

私信访问通过每个渠道的 dmPolicy 控制：

• "pairing"（默认）：未知发送者会获得一次性配对码以完成批准
• "allowlist"：只允许 allowFrom（或已配对允许存储）中的发送者
• "open"：允许所有入站私信（需要 allowFrom: ["*"]）
• "disabled"：忽略所有私信

对于群组，请使用 groupPolicy + groupAllowFrom 或渠道特定允许列表。

请参阅完整参考了解每个渠道的详情。

群组消息默认需要提及。按智能体配置触发模式，并让可见房间回复保持在默认消息工具路径上，除非你有意需要旧版自动最终回复：

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• 元数据提及：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
• 文本模式：mentionPatterns 中的安全正则模式
• 可见回复：messages.visibleReplies 可以全局要求通过消息工具发送；messages.groupChat.visibleReplies 会为群组/渠道覆盖该设置。
• 请参阅完整参考了解可见回复模式、每渠道覆盖和自聊模式。

使用 agents.defaults.skills 设置共享基线，然后用 agents.list[].skills 覆盖特定智能体：

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• 省略 agents.defaults.skills 时，默认不限制 Skills。
• 省略 agents.list[].skills 时继承默认值。
• 设置 agents.list[].skills: [] 表示无 Skills。
• 请参阅 Skills、Skills 配置 和 配置参考。

控制 Gateway 网关重启看起来陈旧的渠道时的积极程度：

{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}

• 设置 gateway.channelHealthCheckMinutes: 0 可全局禁用健康监控重启。
• channelStaleEventThresholdMinutes 应大于或等于检查间隔。
• 使用 channels.<provider>.healthMonitor.enabled 或 channels.<provider>.accounts.<id>.healthMonitor.enabled 可为某个渠道或账户禁用自动重启，而不禁用全局监控。
• 请参阅 Health Checks 了解运维调试，并参阅完整参考了解所有字段。

在负载较高或性能较低的主机上，给本地客户端更多时间完成认证前的 WebSocket 握手：

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• 默认值为 15000 毫秒。
• OPENCLAW_HANDSHAKE_TIMEOUT_MS 仍会优先用于一次性服务或 shell 覆盖。
• 优先修复启动/事件循环停顿；这个旋钮适用于健康但预热期间较慢的主机。

会话控制对话连续性和隔离：

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: main（共享）| per-peer | per-channel-peer | per-account-channel-peer
• threadBindings：线程绑定会话路由的全局默认值（Discord 支持 /focus、/unfocus、/agents、/session idle 和 /session max-age）。
• 请参阅会话管理了解作用域、身份链接和发送策略。
• 请参阅完整参考了解所有字段。

在隔离的沙箱运行时中运行智能体会话：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

先构建镜像 - 从源码检出运行 scripts/sandbox-setup.sh，或从 npm 安装时参见 沙箱隔离 § 镜像和设置 中的内联 docker build 命令。

完整指南见沙箱隔离，所有选项见完整参考。

由中继支持的推送在 openclaw.json 中配置。

在 Gateway 网关配置中设置：

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

等效 CLI：

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

它会执行以下操作：

• 让 Gateway 网关通过外部中继发送 push.test、唤醒提示和重连唤醒。
• 使用已配对 iOS 应用转发的、按注册范围限定的发送授权。Gateway 网关不需要部署范围的中继令牌。
• 将每个由中继支持的注册绑定到与 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。
• 让本地/手动 iOS 构建继续使用直接 APNs。由中继支持的发送仅适用于通过中继注册的官方分发构建。
• 必须匹配内置到官方/TestFlight iOS 构建中的中继基础 URL，这样注册和发送流量才能到达同一个中继部署。

端到端流程：

1. 安装使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。
2. 在 Gateway 网关上配置 gateway.push.apns.relay.baseUrl。
3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都连接。
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用收据向中继注册，然后将由中继支持的 push.apns.register 负载发布到已配对的 Gateway 网关。
5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 push.test、唤醒提示和重连唤醒。

操作说明：

• 如果你将 iOS 应用切换到不同的 Gateway 网关，请重新连接应用，使其可以发布绑定到该 Gateway 网关的新中继注册。
• 如果你发布指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继源。

兼容性说明：

• OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可作为临时环境变量覆盖项使用。
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍是仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP 中继 URL。

端到端流程见 iOS 应用，中继安全模型见身份验证和信任流程。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

• every：时长字符串（30m、2h）。设为 0m 可禁用。
• target：last | none | <channel-id>（例如 discord、matrix、telegram 或 whatsapp）
• directPolicy：针对私信风格 Heartbeat 目标的 allow（默认）或 block
• 完整指南见 Heartbeat。

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention：从 sessions.json 中清理已完成的隔离运行会话（默认 24h；设为 false 可禁用）。
• runLog：按大小和保留行数清理 cron/runs/<jobId>.jsonl。
• 功能概览和 CLI 示例见 Cron 作业。

在 Gateway 网关上启用 HTTP webhook 端点：

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

安全说明：

• 将所有 hook/webhook 负载内容视为不可信输入。
• 使用专用的 hooks.token；不要复用共享的 Gateway 网关令牌。
• Hook 身份验证仅通过标头（Authorization: Bearer ... 或 x-openclaw-token）；查询字符串令牌会被拒绝。
• hooks.path 不能是 /；请将 webhook 入口保留在专用子路径上，例如 /hooks。
• 除非进行严格限定范围的调试，否则请保持不安全内容绕过标志禁用（hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent）。
• 如果启用 hooks.allowRequestSessionKey，还要设置 hooks.allowedSessionKeyPrefixes，以限制调用方选择的会话键。
• 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅限消息，加上可行时的沙箱隔离）。

所有映射选项和 Gmail 集成见完整参考。

运行多个拥有独立工作区和会话的隔离智能体：

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

绑定规则和每个智能体的访问配置文件见 Multi-Agent 和完整参考。

使用 $include 组织大型配置：

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

• 单个文件：替换包含它的对象
• 文件数组：按顺序深度合并（后者优先）
• 同级键：在 include 之后合并（覆盖被 include 的值）
• 嵌套 include：最多支持 10 层深度
• 相对路径：相对于发起 include 的文件解析
• OpenClaw 拥有的写入：当一次写入只更改一个顶层部分， 且该部分由单文件 include 支持（例如 plugins: { $include: "./plugins.json5" }）时， OpenClaw 会更新该被 include 的文件，并保持 openclaw.json 不变
• 不支持的直写：对于 OpenClaw 拥有的写入，根 include、include 数组以及 带有同级覆盖的 include 会关闭失败，而不是 展平配置
• 限制范围：$include 路径必须解析到保存 openclaw.json 的目录下。若要跨机器或用户共享目录树，请将 OPENCLAW_INCLUDE_ROOTS 设置为路径列表（POSIX 上为 :，Windows 上为 ;），其中包含 include 可以引用的其他目录。符号链接会被解析 并重新检查，因此即使某个路径在字面上位于配置目录中，但其 真实目标逃离了每个允许的根，也仍会被拒绝。
• 错误处理：对缺失文件、解析错误和循环 include 提供清晰错误