配置

每个渠道在 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 的允许列表；provider/* 条目会将 /model、/models 和模型选择器筛选为选定的提供商，同时仍使用动态模型发现。
• 使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 添加允许列表条目，而不删除现有模型。如果普通替换会删除条目，除非传入 --replace，否则会被拒绝。
• 模型引用使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
• agents.defaults.imageMaxDimensionPx 控制记录文本/工具图像的缩小尺寸（默认值为 1200）；在大量使用截图的运行中，较低的值通常会减少视觉令牌用量。
• 有关在聊天中切换模型的信息，请参阅模型 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.list[].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.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，可以为单个渠道或账户禁用自动重启，而无需禁用全局监控。
• 有关运维调试，请参阅健康检查；有关所有字段，请参阅完整参考。

在负载较高或性能较低的主机上，为本地客户端提供更多时间来完成 身份验证前的 WebSocket 握手：

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• 默认值为 15000 毫秒。
• 对于一次性的服务或 shell 覆盖，OPENCLAW_HANDSHAKE_TIMEOUT_MS 仍具有更高优先级。
• 应优先修复启动/事件循环停顿；此选项适用于运行正常但预热期间速度较慢的主机。

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

{  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",  // 关闭 | 非主会话 | 全部

        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 仍是仅限回环地址的开发应急选项；不要在配置中持久保存 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,    maxConcurrentRuns: 8, // 默认值；定时任务分派 + 隔离的定时任务智能体轮次执行    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention：从 SQLite 会话行中清理已完成的隔离运行会话（默认 24h；设为 false 可禁用）。
• runLog：按任务清理保留的定时任务运行历史记录行。历史记录存储在 SQLite 中；保留 maxBytes（默认 2_000_000）是为了兼容旧版基于文件的运行日志，keepLines 默认为 2000。
• 有关功能概览和 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 层
• 同级键：在 include 后合并（覆盖 include 中的值）
• 相对路径：相对于执行 include 的文件解析
• 路径格式：include 路径不得包含空字节，并且解析前后的长度都必须严格小于 4096 个字符
• OpenClaw 所有的写入：当一次写入仅更改一个由单文件 include 支持的顶级部分时，例如 plugins: { $include: "./plugins.json5" }， OpenClaw 会更新该 include 文件，并保持 openclaw.json 不变
• 不支持的写入穿透：对于根级 include、include 数组以及带有同级覆盖项的 include，OpenClaw 所有的写入会以失败关闭方式处理，而不会 将配置扁平化
• 范围限制：$include 路径必须解析到包含 openclaw.json 的目录下。若要在多台机器或多个用户之间共享目录树，请将 OPENCLAW_INCLUDE_ROOTS 设置为由路径组成的列表（POSIX 上使用 :，Windows 上使用 ;），其中包含 include 可以引用的其他目录。系统会解析符号链接并 重新检查，因此，即使某路径从字面上看位于配置目录中，只要其 实际目标逃逸出所有允许的根目录，仍会被拒绝。
• 错误处理：针对文件缺失、解析错误、循环 include、无效路径格式和长度超限提供明确错误