配置

每个渠道在 channels.<provider> 下都有自己的配置部分。有关设置步骤，请参阅相应的渠道页面：

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

所有渠道都采用相同的私信策略模式：

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // 配对 | 允许列表 | 开放 | 禁用      allowFrom: ["tg:123"], // 仅用于允许列表/开放    },  },}

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

{  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 或 --model 覆盖。
• agents.defaults.modelPolicy.allow 是覆盖和模型选择器的显式允许列表。它接受精确引用和 provider/* 通配符；省略该项或使用 [] 可允许任何模型。
• 模型引用采用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
• agents.defaults.imageMaxDimensionPx 控制对话记录/工具图像的缩小处理（默认值为 1200）；在大量使用屏幕截图的运行中，较低的值通常能减少视觉 Token 用量。
• 有关在聊天中切换模型的信息，请参阅模型 CLI；有关身份验证轮换和回退行为的信息，请参阅模型故障转移。
• 对于自定义/自行托管的提供商，请参阅参考文档中的自定义提供商。

每个渠道的私信访问权限通过 dmPolicy 控制（默认值为 "pairing"）：

• "pairing"：未知发送者会收到一次性配对码，以供批准
• "allowlist"：仅允许 allowFrom 中的发送者（或已配对允许存储中的发送者）
• "open"：允许所有传入私信（需要 allowFrom: ["*"]）
• "disabled"：忽略所有私信

对于群组，请使用 groupPolicy（"allowlist" | "open" | "disabled"）以及 groupAllowFrom 或渠道专用允许列表。

有关各渠道的详细信息，请参阅完整参考。

群组消息默认要求提及。请为每个智能体配置触发模式。普通群组/渠道回复会自动发布；对于应由智能体决定何时发言的共享房间，可选择启用消息工具路径：

{  messages: {    visibleReplies: "automatic", // 设为 "message_tool" 以要求所有发送都使用消息工具    groupChat: {      visibleReplies: "message_tool", // 选择启用；可见输出需要 message(action=send)      unmentionedInbound: "room_event", // 未提及智能体的持续群聊内容作为静默上下文    },  },  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.entries.*.skills 覆盖特定智能体：

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

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

为渠道或账号禁用或启用自动健康重启：

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• 使用 channels.<provider>.healthMonitor.enabled 或 channels.<provider>.accounts.<id>.healthMonitor.enabled 控制单个渠道或账号的自动重启。
• 有关运维调试，请参阅健康检查；有关所有字段，请参阅完整参考。

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

{  session: {    dmScope: "per-channel-peer",  // 建议用于多用户场景    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：线程绑定会话路由的全局默认值。/focus、/unfocus、/agents、/session idle 和 /session max-age 可按会话绑定、解绑、列出和调整此设置（Discord 绑定线程，Telegram 绑定话题/对话）。
• 有关作用域、身份关联和发送策略，请参阅会话管理。
• 有关所有字段，请参阅完整参考。

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

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

请先构建镜像——如果使用源码检出，请运行 scripts/sandbox-setup.sh；如果通过 npm 安装，请参阅沙箱隔离 § 镜像和设置中的内联 docker build 命令。

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

面向 App Store 公开构建的中继支持推送使用托管的 OpenClaw 中继：https://ios-push-relay.openclaw.ai。

自定义中继部署需要刻意采用单独的 iOS 构建/部署路径，并使其中继 URL 与 Gateway 网关的中继 URL 匹配。如果使用自定义中继构建，请在 Gateway 网关配置中设置：

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // 可选。默认值：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。中继支持的发送仅适用于通过中继注册的官方分发构建。
• 必须与内置于 iOS 构建中的中继基础 URL 匹配，以确保注册和发送流量到达同一个中继部署。

端到端流程：

1. 安装官方 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 仍可用作临时环境变量覆盖项。
• 自定义 Gateway 网关中继 URL 必须与内置于 iOS 构建中的中继基础 URL 匹配；App Store 公开发布通道会拒绝自定义 iOS 中继 URL 覆盖项。
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍是仅限 local loopback 的开发逃生通道；不要在配置中持久化 HTTP 中继 URL。

有关端到端流程，请参阅 iOS 应用；有关中继安全模型，请参阅身份验证和信任流程。

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

• every：持续时间字符串（30m、2h）。设置为 0m 可禁用。默认值：30m。
• target：last | none | <channel-id>（例如 discord、matrix、telegram 或 whatsapp）
• directPolicy：私信式 Heartbeat 目标可设为 allow（默认）或 block
• 完整指南请参阅 Heartbeat。

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention：从 SQLite 会话行中清理已完成的隔离运行会话（默认值为 24h；设置为 false 可禁用）。
• 运行历史记录会自动为每个任务保留最新的 2000 条终端记录；丢失的记录仍保留其 24 小时清理窗口。
• 有关功能概览和 CLI 示例，请参阅定时任务。

在 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 网关身份验证密钥（gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD）。
• 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" } },  ],}

有关绑定规则和按智能体配置的访问配置文件，请参阅多智能体和完整参考。

使用 $include 组织大型配置：

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

• 单个文件：替换包含它的对象
• 文件数组：按顺序深度合并（后者优先），最多嵌套 10 层
• 同级键：在包含操作后合并（覆盖包含的值）
• 相对路径：相对于执行包含操作的文件解析
• 路径格式：包含路径不得含有空字节，并且在解析前后都必须严格短于 4096 个字符
• OpenClaw 所有的写入操作：当写入仅更改一个由单文件包含项（例如 plugins: { $include: "./plugins.json5" }）支持的顶层节时，OpenClaw 会更新该包含文件，并保持 openclaw.json 不变
• 不支持的写穿透：对于根包含项、包含项数组以及带有同级覆盖项的包含项，OpenClaw 所有的写入操作会以失败关闭方式处理，而不会展平配置
• 限制范围：$include 路径必须解析到存放 openclaw.json 的目录之下。要在多台计算机或多个用户之间共享目录树，请将 OPENCLAW_INCLUDE_ROOTS 设置为路径列表（POSIX 上为 :，Windows 上为 ;），列出包含项可以引用的其他目录。系统会解析并重新检查符号链接，因此，即使某个路径在词法上位于配置目录内，但其真实目标逸出所有允许的根目录，该路径仍会被拒绝。
• 错误处理：针对文件缺失、解析错误、循环包含、路径格式无效和长度超限提供清晰的错误信息