配置

每个频道在 `channels.<provider>` 下有自己的配置段。各频道的设置步骤见专用页面：

- [WhatsApp](/docs/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/docs/channels/telegram) — `channels.telegram`
- [Discord](/docs/channels/discord) — `channels.discord`
- [Slack](/docs/channels/slack) — `channels.slack`
- [Signal](/docs/channels/signal) — `channels.signal`
- [iMessage](/docs/channels/imessage) — `channels.imessage`
- [Google Chat](/docs/channels/googlechat) — `channels.googlechat`
- [Mattermost](/docs/channels/mattermost) — `channels.mattermost`
- [MS Teams](/docs/channels/msteams) — `channels.msteams`

所有频道共用相同的 DM 策略模式：

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 仅 allowlist/open 时用
    },
  },
}
```

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

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

- `agents.defaults.models` 定义模型目录，同时作为 `/model` 的白名单。
- 模型引用使用 `provider/model` 格式（如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图片的降采样（默认 `1200`）；降低值通常可减少截图密集运行的视觉 token 消耗。
- 在聊天中切换模型见 [Models CLI](/docs/concepts/models)，认证轮换和回退行为见 [Model Failover](/docs/concepts/model-failover)。
- 自定义/自托管提供商见参考中的[自定义提供商](/docs/gateway/configuration-reference#custom-providers-and-base-urls)。

私聊访问通过每个频道的 `dmPolicy` 控制：

- `"pairing"`（默认）：未知发送者获得一次性配对码等待审批
- `"allowlist"`：仅 `allowFrom`（或已配对的允许列表）中的发送者
- `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有私信

群组使用 `groupPolicy` + `groupAllowFrom` 或频道特定的白名单。

完整详情见[完整参考](/docs/gateway/configuration-reference#dm-and-group-access)。

群消息默认**要求 @提及**。按 Agent 配置匹配模式：

```json5
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **元数据提及**：平台原生的 @提及（WhatsApp 点击提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的正则表达式
- 详情见[完整参考](/docs/gateway/configuration-reference#group-chat-mention-gating)中的频道级覆盖和自聊模式。

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

```json5
{
  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`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
- 会话管理见 [Session Management](/docs/concepts/session)。
- 所有字段见[完整参考](/docs/gateway/configuration-reference#session)。

在隔离的 Docker 容器中运行 Agent 会话：

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

先构建镜像：`scripts/sandbox-setup.sh`

完整指南见 [Sandboxing](/docs/gateway/sandboxing)，所有选项见[完整参考](/docs/gateway/configuration-reference#sandbox)。

Relay 推送在 `openclaw.json` 中配置。

在 Gateway 配置中设置：

```json5
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // 可选。默认：10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
```

CLI 等价写法：

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

这样做的效果：

- 让 Gateway 通过外部 relay 发送 `push.test`、唤醒推送和重连唤醒。
- 使用已配对 iOS 应用转发的、按注册范围的发送授权。Gateway 不需要部署级的 relay token。
- 将每个 relay 注册绑定到 iOS 应用配对时的 Gateway 身份，其他 Gateway 不能复用已存储的注册。
- 本地/手动 iOS 构建继续用直接 APNs。Relay 发送仅适用于通过 relay 注册的官方分发构建。
- 必须与官方/TestFlight iOS 构建中内嵌的 relay base URL 一致，确保注册和发送流量到达同一个 relay 部署。

端到端流程：

1. 安装一个编译了相同 relay base URL 的官方/TestFlight iOS 构建。
2. 在 Gateway 上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用配对到 Gateway，让节点和 operator 会话都连接上。
4. iOS 应用获取 Gateway 身份，使用 App Attest + 应用收据向 relay 注册，然后将 relay 的 `push.apns.register` payload 发布到已配对的 Gateway。
5. Gateway 存储 relay handle 和发送授权，然后用它们做 `push.test`、唤醒推送和重连唤醒。

运维说明：

- 如果把 iOS 应用切换到另一个 Gateway，重新连接应用以发布绑定到新 Gateway 的 relay 注册。
- 如果发布指向不同 relay 部署的新 iOS 构建，应用会刷新缓存的 relay 注册而非复用旧的 relay 来源。

兼容性说明：

- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可用作临时环境变量覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍为仅回环的开发逃生舱；不要在配置中持久化 HTTP relay URL。

端到端流程见 [iOS App](/docs/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型见 [Authentication and trust flow](/docs/platforms/ios#authentication-and-trust-flow)。

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

- `every`：时长字符串（`30m`、`2h`）。设 `0m` 禁用。
- `target`：`last` | `whatsapp` | `telegram` | `discord` | `none`
- `directPolicy`：`allow`（默认）或 `block` 用于私聊类心跳目标
- 完整指南见 [Heartbeat](/docs/gateway/heartbeat)。

```json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
```

- `sessionRetention`：从 `sessions.json` 中清除已完成的隔离定时任务会话（默认 `24h`；设 `false` 禁用）。
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
- 功能概览和 CLI 示例见 [Cron jobs](/docs/automation/cron-jobs)。

在 Gateway 上启用 HTTP webhook 端点：

```json5
{
  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 payload 内容视为不可信输入。
- 保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非在做严格限定范围的调试。
- 对于 hook 驱动的 Agent，优先使用强大的现代模型层和严格的工具策略（比如仅消息加上可能的沙箱）。

所有映射选项和 Gmail 集成见[完整参考](/docs/gateway/configuration-reference#hooks)。

运行多个独立的 Agent，各有独立的工作区和会话：

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

绑定规则和按 Agent 的访问配置见 [Multi-Agent](/docs/concepts/multi-agent) 和[完整参考](/docs/gateway/configuration-reference#multi-agent-routing)。

用 `$include` 组织大型配置：

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

- **单个文件**：替换包含它的对象
- **文件数组**：按顺序深度合并（后面的覆盖前面的）
- **同级键**：在 include 之后合并（覆盖 include 的值）
- **嵌套 include**：最多支持 10 层深度
- **相对路径**：相对于包含文件解析
- **错误处理**：对缺失文件、解析错误和循环 include 给出清晰的错误信息

验证 + 写入完整配置并一步重启 Gateway。

> **注意：** `config.apply` 替换**整个配置**。部分更新用 `config.patch`，单个键用 `openclaw config set`。

参数：

- `raw`（字符串）—— 整个配置的 JSON5 payload
- `baseHash`（可选）—— `config.get` 返回的配置 hash（配置已存在时必填）
- `sessionKey`（可选）—— 重启后唤醒 ping 的会话键
- `note`（可选）—— 重启哨兵的备注
- `restartDelayMs`（可选）—— 重启前延迟（默认 2000）

已有待处理/进行中的重启请求时会合并，重启周期之间有 30 秒冷却。

```bash
openclaw gateway call config.get --params '{}'  # 获取 payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
```

将部分更新合并到现有配置（JSON merge patch 语义）：

- 对象递归合并
- `null` 删除键
- 数组整体替换

参数：

- `raw`（字符串）—— 仅包含要修改的键的 JSON5
- `baseHash`（必填）—— `config.get` 返回的配置 hash
- `sessionKey`、`note`、`restartDelayMs` —— 同 `config.apply`

重启行为与 `config.apply` 一致：合并待处理的重启请求，重启周期之间有 30 秒冷却。

```bash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```

启用后，如果预期的键未设置，OpenClaw 会运行你的登录 shell 并仅导入缺失的键：

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

环境变量等价方式：OPENCLAW_LOAD_SHELL_ENV=1

在任何配置字符串值中用 ${VAR_NAME} 引用环境变量：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

规则：

• 仅匹配大写名称：[A-Z_][A-Z0-9_]*
• 缺失/空变量在加载时报错
• 用 $${VAR} 转义以输出字面量
• 在 $include 文件中同样生效
• 内联替换："${BASE}/v1" → "https://api.example.com/v1"

对于支持 SecretRef 对象的字段，你可以使用：

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRef 详情（包括 secrets.providers 中 env/file/exec 的配置）见 Secrets Management。 支持的凭证路径列表见 SecretRef Credential Surface。