gewe-openclaw 2026.3.25 → 2026.3.26

package/README.md

@@ -95,7 +95,7 @@ openclaw onboard
 - `s3PublicBaseUrl`：`public` 模式下用于拼接可访问 URL（必填）。
 - `s3PresignExpiresSec`：`presigned` 模式签名有效期（默认 3600 秒）。
 - `s3KeyPrefix`：对象 key 前缀（默认 `gewe-openclaw/outbound`）。
-- `allowFrom`：允许私聊触发的微信 ID（或在群里走 allowlist 规则）。
+- `allowFrom`：允许私聊触发的微信 ID；不再隐式用于群聊权限。
 - `voiceAutoConvert`：自动将音频转为 silk（默认开启；设为 `false` 可关闭）。
 - `silkAutoDownload`：自动下载 `rust-silk`（默认开启；可关闭后自行配置 `voiceSilkPath` / `voiceDecodePath`）。
 - `silkVersion`：自动下载的 `rust-silk` 版本（`latest` 会自动清理旧版本）。
@@ -238,6 +238,11 @@ GeWe 现在补齐了目录、标准 allowlist 适配和状态摘要。
 - 私聊：`allowFrom`
 - 群发言人：`groupAllowFrom`
 
+注意：
+
+- 私聊 `pairing` 只会把对方加入私聊 allowlist，不会自动给任何群开权限。
+- 群聊权限只看 `groupAllowFrom` 和 `groups.<groupId>.allowFrom`。
+
 如果你要管理“某一个群自己的 `groups.<groupId>.allowFrom` 覆盖”，请用插件工具：
 
 - `gewe_manage_group_allowlist`
@@ -260,6 +265,75 @@ GeWe 现在补齐了目录、标准 allowlist 适配和状态摘要。
 }
 ```
 
+### 认证方式
+
+如果你是第一次用，可以把它理解成两步：
+
+1. 先在私聊里完成配对
+2. 再在要使用的群里完成认领
+
+为什么要分成两步：
+
+- 私聊配对成功，只表示“你可以在私聊里跟机器人说话了”
+- 这一步不会让机器人自动在所有群里生效
+- 群认领是第二次确认，表示“这个群也允许你使用机器人”
+- 这样做是为了避免机器人一进公开群就被任何人直接触发
+
+你实际要做的事很简单：
+
+1. 先和机器人私聊，完成配对
+2. 再在私聊里让机器人给你一个 8 位认领码
+3. 把机器人拉进目标群
+4. 在目标群里直接发这 8 位认领码
+5. 收到成功提示后，这个群就接入完成了
+
+举个例子：
+
+- 机器人在私聊里给你：`MJSQ2G9H`
+- 你把机器人拉进目标群
+- 你在群里直接发：`MJSQ2G9H`
+
+几个容易搞混的点：
+
+- 群里不需要 `@机器人`
+- 最推荐的发法就是只发这 8 位码
+- `认领码: MJSQ2G9H` 这种写法也能识别，但默认不推荐
+- 认领码有时效，而且只能用一次
+- 这个码是谁拿到的，就只能由谁来完成这次认领
+
+认领成功后会发生什么：
+
+- 机器人会记住“你可以在这个群里使用它了”
+- 只影响当前这个群
+- 不会顺手把别的群也打开
+- 不会自动帮你创建额外的绑定配置
+
+如果你会自己改配置文件：
+
+- 认领成功后，插件会把当前发码者写入 `groups.<groupId>.allowFrom`
+
+### 群认领
+
+如果是一个还没放行的新群，推荐流程是：
+
+1. 先在已配对的私聊里调用 `gewe_issue_group_claim_code`
+2. 把机器人拉进目标群
+3. 在目标群里只发送这 8 位认领码：`XXXXXXXX`
+
+推荐默认话术：
+
+- 私聊里直接把 8 位码发给用户，不要包装成 `认领码: XXXXXXXX`
+- 群里也只发这 8 位码，不要加 `认领码:` 前缀
+
+认领成功后，插件会把“当前发码者”写入该群的 `groups.<groupId>.allowFrom`。
+
+默认特性：
+
+- 认领码短时有效、单次使用
+- 只能由签发它的那个发码者在群里使用
+- 只给当前群开权限，不会改顶层 `groupAllowFrom`
+- 不会自动创建 `bindings[]`
+
 如果你就在目标群里调用，`groupId` 可以省略；工具会自动用当前群。
 
 ### 状态

package/index.ts

@@ -4,6 +4,7 @@ import { createGeweApiTools } from "./src/api-tools.js";
 import { gewePlugin } from "./src/channel.js";
 import { createGeweManageGroupAllowlistTool } from "./src/group-allowlist-tool.js";
 import { createGeweSyncGroupBindingTool } from "./src/group-binding-tool.js";
+import { createGeweIssueGroupClaimCodeTool } from "./src/group-claim-tool.js";
 import { setGeweRuntime } from "./src/runtime.js";
 
 function emptyPluginConfigSchema() {
@@ -44,6 +45,7 @@ const plugin = {
     api.registerChannel({ plugin: gewePlugin });
     api.registerTool((ctx) => createGeweApiTools(ctx));
     api.registerTool((ctx) => createGeweSyncGroupBindingTool(ctx));
+    api.registerTool((ctx) => createGeweIssueGroupClaimCodeTool(ctx));
     api.registerTool((ctx) =>
       createGeweManageGroupAllowlistTool(ctx, {
         readConfig: () => api.runtime.config.loadConfig() as never,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gewe-openclaw",
-  "version": "2026.3.25",
+  "version": "2026.3.26",
   "type": "module",
   "description": "OpenClaw GeWe channel plugin",
   "license": "MIT",

package/skills/gewe-agent-tools/SKILL.md

@@ -14,12 +14,13 @@ metadata:
 
 # GeWe Agent Tools
 
-优先把这四个工具当成 GeWe 的正式操作面：
+优先把这五个工具当成 GeWe 的正式操作面：
 
 - `gewe_contacts`
 - `gewe_groups`
 - `gewe_moments`
 - `gewe_personal`
+- `gewe_issue_group_claim_code`
 
 ## 什么时候用哪个
 
@@ -27,10 +28,48 @@ metadata:
 - 处理群资料、群成员、群公告、群管理：用 `gewe_groups`
 - 处理朋友圈浏览、点赞、评论、发布、转发：用 `gewe_moments`
 - 处理当前登录微信自己的资料、二维码、安全信息、隐私设置：用 `gewe_personal`
+- 处理新群接入、给当前已配对私聊签发群认领码：用 `gewe_issue_group_claim_code`
 
 如果只是想知道“现在这个私聊对象是谁”，优先用 `gewe_contacts`。
 如果只是想知道“现在这个群是谁、有哪些成员”，优先用 `gewe_groups`。
 
+## 新群接入
+
+当用户在 GeWe 当前私聊会话里表达这些意思时，优先进入“群认领”流程，而不是旧的手工绑群流程：
+
+- “我要新绑定一个群”
+- “给这个新群开权限”
+- “把机器人接入一个新群”
+
+这时优先调用 `gewe_issue_group_claim_code`。
+
+关键原则：
+
+- 不要先让用户手填群 id
+- 不要先让用户自己改配置
+- 不要把“私聊已经 pairing 成功”理解成“群已经自动放行”
+
+标准动作：
+
+1. 在当前私聊会话里调用 `gewe_issue_group_claim_code`
+2. 把返回的 8 位认领码原样发给用户
+3. 明确告诉用户：先把机器人拉进目标新群
+4. 再让用户在目标群里只发送这 8 位认领码，例如：`XXXXXXXX`
+
+重要话术约束：
+
+- 默认只把 8 位码发给用户，不要包装成 `认领码: XXXXXXXX`
+- 默认明确提醒：群里也只发这 8 位码，不要加 `认领码:` 前缀
+
+推荐话术要点：
+
+- 这是短时有效、单次使用的认领码
+- 认领成功后，只会授权当前发码者在这个新群里触发机器人
+- 如果只是想查新群资料，再在当前群会话里用 `gewe_groups`
+
+只有在用户已经明确处在目标群里，且需求是“查当前群信息 / 查成员 / 查群 id”时，才优先使用 `gewe_groups`。
+如果需求是“接入一个还没放行的新群”，先发认领码，再谈群信息。
+
 ## 当前会话推断
 
 有些 action 可以少填参数，优先利用当前会话：

package/src/api-tools.ts

@@ -65,7 +65,7 @@ import {
   uploadSnsVideoGewe,
 } from "./moments-api.js";
 import { normalizeGeweMessagingTarget } from "./normalize.js";
-import { normalizeAccountId, type OpenClawConfig } from "./openclaw-compat.js";
+import { buildJsonSchema, normalizeAccountId, type OpenClawConfig } from "./openclaw-compat.js";
 import {
   getProfileGewe,
   getQrCodeGewe,
@@ -74,6 +74,7 @@ import {
   updateHeadImgGewe,
   updateProfileGewe,
 } from "./personal-api.js";
+import { shouldExposeGeweAgentTool } from "./tool-visibility.js";
 import type { CoreConfig, ResolvedGeweAccount } from "./types.js";
 
 const ContactsActionSchema = z.enum([
@@ -243,6 +244,11 @@ const PersonalToolSchema = z
   })
   .strict();
 
+const ContactsToolParameters = buildJsonSchema(ContactsToolSchema) ?? { type: "object" };
+const GroupsToolParameters = buildJsonSchema(GroupsToolSchema) ?? { type: "object" };
+const MomentsToolParameters = buildJsonSchema(MomentsToolSchema) ?? { type: "object" };
+const PersonalToolParameters = buildJsonSchema(PersonalToolSchema) ?? { type: "object" };
+
 type ContactsToolParams = z.infer<typeof ContactsToolSchema>;
 type GroupsToolParams = z.infer<typeof GroupsToolSchema>;
 type MomentsToolParams = z.infer<typeof MomentsToolSchema>;
@@ -1150,15 +1156,17 @@ async function executePersonalTool(
   }
 }
 
-export function createGeweApiTools(ctx: OpenClawPluginToolContext): AnyAgentTool[] {
+export function createGeweApiTools(ctx: OpenClawPluginToolContext): AnyAgentTool[] | null {
+  if (!shouldExposeGeweAgentTool(ctx)) {
+    return null;
+  }
   return [
     {
       name: "gewe_contacts",
       label: "GeWe Contacts",
       description:
         "GeWe contacts operations. Actions: list, list_cache, brief, detail, search, search_im, im_detail, check_relation, set_remark, set_only_chat, delete, add, add_im, sync_im, phones_get, phones_upload.",
-      ownerOnly: true,
-      parameters: ContactsToolSchema,
+      parameters: ContactsToolParameters,
       execute: async (_toolCallId, rawParams) => {
         const params = ContactsToolSchema.parse(rawParams ?? {});
         try {
@@ -1184,8 +1192,7 @@ export function createGeweApiTools(ctx: OpenClawPluginToolContext): AnyAgentTool
       label: "GeWe Groups",
       description:
         "GeWe group operations. Actions: info, announcement, members, member_detail, qr_code, set_self_nickname, rename, set_remark, create, remove_members, agree_join, join_via_qr, add_member_as_friend, approve_join_request, admin_operate, save_to_contacts, pin, disband, set_silence, set_announcement, quit, invite.",
-      ownerOnly: true,
-      parameters: GroupsToolSchema,
+      parameters: GroupsToolParameters,
       execute: async (_toolCallId, rawParams) => {
         const params = GroupsToolSchema.parse(rawParams ?? {});
         try {
@@ -1211,8 +1218,7 @@ export function createGeweApiTools(ctx: OpenClawPluginToolContext): AnyAgentTool
       label: "GeWe Moments",
       description:
         "GeWe Moments operations. Actions: list_self, list_contact, detail, download_video, upload_image, upload_video, delete, post_text, post_image, post_video, post_link, set_stranger_visibility, set_visible_scope, set_privacy, like, comment, forward.",
-      ownerOnly: true,
-      parameters: MomentsToolSchema,
+      parameters: MomentsToolParameters,
       execute: async (_toolCallId, rawParams) => {
         const params = MomentsToolSchema.parse(rawParams ?? {});
         try {
@@ -1238,8 +1244,7 @@ export function createGeweApiTools(ctx: OpenClawPluginToolContext): AnyAgentTool
       label: "GeWe Personal",
       description:
         "GeWe personal-account operations. Actions: profile, qrcode, safety_info, update_profile, update_avatar, privacy.",
-      ownerOnly: true,
-      parameters: PersonalToolSchema,
+      parameters: PersonalToolParameters,
       execute: async (_toolCallId, rawParams) => {
         const params = PersonalToolSchema.parse(rawParams ?? {});
         try {

package/src/delivery.ts

@@ -770,7 +770,6 @@ function buildPartialQuoteXml(params?: {
 function buildQuoteReplyAppMsg(params: {
   title: string;
   svrid: string;
-  atWxid?: string;
   partialText?: {
     text?: string;
     start?: string;
@@ -782,12 +781,12 @@ function buildQuoteReplyAppMsg(params: {
 }): string {
   const safeTitle = escapeXmlText(params.title.trim() || "引用回复");
   const safeSvrid = escapeXmlText(params.svrid.trim());
-  const safeAtWxid = params.atWxid?.trim() ? escapeXmlText(params.atWxid.trim()) : undefined;
-  const encodedMsgSource = safeAtWxid
-    ? `<msgsource><atuserlist>${safeAtWxid}</atuserlist></msgsource>`
-    : "";
   const partialTextXml = buildPartialQuoteXml(params.partialText);
-  return `<appmsg><title>${safeTitle}</title><type>57</type><refermsg>${partialTextXml}<svrid>${safeSvrid}</svrid>${safeAtWxid ? `<msgsource>${encodedMsgSource}</msgsource>` : ""}</refermsg></appmsg>`;
+  return `<appmsg><title>${safeTitle}</title><type>57</type><refermsg>${partialTextXml}<svrid>${safeSvrid}</svrid></refermsg></appmsg>`;
+}
+
+function summarizeOutboundText(value: string): string {
+  return JSON.stringify(value.replace(/\s+/g, " ").trim().slice(0, 120));
 }
 
 async function stageMedia(params: {
@@ -983,15 +982,18 @@ export async function deliverGewePayload(params: {
       : payload.replyToId?.trim() || "";
   const quoteReplyTitle = geweData?.quoteReply?.title?.trim() || trimmedText;
   if (quoteReplySvrid && quoteReplyTitle && geweData?.quoteReply) {
+    core.log?.(
+      `gewe: outbound quoteReply explicit to=${toWxid} ats=${JSON.stringify(geweData.quoteReply.atWxid?.trim() || "")} title=${summarizeOutboundText(quoteReplyTitle)}`,
+    );
     const result = await sendAppMsgGewe({
       account,
       toWxid,
       appmsg: buildQuoteReplyAppMsg({
         svrid: quoteReplySvrid,
         title: quoteReplyTitle,
-        atWxid: geweData.quoteReply.atWxid?.trim(),
         partialText: geweData.quoteReply.partialText,
       }),
+      ats: geweData.quoteReply.atWxid?.trim(),
     });
     core.channel.activity.record({
       channel: CHANNEL_ID,
@@ -1160,6 +1162,9 @@ export async function deliverGewePayload(params: {
   }
 
   if (autoQuoteReplyEnabled && trimmedText && payload.replyToId?.trim() && !mediaUrl) {
+    core.log?.(
+      `gewe: outbound quoteReply auto to=${toWxid} ats=${JSON.stringify(geweData?.ats?.trim() || "")} title=${summarizeOutboundText(trimmedText)}`,
+    );
     const result = await sendAppMsgGewe({
       account,
       toWxid,
@@ -1168,6 +1173,7 @@ export async function deliverGewePayload(params: {
         title: trimmedText,
         partialText: autoQuoteContext?.partialText,
       }),
+      ats: geweData?.ats,
     });
     core.channel.activity.record({
       channel: CHANNEL_ID,

package/src/group-allowlist-tool.ts

@@ -4,8 +4,8 @@ import { z } from "zod";
 import { resolveGeweAccount } from "./accounts.js";
 import { ensureGeweWriteSection } from "./config-edit.js";
 import { normalizeGeweBindingConversationId, inferCurrentGeweGroupId } from "./group-binding.js";
-import { normalizeAccountId, type OpenClawConfig } from "./openclaw-compat.js";
-import { readGeweAllowFromStore } from "./pairing-store.js";
+import { buildJsonSchema, normalizeAccountId, type OpenClawConfig } from "./openclaw-compat.js";
+import { shouldExposeGeweAgentTool } from "./tool-visibility.js";
 import type { GeweGroupConfig } from "./types.js";
 
 const GeweManageGroupAllowlistSchema = z
@@ -17,6 +17,9 @@ const GeweManageGroupAllowlistSchema = z
   })
   .strict();
 
+const GeweManageGroupAllowlistParameters =
+  buildJsonSchema(GeweManageGroupAllowlistSchema) ?? { type: "object" };
+
 function jsonResult(details: Record<string, unknown>) {
   return {
     content: [{ type: "text" as const, text: JSON.stringify(details, null, 2) }],
@@ -80,9 +83,7 @@ function readOverrideEntries(accountConfig: Record<string, unknown>, groupId: st
 
 function resolveEffectiveEntries(params: {
   accountConfig: Record<string, unknown>;
-  accountId: string;
   groupId: string;
-  pairingEntries: string[];
 }): {
   baseEntries: string[];
   overrideEntries: string[];
@@ -93,7 +94,7 @@ function resolveEffectiveEntries(params: {
   return {
     baseEntries,
     overrideEntries,
-    effectiveEntries: dedupeEntries([...baseEntries, ...params.pairingEntries, ...overrideEntries]),
+    effectiveEntries: dedupeEntries([...baseEntries, ...overrideEntries]),
   };
 }
 
@@ -160,14 +161,16 @@ export function createGeweManageGroupAllowlistTool(
     readConfig?: () => OpenClawConfig;
     writeConfigFile?: (next: OpenClawConfig) => Promise<void>;
   },
-): AnyAgentTool {
+): AnyAgentTool | null {
+  if (!shouldExposeGeweAgentTool(ctx)) {
+    return null;
+  }
   return {
     name: "gewe_manage_group_allowlist",
     label: "GeWe Manage Group Allowlist",
     description:
       "Inspect or edit a GeWe group's allowFrom override. Modes: inspect, add, remove, replace, clear.",
-    ownerOnly: true,
-    parameters: GeweManageGroupAllowlistSchema,
+    parameters: GeweManageGroupAllowlistParameters,
     execute: async (_toolCallId, rawParams) => {
       const params = GeweManageGroupAllowlistSchema.parse(rawParams ?? {});
       const cfg = resolveToolConfig(ctx, deps?.readConfig);
@@ -189,12 +192,9 @@ export function createGeweManageGroupAllowlistTool(
               ?.accounts?.[accountId] ?? {})
       ) as Record<string, unknown>;
 
-      const pairingEntries = await readGeweAllowFromStore({ accountId });
       const current = resolveEffectiveEntries({
         accountConfig: resolvedAccount.config as Record<string, unknown>,
-        accountId,
         groupId,
-        pairingEntries,
       });
 
       if (params.mode === "inspect") {
@@ -205,7 +205,6 @@ export function createGeweManageGroupAllowlistTool(
           groupId,
           groupPolicy: resolvedAccount.config.groupPolicy ?? "allowlist",
           baseEntries: current.baseEntries,
-          pairingEntries,
           overrideEntries: current.overrideEntries,
           effectiveEntries: current.effectiveEntries,
         });

package/src/group-binding-tool.ts

@@ -15,7 +15,8 @@ import {
   resolveGeweBindingIdentityConfigForGroup,
   resolveGeweCurrentSelfNickname,
 } from "./group-binding.js";
-import { normalizeAccountId, type OpenClawConfig } from "./openclaw-compat.js";
+import { buildJsonSchema, normalizeAccountId, type OpenClawConfig } from "./openclaw-compat.js";
+import { shouldExposeGeweAgentTool } from "./tool-visibility.js";
 
 const GeweSyncGroupBindingToolSchema = z
   .object({
@@ -27,6 +28,9 @@ const GeweSyncGroupBindingToolSchema = z
   })
   .strict();
 
+const GeweSyncGroupBindingToolParameters =
+  buildJsonSchema(GeweSyncGroupBindingToolSchema) ?? { type: "object" };
+
 function jsonResult(details: Record<string, unknown>) {
   return {
     content: [{ type: "text" as const, text: JSON.stringify(details, null, 2) }],
@@ -34,14 +38,16 @@ function jsonResult(details: Record<string, unknown>) {
   };
 }
 
-export function createGeweSyncGroupBindingTool(ctx: OpenClawPluginToolContext): AnyAgentTool {
+export function createGeweSyncGroupBindingTool(ctx: OpenClawPluginToolContext): AnyAgentTool | null {
+  if (!shouldExposeGeweAgentTool(ctx)) {
+    return null;
+  }
   return {
     name: "gewe_sync_group_binding",
     label: "GeWe Sync Group Binding",
     description:
       "Inspect or manually sync a GeWe group binding identity. Modes: inspect, dry_run, apply.",
-    ownerOnly: true,
-    parameters: GeweSyncGroupBindingToolSchema,
+    parameters: GeweSyncGroupBindingToolParameters,
     execute: async (_toolCallId, rawParams) => {
       const params = GeweSyncGroupBindingToolSchema.parse(rawParams ?? {});
       const cfg = (ctx.config ?? {}) as OpenClawConfig;

package/src/group-claim-tool.ts

@@ -0,0 +1,103 @@
+import type { AnyAgentTool, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+import { normalizeGeweMessagingTarget } from "./normalize.js";
+import { buildJsonSchema, normalizeAccountId } from "./openclaw-compat.js";
+import { issueGeweGroupClaimCode } from "./pairing-store.js";
+import { shouldExposeGeweAgentTool } from "./tool-visibility.js";
+
+const GeweIssueGroupClaimCodeSchema = z
+  .object({
+    accountId: z.string().optional(),
+  })
+  .strict();
+
+const GeweIssueGroupClaimCodeParameters =
+  buildJsonSchema(GeweIssueGroupClaimCodeSchema) ?? { type: "object" };
+
+function extractSessionScopedTarget(
+  sessionKey: string | undefined,
+  markers: string[],
+): string | undefined {
+  const raw = sessionKey?.trim();
+  if (!raw) {
+    return undefined;
+  }
+  const lowered = raw.toLowerCase();
+  for (const marker of markers) {
+    const index = lowered.indexOf(marker);
+    if (index === -1) {
+      continue;
+    }
+    const value = raw.slice(index + marker.length).trim();
+    if (value) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function inferCurrentGeweDirectWxid(ctx: OpenClawPluginToolContext): string | undefined {
+  const fromSession = extractSessionScopedTarget(ctx.sessionKey, [
+    ":gewe-openclaw:direct:",
+    ":gewe-openclaw:dm:",
+    ":gewe:direct:",
+    ":gewe:dm:",
+  ]);
+  const normalizedSession = normalizeGeweMessagingTarget(fromSession ?? "");
+  if (normalizedSession && !normalizedSession.endsWith("@chatroom")) {
+    return normalizedSession;
+  }
+
+  const normalizedRequester = normalizeGeweMessagingTarget(ctx.requesterSenderId ?? "");
+  if (normalizedRequester && !normalizedRequester.endsWith("@chatroom")) {
+    return normalizedRequester;
+  }
+  return undefined;
+}
+
+function jsonResult(details: Record<string, unknown>) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(details, null, 2) }],
+    details,
+  };
+}
+
+export function createGeweIssueGroupClaimCodeTool(ctx: OpenClawPluginToolContext): AnyAgentTool | null {
+  if (!shouldExposeGeweAgentTool(ctx)) {
+    return null;
+  }
+  return {
+    name: "gewe_issue_group_claim_code",
+    label: "GeWe Issue Group Claim Code",
+    description:
+      "Issue a short-lived single-use group claim code for the current GeWe direct-message session.",
+    parameters: GeweIssueGroupClaimCodeParameters,
+    execute: async (_toolCallId, rawParams) => {
+      const params = GeweIssueGroupClaimCodeSchema.parse(rawParams ?? {});
+      const accountId = normalizeAccountId(params.accountId ?? ctx.agentAccountId ?? "default");
+      const issuerId = inferCurrentGeweDirectWxid(ctx);
+      if (!issuerId) {
+        throw new Error(
+          "GeWe group claim code issuance requires a current GeWe direct-message session to infer the owner wxid.",
+        );
+      }
+
+      const issued = await issueGeweGroupClaimCode({
+        accountId,
+        issuerId,
+      });
+
+      return jsonResult({
+        ok: true,
+        accountId: issued.accountId,
+        issuerId: issued.issuerId,
+        code: issued.code,
+        recommendedGroupMessage: issued.code,
+        createdAt: issued.createdAt,
+        expiresAt: issued.expiresAt,
+        usageHint: `把机器人拉进目标群后，在群里只发送这 8 位认领码：${issued.code}（不要加“认领码:”前缀）`,
+      });
+    },
+  };
+}

package/src/inbound.ts

@@ -14,6 +14,7 @@ import {
   buildGeweInboundMediaPayload,
   buildGeweInboundMessageMeta,
 } from "./inbound-batch.js";
+import { ensureGeweWriteSection } from "./config-edit.js";
 import type { GeweDownloadQueue } from "./download-queue.js";
 import { downloadGeweFile, downloadGeweImage, downloadGeweVideo, downloadGeweVoice } from "./download.js";
 import { deliverGewePayload } from "./delivery.js";
@@ -21,7 +22,11 @@ import { applyGeweReplyModeToPayload, resolveGeweReplyOptions } from "./reply-op
 import { rememberGeweDirectoryObservation } from "./directory-cache.js";
 import { getGeweRuntime } from "./runtime.js";
 import { ensureRustSilkBinary } from "./silk.js";
-import { readGeweAllowFromStore, redeemGewePairCode } from "./pairing-store.js";
+import {
+  readGeweAllowFromStore,
+  redeemGeweGroupClaimCode,
+  redeemGewePairCode,
+} from "./pairing-store.js";
 import {
   normalizeGeweAllowlist,
   resolveGeweAllowlistMatch,
@@ -100,6 +105,12 @@ const GEWE_PAIR_CODE_REGEX = /^[A-HJ-NP-Z2-9]{8}$/i;
 const GEWE_PAIR_CODE_PREFIX_REGEX = /^配对码\s*[:：]?\s*([A-HJ-NP-Z2-9]{8})$/i;
 const GEWE_PAIR_CODE_SUCCESS_REPLY = "配对成功，已加入允许列表。请重新发送上一条消息。";
 const GEWE_PAIR_CODE_INVALID_REPLY = "配对码无效或已过期。";
+const GEWE_GROUP_CLAIM_CODE_PREFIX_REGEX = /^(?:群)?认领码\s*[:：]?\s*([A-HJ-NP-Z2-9]{8})$/i;
+const GEWE_GROUP_CLAIM_CODE_INLINE_REGEX = /(?:^|\s)(?:群)?认领码\s*[:：]?\s*([A-HJ-NP-Z2-9]{8})(?=$|\s)/i;
+const GEWE_GROUP_CLAIM_CODE_SUCCESS_REPLY =
+  "当前群认领成功，已授权你在本群触发机器人。请重新发送上一条消息。";
+const GEWE_GROUP_CLAIM_CODE_INVALID_REPLY = "认领码无效、已过期，或不属于当前发送者。";
+const GEWE_GROUP_CLAIM_CODE_DISABLED_REPLY = "当前群已被显式禁用，无法认领。";
 
 function resolveMediaPlaceholder(msgType: number): string {
   if (msgType === 3) return "<media:image>";
@@ -158,6 +169,63 @@ function resolveGewePairCodeCandidate(rawBody: string): string | null {
   return prefixed?.[1]?.toUpperCase() ?? null;
 }
 
+function resolveGeweGroupClaimCodeCandidate(rawBody: string): string | null {
+  const trimmed = rawBody.trim();
+  if (!trimmed) return null;
+  if (GEWE_PAIR_CODE_REGEX.test(trimmed)) {
+    return trimmed.toUpperCase();
+  }
+
+  const candidateLines = trimmed
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      let next = line;
+      while (next.startsWith("@")) {
+        next = next.replace(/^@\S+\s*/u, "").trim();
+      }
+      return next;
+    });
+
+  for (const line of candidateLines) {
+    if (!line) {
+      continue;
+    }
+    if (GEWE_PAIR_CODE_REGEX.test(line)) {
+      return line.toUpperCase();
+    }
+    const prefixed = line.match(GEWE_GROUP_CLAIM_CODE_PREFIX_REGEX);
+    if (prefixed?.[1]) {
+      return prefixed[1].toUpperCase();
+    }
+  }
+
+  const inline = trimmed.match(GEWE_GROUP_CLAIM_CODE_INLINE_REGEX);
+  return inline?.[1]?.toUpperCase() ?? null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+function dedupeAllowEntries(values: readonly unknown[]): string[] {
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    const normalized = String(value ?? "").trim().replace(/^(?:gewe|wechat|wx):/i, "");
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
 function looksLikeSilkVoice(params: {
   buffer: Buffer;
   contentType?: string | null;
@@ -727,6 +795,16 @@ export async function handleGeweInboundBatch(params: {
     senderName,
     groupId,
   });
+  const nativeAtWxids = Array.from(
+    new Set(
+      entries
+        .flatMap((entry) => entry.message.atWxids ?? [])
+        .map((wxid) => wxid.trim())
+        .filter(Boolean),
+    ),
+  );
+  const nativeAtAll = entries.some((entry) => entry.message.atAll === true);
+  const nativeAtTriggered = nativeAtWxids.includes(lastMessage.botWxid.trim());
 
   const dmPolicy = account.config.dmPolicy ?? "pairing";
   const defaultGroupPolicy = config.channels?.defaults?.groupPolicy;
@@ -759,6 +837,78 @@ export async function handleGeweInboundBatch(params: {
       })
     : undefined;
 
+  if (isGroup) {
+    const groupClaimCode = resolveGeweGroupClaimCodeCandidate(rawBodyCandidate);
+    if (groupClaimCode) {
+      const latestCfg = (core.config.loadConfig?.() as CoreConfig | undefined) ?? config;
+      const writeConfigFile = core.config.writeConfigFile?.bind(core.config);
+      const write =
+        groupId && writeConfigFile
+          ? ensureGeweWriteSection({
+              cfg: latestCfg as OpenClawConfig,
+              accountId: account.accountId,
+            })
+          : null;
+      const groups =
+        write && asRecord(write.target.groups)
+          ? (asRecord(write.target.groups) as Record<string, Record<string, unknown>>)
+          : ({} as Record<string, Record<string, unknown>>);
+      const currentGroup = groupId ? asRecord(groups[groupId]) ?? {} : {};
+      const isDisabled =
+        groupPolicy === "disabled" ||
+        groupMatch?.groupConfig?.enabled === false ||
+        groupMatch?.wildcardConfig?.enabled === false ||
+        currentGroup.enabled === false;
+      const claimReply =
+        !groupId || !write || !writeConfigFile
+          ? GEWE_GROUP_CLAIM_CODE_INVALID_REPLY
+          : isDisabled
+            ? GEWE_GROUP_CLAIM_CODE_DISABLED_REPLY
+            : await (async () => {
+            const redeemed = await redeemGeweGroupClaimCode({
+              accountId: account.accountId,
+              code: groupClaimCode,
+              issuerId: senderId,
+              groupId,
+            }).catch((err) => {
+              runtime.error?.(
+                `gewe: group claim code redeem failed for ${senderId} in ${groupId}: ${String(err)}`,
+              );
+              return null;
+            });
+            if (!redeemed) {
+              return GEWE_GROUP_CLAIM_CODE_INVALID_REPLY;
+            }
+            write.target.groups = groups;
+            const allowFrom = dedupeAllowEntries([
+              ...(Array.isArray(currentGroup.allowFrom) ? currentGroup.allowFrom : []),
+              senderId,
+            ]);
+            groups[groupId] = {
+              ...currentGroup,
+              allowFrom,
+            };
+            await writeConfigFile(write.nextCfg);
+            return GEWE_GROUP_CLAIM_CODE_SUCCESS_REPLY;
+          })();
+
+      try {
+        await deliverGewePayload({
+          payload: {
+            text: claimReply,
+          },
+          account,
+          cfg: config as OpenClawConfig,
+          toWxid,
+          statusSink: (patch) => statusSink?.(patch),
+        });
+      } catch (err) {
+        runtime.error?.(`gewe: group claim code reply failed for ${senderId}: ${String(err)}`);
+      }
+      return;
+    }
+  }
+
   if (isGroup && groupMatch && !groupMatch.allowed) {
     runtime.log?.(`gewe: drop group ${groupId} (not allowlisted)`);
     return;
@@ -772,10 +922,9 @@ export async function handleGeweInboundBatch(params: {
   const wildcardRoomAllowFrom = normalizeGeweAllowlist(groupMatch?.wildcardConfig?.allowFrom);
   const roomAllowFrom =
     directRoomAllowFrom.length > 0 ? directRoomAllowFrom : wildcardRoomAllowFrom;
-  const baseGroupAllowFrom =
-    configGroupAllowFrom.length > 0 ? configGroupAllowFrom : configAllowFrom;
+  const baseGroupAllowFrom = configGroupAllowFrom;
   const effectiveAllowFrom = [...configAllowFrom, ...storeAllowList].filter(Boolean);
-  const effectiveGroupAllowFrom = [...baseGroupAllowFrom, ...storeAllowList].filter(Boolean);
+  const effectiveGroupAllowFrom = [...baseGroupAllowFrom].filter(Boolean);
 
   const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
     cfg: config as OpenClawConfig,
@@ -883,16 +1032,6 @@ export async function handleGeweInboundBatch(params: {
     config as OpenClawConfig,
     route.agentId,
   );
-  const nativeAtWxids = Array.from(
-    new Set(
-      entries
-        .flatMap((entry) => entry.message.atWxids ?? [])
-        .map((wxid) => wxid.trim())
-        .filter(Boolean),
-    ),
-  );
-  const nativeAtAll = entries.some((entry) => entry.message.atAll === true);
-  const nativeAtTriggered = nativeAtWxids.includes(lastMessage.botWxid.trim());
   const regexAtTriggered = mentionRegexes.length
     ? core.channel.mentions.matchesMentionPatterns(rawBodyCandidate, mentionRegexes)
     : false;

package/src/openclaw-compat.ts

@@ -567,13 +567,10 @@ export function logInboundDrop(params: {
 }
 
 export function buildChannelConfigSchema(schema: ZodTypeAny): ChannelConfigSchema {
-  const schemaWithJson = schema as ZodSchemaWithToJsonSchema;
-  if (typeof schemaWithJson.toJSONSchema === "function") {
+  const jsonSchema = buildJsonSchema(schema);
+  if (jsonSchema) {
     return {
-      schema: schemaWithJson.toJSONSchema({
-        target: "draft-07",
-        unrepresentable: "any",
-      }) as Record<string, unknown>,
+      schema: jsonSchema,
     };
   }
   return {
@@ -584,6 +581,20 @@ export function buildChannelConfigSchema(schema: ZodTypeAny): ChannelConfigSchem
   };
 }
 
+export function buildJsonSchema(schema: unknown): Record<string, unknown> | null {
+  const schemaWithJson = schema as ZodSchemaWithToJsonSchema | null | undefined;
+  if (schemaWithJson && typeof schemaWithJson.toJSONSchema === "function") {
+    return schemaWithJson.toJSONSchema({
+      target: "draft-07",
+      unrepresentable: "any",
+    }) as Record<string, unknown>;
+  }
+  if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+    return schema as Record<string, unknown>;
+  }
+  return null;
+}
+
 export const DmPolicySchema = z.enum(["pairing", "allowlist", "open", "disabled"]);
 export const GroupPolicySchema = z.enum(["open", "disabled", "allowlist"]);
 

package/src/pairing-store.ts

@@ -7,9 +7,11 @@ import { CHANNEL_ID, stripChannelPrefix } from "./constants.js";
 import { resolveOpenClawStateDir } from "./state-paths.js";
 
 const PAIR_CODE_TTL_MS = 60 * 60 * 1000;
+const GROUP_CLAIM_CODE_TTL_MS = 5 * 60 * 1000;
 const LOCK_STALE_MS = 30_000;
 const LOCK_RETRY_ATTEMPTS = 12;
 const LOCK_RETRY_BASE_MS = 50;
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 
 type AllowFromStore = {
   version: 1;
@@ -27,6 +29,20 @@ type GewePairCodeStore = {
   codes: Array<string | GewePairCodeEntry>;
 };
 
+type GeweGroupClaimCodeEntry = {
+  code: string;
+  accountId?: string;
+  issuerId?: string;
+  createdAt?: string;
+  usedAt?: string;
+  usedGroupId?: string;
+};
+
+type GeweGroupClaimCodeStore = {
+  version: 1;
+  codes: GeweGroupClaimCodeEntry[];
+};
+
 type LegacyPairingRequest = {
   id?: string;
   code?: string;
@@ -53,6 +69,15 @@ type CanonicalLegacyPairingRequest = {
   persisted: LegacyPairingRequest;
 };
 
+type CanonicalGroupClaimCodeEntry = {
+  code: string;
+  accountId: string;
+  issuerId: string;
+  createdAt?: string;
+  usedAt?: string;
+  usedGroupId?: string;
+};
+
 function resolveCredentialsDir(env: NodeJS.ProcessEnv = process.env): string {
   return path.join(resolveOpenClawStateDir(env), "credentials");
 }
@@ -89,6 +114,11 @@ function normalizePairCode(code: string | undefined | null): string {
   return (code ?? "").trim().toUpperCase();
 }
 
+function normalizeGroupClaimIssuerId(value: string | undefined | null): string {
+  const normalized = stripChannelPrefix(String(value ?? "").trim());
+  return normalized || "";
+}
+
 function normalizeAllowFromEntry(entry: string | number): string {
   const normalized = stripChannelPrefix(String(entry).trim());
   if (!normalized || normalized === "*") {
@@ -122,6 +152,22 @@ function isExpired(createdAt: string | undefined, nowMs: number, allowMissing =
   return nowMs - parsed > PAIR_CODE_TTL_MS;
 }
 
+function isExpiredWithTtl(params: {
+  createdAt: string | undefined;
+  nowMs: number;
+  ttlMs: number;
+  allowMissing?: boolean;
+}): boolean {
+  if (!params.createdAt) {
+    return params.allowMissing !== true;
+  }
+  const parsed = Date.parse(params.createdAt);
+  if (!Number.isFinite(parsed)) {
+    return true;
+  }
+  return params.nowMs - parsed > params.ttlMs;
+}
+
 async function readJsonFileWithFallback<T>(
   filePath: string,
   fallback: T,
@@ -277,6 +323,50 @@ function persistPairCodeEntry(entry: CanonicalPairCodeEntry): GewePairCodeEntry
   };
 }
 
+function canonicalizeGroupClaimCodeEntry(
+  raw: GeweGroupClaimCodeEntry,
+): CanonicalGroupClaimCodeEntry | null {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const code = normalizePairCode(raw.code);
+  const issuerId = normalizeGroupClaimIssuerId(raw.issuerId);
+  if (!code || !issuerId) {
+    return null;
+  }
+  return {
+    code,
+    accountId: normalizeStoreAccountId(raw.accountId),
+    issuerId,
+    createdAt: typeof raw.createdAt === "string" ? raw.createdAt : undefined,
+    usedAt: typeof raw.usedAt === "string" ? raw.usedAt : undefined,
+    usedGroupId:
+      typeof raw.usedGroupId === "string" ? stripChannelPrefix(raw.usedGroupId.trim()) : undefined,
+  };
+}
+
+function persistGroupClaimCodeEntry(
+  entry: CanonicalGroupClaimCodeEntry,
+): GeweGroupClaimCodeEntry {
+  return {
+    code: entry.code,
+    ...(entry.accountId !== DEFAULT_ACCOUNT_ID ? { accountId: entry.accountId } : {}),
+    issuerId: entry.issuerId,
+    ...(entry.createdAt ? { createdAt: entry.createdAt } : {}),
+    ...(entry.usedAt ? { usedAt: entry.usedAt } : {}),
+    ...(entry.usedGroupId ? { usedGroupId: entry.usedGroupId } : {}),
+  };
+}
+
+function randomCode(length: number): string {
+  const bytes = crypto.randomBytes(length);
+  let output = "";
+  for (let index = 0; index < length; index += 1) {
+    output += CODE_ALPHABET[bytes[index] % CODE_ALPHABET.length];
+  }
+  return output;
+}
+
 function canonicalizeLegacyPairingRequest(
   raw: LegacyPairingRequest,
 ): CanonicalLegacyPairingRequest | null {
@@ -452,6 +542,16 @@ export function resolveGeweLegacyPairingPath(
   return path.join(resolveCredentialsDir(env), `${safeChannelKey(CHANNEL_ID)}-pairing.json`);
 }
 
+export function resolveGeweGroupClaimCodesPath(
+  accountId?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(
+    resolveCredentialsDir(env),
+    `${safeChannelKey(CHANNEL_ID)}-${safeAccountKey(normalizeStoreAccountId(accountId))}-group-claim-codes.json`,
+  );
+}
+
 export async function readGeweAllowFromStore(params: {
   accountId?: string;
   env?: NodeJS.ProcessEnv;
@@ -476,3 +576,184 @@ export async function redeemGewePairCode(params: {
     (await redeemFromLegacyPairingStore(params))
   );
 }
+
+export async function issueGeweGroupClaimCode(params: {
+  accountId?: string;
+  issuerId: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<{
+  code: string;
+  accountId: string;
+  issuerId: string;
+  createdAt: string;
+  expiresAt: string;
+}> {
+  const resolvedAccountId = normalizeStoreAccountId(params.accountId);
+  const issuerId = normalizeGroupClaimIssuerId(params.issuerId);
+  if (!issuerId) {
+    throw new Error("invalid GeWe group claim issuer");
+  }
+  const filePath = resolveGeweGroupClaimCodesPath(resolvedAccountId, params.env);
+  const createdAt = new Date().toISOString();
+  const expiresAt = new Date(Date.parse(createdAt) + GROUP_CLAIM_CODE_TTL_MS).toISOString();
+
+  const code = await withFileLock(filePath, async () => {
+    const { value } = await readJsonFileWithFallback<GeweGroupClaimCodeStore>(filePath, {
+      version: 1,
+      codes: [],
+    });
+    const nowMs = Date.now();
+    const codes = Array.isArray(value.codes) ? value.codes : [];
+    const nextCodes: GeweGroupClaimCodeEntry[] = [];
+    const activeCodes = new Set<string>();
+    for (const raw of codes) {
+      const entry = canonicalizeGroupClaimCodeEntry(raw);
+      if (!entry) {
+        continue;
+      }
+      if (
+        entry.usedAt ||
+        isExpiredWithTtl({
+          createdAt: entry.createdAt,
+          nowMs,
+          ttlMs: GROUP_CLAIM_CODE_TTL_MS,
+        })
+      ) {
+        continue;
+      }
+      activeCodes.add(entry.code);
+      nextCodes.push(persistGroupClaimCodeEntry(entry));
+    }
+
+    let nextCode = "";
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+      const candidate = randomCode(8);
+      if (!activeCodes.has(candidate)) {
+        nextCode = candidate;
+        break;
+      }
+    }
+    if (!nextCode) {
+      throw new Error("failed generating GeWe group claim code");
+    }
+
+    nextCodes.push({
+      code: nextCode,
+      ...(resolvedAccountId !== DEFAULT_ACCOUNT_ID ? { accountId: resolvedAccountId } : {}),
+      issuerId,
+      createdAt,
+    });
+    await writeJsonFileAtomically(filePath, {
+      version: 1,
+      codes: nextCodes,
+    } satisfies GeweGroupClaimCodeStore);
+    return nextCode;
+  });
+
+  return {
+    code,
+    accountId: resolvedAccountId,
+    issuerId,
+    createdAt,
+    expiresAt,
+  };
+}
+
+export async function redeemGeweGroupClaimCode(params: {
+  accountId?: string;
+  code: string;
+  issuerId: string;
+  groupId: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<{
+  code: string;
+  accountId: string;
+  issuerId: string;
+  groupId: string;
+  createdAt?: string;
+  usedAt: string;
+} | null> {
+  const resolvedAccountId = normalizeStoreAccountId(params.accountId);
+  const targetCode = normalizePairCode(params.code);
+  const issuerId = normalizeGroupClaimIssuerId(params.issuerId);
+  const groupId = stripChannelPrefix(params.groupId.trim());
+  if (!targetCode || !issuerId || !groupId) {
+    return null;
+  }
+  const filePath = resolveGeweGroupClaimCodesPath(resolvedAccountId, params.env);
+
+  const matched = await withFileLock(filePath, async () => {
+    const { value, exists } = await readJsonFileWithFallback<GeweGroupClaimCodeStore>(filePath, {
+      version: 1,
+      codes: [],
+    });
+    const nowMs = Date.now();
+    const usedAt = new Date().toISOString();
+    const codes = Array.isArray(value.codes) ? value.codes : [];
+    let result:
+      | {
+          code: string;
+          accountId: string;
+          issuerId: string;
+          groupId: string;
+          createdAt?: string;
+          usedAt: string;
+        }
+      | null = null;
+    let changed = false;
+    const nextCodes: GeweGroupClaimCodeEntry[] = [];
+    for (const raw of codes) {
+      const entry = canonicalizeGroupClaimCodeEntry(raw);
+      if (!entry) {
+        changed = true;
+        continue;
+      }
+      if (
+        entry.usedAt ||
+        isExpiredWithTtl({
+          createdAt: entry.createdAt,
+          nowMs,
+          ttlMs: GROUP_CLAIM_CODE_TTL_MS,
+        })
+      ) {
+        changed = true;
+        continue;
+      }
+      if (
+        !result &&
+        entry.code === targetCode &&
+        entry.accountId === resolvedAccountId &&
+        entry.issuerId === issuerId
+      ) {
+        changed = true;
+        result = {
+          code: entry.code,
+          accountId: entry.accountId,
+          issuerId: entry.issuerId,
+          groupId,
+          createdAt: entry.createdAt,
+          usedAt,
+        };
+        nextCodes.push(
+          persistGroupClaimCodeEntry({
+            ...entry,
+            usedAt,
+            usedGroupId: groupId,
+          }),
+        );
+        continue;
+      }
+      nextCodes.push(persistGroupClaimCodeEntry(entry));
+    }
+
+    if (changed || exists) {
+      await writeJsonFileAtomically(filePath, {
+        version: 1,
+        codes: nextCodes,
+      } satisfies GeweGroupClaimCodeStore);
+    }
+    return result;
+  });
+
+  return matched;
+}

package/src/send.ts

@@ -196,6 +196,7 @@ export async function sendAppMsgGewe(params: {
   account: ResolvedGeweAccount;
   toWxid: string;
   appmsg: string;
+  ats?: string;
 }): Promise<GeweSendResult> {
   const ctx = buildContext(params.account);
   const resp = await postGeweJson<GeweSendResponseData>({
@@ -206,6 +207,7 @@ export async function sendAppMsgGewe(params: {
       appId: ctx.appId,
       toWxid: params.toWxid,
       appmsg: params.appmsg,
+      ...(params.ats ? { ats: params.ats } : {}),
     },
   });
   const data = assertGeweOk(resp, "postAppMsg");

package/src/tool-visibility.ts

@@ -0,0 +1,27 @@
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+
+import { CHANNEL_ALIASES, CHANNEL_ID } from "./constants.js";
+
+const GEWE_DIRECT_SESSION_MARKERS = [
+  `:${CHANNEL_ID}:direct:`,
+  `:${CHANNEL_ID}:dm:`,
+  ":gewe:direct:",
+  ":gewe:dm:",
+];
+
+export function isCurrentGeweDirectSession(ctx: OpenClawPluginToolContext): boolean {
+  const normalizedChannel = (ctx.messageChannel ?? "").trim().toLowerCase();
+  if (normalizedChannel && !CHANNEL_ALIASES.includes(normalizedChannel as (typeof CHANNEL_ALIASES)[number])) {
+    return false;
+  }
+
+  const normalizedSessionKey = (ctx.sessionKey ?? "").trim().toLowerCase();
+  if (!normalizedSessionKey) {
+    return false;
+  }
+  return GEWE_DIRECT_SESSION_MARKERS.some((marker) => normalizedSessionKey.includes(marker));
+}
+
+export function shouldExposeGeweAgentTool(ctx: OpenClawPluginToolContext): boolean {
+  return ctx.senderIsOwner === true || isCurrentGeweDirectSession(ctx);
+}