配置

```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`）；较低的值通常在截图密集运行中减少视觉令牌使用。
- 请参阅 [Models CLI](/zh/docs/concepts/models) 以在聊天中切换模型，并参阅 [Model Failover](/zh/docs/concepts/model-failover) 了解身份轮换和后备行为。
- 对于自定义/自托管提供商，请参阅参考文档中的 [Custom providers](/zh/docs/gateway/configuration-reference#custom-providers-and-base-urls)。

- `"pairing"`（默认）：未知发送者获得一次性配对代码以进行批准
- `"allowlist"`：仅允许 `allowFrom`（或配对允许存储）中的发送者
- `"open"`：允许所有入站 DM（需要 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有 DM

对于群组，使用 `groupPolicy` + `groupAllowFrom` 或特定频道的允许列表。

请参阅 [完整参考](/zh/docs/gateway/configuration-reference#dm-and-group-access) 了解每个频道的详细信息。

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

- **元数据提及**：原生 @-提及（WhatsApp 点击提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的正则模式
- 请参阅 [完整参考](/zh/docs/gateway/configuration-reference#group-chat-mention-gating) 了解每个频道的覆盖和自我聊天模式。

```json5
{
  session: {
    dmScope: "per-channel-peer",  // 推荐用于多用户
    threadBindings: {
      enabled: true,
      ttlHours: 24,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
```

- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents` 和 `/session ttl`）。
- 请参阅 [Session Management](/zh/docs/concepts/session) 了解范围、身份链接和发送策略。
- 请参阅 [完整参考](/zh/docs/gateway/configuration-reference#session) 了解所有字段。

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

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

请参阅 [Sandboxing](/zh/docs/gateway/sandboxing) 获取完整指南和 [完整参考](/zh/docs/gateway/configuration-reference#sandbox) 了解所有选项。

- `every`：持续时间字符串（`30m`、`2h`）。设置 `0m` 禁用。
- `target`：`last` | `whatsapp` | `telegram` | `discord` | `none`
- `directPolicy`：`allow`（默认）或 `block` 用于 DM 风格的心跳目标
- 请参阅 [Heartbeat](/zh/docs/gateway/heartbeat) 获取完整指南。

- `sessionRetention`：从 `sessions.json` 中修剪已完成的隔离运行会话（默认 `24h`；设置 `false` 禁用）。
- `runLog`：按大小和保留行数修剪 `cron/runs/<jobId>.jsonl`。
- 请参阅 [Cron jobs](/zh/docs/automation/cron-jobs) 了解功能概述和 CLI 示例。

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

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

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

请参阅 [Multi-Agent](/zh/docs/concepts/multi-agent) 和 [完整参考](/zh/docs/gateway/configuration-reference#multi-agent-routing) 了解绑定规则和每个代理的访问配置文件。

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

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

<Warning>
`config.apply` 替换**整个配置**。对部分更新使用 `config.patch`，或对单个键使用 `openclaw config set`。
</Warning>

参数：

- `raw`（字符串）—— 整个配置的 JSON5 有效负载
- `baseHash`（可选）—— `config.get` 中的配置哈希（当配置存在时必需）
- `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:dm:+15555550123"
}'
```

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

参数：

- `raw`（字符串）—— 仅包含要更改的键的 JSON5
- `baseHash`（必需）—— `config.get` 中的配置哈希
- `sessionKey`、`note`、`restartDelayMs`—— 与 `config.apply` 相同

重启行为匹配 `config.apply`：合并待处理的重启加上重启周期之间 30 秒的冷却。

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