访问控制

`channels.telegram.dmPolicy` 控制直接消息（DM）的访问权限：

- `pairing`（默认）
- `allowlist`（要求 `allowFrom` 中至少有一个发送者 ID）
- `open`（要求 `allowFrom` 包含 `"*"`）
- `disabled`

`dmPolicy: "open"` 与 `allowFrom: ["*"]` 会让任何找到或猜出机器人用户名的 Telegram 账户都能对该机器人下达命令。仅用于故意公开且工具受到严格限制的机器人。单所有者机器人应使用带数字用户 ID 的 `allowlist`。

`channels.telegram.allowFrom` 接受数字格式的 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 是一道安全边界。账户级的 `allowFrom: ["*"]` 不会使该账户公开，除非合并后的有效允许列表仍然包含显式的通配符。
`dmPolicy: "allowlist"` 与空的 `allowFrom` 会阻止所有 DM，并被配置校验拒绝。
设置流程只要求数字用户 ID。较旧的设置可能包含 `@username` 形式的允许列表条目。运行 `openclaw doctor --fix` 可将其解析为数字 ID。该解析是尽力而为的，并且需要 Telegram 机器人令牌。
如果你之前依赖 pair-store 的允许列表文件，`openclaw doctor --fix` 可以将条目恢复到 `channels.telegram.allowFrom` 中，用于允许列表流程。其中一种情况是还没有显式 ID 的 `dmPolicy: "allowlist"`。

对于单所有者机器人，应优先使用带显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，而不是依赖之前的配对批准。

常见混淆：DM 配对批准并不意味着“该发送者在任何地方都获得授权”。配对仅授予 DM 访问权限。如果还不存在命令所有者，则第一个获批的配对还会设置 `commands.ownerAllowFrom`。这会为仅所有者命令和 exec 审批提供一个明确的操作者账户。群组发送者授权仍来自显式配置的允许列表。
要使用同一身份同时获得 DM 和群组命令的授权，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`。对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<你的用户 ID>`。

使用 `channels.telegram.direct.<chatId>.tools` 为某个 DM 设置内置工具策略。`toolsBySender` 通过类型化的发送者键（如 `channel:telegram:<userId>` 或 `id:<userId>`）选择特定于发送者的策略：

{
  channels: {
    telegram: {
      direct: {
        "*": { tools: { deny: ["write", "edit"] } },
        "603767951": { tools: {} },
      },
    },
  },
}

匹配的 `toolsBySender` 条目会替换该 DM 的 `tools`。精确的聊天条目会替换整个 `"*"` 条目；它不会继承通配符字段。账户级的 `direct` 在存在时会替换根级 `direct` 映射，仅在省略时才继承根级映射。所选直接策略、全局策略、每个代理策略、`tools.toolsBySender` 和 `agents.<id>.tools.toolsBySender` 作为交叉层应用；任何一层中的 deny 仍会阻止该工具。对于明确受限的轮次，Codex 使用经策略过滤的 OpenClaw 工具，并在默认 profile 收窄时保留其原生工具表面。ACP 绑定的会话在其运行时无法强制执行限制性直接策略时，会拒绝该限制性直接策略。

### 查找你的 Telegram 用户 ID {#finding-your-telegram-user-id}

更安全的方式（无需第三方机器人）：在 DM 策略为 `pairing` 时，向你的机器人发送 DM，并在其配对回复中读取 `Your Telegram user id`。你也可以运行 `openclaw logs --follow`，在 `telegram pairing request` 条目中读取 `senderUserId`。两者都来自传入消息的 `from.id`。

对 `allowFrom` 使用你的数字用户 ID，而不是电话号码、用户名、聊天/群组 ID 或机器人 ID。一旦获得 ID，立即停止跟踪，并保持无关日志内容的私密性。如果当前策略不允许此流程，请使用已验证的 ID；不要为了发现它而扩大访问权限。

官方 Bot API 方法：

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

第三方方式（隐私性较低）：`@userinfobot` 或 `@getidsbot`。

两个控制项会同时生效：

1. **允许哪些群组**（`channels.telegram.groups`）
   - 没有 `groups` 配置且 `groupPolicy: "open"`：任何群组都能通过群组 ID 检查
   - 没有 `groups` 配置且 `groupPolicy: "allowlist"`（默认）：所有群组都被阻止，直到你添加 `groups` 条目（或 `"*"`）
   - 已配置 `groups`：充当允许列表（显式 ID 或 `"*"`）

2. **在群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
   - `open` / `allowlist`（默认）/ `disabled`

`groupAllowFrom` 过滤群组发送者。如果未设置，Telegram 会回退到 `allowFrom`，而不是配对存储。群组发送者授权绝不会继承 DM 配对存储中的批准，这是自 `2026.2.25` 以来的安全边界。
`groupAllowFrom` 条目应为数字 Telegram 用户 ID，`telegram:` / `tg:` 前缀会被规范化。非数字条目会被忽略。不要将群组或超级群组聊天 ID 放在这里——负数聊天 ID 应放在 `channels.telegram.groups` 下。
在多账户配置中，根级 `channels.telegram.groups` 是未设置 `groups` 的账户共享的默认值。账户级的 `groups` 映射会替换该账户的根级映射，而不是深度合并。显式空的账户映射（`groups: {}`）会使该账户与共享群组保持隔离。
单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 不设置，并在 `channels.telegram.groups` 下允许目标群组。
如果配置中完全没有 `channels.telegram`，运行时默认采用失败关闭（fail-closed）的 `groupPolicy="allowlist"`，除非明确设置了 `channels.defaults.groupPolicy`。

群组回复默认需要提及。提及可以来自：

- 原生 `@botusername` 提及，或
- `agents.entries.*.groupChat.mentionPatterns` 或 `messages.groupChat.mentionPatterns` 中的提及模式

会话级开关（仅状态，不持久化）：`/activation always`、`/activation mention`。如需持久化，请使用配置：

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

若要在群组中仍要求提及，但允许在本机器人创建的论坛主题中发送普通消息，请设置 `requireMentionInBotThreads: false`：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          requireMentionInBotThreads: false,
        },
      },
    },
  },
}

此选项仅在 OpenClaw 知道接收消息的机器人创建了该论坛主题时生效。主题的 `requireMentionInBotThreads` 会覆盖所选群组的设置。将其设置为 `true` 可要求在这些主题中必须提及，即使普通 `requireMention` 为 `false`，或消息正在回复机器人。原生和已授权的控制命令保持现有行为。省略该选项可保留现有提及策略。

为了让 `false` 生效，Telegram 必须能够投递普通群消息：请禁用隐私模式或将机器人设为群组管理员。参见 [隐私模式和群组可见性](setup.md#privacy-mode-and-group-visibility)。群组和发送者授权、群组静默策略以及可见回复策略仍然适用。有关所有权跟踪及其限制，参见 [机器人创建的论坛主题](threads-and-sessions.md#bot-created-forum-topics)。

群组历史上下文受 `historyLimit` 限制（默认 50）。设置 `channels.telegram.historyLimit: 0` 可禁用自动窗口，而不会删除保留的群消息或禁用显式历史读取。当要求提及时，被允许的未提及消息会被记录，但不会启动代理轮次。参见 [保留的群组历史](messaging.md#retained-group-history)。`openclaw doctor --fix` 会移除已弃用的 `includeGroupHistoryContext` 键。

获取群组聊天 ID：将一条群消息转发给 `@userinfobot` / `@getidsbot`，从 `openclaw logs --follow` 中读取 `chat.id`，检查 Bot API 的 `getUpdates`，或者（在群组被允许后）运行 `/whoami@<bot_username>`。