配置 🔧

## 部分更新（RPC）

使用 `config.patch` 将部分更新合并到现有配置中，而不会覆盖不相关的键。它采用 JSON 合并补丁语义：
- 对象会递归合并
- `null` 会删除一个键
- 数组会替换

与 `config.apply` 类似，它会验证配置、写入配置、存储一个重启标记，并计划网关重启（如果提供了 `sessionKey`，则会触发唤醒 ping）。

参数：
- `raw`（字符串）— 包含要更改的键的 JSON5 数据包
- `baseHash`（必需）— 来自 `config.get` 的配置哈希
- `sessionKey`（可选）— 最近活动的会话密钥，用于唤醒 ping
- `note`（可选）— 要包含在重启标记中的备注
- `restartDelayMs`（可选）— 重启前的延迟时间（默认 2000 毫秒）

示例：```bash
clawdbot gateway call config.get --params '{}' # capture payload.hash
clawdbot gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'
```
## 最小配置（推荐起点）
json5
{
  agents: { defaults: { workspace: "~/clawd" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

## 自我聊天模式（推荐用于群组控制）

为防止机器人在群组中对 WhatsApp 的 @-提及 作出回应（仅对特定文本触发词作出回应）：
json5
{
  agents: {
    defaults: { workspace: "~/clawd" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@clawd", "reisponde"] }
      }
    ]
  },
  channels: {
    whatsapp: {
      // 允许列表仅限于私聊；包含你自己的号码将启用自我聊天模式。
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  }
}

### 路径解析

- **相对路径**：相对于包含文件进行解析
- **绝对路径**：直接使用
- **父目录**：`../` 的引用按预期工作
json5
{ "$include": "./sub/config.json5" }      // 相对路径
{ "$include": "/etc/clawdbot/base.json5" } // 绝对路径
{ "$include": "../shared/common.json5" }   // 父目录

请参阅 [/environment](/environment) 以获取完整的优先级和来源信息。

### `env.shellEnv`（可选）

选择性便利功能：如果启用，并且当前尚未设置任何预期的键，则 Clawdbot 会运行您的登录 shell 并仅导入缺失的预期键（从不覆盖）。
这实际上会加载您的 shell 配置文件。
json5
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

**规则：**
- 仅匹配大写的环境变量名称：`[A-Z_][A-Z0-9_]*`
- 缺失或为空的环境变量会在配置加载时抛出错误
- 使用 `$${VAR}` 来输出一个字面量 `${VAR}`
- 支持 `$include`（包含的文件也会进行替换）
json5
{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1"  // → "https://api.example.com/v1"
      }
    }
  }
}

注意：即使存储的凭证是 setup-token，也应使用 `mode: "oauth"`。Clawdbot 会自动迁移之前使用 `mode: "token"` 的配置。

### `agents.list[].identity`

用于默认值和用户体验的可选代理身份信息。这是由 macOS 引导助手写入的。

如果设置了此字段，Clawdbot 会根据**当前代理**的 `identity.emoji` 推导默认值（如果未显式设置）：
- `messages.ackReaction` 从当前代理的 `identity.emoji` 获取（若未设置则回退为 👀）
- `agents.list[].groupChat.mentionPatterns` 从代理的 `identity.name` 或 `identity.emoji` 获取（这样在 Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp 等群组中，“@Samantha” 就可以正常工作）

`identity.avatar` 支持：
- 工作区相对路径（必须位于代理工作区内）
- `http(s)` 协议的 URL
- `data:` 协议的 URI
json5
{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png"
        }
      }
    ]
  }
}

### `logging`

- 默认日志文件：`/tmp/clawdbot/clawdbot-YYYY-MM-DD.log`
- 如果你想使用一个稳定的路径，请将 `logging.file` 设置为 `/tmp/clawdbot/clawdbot.log`。
- 控制台输出可以通过以下选项单独调整：
  - `logging.consoleLevel`（默认为 `info`，当使用 `--verbose` 时提升为 `debug`）
  - `logging.consoleStyle`（`pretty` | `compact` | `json`）
- 工具摘要可以被脱敏以避免泄露敏感信息：
  - `logging.redactSensitive`（`off` | `tools`，默认：`tools`）
  - `logging.redactPatterns`（正则表达式字符串数组；覆盖默认设置）
json5
{
  logging: {
    level: "info",
    file: "/tmp/clawdbot/clawdbot.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // 示例：使用你自己的规则覆盖默认设置。
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
    ]
  }
}

### `channels.whatsapp.sendReadReceipts`

控制是否将传入的 WhatsApp 消息标记为已读（蓝色对勾）。默认值：`true`。

在自我聊天模式下，即使已启用，也会跳过已读回执。

按账户覆盖设置：`channels.whatsapp.accounts.<id>.sendReadReceipts`。
json5
{
  channels: {
    whatsapp: { sendReadReceipts: false }
  }
}

注意事项：
- 如果存在，则出站命令默认使用账户 `default`；否则使用第一个配置的账户 ID（按顺序排序）。
- 旧版的单账户 Baileys 身份验证目录会通过 `clawdbot doctor` 迁移至 `whatsapp/default`。

### `channels.telegram.accounts` / `channels.discord.accounts` / `channels.googlechat.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`

每个频道可以运行多个账户（每个账户拥有自己的 `accountId` 和可选的 `name`）：
json5
{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "主机器人",
          botToken: "123456:ABC..."
        },
        alerts: {
          name: "警报机器人",
          botToken: "987654:XYZ..."
        }
      }
    }
  }
}

优先级顺序：
1. 按用户覆盖：`channels.<provider>.dms[userId].historyLimit`
2. 供应商默认值：`channels.<provider>.dmHistoryLimit`
3. 无限制（保留所有历史记录）

支持的供应商：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。

按代理覆盖（设置时具有优先级，即使为 `[]`）：```json5
{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } }
    ]
  }
}
```
提及过滤器默认按频道开启（`channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`、`channels.discord.guilds`）。当设置 `*.groups` 时，它也会作为群组白名单；若要允许所有群组，请包含 `"*"`。

要**仅**对特定文本触发词作出响应（忽略原生的 @-提及）：
json5
{
  channels: {
    whatsapp: {
      // 将你的号码包含在内以启用自定义聊天模式（忽略原生的 @-提及）。
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // 只有这些文本模式会触发回复
          mentionPatterns: ["reisponde", "@clawd"]
        }
      }
    ]
  }
}

### 注意事项：
- `"open"`：允许所有群组；仍需遵守提及限制。
- `"disabled"`：阻止所有群组/房间消息。
- `"allowlist"`：仅允许与配置的允许列表匹配的群组/房间。
- `channels.defaults.groupPolicy` 设置当提供者未设置 `groupPolicy` 时的默认值。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams 使用 `groupAllowFrom`（回退：显式的 `allowFrom`）。
- Discord/Slack 使用频道允许列表（`channels.discord.guilds.*.channels`, `channels.slack.channels`）。
- 群组私信（Discord/Slack）仍由 `dm.groupEnabled` + `dm.groupChannels` 控制。
- 默认为 `groupPolicy: "allowlist"`（除非被 `channels.defaults.groupPolicy` 覆盖）；如果没有配置允许列表，群组消息将被阻止。

### 多代理路由（`agents.list` + `bindings`）

在一个 Gateway 中运行多个隔离的代理（独立的工作空间，`agentDir`，会话）。
入站消息通过 `bindings` 路由到对应的代理。- `agents.list[]`: 每个代理的覆盖配置。
  - `id`: 稳定的代理ID（必填）。
  - `default`: 可选；当设置多个时，第一个生效并记录警告。
    如果未设置，则**列表中的第一个条目**为默认代理。
  - `name`: 代理的显示名称。
  - `workspace`: 默认为 `~/clawd-<agentId>`（对于 `main` 代理，会回退到 `agents.defaults.workspace`）。
  - `agentDir`: 默认为 `~/.clawdbot/agents/<agentId>/agent`。
  - `model`: 每个代理的默认模型，覆盖该代理的 `agents.defaults.model`。
    - 字符串形式：`"provider/model"`，仅覆盖 `agents.defaults.model.primary`。
    - 对象形式：`{ primary, fallbacks }`（fallbacks 覆盖 `agents.defaults.model.fallbacks`；`[]` 会禁用全局 fallbacks）。
  - `identity`: 每个代理的名称/主题/表情符号（用于提及模式 + 确认反应）。
  - `groupChat`: 每个代理的提及控制（`mentionPatterns`）。
  - `sandbox`: 每个代理的沙箱配置（覆盖 `agents.defaults.sandbox`）。
    - `mode`: `"off"` | `"non-main"` | `"all"`
    - `workspaceAccess`: `"none"` | `"ro"` | `"rw"`
    - `scope`: `"session"` | `"agent"` | `"shared"`
    - `workspaceRoot`: 自定义沙箱工作区根目录
    - `docker`: 每个代理的 Docker 覆盖配置（如 `image`、`network`、`env`、`setupCommand`、limits；当 `scope: "shared"` 时被忽略）
    - `browser`: 每个代理的沙箱浏览器覆盖配置（当 `scope: "shared"` 时被忽略）
    - `prune`: 每个代理的沙箱清理覆盖配置（当 `scope: "shared"` 时被忽略）
  - `subagents`: 每个代理的子代理默认配置。
    - `allowAgents`: 允许从该代理启动 `sessions_spawn` 的代理ID白名单（`["*"]` 表示允许任何；默认：仅允许同一代理）。
  - `tools`: 每个代理的工具限制（在沙箱工具策略之前应用）。
    - `profile`: 基础工具配置文件（在允许/拒绝之前应用）
    - `allow`: 允许的工具名称数组
    - `deny`: 拒绝的工具名称数组（拒绝优先）

- `agents.defaults`: 共享的代理默认配置（模型、工作区、沙箱等）。
- `bindings[]`: 将入站消息路由到某个 `agentId`。
  - `match.channel`（必填）
  - `match.accountId`（可选；`*` 表示任何账户；省略表示默认账户）
  - `match.peer`（可选；`{ kind: dm|group|channel, id }`）
  - `match.guildId` / `match.teamId`（可选；与频道相关）

确定性匹配顺序：
1) `match.peer`
2) `match.guildId`
3) `match.teamId`
4) `match.accountId`（精确匹配，不包含 peer/guild/team）
5) `match.accountId: "*"`（频道范围匹配，不包含 peer/guild/team）
6) 默认代理（`agents.list[].default`，否则为列表中的第一个条目，否则为 `"main"`）

在每个匹配层级中，`bindings` 中第一个匹配的条目将被优先使用。

#### 每个代理的访问配置文件（多代理）

每个代理可以拥有自己的沙箱和工具策略。可用于在同一个网关中混合访问级别：
- **全权限**（个人代理）
- **只读工具 + 工作区**
- **无文件系统访问**（仅限消息/会话工具）

有关优先级和更多示例，请参见 [多代理沙箱与工具](/multi-agent-sandbox-tools)。{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/clawd-personal",
        sandbox: { mode: "off" }
      }
    ]
  }
}```
只读工具 + 只读工作区：```json5
{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/clawd-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "ro"
        },
        tools: {
          allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"]
        }
      }
    ]
  }
}

示例：两个 WhatsApp 账户 → 两个代理：```json5
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/clawd-home" },
      { id: "work", workspace: "~/clawd-work" }
    ]
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      }
    }
  }
}
```
### `tools.agentToAgent`（可选）

代理间消息传递是可选的：
json5
{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"]
    }
  }
}

### `messages.inbound`

对来自**同一发送者**的快速入站消息进行防抖处理，使连续的消息变为一次代理回复。防抖处理是按渠道 + 会话作用域进行的，并使用最新消息用于回复的线程/ID。
json5
{
  messages: {
    inbound: {
      debounceMs: 2000, // 0 表示禁用
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500
      }
    }
  }
}
```注意事项：
- 对**纯文本**消息进行防抖处理；媒体/附件消息会立即发送。
- 控制命令（例如 `/queue`, `/new`）会绕过防抖处理，因此它们会单独执行。

### `commands`（聊天命令处理）

控制聊天命令在各个连接器上的启用情况。
json5
{
  commands: {
    native: "auto",         // 在支持时注册原生命令（auto）
    text: true,             // 解析聊天消息中的斜杠命令
    bash: false,            // 允许 !（别名：/bash）（仅限主机；需要 tools.elevated 的允许列表）
    bashForegroundMs: 2000, // bash 前台窗口（0 表示立即后台运行）
    config: false,          // 允许 /config（写入磁盘）
    debug: false,           // 允许 /debug（仅限运行时覆盖）
    restart: false,         // 允许 /restart 以及网关重启工具
    useAccessGroups: true   // 为命令强制执行访问组允许列表/策略
  }
}

### `channels.telegram`（机器人传输方式）

当存在 `channels.telegram` 配置部分时，Clawdbot 会启动 Telegram。机器人的令牌通过 `channels.telegram.botToken`（或 `channels.telegram.tokenFile`）解析，`TELEGRAM_BOT_TOKEN` 作为默认账户的备用选项。  
将 `channels.telegram.enabled: false` 设置为禁用自动启动。  
多账户支持位于 `channels.telegram.accounts` 下（参见上方的多账户部分）。环境变量令牌仅适用于默认账户。  
将 `channels.telegram.configWrites: false` 设置为阻止 Telegram 引发的配置写入（包括超级群组 ID 迁移和 `/config set|unset` 命令）。
json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",                 // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"],         // 可选；"open" 需要 ["*"]
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "保持回答简洁。",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "紧扣主题。"
            }
          }
        }
      },
      customCommands: [
        { command: "backup", description: "Git 备份" },
        { command: "generate", description: "生成一张图片" }
      ],
      historyLimit: 50,                     // 包含最后 N 条群组消息作为上下文（0 表示禁用）
      replyToMode: "first",                 // off | first | all
      linkPreview: true,                   // 切换出站链接预览
      streamMode: "partial",               // off | partial | block（草稿流模式；与块流模式分开）
      draftChunk: {                        // 可选；仅在 streamMode=block 时使用
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"       // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // 工具操作开关（false 表示禁用）
      reactionNotifications: "own",   // off | own | all
      mediaMaxMb: 5,
      retry: {                             // 出站重试策略
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook"
    }
  }
}

Clawdbot 仅在存在 `channels.discord` 配置部分时才会启动 Discord。`token` 从 `channels.discord.token` 解析，`DISCORD_BOT_TOKEN` 作为默认账户的回退（除非 `channels.discord.enabled` 设置为 `false`）。在指定 cron/CLI 命令的交付目标时，使用 `user:<id>`（私信）或 `channel:<id>`（服务器频道）；纯数字 ID 会产生歧义并被拒绝。

服务器别名（guild slugs）为小写，空格替换为 `-`；频道键使用别名化的频道名称（不带前缀 `#`）。优先使用服务器 ID 作为键，以避免重命名带来的歧义。

默认情况下，机器人发布的消息会被忽略。可通过 `channels.discord.allowBots` 启用。自己的消息仍会被过滤，以防止自我回复循环。

反应通知模式：
- `off`：不接收反应事件。
- `own`：仅接收机器人自己消息上的反应（默认）。
- `all`：接收所有消息上的所有反应。
- `allowlist`：接收 `guilds.<id>.users` 列表中用户的所有消息上的反应（空列表则禁用）。

出站文本会根据 `channels.discord.textChunkLimit` 进行分块（默认为 2000）。设置 `channels.discord.chunkMode="newline"` 可在长度分块前按空行（段落边界）进行分割。Discord 客户端可能会截断非常长的消息，因此 `channels.discord.maxLinesPerMessage`（默认为 17）会在字符数低于 2000 时，仍对长的多行回复进行分割。

重试策略的默认值和行为在 [重试策略](/concepts/retry) 中有文档说明。

### `channels.googlechat`（Chat API 网络钩子）

Google Chat 通过 HTTP 网络钩子运行，并使用应用级认证（服务账户）。
多账户支持位于 `channels.googlechat.accounts` 下（请参见上方的多账户部分）。环境变量仅适用于默认账户。
json5
{
  channels: {
    "googlechat": {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",             // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",        // 可选；提升@检测
      dm: {
        enabled: true,
        policy: "pairing",                // pairing | allowlist | open | disabled
        allowFrom: ["users/1234567890"]   // 可选；"open" 需要 ["*"]
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true }
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20
    }
  }
}

Clawdbot 在配置好账户（bot token + 基础 URL）并启用后启动 Mattermost。token 和基础 URL 会从 `channels.mattermost.botToken` + `channels.mattermost.baseUrl` 或 `MATTERMOST_BOT_TOKEN` + `MATTERMOST_URL` 解析得到，除非 `channels.mattermost.enabled` 为 `false`。

聊天模式：
- `oncall`（默认）：仅在 @ 提及机器人时回复频道消息。
- `onmessage`：回复每个频道消息。
- `onchar`：当消息以触发前缀开头时回复（`channels.mattermost.oncharPrefixes`，默认为 `[">", "!"]`）。

访问控制：
- 默认私信（DM）：`channels.mattermost.dmPolicy="pairing"`（未知发送者会收到配对码）。
- 公共私信（DM）：`channels.mattermost.dmPolicy="open"` 并加上 `channels.mattermost.allowFrom=["*"]`。
- 群组：默认为 `channels.mattermost.groupPolicy="allowlist"`（提及权限控制）。可以使用 `channels.mattermost.groupAllowFrom` 来限制发送者。

多账户支持位于 `channels.mattermost.accounts` 下（请参见上面的多账户部分）。环境变量仅适用于默认账户。
在指定交付目标时，请使用 `channel:<id>` 或 `user:<id>`（或 `@username`）；纯 ID 会被视为频道 ID。```json5
{
  channels: {
    signal: {
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50 // include last N group messages as context (0 disables)
    }
  }
}
```
### `channels.imessage`（imsg CLI）

Clawdbot 会启动 `imsg rpc`（通过标准输入输出的 JSON-RPC）。无需守护进程或端口。
json5
{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host", // 当使用 SSH 包装器时，用于远程附件的 SCP
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,    // 包含最后 N 条群组消息作为上下文（0 表示禁用）
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US"
    }
  }
}

### `channels.feishu` (飞书 Webhook 传输方式)

飞书通过 HTTP Webhook 运行，利用飞书开放平台进行集成。

```json5
{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_...",
      appSecret: "...",
      encryptKey: "...",              // 可选
      verificationToken: "...",        // 可选
      dmPolicy: "pairing",            // pairing | allowlist | open | disabled
      allowFrom: ["ou_..."],          // 可选；"open" 需要 ["*"]
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_..."]      // 可选的群组 ID 白名单
    }
  }
}

如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用自己的作用域工作区进行覆盖。

### `agents.defaults.repoRoot`

可选的仓库根目录，用于在系统提示的 Runtime 行中显示。如果未设置，Clawdbot 会尝试从工作区（以及当前工作目录）向上查找 `.git` 目录。该路径必须存在才能被使用。```json5
{
  agents: { defaults: { repoRoot: "~/Projects/clawdbot" } }
}
```
### `agents.defaults.skipBootstrap`

禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md` 和 `BOOTSTRAP.md`）。

在预填充部署中使用此选项，其中工作区文件来自仓库。
json5
{
  agents: { defaults: { skipBootstrap: true } }
}

### `agents.defaults.userTimezone`

设置用户的时区以用于 **系统提示上下文**（不用于消息信封中的时间戳）。如果未设置，Clawdbot 在运行时会使用主机的时区。
json5
{
  agents: { defaults: { userTimezone: "America/Chicago" } }
}

### `messages`

控制入站/出站前缀和可选的确认反应。
有关队列、会话和流式上下文，请参阅 [Messages](/concepts/messages)。
json5
{
  messages: {
    responsePrefix: "🦞", // 或 "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false
  }
}

示例输出：`[claude-opus-4-5 | think:high] 这是我的回复...`

WhatsApp 入站消息前缀通过 `channels.whatsapp.messagePrefix` 配置（已弃用：`messages.messagePrefix`）。默认值保持 **不变**：当 `channels.whatsapp.allowFrom` 为空时为 `"[clawdbot]"`，否则为 `""`（无前缀）。当使用 `"[clawdbot]"` 时，Clawdbot 会改用 `[{identity.name}]`，如果路由的代理有设置 `identity.name`。

`ackReaction` 会在支持反应的渠道（如 Slack/Discord/Telegram/Google Chat）上发送一个尽力而为的 emoji 反应，以确认收到入站消息。当设置了活跃代理的 `identity.emoji` 时，默认使用该 emoji，否则默认为 `"👀"`。设置为 `""` 可以禁用该功能。

`ackReactionScope` 控制反应触发的时机：
- `group-mentions`（默认）：仅当群组/房间需要@提及 **且** 机器人被@时
- `group-all`：所有群组/房间消息
- `direct`：仅限私信
- `all`：所有消息

`removeAckAfterReply` 在发送回复后移除机器人的确认反应（仅限 Slack/Discord/Telegram/Google Chat）。默认值为 `false`。

#### `messages.tts`

启用出站回复的文本转语音功能。当开启时，Clawdbot 会使用 ElevenLabs 或 OpenAI 生成音频，并将其附加到回复中。Telegram 使用 Opus 语音消息；其他渠道发送 MP3 音频。
json5
{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all (包含工具/块回复)
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true
      },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.clawdbot/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0
        }
      },
      openai: {
        apiKey: "openai_api_key",
        model: "gpt-4o-mini-tts",
        voice: "alloy"
      }
    }
  }
}
```说明：
- `messages.tts.auto` 控制自动语音合成（TTS）（`off`、`always`、`inbound`、`tagged`）。
- `/tts off|always|inbound|tagged` 设置会话级别的自动模式（覆盖配置）。
- `messages.tts.enabled` 是旧版设置；系统会将其迁移至 `messages.tts.auto`。
- `prefsPath` 存储本地覆盖设置（provider/limit/summarize）。
- `maxTextLength` 是 TTS 输入的硬性限制；摘要内容会被截断以适应限制。
- `summaryModel` 用于自动摘要的模型覆盖；
  - 接受 `provider/model` 格式或 `agents.defaults.models` 中的别名。
- `modelOverrides` 启用基于模型的覆盖设置，如 `[[tts:...]]` 标签（默认开启）。
- `/tts limit` 和 `/tts summary` 控制用户的摘要设置。
- `apiKey` 值在未设置时会回退至 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- `elevenlabs.baseUrl` 可覆盖 ElevenLabs API 的基础 URL。
- `elevenlabs.voiceSettings` 支持 `stability`/`similarityBoost`/`style`（0..1）、`useSpeakerBoost` 和 `speed`（0.5..2.0）。

### `talk`

Talk 模式默认设置（适用于 macOS/iOS/Android）。当未设置时，语音 ID 会回退至 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
`apiKey` 在未设置时会回退至 `ELEVENLABS_API_KEY`（或网关的 shell 配置文件）。
`voiceAliases` 允许 Talk 指令使用友好名称（例如 `"voice":"Clawd"`）。
json5
{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17"
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    interruptOnSpeech: true
  }
}

"Z.AI GLM-4.x 模型会自动启用思考模式，除非你：
- 设置 `--thinking off`，或者
- 自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。

Clawdbot 还预装了一些内置的别名快捷方式。默认设置仅在模型已存在于 `agents.defaults.models` 中时生效：

- `opus` -> `anthropic/claude-opus-4-5`
- `sonnet` -> `anthropic/claude-sonnet-4-5`
- `gpt` -> `openai/gpt-5.2`
- `gpt-mini` -> `openai/gpt-5-mini`
- `gemini` -> `google/gemini-3-pro-preview`
- `gemini-flash` -> `google/gemini-3-flash-preview`

如果你自己配置了相同的别名名称（不区分大小写），你的设置将优先生效（默认设置不会被覆盖）。

示例：使用 Opus 4.5 作为主模型，MiniMax M2.1 作为备用模型（托管在 MiniMax）：
json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" }
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["minimax/MiniMax-M2.1"]
      }
    }
  }
}

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4.7": {
          alias: "GLM",
          params: {
            thinking: {
              type: "enabled",
              clear_thinking: false
            }
          }
        }
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free"
        ]
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: [
          "openrouter/google/gemini-2.0-flash-vision:free"
        ]
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        target: "last"
      },
      maxConcurrent: 3,
      subagents: {
        model: "minimax/MiniMax-M2.1",
        maxConcurrent: 1,
        archiveAfterMinutes: 60
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000
      },
      contextTokens: 200000
    }
  }
}#### `agents.defaults.contextPruning`（上下文裁剪）

`agents.defaults.contextPruning` 在将请求发送到 LLM 之前，从内存中的上下文里**裁剪旧的工具结果**。  
它**不会**修改磁盘上的会话历史记录（`*.jsonl` 文件保持完整）。

此功能旨在减少那些频繁交互的代理在长时间运行后积累大量工具输出所导致的 token 使用量。

高层次说明：
- 从不修改用户/助理的消息。
- 保留最后的 `keepLastAssistants` 条助理消息（该点之后的工具结果不会被裁剪）。
- 保留引导前缀（第一个用户消息之前的任何内容都不会被裁剪）。
- 模式：
  - `adaptive`（自适应）：当估计的上下文比例超过 `softTrimRatio` 时，**软裁剪**过长的工具结果（保留开头和结尾）。  
    然后，当估计的上下文比例超过 `hardClearRatio` **且**有足够的可裁剪工具结果（`minPrunableToolChars`）时，**硬清除**最旧的可裁剪工具结果。
  - `aggressive`（激进）：在截止点之前，总是用 `hardClear.placeholder` 替换可裁剪的工具结果（不进行比例检查）。

软裁剪 vs 硬清除（对发送给 LLM 的上下文的影响）：
- **软裁剪**：仅适用于**过长**的工具结果。保留开头 + 结尾，并在中间插入 `...`。
  - 之前：`toolResult("…非常长的输出…")`
  - 之后：`toolResult("HEAD…\n...\n…TAIL\n\n[工具结果被裁剪：…]")`
- **硬清除**：将整个工具结果替换为占位符。
  - 之前：`toolResult("…非常长的输出…")`
  - 之后：`toolResult("[旧工具结果内容已清除]")`

注意事项 / 当前限制：
- 包含**图像块**的工具结果**会被跳过**（目前不会被裁剪/清除）。
- 估计的“上下文比例”基于**字符数**（近似值），而不是精确的 token 数。
- 如果会话中尚未包含至少 `keepLastAssistants` 条助理消息，则跳过裁剪。
- 在 `aggressive` 模式下，`hardClear.enabled` 会被忽略（可裁剪的工具结果总是被替换为 `hardClear.placeholder`）。

默认模式（自适应）：
json5
{
  agents: { defaults: { contextPruning: { mode: "adaptive" } } }
}

当 `mode` 为 `"adaptive"` 或 `"aggressive"` 时的默认值：
- `keepLastAssistants`: `3`
- `softTrimRatio`: `0.3`（仅适用于 adaptive）
- `hardClearRatio`: `0.5`（仅适用于 adaptive）
- `minPrunableToolChars`: `50000`（仅适用于 adaptive）
- `softTrim`: `{ maxChars: 4000, headChars: 1500, tailChars: 1500 }`（仅适用于 adaptive）
- `hardClear`: `{ enabled: true, placeholder: "[已清除旧工具结果内容]" }`

示例（aggressive，最小化）：
json5
{
  agents: { defaults: { contextPruning: { mode: "aggressive" } } }
}

有关行为细节，请参见 [/concepts/session-pruning](/concepts/session-pruning)。

#### `agents.defaults.compaction`（保留空间 + 内存刷新）

`agents.defaults.compaction.mode` 选择压缩的摘要策略。默认为 `default`；设置为 `safeguard` 以启用针对非常长的历史记录的分块摘要。请参见 [/concepts/compaction](/concepts/compaction)。

`agents.defaults.compaction.reserveTokensFloor` 为 Pi 压缩设置一个最低的 `reserveTokens` 值（默认：`20000`）。将其设为 `0` 以禁用该下限。

`agents.defaults.compaction.memoryFlush` 在自动压缩之前运行一次 **静默** 的代理操作，指示模型将持久化记忆存储到磁盘（例如 `memory/YYYY-MM-DD.md`）。当会话的令牌估算值低于压缩限制的软阈值时会触发此操作。

旧版默认值：
- `memoryFlush.enabled`: `true`
- `memoryFlush.softThresholdTokens`: `4000`
- `memoryFlush.prompt` / `memoryFlush.systemPrompt`: 内置默认值，包含 `NO_REPLY`
- 注意：当会话工作区为只读时（`agents.defaults.sandbox.workspaceAccess: "ro"` 或 `"none"`），内存刷新会被跳过。

示例（调优后）：
json5
{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard",
        reserveTokensFloor: 24000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

配置子代理的默认设置：`agents.defaults.subagents`
- `model`: 生成的子代理的默认模型（字符串或 `{ primary, fallbacks }`）。如果未设置，子代理将继承调用者的模型，除非在特定代理或特定调用中被覆盖。
- `maxConcurrent`: 最大同时运行的子代理数量（默认值为 1）
- `archiveAfterMinutes`: 在 N 分钟后自动归档子代理会话（默认 60；设置 `0` 以禁用）
- 每个子代理的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`（拒绝策略优先）

`tools.profile` 在 `tools.allow`/`tools.deny` 之前设置一个**基础工具白名单**：
- `minimal`: 仅允许 `session_status`
- `coding`: `group:fs`, `group:runtime`, `group:sessions`, `group:memory`, `image`
- `messaging`: `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`
- `full`: 没有限制（与未设置相同）

特定代理的覆盖设置：`agents.list[].tools.profile`。

示例（默认仅允许消息功能，同时允许 Slack 和 Discord 工具）：
json5
{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"]
  }
}

`tools.byProvider` 允许你 **进一步限制** 特定提供者（或单个 `provider/model`）的工具。
按代理覆盖：`agents.list[].tools.byProvider`。

顺序：基础配置文件 → 提供者配置文件 → 允许/拒绝策略。
提供者键可以是 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.2`）。

示例（保留全局编码配置文件，但为 Google Antigravity 设置最少的工具）：
json5
{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" }
    }
  }
}

`tools.allow` / `tools.deny` 配置全局工具允许/拒绝策略（拒绝策略优先）。
匹配不区分大小写，并支持 `*` 通配符（`"*"` 表示所有工具）。
即使 Docker 沙箱处于 **关闭** 状态时也会生效。

示例（在所有地方禁用浏览器/画布）：
json5
{
  tools: { deny: ["browser", "canvas"] }
}

{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          elevated: { enabled: false }
        }
      }
    ]
  }
}```
说明：
- `tools.elevated` 是全局基线。`agents.list[].tools.elevated` 只能进一步限制（两者都必须允许）。
- `/elevated on|off|ask|full` 会按会话键存储状态；内联指令仅对单条消息生效。
- 提升权限的 `exec` 在主机上运行，并绕过沙箱机制。
- 工具策略仍然适用；如果 `exec` 被拒绝，则无法使用提升权限。

`agents.defaults.maxConcurrent` 设置了跨会话可以并行执行的嵌入式代理的最大数量。每个会话仍然序列化执行（每个会话键一次只运行一个代理）。默认值：1。

### `agents.defaults.sandbox`

可选的 **Docker 沙箱**，用于嵌入式代理。适用于非主会话，以防止其访问你的主机系统。

详情：[沙箱机制](/gateway/sandboxing)

默认值（如果启用）：
- scope: `"agent"`（每个代理一个容器 + 工作区）
- 基于 Debian bookworm-slim 的镜像
- 代理工作区访问：`workspaceAccess: "none"`（默认）
  - `"none"`：使用 `~/.clawdbot/sandboxes` 下的按作用域沙箱工作区
- `"ro"`：将沙箱工作区保留在 `/workspace`，并将代理工作区只读挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`）
  - `"rw"`：将代理工作区以读写方式挂载到 `/workspace`
- 自动清理：空闲超过 24 小时或年龄超过 7 天
- 工具策略：仅允许 `exec`、`process`、`read`、`write`、`edit`、`apply_patch`、`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`（拒绝优先）
  - 通过 `tools.sandbox.tools` 配置，可通过 `agents.list[].tools.sandbox.tools` 覆盖每个代理
  - 沙箱策略支持工具组简写：`group:runtime`、`group:fs`、`group:sessions`、`group:memory`（参见 [沙箱 vs 工具策略 vs 提升权限](/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)）
- 可选的沙箱浏览器（Chromium + CDP，noVNC 观察者）
- 加固选项：`network`、`user`、`pidsLimit`、`memory`、`cpus`、`ulimits`、`seccompProfile`、`apparmorProfile`

警告：`scope: "shared"` 表示共享容器和共享工作区。没有跨会话隔离。如需会话隔离，请使用 `scope: "session"`。

遗留支持：`perSession` 仍然有效（`true` → `scope: "session"`，`false` → `scope: "shared"`）。

`setupCommand` 在容器创建后 **仅运行一次**（通过 `sh -lc` 在容器内部运行）。
对于包安装，请确保网络出站、可写根文件系统和 root 用户权限。```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.clawdbot/sandboxes",
        docker: {
          image: "clawdbot-sandbox:bookworm-slim",
          containerPrefix: "clawdbot-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          // Per-agent override (multi-agent): agents.list[].sandbox.docker.*
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "clawdbot-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"]
        },
        browser: {
          enabled: false,
          image: "clawdbot-sandbox-browser:bookworm-slim",
          containerPrefix: "clawdbot-sbx-browser-",
          cdpPort: 9222,
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          allowedControlUrls: ["http://10.0.0.42:18791"],
          allowedControlHosts: ["browser.lab.local", "10.0.0.42"],
          allowedControlPorts: [18791],
          autoStart: true,
          autoStartTimeoutMs: 12000
        },
        prune: {
          idleHours: 24,  // 0 disables idle pruning
          maxAgeDays: 7   // 0 disables max-age pruning
        }
      }
    }
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["exec", "process", "read", "write", "edit", "apply_patch", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
  }
}

注意：沙盒容器默认使用 `network: "none"`；如果代理需要出站访问，请将 `agents.defaults.sandbox.docker.network` 设置为 `"bridge"`（或您的自定义网络）。

注意：入站附件会被暂存到活动工作区的 `media/inbound/*` 路径下。当使用 `workspaceAccess: "rw"` 时，这意味着文件会被写入代理的工作区。

注意：`docker.binds` 会挂载额外的主机目录；全局绑定和代理级别的绑定会合并。```bash
scripts/sandbox-browser-setup.sh
```
当 `agents.defaults.sandbox.browser.enabled=true` 时，浏览器工具将使用沙盒化的 Chromium 实例（CDP）。如果启用了 noVNC（当 headless=false 时默认启用），则会将 noVNC 的 URL 注入到系统提示中，以便代理可以引用它。这不需要在主配置中设置 `browser.enabled`；沙盒控制 URL 是按会话注入的。

`agents.defaults.sandbox.browser.allowHostControl`（默认值：false）允许沙盒会话通过浏览器工具（`target: "host"`）显式地指向 **主机** 的浏览器控制服务器。如果你希望严格的沙盒隔离，请保持此选项关闭。

远程控制的允许列表：
- `allowedControlUrls`：允许用于 `target: "custom"` 的确切控制 URL。
- `allowedControlHosts`：允许的主机名（仅主机名，不包含端口）。
- `allowedControlPorts`：允许的端口（默认：http=80，https=443）。
默认值：所有允许列表均未设置（无限制）。`allowHostControl` 默认为 false。

### `models`（自定义提供者 + 基础 URL）

Clawdbot 使用 **pi-coding-agent** 模型目录。你可以通过编写 `~/.clawdbot/agents/<agentId>/agent/models.json` 或在 Clawdbot 配置中定义相同结构的 `models.providers` 来添加自定义提供者（如 LiteLLM、本地 OpenAI 兼容服务器、Anthropic 代理等）。
提供者详解 + 示例：[/concepts/model-providers](/concepts/model-providers)。

当 `models.providers` 存在时，Clawdbot 在启动时会将 `models.json` 写入/合并到 `~/.clawdbot/agents/<agentId>/agent/` 目录中：
- 默认行为：**合并**（保留现有提供者，按名称覆盖）
- 设置 `models.mode: "replace"` 以覆盖文件内容

通过 `agents.defaults.model.primary`（提供者/模型）选择模型。
json5
{
  agents: {
    defaults: {
      model: { primary: "custom-proxy/llama-3.1-8b" },
      models: {
        "custom-proxy/llama-3.1-8b": {}
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions",
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000
          }
        ]
      }
    }
  }
}

注意事项：
- `z.ai/*` 和 `z-ai/*` 是被接受的别名，并会标准化为 `zai/*`。
- 如果缺少 `ZAI_API_KEY`，对 `zai/*` 的请求将在运行时因认证错误而失败。
- 示例错误：`No API key found for provider "zai".`
- Z.AI 的通用 API 端点是 `https://api.z.ai/api/paas/v4`。GLM 编码请求使用专用的编码端点 `https://api.z.ai/api/coding/paas/v4`。
  内置的 `zai` 提供者使用编码端点。如果你需要通用端点，请在 `models.providers` 中定义一个自定义提供者，并覆盖基础 URL（参见上方的自定义提供者部分）。
- 在 docs/configs 中使用假占位符；永远不要提交真实的 API 密钥。```json5
{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2-0905-preview" },
      models: { "moonshot/kimi-k2-0905-preview": { alias: "Kimi K2" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2-0905-preview",
            name: "Kimi K2 0905 Preview",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}
```
### 注意事项：
- 在环境变量中设置 `MOONSHOT_API_KEY` 或使用 `clawdbot onboard --auth-choice moonshot-api-key`。
- 模型引用：`moonshot/kimi-k2-0905-preview`。
- 如果需要中国区域的端点，请使用 `https://api.moonshot.cn/v1`。

### Kimi Code

使用 Kimi Code 的专用 OpenAI 兼容端点（与 Moonshot 分离）：
json5
{
  env: { KIMICODE_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi-code/kimi-for-coding" },
      models: { "kimi-code/kimi-for-coding": { alias: "Kimi Code" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      "kimi-code": {
        baseUrl: "https://api.kimi.com/coding/v1",
        apiKey: "${KIMICODE_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-for-coding",
            name: "Kimi For Coding",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 32768,
            headers: { "User-Agent": "KimiCLI/0.77" },
            compat: { supportsDeveloperRole: false }
          }
        ]
      }
    }
  }
}

注意事项：
- 设置 `SYNTHETIC_API_KEY` 或使用 `clawdbot onboard --auth-choice synthetic-api-key`。
- 模型引用：`synthetic/hf:MiniMaxAI/MiniMax-M2.1`。
- 基础 URL 应省略 `/v1`，因为 Anthropic 客户端会自动追加它。

### 本地模型（LM Studio）—— 推荐设置

有关当前本地模型的指导，请参阅 [/gateway/local-models](/gateway/local-models)。TL;DR：在高性能硬件上通过 LM Studio 的 Responses API 运行 MiniMax M2.1；保持托管模型合并以备回退。
json5
{
  agent: {
    model: { primary: "minimax/MiniMax-M2.1" },
    models: {
      "anthropic/claude-opus-4-5": { alias: "Opus" },
      "minimax/MiniMax-M2.1": { alias: "Minimax" }
    }
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.1",
            name: "MiniMax M2.1",
            reasoning: false,
            input: ["text"],
            // 定价：如需精确成本跟踪，请在 models.json 中更新。
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

注意事项：
- 使用 `cerebras/zai-glm-4.7` 用于 Cerebras；使用 `zai/glm-4.7` 用于 Z.AI 直接接口。
- 在环境变量或配置中设置 `CEREBRAS_API_KEY`。

注意事项：
- 支持的 API：`openai-completions`、`openai-responses`、`anthropic-messages`、
  `google-generative-ai`
- 如需自定义认证，请使用 `authHeader: true` + `headers`。
- 如果希望将 `models.json` 存储在其他位置，可以通过 `CLAWDBOT_AGENT_DIR`（或 `PI_CODING_AGENT_DIR`）
  覆盖代理配置根目录（默认：`~/.clawdbot/agents/main/agent`）。

### `session`

用于控制会话作用域、重置策略、重置触发条件以及会话存储的写入位置。
json5
{
  session: {
    scope: "per-sender",
    dmScope: "main",
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"]
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      dm: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 }
    },
    resetTriggers: ["/new", "/reset"],
    // 默认存储位置为 ~/.clawdbot/agents/<agentId>/sessions/sessions.json
    // 可以通过 {agentId} 模板进行覆盖：
    store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
    // 直接聊天会合并到 agent:<agentId>:<mainKey>（默认："main"）。
    mainKey: "main",
    agentToAgent: {
      // 请求者/目标之间最大回复轮次（0–5）。
      maxPingPongTurns: 5
    },
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } }
      ],
      default: "allow"
    }
  }
}

### `plugins`（扩展）

控制插件的发现、允许/拒绝以及每个插件的配置。插件将从 `~/.clawdbot/extensions`、`<workspace>/.clawdbot/extensions` 以及任何 `plugins.load.paths` 中的条目加载。**配置更改需要重启网关。**  
有关完整用法，请参见 [/plugin](/plugin)。

字段：
- `enabled`: 插件加载的主开关（默认值：true）。
- `allow`: 可选的插件 ID 允许列表；设置后，仅加载列出的插件。
- `deny`: 可选的插件 ID 拒绝列表（拒绝优先）。
- `load.paths`: 额外的插件文件或目录以加载（可以是绝对路径或 `~`）。
- `entries.<pluginId>`: 每个插件的覆盖配置。
  - `enabled`: 设置为 `false` 以禁用该插件。
  - `config`: 插件特定的配置对象（如果提供，将由插件进行验证）。

示例：
json5
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    load: {
      paths: ["~/Projects/oss/voice-call-extension"]
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio"
        }
      }
    }
  }
}

### `gateway`（网关服务器模式 + 绑定）

使用 `gateway.mode` 明确声明此机器是否应运行网关。

默认值：
- mode: **未设置**（视为“不自动启动”）
- bind: `loopback`
- port: `18789`（用于 WS 和 HTTP 的单一端口）```json5
{
  gateway: {
    mode: "local", // or "remote"
    port: 18789, // WS + HTTP multiplex
    bind: "loopback",
    // controlUi: { enabled: true, basePath: "/clawdbot" }
    // auth: { mode: "token", token: "your-token" } // token gates WS + Control UI access
    // tailscale: { mode: "off" | "serve" | "funnel" }
  }
}
```
Control UI 基础路径：
- `gateway.controlUi.basePath` 设置 Control UI 提供服务的 URL 前缀。
- 示例：`"/ui"`、`"/clawdbot"`、`"/apps/clawdbot"`。
- 默认值：根路径 (`/`)（保持不变）。
- `gateway.controlUi.allowInsecureAuth` 允许仅使用 token 的认证，并跳过设备身份 + 配对（即使在 HTTPS 上）。默认值：`false`。优先使用 HTTPS（Tailscale Serve）或 `127.0.0.1`。

相关文档：
- [Control UI](/web/control-ui)
- [Web 概览](/web)
- [Tailscale](/gateway/tailscale)
- [远程访问](/gateway/remote)

可信代理：
- `gateway.trustedProxies`：列出在 Gateway 前端终止 TLS 的反向代理 IP。
- 当连接来自这些 IP 之一时，Clawdbot 会使用 `x-forwarded-for`（或 `x-real-ip`）来确定客户端 IP，用于本地配对检查和 HTTP 认证/本地检查。
- 仅列出你完全控制的代理，并确保它们 **覆盖** 入站的 `x-forwarded-for`。

注意：
- `clawdbot gateway` 除非设置 `gateway.mode` 为 `local`（或传递覆盖标志），否则不会启动。
- `gateway.port` 控制用于 WebSocket + HTTP 的单一多路复用端口（Control UI、hooks、A2UI）。
- OpenAI Chat Completions 端点：**默认禁用**；通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
- 优先级：`--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > 默认值 `18789`。
- 非回环绑定（`lan`/`tailnet`/`auto`）需要认证。使用 `gateway.auth.token`（或 `CLAWDBOT_GATEWAY_TOKEN`）。
- 引导向导默认会生成一个网关 token（即使在回环上）。
- `gateway.remote.token` 仅用于远程 CLI 调用；它不会启用本地网关认证。`gateway.token` 会被忽略。

认证与 Tailscale：
- `gateway.auth.mode` 设置握手要求（`token` 或 `password`）。
- `gateway.auth.token` 存储用于 token 认证的共享 token（用于同一台机器上的 CLI）。
- 当设置 `gateway.auth.mode` 时，仅接受该方法（加上可选的 Tailscale 头信息）。
- `gateway.auth.password` 可以在此设置，或通过 `CLAWDBOT_GATEWAY_PASSWORD`（推荐）。
- `gateway.auth.allowTailscale` 允许 Tailscale Serve 身份头（`tailscale-user-login`）在请求通过回环（`x-forwarded-for`、`x-forwarded-proto` 和 `x-forwarded-host`）到达时满足认证。当为 `true` 时，Serve 请求不需要 token 或密码；设置为 `false` 时需要显式凭证。当 `tailscale.mode = "serve"` 且认证模式不是 `password` 时，默认为 `true`。
- `gateway.tailscale.mode: "serve"` 使用 Tailscale Serve（仅限 tailnet，绑定到回环）。
- `gateway.tailscale.mode: "funnel"` 将仪表板公开暴露；需要认证。
- `gateway.tailscale.resetOnExit` 在关闭时重置 Serve/Funnel 配置。

远程客户端默认设置（CLI）：
- `gateway.remote.url` 用于在 `gateway.mode = "remote"` 时设置 CLI 调用的默认网关 WebSocket 地址。
- `gateway.remote.transport` 选择 macOS 的远程传输方式（`ssh` 为默认，`direct` 用于 ws/wss）。当使用 `direct` 时，`gateway.remote.url` 必须是 `ws://` 或 `wss://`。`ws://host` 默认使用端口 `18789`。
- `gateway.remote.token` 为远程调用提供令牌（不进行认证时可留空）。
- `gateway.remote.password` 为远程调用提供密码（不进行认证时可留空）。

macOS 应用程序行为：
- Clawdbot.app 会监视 `~/.clawdbot/clawdbot.json`，并在 `gateway.mode` 或 `gateway.remote.url` 发生变化时实时切换模式。
- 如果 `gateway.mode` 未设置但 `gateway.remote.url` 已设置，则 macOS 应用程序会将其视为远程模式。
- 当你在 macOS 应用程序中更改连接模式时，它会将 `gateway.mode`（在远程模式下还会写入 `gateway.remote.url` 和 `gateway.remote.transport`）写回配置文件。
json5
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password"
    }
  }
}

### `gateway.reload`（配置热加载）

网关会监视 `~/.clawdbot/clawdbot.json`（或 `CLAWDBOT_CONFIG_PATH`）并自动应用更改。

模式：
- `hybrid`（默认）：热加载安全的更改；对于关键更改需要重启网关。
- `hot`：仅应用热加载安全的更改；当需要重启时进行日志记录。
- `restart`：在任何配置更改时重启网关。
- `off`：禁用热加载。
json5
{
  gateway: {
    reload: {
      mode: "hybrid",
      debounceMs: 300
    }
  }
}

### `hooks` (网关的 Webhook)

在网关的 HTTP 服务器上启用一个简单的 HTTP Webhook 端点。

默认值：
- enabled: `false`
- path: `/hooks`
- maxBodyBytes: `262144` (256 KB)
json5
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    presets: ["gmail"],
    transformsDir: "~/.clawdbot/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:",
        messageTemplate:
          "From: \nSubject: \n",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.2-mini",
      },
    ],
  }
}

  // Optional: use a cheaper model for Gmail hook processing
  // Falls back to agents.defaults.model.fallbacks, then primary, on auth/rate-limit/timeout
  model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
  // Optional: default thinking level for Gmail hooks
  thinking: "off",
}   } } ``` Gmail 钩子的模型配置： - `hooks.gmail.model` 指定用于 Gmail 钩子处理的模型（默认使用会话主模型）。 - 接受来自 `agents.defaults.models` 的 `provider/model` 引用或别名。 - 在认证/速率限制/超时情况下，回退到 `agents.defaults.model.fallbacks`，然后是 `agents.defaults.model.primary`。 - 如果设置了 `agents.defaults.models`，则需要将钩子模型包含在允许列表中。 - 启动时，如果配置的模型不在模型目录或允许列表中，会发出警告。 - `hooks.gmail.thinking` 设置 Gmail 钩子的默认思考级别，并可通过每个钩子的 `thinking` 设置进行覆盖。

### `discovery.wideArea`（广域Bonjour / 单播DNS-SD）

当启用时，网关会在 `~/.clawdbot/dns/` 目录下为 `_clawdbot-bridge._tcp` 写入一个单播DNS-SD区域，使用标准的发现域 `clawdbot.internal.`。

为了让iOS/Android设备在不同网络之间进行发现（例如：维也纳 ⇄ 伦敦），请配合使用以下工具：
- 网关主机上的DNS服务器，用于解析 `clawdbot.internal.`（推荐使用CoreDNS）
- Tailscale 的 **split DNS** 功能，使客户端通过该DNS服务器解析 `clawdbot.internal`

一次性设置助手（网关主机）：
bash
clawdbot dns setup --apply

## 模板变量

模板占位符会在 `tools.media.*.models[].args` 和 `tools.media.models[].args`（以及任何未来的模板参数字段）中展开。

| 变量 | 描述 |
|------|------|
| `` | 完整的入站消息内容 |
| `` | 原始的入站消息内容（无历史/发送者包装；最适合命令解析） |
| `` | 去除群组提及后的消息内容（最适合代理的默认值） |
| `` | 发送者标识符（WhatsApp 中为 E.164 格式；不同渠道可能不同） |
| `` | 目标标识符 |
| `` | 渠道消息 ID（当可用时） |
| `` | 当前会话 UUID |
| `` | 当创建了一个新会话时为 `"true"` |
| `` | 入站媒体伪 URL（如果存在） |
| `` | 本地媒体路径（如果已下载） |
| `` | 媒体类型（image/audio/document/…） |
| `` | 音频转录文本（当启用时） |
| `` | CLI 条目的解析后媒体提示 |
| `` | CLI 条目的最大输出字符数 |
| `` | `"direct"` 或 `"group"` |
| `` | 群组主题（尽力而为） |
| `` | 群组成员预览（尽力而为） |
| `` | 发送者显示名称（尽力而为） |
| `` | 发送者电话号码（尽力而为） |
| `` | 提供商提示（whatsapp|telegram|discord|googlechat|slack|signal|imessage|msteams|webchat|…） |

## 定时任务（网关调度器）

定时任务是网关自带的调度器，用于唤醒和定时任务。请参阅 [定时任务](/automation/cron-jobs) 了解该功能的概览和 CLI 示例。
json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2
  }
}