gewe-openclaw 2026.3.24 → 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` 会自动清理旧版本）。
@@ -141,7 +141,12 @@ openclaw onboard
 - `plain`：普通回复
 - `quote_source`：首条回复自动引用当前入站消息
 - `at_sender`：首条文本回复自动 `@` 发送者
-- `quote_and_at`：首条文本回复同时引用并 `@`；非文本回复会自动退化为 `quote_source`
+
+兼容说明：
+
+- `quote_and_at` 已下线，不再建议继续配置
+- 历史配置里的 `quote_and_at` 仍会被兼容读取，但会自动降级为 `quote_source + 可见 @昵称前缀`
+- 这个兼容降级不是微信原生 `@`，只是为了避免旧配置直接失效
 
 群聊默认值会跟随 `autoQuoteReply`：
 
@@ -167,6 +172,7 @@ openclaw onboard
 - `requireMention: true/false` 仍然可用，会分别映射到群聊 `trigger.mode = "at"` / `"any_message"`
 - 新的 `trigger` / `reply` 配置优先级更高
 - `autoQuoteReply` 现在主要用于“未显式配置 `reply.mode` 时”的默认值回退
+- 历史 `reply.mode = "quote_and_at"` 会自动降级为 `quote_source + 可见 @昵称前缀`
 
 示例：
 
@@ -182,7 +188,7 @@ openclaw onboard
         },
         "project-room@chatroom": {
           "trigger": { "mode": "at_or_quote" },
-          "reply": { "mode": "quote_and_at" },
+          "reply": { "mode": "at_sender" },
           "skills": ["project-skill"]
         },
         "ops-room@chatroom": {
@@ -232,6 +238,11 @@ GeWe 现在补齐了目录、标准 allowlist 适配和状态摘要。
 - 私聊：`allowFrom`
 - 群发言人：`groupAllowFrom`
 
+注意：
+
+- 私聊 `pairing` 只会把对方加入私聊 allowlist，不会自动给任何群开权限。
+- 群聊权限只看 `groupAllowFrom` 和 `groups.<groupId>.allowFrom`。
+
 如果你要管理“某一个群自己的 `groups.<groupId>.allowFrom` 覆盖”，请用插件工具：
 
 - `gewe_manage_group_allowlist`
@@ -254,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` 可以省略；工具会自动用当前群。
 
 ### 状态
@@ -303,7 +383,7 @@ GeWe 的状态页现在会额外显示：
           "groups": {
             "ops-room@chatroom": {
               "trigger": { "mode": "at_or_quote" },
-              "reply": { "mode": "quote_and_at" }
+              "reply": { "mode": "quote_source" }
             }
           }
         }

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.24",
+  "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/config-schema.ts

@@ -7,8 +7,11 @@ import {
   ToolPolicySchema,
   requireOpenAllowFrom,
 } from "./openclaw-compat.js";
+import type { GeweGroupReplyModeInput } from "./types.js";
 import { z } from "zod";
 
+const GEWE_GROUP_REPLY_MODES = ["plain", "quote_source", "at_sender", "quote_and_at"] as const;
+
 const GeweGroupTriggerSchema = z
   .object({
     mode: z.enum(["at", "quote", "at_or_quote", "any_message"]).optional(),
@@ -23,7 +26,15 @@ const GeweDmTriggerSchema = z
 
 const GeweGroupReplySchema = z
   .object({
-    mode: z.enum(["plain", "quote_source", "at_sender", "quote_and_at"]).optional(),
+    mode: z
+      .custom<GeweGroupReplyModeInput>(
+        (value) => typeof value === "string" && GEWE_GROUP_REPLY_MODES.includes(value as GeweGroupReplyModeInput),
+        {
+          message:
+            "invalid GeWe group reply mode; supported values are plain, quote_source, at_sender (quote_and_at is accepted only for compatibility)",
+        },
+      )
+      .optional(),
   })
   .strict();
 

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}（不要加“认领码:”前缀）`,
+      });
+    },
+  };
+}