clawgram 2.20.0 → 2.21.0

package/README.md

@@ -94,7 +94,7 @@ Follow the steps in the console
 ```bash
 Starting Clawgram authorization...
 Please enter your apiId: 12345678
-Please enter your apiHash: c4b9c0fde16342afe52907847df27596
+Please enter your apiHash: EXAMPLE0123456789abcdef01234567
 [2026-05-10T16:01:24.570] [INFO] - [Running gramJS version 2.26.21]
 [2026-05-10T16:01:24.578] [INFO] - [Connecting to x.x.x.x:80/TCPFull...]
 [2026-05-10T16:01:25.804] [INFO] - [Connection to x.x.x.x:80/TCPFull complete!]
@@ -191,6 +191,23 @@ config watcher and restart only this channel (a few seconds of MTProto
 reconnect), not the whole Gateway.
 
 
+## Upgrading to 2.21.0
+
+One config key changed meaning: **`allowFrom: []` now denies everyone.** It used
+to resolve to the wildcard, so emptying the list to shut an account off opened it
+to every Telegram user instead — the opposite of the request, and the opposite of
+`readChats: []` and `manageChats: []`, which have always been documented as deny.
+
+An absent key still means everyone, so an install that never set `allowFrom` is
+unaffected; only an explicitly empty list changes. If you relied on `[]` to admit
+everyone, write `["*"]`. The account logs `clawgram allowFrom is empty: no direct
+message will be accepted` at start, so the new state is never silent.
+
+This is a behaviour change to a config key and by the usual rule it would cost a
+major bump. It ships as a minor deliberately: the plugin currently has one
+operator, the value is almost certainly nowhere, and the warning makes the case
+loud where it does occur.
+
 ## Configuration Reference
 
 ### JSON Reference
@@ -231,7 +248,7 @@ reconnect), not the whole Gateway.
 | `apiId` | number | required | Telegram API ID |
 | `apiHash` | string | required | Telegram API hash |
 | `sessionString` | string | `""` | Authenticated StringSession |
-| `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames for direct messages only |
+| `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames for direct messages only. Three states: absent means everyone, `[]` denies everyone (a warning is logged at account start), a list allows those senders |
 | `groups` | object | `{}` | Allowed groups map keyed by explicit group id or `*` |
 | `proxy` | object | unset | Optional SOCKS4/SOCKS5 proxy for this account — see [Proxy (SOCKS4/SOCKS5)](#proxy-socks4socks5) |
 | `manageChats` | string[] | unset | Chats the assistant may **manage** — see [Chat management](#chat-management). Absent or empty = management off; `["*"]` = every chat |
@@ -245,7 +262,7 @@ Group config fields:
 |---|---|---|---|
 | `enabled` | boolean | `true` | Enables or disables replies in the group |
 | `groupPolicy` | `"open"` \| `"mention"` \| `"tag"` | `"mention"` | What wakes the agent here — see [What wakes the agent in a group](#what-wakes-the-agent-in-a-group) |
-| `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames inside that group |
+| `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames inside that group. `[]` denies everyone, same as the account-level key |
 | `tools` | object | unset | `{ allow?, alsoAllow?, deny? }` — tool policy for this group; see [Per-group tools, skills and system prompt](#per-group-tools-skills-and-system-prompt) |
 | `toolsBySender` | object | unset | Per-sender tool policy inside this group, keys `id:<id>`, `username:<handle>`, `name:<display>` or `*` |
 | `skills` | string[] | unset | Skill allowlist for this group; `[]` = no skills here, unset = the agent's skills |
@@ -807,7 +824,7 @@ that means in practice, and what the code does about it:
 | `apiHash`, `sessionString` | `openclaw.json`, or a secret store | Written there by `--auth`. Never logged. Since 2.1.0 the session string is not printed after login either — only shown, behind an explicit warning, if you decline the automatic config write. Since 2.2.0 both accept a **SecretRef** instead of a literal, so the credential need not sit in the config file at all |
 | Proxy password | `accounts.*.proxy.password`, or a secret store | Also accepts a SecretRef since 2.2.0. Marked `sensitive` in `uiHints`; diagnostics say `socks4`/`socks5` and nothing more. An invalid proxy fails the account rather than falling back to a direct connection, which would leak the host IP to Telegram |
 | Message bodies | channel logs | **Not logged.** Outbound sends record recipient, ids and `textLength`. Until 2.1.0 the full outbound text was written to the channel log — if you ran 2.0.x, treat those journal entries as containing private correspondence |
-| Read scope | `accounts.*.readChats` | History, membership and attachment fetches are confined to the listed chats. Absent means no restriction; an empty array denies everything |
+| Read scope | `accounts.*.readChats` | History, membership and attachment fetches are confined to the listed chats. Absent means no restriction; an empty array denies everything. Telegram's own service chat (`777000`, where login codes arrive) is refused unconditionally, including under a wildcard |
 | Manage scope | `accounts.*.manageChats` | Creating groups, changing membership, admin rights, ownership and invite links are confined to the listed chats — and **off entirely** when the key is absent or empty (opposite default to `readChats`, because these actions change chats rather than read them) |
 | 2FA password | `accounts.*.twoFaPassword`, or a secret store | Read only by `transferOwnership`, exchanged for an SRP proof in-process. Accepts a SecretRef since 2.12.0; `sensitive` in `uiHints`; on the forbidden-log-keys list the static tests enforce |
 | Who may talk to it | `allowFrom`, `groups.*.groupPolicy` | Direct-message senders and group behaviour are allowlisted; `mention` limits group replies to explicit mentions |

package/dist/channel.js

@@ -63,6 +63,7 @@ const inbound_envelope_1 = require("openclaw/plugin-sdk/inbound-envelope");
 const inbound_reply_dispatch_1 = require("openclaw/plugin-sdk/inbound-reply-dispatch");
 const channel_pairing_1 = require("openclaw/plugin-sdk/channel-pairing");
 const events_1 = require("telegram/events");
+const constants_1 = require("./constants");
 const gramjs_client_1 = require("./gramjs-client");
 const normalize_1 = require("./normalize");
 const history_1 = require("./history");
@@ -81,7 +82,7 @@ const group_reply_address_1 = require("./group-reply-address");
 const group_visible_reply_guard_1 = require("./group-visible-reply-guard");
 const helpers_1 = require("./helpers");
 const proxy_config_1 = require("./proxy-config");
-const constants_1 = require("./constants");
+const constants_2 = require("./constants");
 const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
 /** Reads the configured reaction level for an account, tolerating a missing config. */
 function readAccountReactionLevel(cfg, accountId) {
@@ -89,7 +90,7 @@ function readAccountReactionLevel(cfg, accountId) {
     if (!resolvedAccountId) {
         return undefined;
     }
-    return cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionLevel;
+    return cfg?.channels?.[constants_2.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionLevel;
 }
 /**
  * Model ref for the emoji pick, when the account names one.
@@ -104,7 +105,7 @@ function readAccountReactionModel(cfg, accountId) {
     if (!resolvedAccountId) {
         return undefined;
     }
-    const raw = cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionModel;
+    const raw = cfg?.channels?.[constants_2.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionModel;
     return typeof raw === "string" && raw.trim() ? raw.trim() : undefined;
 }
 /**
@@ -192,8 +193,10 @@ function readAccountManageChats(account) {
  * from the same caller, on the same chat.
  *
  * Every name on the right maps to core target mode `"none"` except
- * `channel-info`, which is `"to"` and therefore arrives with the chat in
- * `params.to` — a spelling all of these parsers already accept.
+ * `channel-info`, which is `"channelId"`: the chat arrives in
+ * `params.channelId`, a spelling no parser here read until 2.21.0 — so the
+ * call fell through to the current chat and answered about the wrong one.
+ * `readChatTargetParam` is the single list of accepted spellings now.
  */
 exports.CORE_ACTION_SYNONYMS = {
     "thread-list": "topics",
@@ -480,8 +483,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     apiId: Number(account?.apiId),
                     apiHash: (0, secret_refs_1.readSecretInput)(account?.apiHash),
                     sessionString: (0, secret_refs_1.readSecretInput)(account?.sessionString),
-                    allowFrom: (0, helpers_1.resolveAllowFrom)(account?.allowFrom),
-                    groups: (0, helpers_1.resolveGroups)(account?.groups),
+                    ...(0, helpers_1.resolveAccountScopes)(cfg, accountId),
                     readChats: readAccountReadChats(account),
                     enabled: account?.enabled,
                     accountId,
@@ -505,6 +507,16 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 if (!channelRuntime) {
                     throw new Error("clawgram: channelRuntime is required");
                 }
+                // An empty allowlist denies everyone (2.21.0). That is the right
+                // default for a scope, but "the agent answers nobody" is indis-
+                // tinguishable from "the channel is broken" in a log, so say it out
+                // loud once per account start.
+                if (account.allowFrom.length === 0) {
+                    log?.warn?.("clawgram allowFrom is empty: no direct message will be accepted", {
+                        accountId,
+                        hint: 'set allowFrom to ["*"] to accept everyone, or list the senders',
+                    });
+                }
                 if (runtimes.has(accountId)) {
                     log?.warn?.("clawgram stale runtime detected, reconnecting", { accountId });
                     await runtimes.get(accountId)?.stop().catch(() => undefined);
@@ -640,13 +652,41 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             return;
                         }
                         let text = normalized.text?.trim();
+                        // Whether this sender may reach the agent at all — decided before
+                        // the attachment is fetched.
+                        //
+                        // Reading an attachment downloads up to 25 MB and then spends a
+                        // transcription or vision call on it. That used to happen for
+                        // every photo and voice note from anyone in any group the account
+                        // sits in, and only afterwards was the sender checked against
+                        // `allowFrom`. A stranger could therefore spend the owner's model
+                        // budget at will. None of these checks depend on the message text,
+                        // so they cost nothing to run first.
+                        const inboundSenderId = normalized.senderId ?? normalized.chatId;
+                        const inboundScopes = (0, helpers_1.resolveAccountScopes)(cfg, accountId);
+                        const inboundGroupConfig = normalized.chatType === "group"
+                            ? (0, helpers_1.resolveGroupConfig)(inboundScopes.groups, normalized.chatId)
+                            : undefined;
+                        const senderMayReachAgent = normalized.chatType === "group"
+                            ? Boolean(inboundGroupConfig
+                                && inboundGroupConfig.enabled !== false
+                                && (0, helpers_1.isSenderAllowed)({
+                                    allowFrom: inboundGroupConfig.allowFrom,
+                                    senderId: inboundSenderId,
+                                    senderUsername: normalized.senderUsername,
+                                }))
+                            : (0, helpers_1.isSenderAllowed)({
+                                allowFrom: inboundScopes.allowFrom,
+                                senderId: inboundSenderId,
+                                senderUsername: normalized.senderUsername,
+                            });
                         // An attachment carries no text of its own, and dropping it as
                         // "empty" is how the assistant used to go silent on being spoken
                         // to or shown something. Read it into the body instead: for a
                         // voice note and a screenshot alike, the attachment *is* the
                         // message. A caption is kept and the reading appended, because
                         // "look at this" plus the picture is one thought, not two.
-                        const attachment = await readInboundAttachment({
+                        const attachment = senderMayReachAgent ? await readInboundAttachment({
                             gram,
                             event,
                             cfg,
@@ -655,12 +695,25 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             accountId,
                             chatId: normalized.chatId,
                             messageId: normalized.messageId,
-                        });
+                        }) : undefined;
                         if (attachment) {
                             const marker = attachment.understanding === "transcript" ? "голосовое" : "изображение";
                             const read = `[${marker}] ${attachment.text}`;
                             text = text ? `${text}\n\n${read}` : read;
                         }
+                        // What the mention gate is allowed to read.
+                        //
+                        // A transcript is the sender's own speech, so "Тина, посмотри"
+                        // said aloud addresses the agent exactly as typing it would. A
+                        // description is not: it is a vision model reading somebody
+                        // else's content, and a screenshot of a chat where a third party
+                        // wrote "@tina_bot" is not an address to her. Feeding the whole
+                        // body to the gate made every such screenshot wake her up.
+                        const addressableText = (0, helpers_1.resolveAddressableText)({
+                            messageText: normalized.text,
+                            bodyText: text,
+                            understanding: attachment?.understanding,
+                        });
                         if (!text) {
                             log?.info?.("clawgram skipping empty inbound text", {
                                 accountId,
@@ -671,7 +724,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         }
                         const senderId = normalized.senderId ?? normalized.chatId;
                         const isTelegramServiceDirect = normalized.chatType === "direct" &&
-                            (normalized.chatId === "777000" || senderId === "777000");
+                            (normalized.chatId === constants_1.TELEGRAM_SERVICE_CHAT_ID || senderId === constants_1.TELEGRAM_SERVICE_CHAT_ID);
                         const isSavedMessagesDirect = normalized.chatType === "direct" &&
                             Boolean(selfId) &&
                             normalized.chatId === selfId &&
@@ -734,14 +787,13 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             }
                             throw lastError;
                         };
-                        const accountConfig = cfg?.channels?.["clawgram"]?.accounts?.[accountId] ??
-                            cfg?.channels?.["clawgram"] ??
-                            {};
-                        const directAllowFrom = (0, helpers_1.resolveAllowFrom)(accountConfig?.allowFrom ?? account?.allowFrom);
-                        const groups = (0, helpers_1.resolveGroups)(accountConfig?.groups ?? account?.groups);
+                        // Resolved once, above, before the attachment fetch that depends on
+                        // the answer — and by the same resolver `resolveAccount` uses, so the
+                        // gate applied here is the one the account was started with.
+                        const { allowFrom: directAllowFrom } = inboundScopes;
                         const dmPolicy = "open";
                         if (normalized.chatType === "group") {
-                            const groupConfig = (0, helpers_1.resolveGroupConfig)(groups, normalized.chatId);
+                            const groupConfig = inboundGroupConfig;
                             if (!groupConfig) {
                                 log?.info?.("clawgram skipping group not present in groups config", {
                                     accountId,
@@ -793,20 +845,24 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             // almost never. Only the `@` counts, and it is the same fact the
                             // stricter rung of the ladder is named after.
                             const wasMentioned = groupConfig.groupPolicy === "tag"
-                                ? (0, helpers_1.hasExplicitTelegramMention)({ selfUsername, text, message: rawMessage })
+                                ? (0, helpers_1.hasExplicitTelegramMention)({ selfUsername, text: addressableText, message: rawMessage })
                                 : (0, helpers_1.hasTelegramMention)({
                                     cfg,
                                     agentId: route.agentId,
                                     selfUsername,
-                                    text,
+                                    text: addressableText,
                                     message: rawMessage,
                                 });
-                            const wasReplyToSelf = await (0, helpers_1.isReplyToSelfMessage)(rawMessage, selfId);
+                            // One fetch serves two needs: the reply-to-self gate below and
+                            // the parent's text for the agent (ReplyToBody), which a plain
+                            // reply does not carry on its own.
+                            const replyParent = await (0, helpers_1.resolveReplyParent)(rawMessage, { selfId, selfLabel });
+                            const wasReplyToSelf = replyParent.isSelf;
                             const mentionDecision = (0, channel_inbound_1.resolveInboundMentionDecision)({
                                 facts: {
                                     canDetectMention: true,
                                     wasMentioned,
-                                    hasAnyMention: /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(text),
+                                    hasAnyMention: /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(addressableText),
                                 },
                                 policy: {
                                     isGroup: true,
@@ -827,7 +883,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 wasMentioned,
                                 wasReplyToSelf,
                                 shouldSkip: mentionDecision.shouldSkip,
-                                text,
+                                textLength: text.length,
                             });
                             if (groupConfig.groupPolicy !== "open" && mentionDecision.shouldSkip && !wasReplyToSelf) {
                                 log?.info?.("clawgram skipping group message without mention", {
@@ -875,6 +931,10 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 // bare text, and the fragment the person pointed at is lost.
                                 ReplyToQuoteText: normalized.replyQuoteText,
                                 ReplyToIsQuote: normalized.replyIsQuote,
+                                // A plain reply has no highlight; core then falls back to the
+                                // parent's body, which only exists if the channel fetched it.
+                                ReplyToBody: replyParent.body,
+                                ReplyToSender: replyParent.sender,
                                 MessageThreadId: normalized.messageThreadId,
                                 NativeChannelId: normalized.chatId,
                                 // Trusted per-group prompt block from `groups.<id>.systemPrompt`.
@@ -911,7 +971,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                     ctx: ctxPayload,
                                     updateLastRoute: {
                                         sessionKey: route.sessionKey,
-                                        channel: constants_1.CHANNEL_ID,
+                                        channel: constants_2.CHANNEL_ID,
                                         to: conversationRouteTarget,
                                         accountId: route.accountId ?? accountId,
                                     },
@@ -954,7 +1014,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                                 accountId,
                                                 chatId: normalized.chatId,
                                                 messageId: normalized.messageId,
-                                                payloadText: outboundText,
+                                                payloadTextLength: outboundText.length,
                                                 payloadReplyToId: payload.replyToId ?? null,
                                             });
                                             if (!outboundText) {
@@ -1080,7 +1140,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                             chatId: normalized.chatId,
                                             messageId: normalized.messageId,
                                             routeSessionKey: route.sessionKey,
-                                            fallbackText: visibleFallbackText,
+                                            fallbackTextLength: visibleFallbackText.length,
                                         });
                                         await sendTextToConversation({
                                             text: (0, helpers_1.prefixReplyTextToAddress)(visibleFallbackText, groupReplyAddress),
@@ -1179,6 +1239,10 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             });
                             return;
                         }
+                        // Same fetch as the group path. In a DM the parent is as often
+                        // the agent's own message as the person's — the owner answers a
+                        // notice she sent — and neither text is available any other way.
+                        const replyParent = await (0, helpers_1.resolveReplyParent)(rawMessage, { selfId, selfLabel });
                         await gram.withTyping(conversationTarget, async () => {
                             await (0, direct_dm_1.dispatchInboundDirectDmWithRuntime)({
                                 cfg,
@@ -1210,6 +1274,8 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                     // direct messages too, and the fragment is not part of the text.
                                     ReplyToQuoteText: normalized.replyQuoteText,
                                     ReplyToIsQuote: normalized.replyIsQuote,
+                                    ReplyToBody: replyParent.body,
+                                    ReplyToSender: replyParent.sender,
                                     NativeChannelId: normalized.chatId,
                                 },
                                 deliver: async (payload) => {
@@ -1324,7 +1390,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
             },
         },
         messaging: {
-            targetPrefixes: [constants_1.CHANNEL_ID, "tguserbot", "telegram", "tg"],
+            targetPrefixes: [constants_2.CHANNEL_ID, "tguserbot", "telegram", "tg"],
             normalizeTarget(raw) {
                 const normalized = (0, helpers_1.normalizeOutboundTarget)(raw);
                 return normalized || undefined;
@@ -1396,7 +1462,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 return (0, core_1.buildChannelOutboundSessionRoute)({
                     cfg: params.cfg,
                     agentId: params.agentId,
-                    channel: constants_1.CHANNEL_ID,
+                    channel: constants_2.CHANNEL_ID,
                     accountId,
                     peer: {
                         kind: (0, helpers_1.routeKindFromChatType)(chatType),
@@ -1492,7 +1558,13 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "download-file": { aliases: ["chatId"] },
             },
             extractToolSend: ({ args }) => (0, tool_send_1.extractToolSend)(args, "sendMessage"),
-            handleAction: async ({ action, params, cfg, accountId, dryRun: dryRunFlag, toolContext }) => {
+            handleAction: async ({ action, params, cfg, accountId, dryRun: dryRunFlag, toolContext, 
+            // Core scopes every action to the media roots the agent may read, and
+            // bundled channels enforce them. This one used to take `filePath`
+            // verbatim, so a path naming the secret store or the config holding
+            // `sessionString` was uploaded like any attachment.
+            mediaLocalRoots, mediaAccess, }) => {
+                const allowedMediaRoots = mediaLocalRoots ?? mediaAccess?.localRoots;
                 // Core passes the flag beside `params`; callers write it inside.
                 // Both count, because a rehearsal flag that is silently ignored puts
                 // a real message in a real chat — twice, so far (2.13.1).
@@ -2149,6 +2221,9 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     if (!file) {
                         throw new Error("clawgram: upload-file requires filePath, path, media, or mediaUrl");
                     }
+                    // Before anything else about the message is considered: an
+                    // out-of-scope path is refused, not sent and then regretted.
+                    (0, media_1.assertLocalMediaWithinRoots)(file, allowedMediaRoots);
                     const captionText = (0, helpers_1.readMessageText)(params) || ((0, param_readers_1.readStringParam)(params, "caption") ?? "");
                     // A caption is optional, but the silent-reply sentinel must never
                     // reach Telegram as one — same reasoning as the `send` path below.
@@ -2252,8 +2327,11 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         currentMessageId: String(currentMessageId),
                         toolContextCurrentChannelId: currentChannelId || null,
                     });
+                    // A dry run reports the suppression instead of impersonating it: the
+                    // caller asked what would happen, and what would happen is nothing.
                     return (0, core_1.jsonResult)({
                         ok: true,
+                        ...(dryRun ? { dryRun: true } : {}),
                         suppressedDuplicate: true,
                         to,
                         accountId: resolvedAccountId,
@@ -2264,7 +2342,10 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 // `replyToId`, and until 2026-08-10 that fell through to the most
                 // recent sender: in an interleaved chat the owner's report went out
                 // addressed to a colleague who had asked something else entirely.
-                const groupReplyAddress = (0, group_reply_address_1.consumeGroupReplyAddress)({
+                // A dry run peeks: consuming the address here left the real send with
+                // no greeting, so a rehearsal silently changed the message that went
+                // out afterwards.
+                const groupReplyAddress = (dryRun ? group_reply_address_1.peekGroupReplyAddress : group_reply_address_1.consumeGroupReplyAddress)({
                     accountId: resolvedAccountId,
                     chatId: to,
                     replyToId: replyToId ?? currentMessageId,
@@ -2483,6 +2564,11 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 if (!gram) {
                     throw new Error(`clawgram: runtime not found for account ${ctx.accountId}`);
                 }
+                // Same rule as the action path: a local file outside the declared
+                // roots is refused before anything is uploaded.
+                const outboundRoots = ctx.mediaLocalRoots ?? ctx.mediaAccess?.localRoots;
+                (0, media_1.assertLocalMediaWithinRoots)(ctx.filePath, outboundRoots);
+                (0, media_1.assertLocalMediaWithinRoots)(ctx.mediaUrl, outboundRoots);
                 actionLog.info("clawgram outbound sendMedia", {
                     accountId: ctx.accountId,
                     rawTo: ctx.to,

package/dist/chat-info.js

@@ -19,7 +19,7 @@ exports.parseChatInfoParams = parseChatInfoParams;
 exports.describeChat = describeChat;
 const helpers_1 = require("./helpers");
 function parseChatInfoParams(params, toolContext) {
-    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat ?? toolContext?.currentChannelId;
+    const rawTarget = (0, helpers_1.readChatTargetParam)(params, toolContext);
     const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
     if (!target) {
         throw new Error("clawgram: chatInfo requires a chatId");

package/dist/cli-core.js

@@ -10,6 +10,7 @@ const telegram_1 = require("telegram");
 const sessions_1 = require("telegram/sessions");
 const config_runtime_1 = require("openclaw/plugin-sdk/config-runtime");
 const constants_1 = require("./constants");
+const proxy_config_1 = require("./proxy-config");
 const update_config_1 = require("./update-config");
 function printRestartNotice() {
     console.log("");
@@ -114,12 +115,29 @@ function buildConfigFragment(accountId, auth) {
         },
     };
 }
-async function runTelegramAuthorization(prompt) {
+/**
+ * The proxy the account this login is for already uses, if any.
+ *
+ * The login handshake carries the phone number, the code and the 2FA password,
+ * and it used to go out from the host's real IP even on a deployment whose
+ * whole point is that Telegram never sees it: this flow built its own client
+ * and read no proxy at all. An unresolved SecretRef throws out of
+ * `buildTelegramClientOptions` rather than silently falling back to a direct
+ * connection — the same fail-closed rule the channel follows.
+ */
+function resolveAuthProxy(config, accountId) {
+    return config?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[accountId]?.proxy;
+}
+async function runTelegramAuthorization(prompt, proxy) {
     const apiId = await prompt.askPositiveInteger("Please enter your apiId: ");
     const apiHash = await prompt.askRequired("Please enter your apiHash: ");
-    const client = new telegram_1.TelegramClient(new sessions_1.StringSession(""), apiId, apiHash, {
-        connectionRetries: 5,
-    });
+    const clientOptions = (0, proxy_config_1.buildTelegramClientOptions)(proxy);
+    if (clientOptions.proxy) {
+        // Scheme only. The host, port and credentials are exactly what must not
+        // reach a terminal, a screen share or CI scrollback.
+        console.log(`Connecting through the account's ${(0, proxy_config_1.describeProxy)(clientOptions.proxy)} proxy.`);
+    }
+    const client = new telegram_1.TelegramClient(new sessions_1.StringSession(""), apiId, apiHash, clientOptions);
     try {
         await client.start({
             phoneNumber: async () => await prompt.askRequired("Please enter your number: "),
@@ -143,7 +161,8 @@ async function runTelegramUserbotAuth(config) {
     const prompt = createPrompt();
     try {
         console.log("Starting Clawgram authorization...");
-        const auth = await runTelegramAuthorization(prompt);
+        const authAccountId = resolveDefaultAccountId(config);
+        const auth = await runTelegramAuthorization(prompt, resolveAuthProxy(config, authAccountId));
         console.log("Telegram authorization completed successfully.");
         console.log("");
         // The session string is a bearer secret for the whole Telegram account.
@@ -152,7 +171,7 @@ async function runTelegramUserbotAuth(config) {
         // automatic config write and therefore has to paste it by hand.
         console.log(`Session string received (${auth.sessionString.length} chars) — kept out of this output.`);
         console.log("");
-        const defaultAccountId = resolveDefaultAccountId(config);
+        const defaultAccountId = authAccountId;
         const rawAccountId = await prompt.ask(`Enter account id for config [${defaultAccountId}]: `);
         const accountId = rawAccountId.trim() || defaultAccountId;
         const shouldUpdateConfig = await prompt.askYesNo("Update OpenClaw config automatically? [y/N]: ", false);

package/dist/constants.js

@@ -1,7 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLI_COMMAND = exports.CHANNEL_ID = void 0;
+exports.TELEGRAM_SERVICE_CHAT_ID = exports.CLI_COMMAND = exports.CHANNEL_ID = void 0;
 const CHANNEL_ID = "clawgram";
 exports.CHANNEL_ID = CHANNEL_ID;
 const CLI_COMMAND = "clawgram";
 exports.CLI_COMMAND = CLI_COMMAND;
+/**
+ * Telegram's own service account: login codes, password-reset notices and
+ * termination warnings arrive from it. Its messages are dropped on the way in
+ * and refused on the way out — a login code reaching the agent is an account
+ * takeover, not a privacy nuisance, so no `readChats` entry may enable it.
+ */
+const TELEGRAM_SERVICE_CHAT_ID = "777000";
+exports.TELEGRAM_SERVICE_CHAT_ID = TELEGRAM_SERVICE_CHAT_ID;

package/dist/fetch-media.js

@@ -21,6 +21,7 @@ exports.parseFetchMediaParams = parseFetchMediaParams;
 exports.sanitizeFileName = sanitizeFileName;
 exports.fetchedMediaFileName = fetchedMediaFileName;
 const history_1 = require("./history");
+const helpers_1 = require("./helpers");
 /**
  * A caller that guessed a neighbouring word is not refused: these are all
  * unambiguous, and an error over vocabulary costs a turn to say nothing.
@@ -52,7 +53,7 @@ function parseFetchMediaMode(value) {
     return mode;
 }
 function parseFetchMediaParams(params) {
-    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const rawTarget = (0, helpers_1.readChatTargetParam)(params);
     const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
     if (!target) {
         throw new Error("clawgram: fetch-media requires a chatId");

package/dist/gramjs-client.js

@@ -209,6 +209,7 @@ class GramJsClientManager {
     client;
     proxy;
     started = false;
+    connected = false;
     constructor(config) {
         this.config = config;
         // Credentials may be written as SecretRefs; account start-up resolves them
@@ -231,10 +232,24 @@ class GramJsClientManager {
     async start() {
         if (this.started)
             return;
-        await this.client.connect();
-        const authorized = await this.client.checkAuthorization();
-        if (!authorized) {
-            throw new Error("GramJS client connected, but session is not authorized.");
+        // `connect()` starts the update loop before anything is known about the
+        // session, so a revoked or expired one used to throw with `started` still
+        // false — and `stop()`, which returned early on exactly that flag, then
+        // left a connected client retrying forever. That is the same leak 2.17.1
+        // fixed for the ordinary teardown path, reached through the failure path
+        // instead.
+        try {
+            await this.client.connect();
+            this.connected = true;
+            const authorized = await this.client.checkAuthorization();
+            if (!authorized) {
+                throw new Error("GramJS client connected, but session is not authorized.");
+            }
+        }
+        catch (error) {
+            await this.client.destroy().catch(() => undefined);
+            this.connected = false;
+            throw error;
         }
         this.started = true;
     }
@@ -254,10 +269,15 @@ class GramJsClientManager {
      * before a restart, ~4.5/min after one.
      */
     async stop() {
-        if (!this.started)
+        // Keyed on `connected`, not `started`: a client whose `connect()` succeeded
+        // and whose authorization then failed never set `started`, and the old
+        // guard let it keep its update loop. A client that never connected is
+        // still left alone, and a second `stop()` still destroys nothing.
+        if (!this.started && !this.connected)
             return;
-        await this.client.destroy();
+        await this.client.destroy().catch(() => undefined);
         this.started = false;
+        this.connected = false;
     }
     getClient() {
         return this.client;

package/dist/group-reply-address.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rememberGroupReplyAddress = rememberGroupReplyAddress;
 exports.consumeGroupReplyAddress = consumeGroupReplyAddress;
+exports.peekGroupReplyAddress = peekGroupReplyAddress;
 exports.resetGroupReplyAddresses = resetGroupReplyAddresses;
 exports.buildGroupReplyAddress = buildGroupReplyAddress;
 const helpers_1 = require("./helpers");
@@ -45,7 +46,7 @@ function rememberGroupReplyAddress(input) {
  * to "who am I replying to", so the fallback is gone — callers pass the message
  * the turn is actually answering, and no message means no greeting.
  */
-function consumeGroupReplyAddress(input) {
+function readGroupReplyAddress(input, consume) {
     const key = buildGroupReplyAddressKey(input);
     if (!key) {
         return undefined;
@@ -54,12 +55,27 @@ function consumeGroupReplyAddress(input) {
     if (!stored) {
         return undefined;
     }
-    groupReplyAddresses.delete(key);
+    if (consume) {
+        groupReplyAddresses.delete(key);
+    }
     if (stored.expiresAt < Date.now()) {
         return undefined;
     }
     return stored.address;
 }
+function consumeGroupReplyAddress(input) {
+    return readGroupReplyAddress(input, true);
+}
+/**
+ * The same lookup without the delete, for a dry run.
+ *
+ * A rehearsal that consumed the address changed what the real send would do:
+ * the greeting was gone by the time the message actually went out. A dry run
+ * has to answer "what would happen" without being the thing that happens.
+ */
+function peekGroupReplyAddress(input) {
+    return readGroupReplyAddress(input, false);
+}
 /** Test seam: the map is module state, and suites must not leak into each other. */
 function resetGroupReplyAddresses() {
     groupReplyAddresses.clear();

package/dist/helpers.js

@@ -3,7 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SILENT_REPLY_TOKEN = void 0;
+exports.SILENT_REPLY_TOKEN = exports.CHAT_TARGET_PARAM_KEYS = void 0;
+exports.resolveAddressableText = resolveAddressableText;
+exports.readChatTargetParam = readChatTargetParam;
+exports.resolveAccountScopes = resolveAccountScopes;
 exports.normalizeOutboundTarget = normalizeOutboundTarget;
 exports.resolveConfiguredAccountId = resolveConfiguredAccountId;
 exports.inferOutboundTargetKind = inferOutboundTargetKind;
@@ -36,6 +39,7 @@ exports.prefixReplyTextToAddress = prefixReplyTextToAddress;
 exports.resolveReplyTarget = resolveReplyTarget;
 exports.resolveChatTarget = resolveChatTarget;
 exports.isReplyToSelfMessage = isReplyToSelfMessage;
+exports.resolveReplyParent = resolveReplyParent;
 exports.resolveSenderProfile = resolveSenderProfile;
 exports.resolveSenderProfileWithTimeout = resolveSenderProfileWithTimeout;
 exports.normalizeParseMode = normalizeParseMode;
@@ -193,14 +197,74 @@ function readLatestAssistantFallbackFromTranscript(sessionKey, storePath, notBef
     }
     return undefined;
 }
-function resolveActionTarget(params, toolContext) {
-    const explicitTo = (0, core_1.readStringParam)(params, "to") ?? (0, core_1.readStringParam)(params, "target");
-    if (explicitTo?.trim()) {
-        return explicitTo.trim();
+/**
+ * The part of an inbound message the mention gate may read.
+ *
+ * A voice transcript is the sender's own speech: "Тина, посмотри" said aloud
+ * addresses the agent exactly as typing it would, and gating on the caption
+ * alone would make her deaf to being spoken to. A vision description is not
+ * speech — it is a model reading somebody else's content, so a screenshot of a
+ * chat in which a third party wrote `@tina_bot`, or a photo of a poster
+ * bearing the name, used to count as an address and wake her up.
+ *
+ * The body handed to the agent is unaffected; only what may count as being
+ * addressed is narrowed.
+ */
+function resolveAddressableText(input) {
+    if (input.understanding === "description") {
+        return input.messageText?.trim() ?? "";
     }
-    const contextTarget = toolContext?.currentChannelId?.trim();
-    if (contextTarget) {
-        return contextTarget;
+    return input.bodyText?.trim() ?? input.messageText?.trim() ?? "";
+}
+/**
+ * The chat named by a call, in the spellings this channel accepts.
+ *
+ * Five parsers spelled this chain out separately and none of them read
+ * `channelId` — which is the key core fills for its `channelId`-mode actions
+ * (`channel-info`, the name `chatInfo` answers to). A call that named another
+ * chat that way fell through to the current one and was answered about the
+ * wrong chat, silently. One list, one order, every caller.
+ */
+exports.CHAT_TARGET_PARAM_KEYS = ["chatId", "channelId", "target", "to", "chat"];
+function readChatTargetParam(params, toolContext) {
+    // Strings only, exactly like the SDK's `readStringParam` and like every
+    // parser here before the chain was shared: a numeric `chatId` is refused
+    // rather than coerced, because `-1001234567890` loses precision as a JSON
+    // number long before it reaches Telegram.
+    const named = [];
+    for (const key of exports.CHAT_TARGET_PARAM_KEYS) {
+        const value = params?.[key];
+        const trimmed = typeof value === "string" ? value.trim() : "";
+        if (trimmed && !named.includes(trimmed)) {
+            named.push(trimmed);
+        }
+    }
+    // Two keys naming two different chats is a caller error, and picking one by
+    // key order would send a message to a chat nobody asked for — the failure
+    // this whole resolver exists to prevent. Say so instead of guessing.
+    if (named.length > 1) {
+        throw new Error(`clawgram: conflicting chat targets (${named.join(", ")})`);
+    }
+    return named[0] ?? toolContext?.currentChannelId?.trim() ?? "";
+}
+/**
+ * Which chat an outbound action is for.
+ *
+ * `chatId` and `channelId` are read alongside `to`/`target` because the read
+ * actions accept them and this plugin's own tool hints tell the agent to name
+ * a chat that way. Until 2.21.0 the send path ignored them: a `send` carrying
+ * `chatId` fell through to the current chat, so a message meant for another
+ * chat was delivered to the one the turn came from — the wrong audience, with
+ * no error anywhere.
+ *
+ * A named chat always wins over the context. The context fallback exists for
+ * a send that names nothing, which is the ordinary "answer where you were
+ * asked" case.
+ */
+function resolveActionTarget(params, toolContext) {
+    const target = readChatTargetParam(params, toolContext);
+    if (target) {
+        return target;
     }
     throw new Error("clawgram: message target is required");
 }
@@ -258,19 +322,32 @@ function readMessageText(params) {
     }
     return "";
 }
+/**
+ * Three states, and the empty one is the whole point:
+ *
+ * - absent (or a shape this cannot read) → `["*"]`, the historical default that
+ *   keeps a fresh install usable;
+ * - `"*"` or a non-empty list → itself;
+ * - `[]`, `""`, or a list of blanks → `[]`, which denies everyone.
+ *
+ * The last used to return `["*"]`: an operator who emptied the list to shut the
+ * account off opened it to every Telegram user instead, and the sibling scopes
+ * (`readChats: []`, `manageChats: []`) already read an empty list as deny.
+ * `startAccount` logs a warning when this returns empty, because "nobody can
+ * reach the agent" must not be a silent state.
+ */
 function resolveAllowFrom(value) {
     if (value === "*") {
         return ["*"];
     }
     if (typeof value === "string" || typeof value === "number") {
         const entry = String(value).trim();
-        return entry ? [entry] : ["*"];
+        return entry ? [entry] : [];
     }
     if (!Array.isArray(value)) {
         return ["*"];
     }
-    const entries = value.map((entry) => String(entry).trim()).filter(Boolean);
-    return entries.length > 0 ? entries : ["*"];
+    return value.map((entry) => String(entry).trim()).filter(Boolean);
 }
 /**
  * Three rungs, widest first: `open` wakes on every message, `mention` on the
@@ -306,6 +383,28 @@ function resolveGroupPromptSettings(groupConfig) {
     }
     return settings;
 }
+/**
+ * The sender scopes for one account: who may write, and what each group allows.
+ *
+ * `allowFrom` and `groups` are declared both per account and at the channel
+ * level, and the manifest validates them in both places — but only the account
+ * copies were read, so a channel-level allowlist passed validation and then
+ * admitted everyone. Worse, the config was read twice by two different paths
+ * (`resolveAccount` and the inbound handler), which is how they could disagree
+ * at all. One function serves both now.
+ *
+ * The account's own value wins, including a deliberate `[]`; the channel level
+ * is the default beneath it. Groups merge per key rather than replacing, so a
+ * channel-wide default and a per-account override can coexist.
+ */
+function resolveAccountScopes(cfg, accountId) {
+    const channel = cfg?.channels?.clawgram;
+    const account = channel?.accounts?.[accountId];
+    return {
+        allowFrom: resolveAllowFrom(account?.allowFrom ?? channel?.allowFrom),
+        groups: { ...resolveGroups(channel?.groups), ...resolveGroups(account?.groups) },
+    };
+}
 function resolveGroups(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return {};
@@ -549,27 +648,58 @@ async function resolveChatTarget(message) {
     }
     return message?.inputChat ?? message?._inputChat ?? message?.chat ?? message?._chat ?? message?.peerId;
 }
-async function isReplyToSelfMessage(message, selfId) {
-    if (!selfId) {
-        return false;
-    }
+/**
+ * The message a reply points at, fetched once.
+ *
+ * Telegram does not put the parent's text into the reply; a highlight
+ * (`quoteText`) is the only fragment that travels with it, and most replies
+ * have none. Core renders `[Replying to: …]` from the highlight or, failing
+ * that, from `ReplyToBody` — so without this fetch a plain reply reaches the
+ * agent as a bare parent id. The case that exposed it: the owner answered, in
+ * a DM, the agent's own notice about an unknown sender; the notice had been
+ * sent from another session, DMs are outside `readChats`, and the agent had
+ * no way to learn what "reply to #1011" referred to.
+ *
+ * Failure degrades to "no context" on purpose: a parent that cannot be
+ * fetched (deleted, flood-waited, transport hiccup) must not cost the
+ * message itself.
+ */
+async function resolveReplyParent(message, input) {
     const replyToMessageId = message?.replyTo?.replyToMsgId ?? message?.replyToMsgId;
     if (!replyToMessageId) {
-        return false;
+        return { isSelf: false };
     }
     const replied = typeof message?.getReplyMessage === "function"
         ? await message.getReplyMessage().catch(() => undefined)
         : undefined;
     if (!replied) {
-        return false;
-    }
-    if (replied.out === true) {
-        return true;
+        return { isSelf: false };
     }
     const replySenderId = replied.senderId ??
         replied.fromId?.userId ??
         replied.fromId?.channelId;
-    return replySenderId !== undefined && String(replySenderId) === selfId;
+    const isSelf = replied.out === true ||
+        (input.selfId !== undefined && replySenderId !== undefined && String(replySenderId) === input.selfId);
+    const rawText = typeof replied.message === "string" ? replied.message :
+        typeof replied.text === "string" ? replied.text :
+            "";
+    const body = rawText.trim() ? rawText : undefined;
+    const source = replied.sender ?? replied._sender;
+    const sender = isSelf
+        ? (input.selfLabel ?? (input.selfId !== undefined ? input.selfId : undefined))
+        : toDisplayName({
+            firstName: typeof source?.firstName === "string" ? source.firstName : undefined,
+            lastName: typeof source?.lastName === "string" ? source.lastName : undefined,
+            username: undefined,
+            fallback: resolveActiveUsername(source) ? `@${resolveActiveUsername(source)}` : (replySenderId !== undefined ? String(replySenderId) : undefined),
+        });
+    return { isSelf, body, sender: sender || undefined };
+}
+async function isReplyToSelfMessage(message, selfId) {
+    if (!selfId) {
+        return false;
+    }
+    return (await resolveReplyParent(message, { selfId })).isSelf;
 }
 async function resolveSenderProfile(message, input) {
     const pickProfile = (source) => {

package/dist/history.js

@@ -28,6 +28,7 @@ exports.HISTORY_DEFAULT_LIMIT = 100;
 exports.HISTORY_MAX_LIMIT = 500;
 const media_1 = require("./media");
 const helpers_1 = require("./helpers");
+const constants_1 = require("./constants");
 /**
  * Matches `normalize.ts` and `gramjs-client.ts` deliberately.
  *
@@ -107,7 +108,7 @@ function parseMessageId(value, field) {
     return numeric;
 }
 function parseListMessagesParams(params) {
-    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const rawTarget = (0, helpers_1.readChatTargetParam)(params);
     const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
     if (!target) {
         throw new Error("clawgram: list requires a chatId");
@@ -190,7 +191,7 @@ function parseParticipantsFilter(params) {
  * not silently turn into an unbounded response.
  */
 function parseListParticipantsParams(params) {
-    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const rawTarget = (0, helpers_1.readChatTargetParam)(params);
     const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
     if (!target) {
         throw new Error("clawgram: participants requires a chatId");
@@ -252,6 +253,14 @@ function normalizeChatKey(value) {
  * rather than a sentence in a prompt that a model may be argued out of.
  */
 function isChatReadable(target, readChats) {
+    // The inbound path has always dropped Telegram's service chat so login codes
+    // never reach the model; the read path did not, so `read chatId=777000`
+    // handed them over whenever `readChats` was absent (the default `--auth`
+    // writes) or held `*`. The deny is unconditional on purpose: no deployment
+    // has a reason to let the agent read its own login codes, and a config entry
+    // that enabled it would be an account-takeover switch.
+    if (normalizeChatKey(target) === constants_1.TELEGRAM_SERVICE_CHAT_ID)
+        return false;
     if (readChats === undefined || readChats === null)
         return true;
     const entries = (Array.isArray(readChats) ? readChats : [readChats])

package/dist/manage.js

@@ -32,6 +32,7 @@ exports.resolveCreatedChannelId = resolveCreatedChannelId;
 exports.summarizeMissingInvitees = summarizeMissingInvitees;
 exports.readInviteLink = readInviteLink;
 const history_1 = require("./history");
+const helpers_1 = require("./helpers");
 function readString(value) {
     if (typeof value !== "string") {
         return undefined;
@@ -47,7 +48,7 @@ function readUserRef(value) {
     return readString(value);
 }
 function readTarget(params, toolContext, action) {
-    const raw = params.chatId ?? params.target ?? params.to ?? params.chat ?? toolContext?.currentChannelId;
+    const raw = (0, helpers_1.readChatTargetParam)(params, toolContext);
     const target = readString(raw);
     if (!target) {
         throw new Error(`clawgram: ${action} requires a chatId`);

package/dist/media.js

@@ -11,12 +11,19 @@
  * 240 KB" was posted is what a summary needs, and fetching the bytes of every
  * attachment in a window would be a different feature with different costs.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeMedia = describeMedia;
 exports.inboundMediaUnderstanding = inboundMediaUnderstanding;
 exports.downloadInboundMediaToTempFile = downloadInboundMediaToTempFile;
 exports.downloadMessageMediaToFile = downloadMessageMediaToFile;
 exports.pruneFetchedMedia = pruneFetchedMedia;
+exports.isLocalMediaPath = isLocalMediaPath;
+exports.assertLocalMediaWithinRoots = assertLocalMediaWithinRoots;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
 /**
  * GramJS carries numbers as `big-integer` objects as often as native numbers —
  * the same shape that once made `senderId` silently undefined. Anything that
@@ -237,3 +244,52 @@ function extensionFor(media, understanding) {
         return "m4a";
     return "ogg";
 }
+/**
+ * Whether an outbound `file` is a local path rather than a URL.
+ *
+ * GramJS accepts both, and only a path can reach the host filesystem.
+ */
+function isLocalMediaPath(file) {
+    if (typeof file !== "string" || !file.trim()) {
+        return false;
+    }
+    return !/^[a-z][a-z0-9+.-]*:/i.test(file.trim());
+}
+/**
+ * Refuses an outbound local file that sits outside the roots the host declared.
+ *
+ * Core hands every action the `mediaLocalRoots` the agent is scoped to, and
+ * bundled channels enforce them; this one passed `filePath` straight to
+ * `sendFile`, so a prompt-injected agent could name `/opt/openclaw-secrets/
+ * secrets.json` — or the config holding `sessionString` — and have it uploaded
+ * to any peer. Symlinks are resolved first, because a link inside a root
+ * pointing out of it is the obvious way around a prefix check.
+ *
+ * When the host declares no roots the path is left alone: the gateway RPC and
+ * the TTS contour both send files core never scoped, and refusing them here
+ * would break sending altogether rather than narrow it.
+ */
+function assertLocalMediaWithinRoots(file, roots) {
+    if (!isLocalMediaPath(file) || !roots || roots.length === 0) {
+        return;
+    }
+    const realPath = (candidate) => {
+        try {
+            return (0, node_fs_1.realpathSync)(candidate);
+        }
+        catch {
+            return node_path_1.default.resolve(candidate);
+        }
+    };
+    const target = realPath(file.trim());
+    const allowed = roots.some((root) => {
+        const resolvedRoot = realPath(root);
+        return target === resolvedRoot || target.startsWith(`${resolvedRoot}${node_path_1.default.sep}`);
+    });
+    if (!allowed) {
+        // The path is the agent's own input, not a secret, and naming it is what
+        // makes the refusal actionable. The roots are not listed: they describe
+        // the host's layout.
+        throw new Error(`clawgram: ${file} is outside the media roots this agent may read`);
+    }
+}

package/dist/reactions.js

@@ -13,6 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAgentReactionGuidance = resolveAgentReactionGuidance;
 exports.parseReactionParams = parseReactionParams;
+const helpers_1 = require("./helpers");
 /**
  * How freely the agent may react, from the account's `reactionLevel`.
  *
@@ -69,7 +70,7 @@ function parseMessageId(value) {
     return parsed;
 }
 function parseReactionParams(params, toolContext) {
-    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat ?? toolContext?.currentChannelId;
+    const rawTarget = (0, helpers_1.readChatTargetParam)(params, toolContext);
     const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
     if (!target) {
         throw new Error("clawgram: react requires a chatId");

package/dist/topics.js

@@ -16,10 +16,11 @@ exports.normalizeForumTopics = normalizeForumTopics;
  * client; the transport lives in `GramJsClientManager.listTopics`.
  */
 const normalize_js_1 = require("./normalize.js");
+const helpers_1 = require("./helpers");
 exports.TOPICS_DEFAULT_LIMIT = 100;
 exports.TOPICS_MAX_LIMIT = 500;
 function parseTopicsParams(params) {
-    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const rawTarget = (0, helpers_1.readChatTargetParam)(params);
     const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
     if (!target) {
         throw new Error("clawgram: topics requires a chatId");

package/dist/update-config.js

@@ -351,10 +351,26 @@ function buildUpdatedConfigText(raw, accountId, auth) {
     }
     return replaceObjectPropertyValue(raw, channelsProperty, updatedChannels, format);
 }
+/**
+ * The config this writes holds `apiHash` and `sessionString` in plaintext, so
+ * the permissions of the file it replaces are part of the credential's
+ * protection. `writeFile`'s own `mode` is masked by the process umask (0644
+ * under the usual 022), which is how a 0600 config came back world-readable
+ * after `--auth`; the explicit `chmod` on the temp file is what actually
+ * fixes it, and it happens before the rename so the config is never briefly
+ * readable at the wrong mode.
+ */
+const SECRET_FILE_MODE = 0o600;
+async function readFileMode(filePath) {
+    const stats = await node_fs_1.promises.stat(filePath).catch(() => null);
+    return stats ? stats.mode & 0o777 : SECRET_FILE_MODE;
+}
 async function writeConfigAtomically(configPath, raw) {
     const tempPath = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+    const mode = await readFileMode(configPath);
     try {
-        await node_fs_1.promises.writeFile(tempPath, raw, "utf8");
+        await node_fs_1.promises.writeFile(tempPath, raw, { encoding: "utf8", mode });
+        await node_fs_1.promises.chmod(tempPath, mode);
         await node_fs_1.promises.rename(tempPath, configPath);
     }
     catch (error) {
@@ -367,8 +383,12 @@ async function createConfigBackup(configPath) {
     if (raw === null) {
         return null;
     }
+    // The backup is a verbatim copy of a credential file and it is never cleaned
+    // up, so it inherits the original's mode rather than the umask default.
+    const mode = await readFileMode(configPath);
     const backupPath = buildConfigBackupPath(configPath);
-    await node_fs_1.promises.writeFile(backupPath, raw, "utf8");
+    await node_fs_1.promises.writeFile(backupPath, raw, { encoding: "utf8", mode });
+    await node_fs_1.promises.chmod(backupPath, mode);
     return backupPath;
 }
 async function updateConfigFileDirectly(configPath, accountId, auth) {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawgram",
   "name": "Clawgram",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -57,7 +57,7 @@
                     "tag"
                   ],
                   "default": "mention",
-                  "description": "What wakes the agent in this chat (2.18.0). `mention` \u2014 the name, an @mention or a reply to it; `open` \u2014 every message, the agent decides for itself whether words are owed; `tag` \u2014 only an explicit @username or a reply, for chats where the name occurs in conversation constantly."
+                  "description": "What wakes the agent in this chat (2.18.0). `mention` — the name, an @mention or a reply to it; `open` — every message, the agent decides for itself whether words are owed; `tag` — only an explicit @username or a reply, for chats where the name occurs in conversation constantly."
                 },
                 "allowFrom": {
                   "type": "array",
@@ -364,7 +364,7 @@
                           "tag"
                         ],
                         "default": "mention",
-                        "description": "What wakes the agent in this chat (2.18.0). `mention` \u2014 the name, an @mention or a reply to it; `open` \u2014 every message; `tag` \u2014 only an explicit @username or a reply."
+                        "description": "What wakes the agent in this chat (2.18.0). `mention` — the name, an @mention or a reply to it; `open` — every message; `tag` — only an explicit @username or a reply."
                       },
                       "allowFrom": {
                         "type": "array",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawgram",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
   "main": "./dist/index.js",
   "scripts": {