gewe-openclaw 2026.3.13 → 2026.3.14

package/README.md

@@ -44,6 +44,8 @@ openclaw onboard
 
 在通道列表中选择 **GeWe**，按提示填写 `token`、`appId`、`webhook`，以及可选的 `mediaPublicUrl`/`S3` 媒体配置。
 
+如果你使用 `gewe-gateway` 网关模式，则改为填写 `gatewayUrl`、`gatewayKey`、`gatewayInstanceId`、`webhookPublicUrl` 和显式群列表。
+
 ### 方式 B：直接编辑配置文件
 
 直接编辑 `~/.openclaw/openclaw.json` 的 `channels.gewe-openclaw` 段落（见下方示例）。
@@ -117,6 +119,48 @@ openclaw onboard
 
 > 配置变更后需重启 Gateway。
 
+## 网关模式
+
+当你没有足够多的微信号，但希望让多台 OpenClaw 临时分别服务不同微信群时，可以把 `gewe-openclaw` 配成网关模式。
+
+网关模式下：
+
+- GeWe 官方 webhook 只打到 `gewe-gateway`
+- `gewe-openclaw` 不再直连 GeWe，也不再要求本地配置 `token/appId`
+- 每台 OpenClaw 只声明自己负责的群
+- 网关按群转发入站消息，并统一代理所有出站请求
+
+最小配置示例：
+
+```json5
+{
+  "channels": {
+    "gewe-openclaw": {
+      "enabled": true,
+      "gatewayUrl": "https://your-gateway.example.com",
+      "gatewayKey": "<gateway-key>",
+      "gatewayInstanceId": "openclaw-demo-a",
+      "webhookPublicUrl": "https://your-openclaw.example.com/gewe/webhook",
+      "webhookSecret": "<callback-secret>",
+      "groups": {
+        "123456@chatroom": {
+          "enabled": true,
+          "requireMention": true
+        }
+      }
+    }
+  }
+}
+```
+
+网关模式注意事项：
+
+- `gatewayUrl` 和 `gatewayKey` 必须成对配置
+- 一旦进入网关模式，`apiBaseUrl` 会被忽略
+- `groups` 必须显式列出群 ID，不能用 `*`
+- `webhookPublicUrl` 必须是网关可访问到的完整回调地址
+- 一个群同一时间只能绑定到一个活跃 OpenClaw 实例
+
 ## 高级用法：让未安装插件也出现在 onboarding 列表
 
 默认情况下，**只有已安装的插件**会出现在 onboarding 列表中。  

package/package.json

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

package/src/accounts.ts

@@ -3,21 +3,16 @@ import { readFileSync } from "node:fs";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
 
 import { CHANNEL_CONFIG_KEY } from "./constants.js";
-import type { CoreConfig, GeweAccountConfig, GeweAppIdSource, GeweTokenSource } from "./types.js";
+import type {
+  CoreConfig,
+  GeweAccountConfig,
+  GeweAppIdSource,
+  GeweTokenSource,
+  ResolvedGeweAccount,
+} from "./types.js";
 
 const DEFAULT_API_BASE_URL = "https://www.geweapi.com";
 
-export type ResolvedGeweAccount = {
-  accountId: string;
-  enabled: boolean;
-  name?: string;
-  token: string;
-  tokenSource: GeweTokenSource;
-  appId: string;
-  appIdSource: GeweAppIdSource;
-  config: GeweAccountConfig;
-};
-
 function listConfiguredAccountIds(cfg: CoreConfig): string[] {
   const accounts = cfg.channels?.[CHANNEL_CONFIG_KEY]?.accounts;
   if (!accounts || typeof accounts !== "object") return [];
@@ -59,11 +54,24 @@ function mergeGeweAccountConfig(cfg: CoreConfig, accountId: string): GeweAccount
   return { ...base, ...account };
 }
 
+function normalizeUrl(url?: string): string | undefined {
+  const trimmed = url?.trim();
+  if (!trimmed) return undefined;
+  return trimmed.replace(/\/$/, "");
+}
+
+function isGatewayModeConfig(config?: Pick<GeweAccountConfig, "gatewayUrl" | "gatewayKey">): boolean {
+  return Boolean(normalizeUrl(config?.gatewayUrl) && config?.gatewayKey?.trim());
+}
+
 function resolveToken(
   cfg: CoreConfig,
   accountId: string,
 ): { token: string; source: GeweTokenSource } {
   const merged = mergeGeweAccountConfig(cfg, accountId);
+  if (isGatewayModeConfig(merged)) {
+    return { token: "", source: "none" };
+  }
 
   const envToken = process.env.GEWE_TOKEN?.trim();
   if (envToken && accountId === DEFAULT_ACCOUNT_ID) {
@@ -91,6 +99,9 @@ function resolveAppId(
   accountId: string,
 ): { appId: string; source: GeweAppIdSource } {
   const merged = mergeGeweAccountConfig(cfg, accountId);
+  if (isGatewayModeConfig(merged)) {
+    return { appId: "", source: "none" };
+  }
 
   const envAppId = process.env.GEWE_APP_ID?.trim();
   if (envAppId && accountId === DEFAULT_ACCOUNT_ID) {
@@ -124,19 +135,18 @@ export function resolveGeweAccount(params: {
     const merged = mergeGeweAccountConfig(params.cfg, accountId);
     const accountEnabled = merged.enabled !== false;
     const enabled = baseEnabled && accountEnabled;
+    const mode = isGatewayModeConfig(merged) ? "gateway" : "direct";
     const tokenResolution = resolveToken(params.cfg, accountId);
     const appIdResolution = resolveAppId(params.cfg, accountId);
 
-    if (!merged.apiBaseUrl) {
-      merged.apiBaseUrl = DEFAULT_API_BASE_URL;
-    } else {
-      merged.apiBaseUrl = merged.apiBaseUrl.trim().replace(/\/$/, "");
-    }
+    merged.apiBaseUrl = normalizeUrl(merged.apiBaseUrl) ?? DEFAULT_API_BASE_URL;
+    merged.gatewayUrl = normalizeUrl(merged.gatewayUrl);
 
     return {
       accountId,
       enabled,
       name: merged.name?.trim() || undefined,
+      mode,
       token: tokenResolution.token,
       tokenSource: tokenResolution.source,
       appId: appIdResolution.appId,
@@ -162,3 +172,59 @@ export function listEnabledGeweAccounts(cfg: CoreConfig): ResolvedGeweAccount[]
     .map((accountId) => resolveGeweAccount({ cfg, accountId }))
     .filter((account) => account.enabled);
 }
+
+export function resolveIsGatewayMode(
+  account: ResolvedGeweAccount | GeweAccountConfig | null | undefined,
+): boolean {
+  if (!account) return false;
+  if ("mode" in account && account.mode) {
+    return account.mode === "gateway";
+  }
+  if ("config" in account && account.config) {
+    return isGatewayModeConfig(account.config);
+  }
+  return isGatewayModeConfig(account);
+}
+
+export function resolveIsGeweAccountConfigured(account: ResolvedGeweAccount): boolean {
+  if (resolveIsGatewayMode(account)) {
+    return Boolean(
+      account.config.gatewayUrl?.trim() &&
+        account.config.gatewayKey?.trim() &&
+        account.config.gatewayInstanceId?.trim() &&
+        resolveGatewayCallbackUrl(account) &&
+        resolveGatewayGroupBindings(account).length > 0,
+    );
+  }
+  return Boolean(account.token?.trim() && account.appId?.trim());
+}
+
+export function resolveGeweTransportBaseUrl(account: ResolvedGeweAccount): string {
+  if (resolveIsGatewayMode(account)) {
+    return normalizeUrl(account.config.gatewayUrl) ?? DEFAULT_API_BASE_URL;
+  }
+  return normalizeUrl(account.config.apiBaseUrl) ?? DEFAULT_API_BASE_URL;
+}
+
+export function resolveGatewayGroupBindings(account: ResolvedGeweAccount): string[] {
+  const groups = account.config.groups;
+  if (!groups || typeof groups !== "object") return [];
+  return Object.keys(groups).filter((groupId) => {
+    const trimmed = groupId.trim();
+    if (!trimmed || trimmed === "*") return false;
+    const groupConfig = groups[groupId];
+    return groupConfig?.enabled !== false;
+  });
+}
+
+export function resolveGatewayCallbackUrl(account: ResolvedGeweAccount): string | undefined {
+  return account.config.webhookPublicUrl?.trim() || undefined;
+}
+
+export function resolveGatewayRegisterIntervalMs(account: ResolvedGeweAccount): number {
+  const seconds = account.config.gatewayRegisterIntervalSec;
+  if (typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0) {
+    return Math.round(seconds * 1000);
+  }
+  return 60_000;
+}

package/src/api.ts

@@ -18,6 +18,26 @@ async function readResponseText(res: Response): Promise<string> {
   }
 }
 
+async function postJson<T>(params: {
+  url: string;
+  headers: Record<string, string>;
+  body: Record<string, unknown>;
+}): Promise<T> {
+  const res = await fetch(params.url, {
+    method: "POST",
+    headers: params.headers,
+    body: JSON.stringify(params.body),
+  });
+
+  if (!res.ok) {
+    const text = await readResponseText(res);
+    const detail = text ? `: ${text}` : "";
+    throw new Error(`HTTP request failed (${res.status})${detail}`);
+  }
+
+  return (await res.json()) as T;
+}
+
 export async function postGeweJson<T>(params: {
   baseUrl: string;
   token: string;
@@ -25,23 +45,31 @@ export async function postGeweJson<T>(params: {
   body: Record<string, unknown>;
 }): Promise<GeweApiResponse<T>> {
   const url = buildGeweUrl(params.baseUrl, params.path);
-  const res = await fetch(url, {
-    method: "POST",
+  return postJson<GeweApiResponse<T>>({
+    url,
     headers: {
       "Content-Type": "application/json",
       "X-GEWE-TOKEN": params.token,
     },
-    body: JSON.stringify(params.body),
+    body: params.body,
   });
+}
 
-  if (!res.ok) {
-    const text = await readResponseText(res);
-    const detail = text ? `: ${text}` : "";
-    throw new Error(`GeWe API request failed (${res.status})${detail}`);
-  }
-
-  const json = (await res.json()) as GeweApiResponse<T>;
-  return json;
+export async function postGatewayJson<T>(params: {
+  baseUrl: string;
+  gatewayKey: string;
+  path: string;
+  body: Record<string, unknown>;
+}): Promise<T> {
+  const url = buildGeweUrl(params.baseUrl, params.path);
+  return postJson<T>({
+    url,
+    headers: {
+      "Content-Type": "application/json",
+      "X-GeWe-Gateway-Key": params.gatewayKey,
+    },
+    body: params.body,
+  });
 }
 
 export function assertGeweOk<T>(resp: GeweApiResponse<T>, context: string): T | undefined {

package/src/channel.ts

@@ -13,7 +13,13 @@ import {
   type ChannelSetupInput,
 } from "openclaw/plugin-sdk";
 
-import { resolveGeweAccount, resolveDefaultGeweAccountId, listGeweAccountIds } from "./accounts.js";
+import {
+  listGeweAccountIds,
+  resolveDefaultGeweAccountId,
+  resolveGeweAccount,
+  resolveGeweTransportBaseUrl,
+  resolveIsGeweAccountConfigured,
+} from "./accounts.js";
 import { GeweConfigSchema } from "./config-schema.js";
 import {
   CHANNEL_ALIASES,
@@ -62,8 +68,8 @@ export const gewePlugin: ChannelPlugin<ResolvedGeweAccount> = {
     normalizeAllowEntry: (entry) => stripChannelPrefix(entry),
     notifyApproval: async ({ cfg, id }) => {
       const account = resolveGeweAccount({ cfg: cfg as CoreConfig });
-      if (!account.token || !account.appId) {
-        throw new Error("GeWe token/appId not configured");
+      if (!resolveIsGeweAccountConfigured(account)) {
+        throw new Error("GeWe account is not configured");
       }
       await sendTextGewe({
         account,
@@ -101,14 +107,15 @@ export const gewePlugin: ChannelPlugin<ResolvedGeweAccount> = {
         accountId,
         clearBaseFields: ["token", "tokenFile", "appId", "appIdFile", "name"],
       }),
-    isConfigured: (account) => Boolean(account.token?.trim() && account.appId?.trim()),
+    isConfigured: (account) => resolveIsGeweAccountConfigured(account),
     describeAccount: (account) => ({
       accountId: account.accountId,
       name: account.name,
       enabled: account.enabled,
-      configured: Boolean(account.token?.trim() && account.appId?.trim()),
+      configured: resolveIsGeweAccountConfigured(account),
+      mode: account.mode ?? "direct",
       tokenSource: account.tokenSource,
-      baseUrl: account.config.apiBaseUrl ? "[set]" : "[missing]",
+      baseUrl: resolveGeweTransportBaseUrl(account),
     }),
     resolveAllowFrom: ({ cfg, accountId }) =>
       (resolveGeweAccount({ cfg: cfg as CoreConfig, accountId }).config.allowFrom ?? []).map(
@@ -270,6 +277,9 @@ export const gewePlugin: ChannelPlugin<ResolvedGeweAccount> = {
       lastStartAt: null,
       lastStopAt: null,
       lastError: null,
+      lastGatewayRegisterAt: null,
+      lastGatewayHeartbeatAt: null,
+      lastGatewayError: null,
     },
     buildChannelSummary: ({ snapshot }) => ({
       configured: snapshot.configured ?? false,
@@ -281,23 +291,29 @@ export const gewePlugin: ChannelPlugin<ResolvedGeweAccount> = {
       lastError: snapshot.lastError ?? null,
       lastInboundAt: snapshot.lastInboundAt ?? null,
       lastOutboundAt: snapshot.lastOutboundAt ?? null,
+      lastGatewayRegisterAt: snapshot.lastGatewayRegisterAt ?? null,
+      lastGatewayHeartbeatAt: snapshot.lastGatewayHeartbeatAt ?? null,
+      lastGatewayError: snapshot.lastGatewayError ?? null,
     }),
     buildAccountSnapshot: ({ account, runtime }) => {
-      const configured = Boolean(account.token?.trim() && account.appId?.trim());
+      const configured = resolveIsGeweAccountConfigured(account);
       return {
         accountId: account.accountId,
         name: account.name,
         enabled: account.enabled,
         configured,
         tokenSource: account.tokenSource,
-        baseUrl: account.config.apiBaseUrl ? "[set]" : "[missing]",
+        baseUrl: resolveGeweTransportBaseUrl(account),
         running: runtime?.running ?? false,
         lastStartAt: runtime?.lastStartAt ?? null,
         lastStopAt: runtime?.lastStopAt ?? null,
         lastError: runtime?.lastError ?? null,
-        mode: "webhook",
+        mode: account.mode ?? "direct",
         lastInboundAt: runtime?.lastInboundAt ?? null,
         lastOutboundAt: runtime?.lastOutboundAt ?? null,
+        lastGatewayRegisterAt: runtime?.lastGatewayRegisterAt ?? null,
+        lastGatewayHeartbeatAt: runtime?.lastGatewayHeartbeatAt ?? null,
+        lastGatewayError: runtime?.lastGatewayError ?? null,
         dmPolicy: account.config.dmPolicy ?? "pairing",
       };
     },
@@ -305,10 +321,8 @@ export const gewePlugin: ChannelPlugin<ResolvedGeweAccount> = {
   gateway: {
     startAccount: async (ctx) => {
       const account = ctx.account;
-      if (!account.token || !account.appId) {
-        throw new Error(
-          `GeWe not configured for account "${account.accountId}" (missing token/appId)`,
-        );
+      if (!resolveIsGeweAccountConfigured(account)) {
+        throw new Error(`GeWe not configured for account "${account.accountId}"`);
       }
       ctx.log?.info(`[${account.accountId}] starting GeWe webhook server`);
       const { stop } = await monitorGeweProvider({

package/src/config-schema.ts

@@ -26,6 +26,10 @@ export const GeweAccountSchemaBase = z
     enabled: z.boolean().optional(),
     markdown: MarkdownConfigSchema,
     apiBaseUrl: z.string().optional(),
+    gatewayUrl: z.string().optional(),
+    gatewayKey: z.string().optional(),
+    gatewayInstanceId: z.string().optional(),
+    gatewayRegisterIntervalSec: z.number().positive().optional(),
     token: z.string().optional(),
     tokenFile: z.string().optional(),
     appId: z.string().optional(),
@@ -128,6 +132,68 @@ export const GeweAccountSchemaBase = z
         }
       }
     }
+
+    const gatewayUrl = value.gatewayUrl?.trim();
+    const gatewayKey = value.gatewayKey?.trim();
+    const gatewayMode = Boolean(gatewayUrl || gatewayKey);
+
+    if (gatewayMode && (!gatewayUrl || !gatewayKey)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: [gatewayUrl ? "gatewayKey" : "gatewayUrl"],
+        message: "gatewayUrl and gatewayKey must be configured together",
+      });
+    }
+
+    if (!gatewayMode) return;
+
+    const instanceId = value.gatewayInstanceId?.trim();
+    if (!instanceId) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["gatewayInstanceId"],
+        message: "gatewayInstanceId is required in gateway mode",
+      });
+    }
+
+    const callbackUrl = value.webhookPublicUrl?.trim();
+    if (!callbackUrl) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["webhookPublicUrl"],
+        message: "webhookPublicUrl is required in gateway mode",
+      });
+    } else {
+      try {
+        new URL(callbackUrl);
+      } catch {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["webhookPublicUrl"],
+          message: "webhookPublicUrl must be a valid URL in gateway mode",
+        });
+      }
+    }
+
+    const groups = value.groups ?? {};
+    const explicitGroups = Object.keys(groups).filter((groupId) => {
+      const trimmed = groupId.trim();
+      return Boolean(trimmed) && trimmed !== "*";
+    });
+    if (explicitGroups.length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["groups"],
+        message: "gateway mode requires explicit group bindings",
+      });
+    }
+    if (Object.prototype.hasOwnProperty.call(groups, "*")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["groups", "*"],
+        message: 'gateway mode does not allow wildcard group "*"',
+      });
+    }
   });
 
 export const GeweAccountSchema = GeweAccountSchemaBase.superRefine((value, ctx) => {

package/src/download.ts

@@ -1,10 +1,55 @@
-import { assertGeweOk, postGeweJson } from "./api.js";
+import { resolveGeweTransportBaseUrl, resolveIsGatewayMode } from "./accounts.js";
+import { assertGeweOk, postGatewayJson, postGeweJson } from "./api.js";
 import type { ResolvedGeweAccount } from "./types.js";
 
 type DownloadResult = { fileUrl: string };
 
-function resolveBaseUrl(account: ResolvedGeweAccount): string {
-  return account.config.apiBaseUrl?.trim() || "https://www.geweapi.com";
+type DownloadContext = {
+  mode: "direct" | "gateway";
+  baseUrl: string;
+  token?: string;
+  gatewayKey?: string;
+  appId?: string;
+};
+
+function buildContext(account: ResolvedGeweAccount): DownloadContext {
+  if (resolveIsGatewayMode(account)) {
+    return {
+      mode: "gateway",
+      baseUrl: resolveGeweTransportBaseUrl(account),
+      gatewayKey: account.config.gatewayKey?.trim(),
+    };
+  }
+  return {
+    mode: "direct",
+    baseUrl: resolveGeweTransportBaseUrl(account),
+    token: account.token,
+    appId: account.appId,
+  };
+}
+
+async function postDownloadJson(params: {
+  ctx: DownloadContext;
+  path: string;
+  body: Record<string, unknown>;
+}): Promise<{ ret: number; msg: string; data?: DownloadResult }> {
+  if (params.ctx.mode === "gateway") {
+    return postGatewayJson<{ ret: number; msg: string; data?: DownloadResult }>({
+      baseUrl: params.ctx.baseUrl,
+      gatewayKey: params.ctx.gatewayKey?.trim() ?? "",
+      path: params.path,
+      body: params.body,
+    });
+  }
+  return postGeweJson<DownloadResult>({
+    baseUrl: params.ctx.baseUrl,
+    token: params.ctx.token?.trim() ?? "",
+    path: params.path,
+    body: {
+      appId: params.ctx.appId,
+      ...params.body,
+    },
+  });
 }
 
 export async function downloadGeweImage(params: {
@@ -12,12 +57,10 @@ export async function downloadGeweImage(params: {
   xml: string;
   type: 1 | 2 | 3;
 }): Promise<string> {
-  const resp = await postGeweJson<DownloadResult>({
-    baseUrl: resolveBaseUrl(params.account),
-    token: params.account.token,
+  const resp = await postDownloadJson({
+    ctx: buildContext(params.account),
     path: "/gewe/v2/api/message/downloadImage",
     body: {
-      appId: params.account.appId,
       xml: params.xml,
       type: params.type,
     },
@@ -32,12 +75,10 @@ export async function downloadGeweVoice(params: {
   xml: string;
   msgId: number;
 }): Promise<string> {
-  const resp = await postGeweJson<DownloadResult>({
-    baseUrl: resolveBaseUrl(params.account),
-    token: params.account.token,
+  const resp = await postDownloadJson({
+    ctx: buildContext(params.account),
     path: "/gewe/v2/api/message/downloadVoice",
     body: {
-      appId: params.account.appId,
       xml: params.xml,
       msgId: params.msgId,
     },
@@ -51,12 +92,10 @@ export async function downloadGeweVideo(params: {
   account: ResolvedGeweAccount;
   xml: string;
 }): Promise<string> {
-  const resp = await postGeweJson<DownloadResult>({
-    baseUrl: resolveBaseUrl(params.account),
-    token: params.account.token,
+  const resp = await postDownloadJson({
+    ctx: buildContext(params.account),
     path: "/gewe/v2/api/message/downloadVideo",
     body: {
-      appId: params.account.appId,
       xml: params.xml,
     },
   });
@@ -69,12 +108,10 @@ export async function downloadGeweFile(params: {
   account: ResolvedGeweAccount;
   xml: string;
 }): Promise<string> {
-  const resp = await postGeweJson<DownloadResult>({
-    baseUrl: resolveBaseUrl(params.account),
-    token: params.account.token,
+  const resp = await postDownloadJson({
+    ctx: buildContext(params.account),
     path: "/gewe/v2/api/message/downloadFile",
     body: {
-      appId: params.account.appId,
       xml: params.xml,
     },
   });

package/src/gateway-client.ts

@@ -0,0 +1,104 @@
+import {
+  resolveGatewayCallbackUrl,
+  resolveGatewayGroupBindings,
+  resolveGeweTransportBaseUrl,
+} from "./accounts.js";
+import { postGatewayJson } from "./api.js";
+import type { ResolvedGeweAccount } from "./types.js";
+
+type GatewayControlResponse = {
+  ok?: boolean;
+  error?: string;
+};
+
+function requireGatewayField(value: string | undefined, field: string): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    throw new Error(`GeWe gateway ${field} is required`);
+  }
+  return trimmed;
+}
+
+function buildGatewayRegistrationBody(params: {
+  account: ResolvedGeweAccount;
+  pluginVersion: string;
+}) {
+  const callbackUrl = resolveGatewayCallbackUrl(params.account);
+  const groups = resolveGatewayGroupBindings(params.account);
+  return {
+    instanceId: requireGatewayField(params.account.config.gatewayInstanceId, "instanceId"),
+    callbackUrl: requireGatewayField(callbackUrl, "callbackUrl"),
+    callbackSecret: params.account.config.webhookSecret?.trim() ?? "",
+    groups,
+    pluginVersion: params.pluginVersion,
+  };
+}
+
+async function postGatewayControl(params: {
+  account: ResolvedGeweAccount;
+  path: string;
+  body: Record<string, unknown>;
+}): Promise<GatewayControlResponse> {
+  const baseUrl = resolveGeweTransportBaseUrl(params.account);
+  const gatewayKey = requireGatewayField(params.account.config.gatewayKey, "key");
+  return postGatewayJson<GatewayControlResponse>({
+    baseUrl,
+    gatewayKey,
+    path: params.path,
+    body: params.body,
+  });
+}
+
+function assertGatewayOk(
+  response: GatewayControlResponse,
+  action: "register" | "heartbeat" | "unregister",
+): GatewayControlResponse {
+  if (response.ok === false) {
+    throw new Error(response.error?.trim() || `GeWe gateway ${action} failed`);
+  }
+  return response;
+}
+
+export async function registerGatewayInstance(params: {
+  account: ResolvedGeweAccount;
+  pluginVersion: string;
+}): Promise<GatewayControlResponse> {
+  return assertGatewayOk(
+    await postGatewayControl({
+      account: params.account,
+      path: "/gateway/v1/instances/register",
+      body: buildGatewayRegistrationBody(params),
+    }),
+    "register",
+  );
+}
+
+export async function heartbeatGatewayInstance(params: {
+  account: ResolvedGeweAccount;
+}): Promise<GatewayControlResponse> {
+  return assertGatewayOk(
+    await postGatewayControl({
+      account: params.account,
+      path: "/gateway/v1/instances/heartbeat",
+      body: {
+        instanceId: requireGatewayField(params.account.config.gatewayInstanceId, "instanceId"),
+      },
+    }),
+    "heartbeat",
+  );
+}
+
+export async function unregisterGatewayInstance(params: {
+  account: ResolvedGeweAccount;
+}): Promise<GatewayControlResponse> {
+  return assertGatewayOk(
+    await postGatewayControl({
+      account: params.account,
+      path: "/gateway/v1/instances/unregister",
+      body: {
+        instanceId: requireGatewayField(params.account.config.gatewayInstanceId, "instanceId"),
+      },
+    }),
+    "unregister",
+  );
+}

package/src/monitor.ts

@@ -2,11 +2,21 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 
 import type { OpenClawConfig, RuntimeEnv } from "openclaw/plugin-sdk";
 
-import { resolveGeweAccount } from "./accounts.js";
+import {
+  resolveGatewayRegisterIntervalMs,
+  resolveGeweAccount,
+  resolveIsGatewayMode,
+} from "./accounts.js";
 import { GeweDownloadQueue } from "./download-queue.js";
+import {
+  heartbeatGatewayInstance,
+  registerGatewayInstance,
+  unregisterGatewayInstance,
+} from "./gateway-client.js";
 import { createGeweInboundDebouncer } from "./inbound-batch.js";
 import { handleGeweInboundBatch } from "./inbound.js";
 import { createGeweMediaServer, DEFAULT_MEDIA_HOST, DEFAULT_MEDIA_PATH, DEFAULT_MEDIA_PORT } from "./media-server.js";
+import { resolvePluginVersion } from "./plugin-version.js";
 import { getGeweRuntime } from "./runtime.js";
 import type {
   CoreConfig,
@@ -250,7 +260,13 @@ export type GeweMonitorOptions = {
   config?: CoreConfig;
   runtime?: RuntimeEnv;
   abortSignal?: AbortSignal;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  statusSink?: (patch: {
+    lastInboundAt?: number;
+    lastOutboundAt?: number;
+    lastGatewayRegisterAt?: number;
+    lastGatewayHeartbeatAt?: number;
+    lastGatewayError?: string | null;
+  }) => void;
 };
 
 export async function monitorGeweProvider(
@@ -267,7 +283,8 @@ export async function monitorGeweProvider(
     },
   };
 
-  if (!account.token || !account.appId) {
+  const gatewayMode = resolveIsGatewayMode(account);
+  if (!gatewayMode && (!account.token || !account.appId)) {
     throw new Error(`GeWe not configured for account "${account.accountId}" (token/appId missing)`);
   }
 
@@ -339,18 +356,85 @@ export async function monitorGeweProvider(
     );
   }
 
+  let gatewayHeartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  let gatewayStopped = false;
+  const stopGatewayRegistration = () => {
+    if (gatewayStopped) return;
+    gatewayStopped = true;
+    if (gatewayHeartbeatTimer) {
+      clearInterval(gatewayHeartbeatTimer);
+      gatewayHeartbeatTimer = undefined;
+    }
+    if (!gatewayMode) return;
+    void unregisterGatewayInstance({ account }).catch((err) => {
+      runtime.error?.(`[${account.accountId}] GeWe gateway unregister failed: ${String(err)}`);
+    });
+  };
+
+  if (gatewayMode) {
+    const pluginVersion = resolvePluginVersion();
+    await registerGatewayInstance({ account, pluginVersion });
+    opts.statusSink?.({
+      lastGatewayRegisterAt: Date.now(),
+      lastGatewayError: null,
+    });
+    runtime.log?.(
+      `[${account.accountId}] registered GeWe gateway instance ${account.config.gatewayInstanceId?.trim() || account.accountId}`,
+    );
+    const intervalMs = resolveGatewayRegisterIntervalMs(account);
+    gatewayHeartbeatTimer = setInterval(() => {
+      void heartbeatGatewayInstance({ account })
+        .then(() => {
+          opts.statusSink?.({
+            lastGatewayHeartbeatAt: Date.now(),
+            lastGatewayError: null,
+          });
+        })
+        .catch(async (heartbeatError) => {
+          const message = String(heartbeatError);
+          opts.statusSink?.({ lastGatewayError: message });
+          runtime.error?.(
+            `[${account.accountId}] GeWe gateway heartbeat failed: ${message}`,
+          );
+          try {
+            await registerGatewayInstance({ account, pluginVersion });
+            opts.statusSink?.({
+              lastGatewayRegisterAt: Date.now(),
+              lastGatewayError: null,
+            });
+            runtime.log?.(`[${account.accountId}] re-registered GeWe gateway instance`);
+          } catch (registerError) {
+            const registerMessage = String(registerError);
+            opts.statusSink?.({ lastGatewayError: registerMessage });
+            runtime.error?.(
+              `[${account.accountId}] GeWe gateway re-register failed: ${registerMessage}`,
+            );
+          }
+        });
+    }, intervalMs);
+  }
+
   let resolveRunning: (() => void) | undefined;
   const runningPromise = new Promise<void>((resolve) => {
     resolveRunning = resolve;
     if (!opts.abortSignal) return;
     if (opts.abortSignal.aborted) {
+      stopGatewayRegistration();
       resolve();
       return;
     }
-    opts.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    opts.abortSignal.addEventListener(
+      "abort",
+      () => {
+        stopGatewayRegistration();
+        resolve();
+      },
+      { once: true },
+    );
   });
 
   const stop = () => {
+    stopGatewayRegistration();
     void debouncer.flushAll();
     webhookServer.stop();
     if (mediaStop) mediaStop();

package/src/onboarding.ts

@@ -2,7 +2,12 @@ import type { ChannelPlugin, OpenClawConfig, WizardPrompter } from "openclaw/plu
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
 
 import type { CoreConfig, GeweAccountConfig, ResolvedGeweAccount } from "./types.js";
-import { resolveGeweAccount, resolveDefaultGeweAccountId, listGeweAccountIds } from "./accounts.js";
+import {
+  listGeweAccountIds,
+  resolveDefaultGeweAccountId,
+  resolveGeweAccount,
+  resolveIsGeweAccountConfigured,
+} from "./accounts.js";
 import { CHANNEL_CONFIG_KEY, CHANNEL_ID, stripChannelPrefix } from "./constants.js";
 
 const DEFAULT_WEBHOOK_HOST = "0.0.0.0";
@@ -69,6 +74,14 @@ function parseAllowFrom(raw: string): string[] {
     .filter(Boolean);
 }
 
+function parseGroupIds(raw: string): string[] {
+  return raw
+    .split(/[\n,;]+/g)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .filter((entry) => entry !== "*");
+}
+
 async function promptAllowFrom(params: {
   prompter: WizardPrompter;
   existing?: Array<string | number>;
@@ -148,9 +161,9 @@ export const geweOnboarding: GeweOnboardingAdapter = {
       ctx.accountOverrides?.[CHANNEL_ID] ??
       resolveDefaultGeweAccountId(ctx.cfg as CoreConfig);
     const account = resolveGeweAccount({ cfg: ctx.cfg as CoreConfig, accountId });
-    const configured = Boolean(account.token?.trim() && account.appId?.trim());
+    const configured = resolveIsGeweAccountConfigured(account);
     const label = configured ? "configured" : "not configured";
-    const status = `GeWe (${accountId}): ${label}`;
+    const status = `GeWe (${accountId}, ${account.mode ?? "direct"}): ${label}`;
     return {
       channel: CHANNEL_ID,
       configured,
@@ -165,33 +178,83 @@ export const geweOnboarding: GeweOnboardingAdapter = {
       : resolveDefaultGeweAccountId(ctx.cfg as CoreConfig);
     const resolved = resolveGeweAccount({ cfg: ctx.cfg as CoreConfig, accountId });
     const existing = readAccountConfig(ctx.cfg, accountId);
+    const mode = await ctx.prompter.select({
+      message: "Connection mode",
+      options: [
+        { value: "direct", label: "Direct GeWe API" },
+        { value: "gateway", label: "Gateway mode" },
+      ],
+      initialValue: resolved.mode ?? "direct",
+    });
 
     await ctx.prompter.note(
-      [
-        "You will need:",
-        "- GeWe token + appId",
-        "- Public webhook endpoint (FRP or reverse proxy)",
-        "- Public media base URL (optional proxy fallback)",
-      ].join("\n"),
+      mode === "gateway"
+        ? [
+            "You will need:",
+            "- Gateway URL + gateway key",
+            "- Gateway instance id",
+            "- Public webhook endpoint reachable by the gateway",
+            "- Explicit WeChat group ids (chatroom ids) for routing",
+            "- Public media base URL (optional proxy fallback)",
+          ].join("\n")
+        : [
+            "You will need:",
+            "- GeWe token + appId",
+            "- Public webhook endpoint (FRP or reverse proxy)",
+            "- Public media base URL (optional proxy fallback)",
+          ].join("\n"),
       "GeWe setup",
     );
 
-    const token = await ctx.prompter.text({
-      message: "GeWe token",
-      initialValue: resolved.tokenSource !== "none" ? resolved.token : existing.token,
-      validate: (value) => (value.trim() ? undefined : "Required"),
-    });
-    const appId = await ctx.prompter.text({
-      message: "GeWe appId",
-      initialValue: resolved.appIdSource !== "none" ? resolved.appId : existing.appId,
-      validate: (value) => (value.trim() ? undefined : "Required"),
-    });
+    const token =
+      mode === "direct"
+        ? await ctx.prompter.text({
+            message: "GeWe token",
+            initialValue: resolved.tokenSource !== "none" ? resolved.token : existing.token,
+            validate: (value) => (value.trim() ? undefined : "Required"),
+          })
+        : "";
+    const appId =
+      mode === "direct"
+        ? await ctx.prompter.text({
+            message: "GeWe appId",
+            initialValue: resolved.appIdSource !== "none" ? resolved.appId : existing.appId,
+            validate: (value) => (value.trim() ? undefined : "Required"),
+          })
+        : "";
 
-    const apiBaseUrl = await ctx.prompter.text({
-      message: "GeWe API base URL",
-      initialValue: existing.apiBaseUrl ?? DEFAULT_API_BASE_URL,
-      validate: (value) => (value.trim() ? undefined : "Required"),
-    });
+    const gatewayUrl =
+      mode === "gateway"
+        ? await ctx.prompter.text({
+            message: "Gateway URL",
+            initialValue: existing.gatewayUrl,
+            validate: (value) => (value.trim() ? undefined : "Required"),
+          })
+        : "";
+    const gatewayKey =
+      mode === "gateway"
+        ? await ctx.prompter.text({
+            message: "Gateway key",
+            initialValue: existing.gatewayKey,
+            validate: (value) => (value.trim() ? undefined : "Required"),
+          })
+        : "";
+    const gatewayInstanceId =
+      mode === "gateway"
+        ? await ctx.prompter.text({
+            message: "Gateway instance id",
+            initialValue: existing.gatewayInstanceId ?? accountId,
+            validate: (value) => (value.trim() ? undefined : "Required"),
+          })
+        : "";
+    const apiBaseUrl =
+      mode === "direct"
+        ? await ctx.prompter.text({
+            message: "GeWe API base URL",
+            initialValue: existing.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+            validate: (value) => (value.trim() ? undefined : "Required"),
+          })
+        : "";
 
     const webhookHost = await ctx.prompter.text({
       message: "Webhook host",
@@ -212,6 +275,31 @@ export const geweOnboarding: GeweOnboardingAdapter = {
       initialValue: existing.webhookPath ?? DEFAULT_WEBHOOK_PATH,
       validate: (value) => (value.trim() ? undefined : "Required"),
     });
+    const webhookPublicUrl =
+      mode === "gateway"
+        ? await ctx.prompter.text({
+            message: "Webhook public URL",
+            placeholder: "https://openclaw.example.com/webhook",
+            initialValue: existing.webhookPublicUrl,
+            validate: (value) => (value.trim() ? undefined : "Required"),
+          })
+        : existing.webhookPublicUrl;
+    const gatewayGroups =
+      mode === "gateway"
+        ? parseGroupIds(
+            String(
+              await ctx.prompter.text({
+                message: "Gateway group ids (comma or newline separated)",
+                placeholder: "123456@chatroom",
+                initialValue: Object.keys(existing.groups ?? {})
+                  .filter((groupId) => groupId !== "*")
+                  .join(", "),
+                validate: (value) =>
+                  parseGroupIds(value).length > 0 ? undefined : "At least one group is required",
+              }),
+            ),
+          )
+        : [];
 
     const mediaPublicUrl = await ctx.prompter.text({
       message: "Media public URL (prefix)",
@@ -346,16 +434,31 @@ export const geweOnboarding: GeweOnboardingAdapter = {
 
     let nextCfg = applyAccountPatch(ctx.cfg, accountId, {
       enabled: true,
-      token: token.trim(),
-      appId: appId.trim(),
-      apiBaseUrl: apiBaseUrl.trim().replace(/\/$/, ""),
+      token: mode === "direct" ? token.trim() : undefined,
+      appId: mode === "direct" ? appId.trim() : undefined,
+      apiBaseUrl:
+        mode === "direct" ? apiBaseUrl.trim().replace(/\/$/, "") : undefined,
+      gatewayUrl: mode === "gateway" ? gatewayUrl.trim().replace(/\/$/, "") : undefined,
+      gatewayKey: mode === "gateway" ? gatewayKey.trim() : undefined,
+      gatewayInstanceId: mode === "gateway" ? gatewayInstanceId.trim() : undefined,
       webhookHost: webhookHost.trim(),
       webhookPort: Number(webhookPortRaw),
       webhookPath: webhookPath.trim(),
+      webhookPublicUrl:
+        mode === "gateway" ? webhookPublicUrl?.trim() || undefined : existing.webhookPublicUrl,
       mediaHost: existing.mediaHost ?? DEFAULT_MEDIA_HOST,
       mediaPort: existing.mediaPort ?? DEFAULT_MEDIA_PORT,
       mediaPath: existing.mediaPath ?? DEFAULT_MEDIA_PATH,
       mediaPublicUrl: mediaPublicUrl.trim() || undefined,
+      groups:
+        mode === "gateway"
+          ? Object.fromEntries(
+              gatewayGroups.map((groupId) => [
+                groupId,
+                existing.groups?.[groupId] ?? { enabled: true },
+              ]),
+            )
+          : existing.groups,
       ...s3Patch,
       ...(allowFrom ? { allowFrom } : {}),
       ...(dmPolicy ? { dmPolicy } : {}),

package/src/plugin-version.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+
+let cachedVersion: string | undefined;
+
+export function resolvePluginVersion(): string {
+  if (cachedVersion) return cachedVersion;
+  try {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    const version = parsed.version?.trim();
+    cachedVersion = version || "0.0.0";
+  } catch {
+    cachedVersion = "0.0.0";
+  }
+  return cachedVersion;
+}

package/src/send.ts

@@ -1,15 +1,53 @@
-import { assertGeweOk, postGeweJson } from "./api.js";
+import { resolveGeweTransportBaseUrl, resolveIsGatewayMode } from "./accounts.js";
+import { assertGeweOk, postGatewayJson, postGeweJson } from "./api.js";
 import type { GeweSendResult, ResolvedGeweAccount } from "./types.js";
 
 type GeweSendContext = {
   baseUrl: string;
-  token: string;
-  appId: string;
+  mode: "direct" | "gateway";
+  token?: string;
+  gatewayKey?: string;
+  appId?: string;
 };
 
 function buildContext(account: ResolvedGeweAccount): GeweSendContext {
-  const baseUrl = account.config.apiBaseUrl?.trim() || "https://www.geweapi.com";
-  return { baseUrl, token: account.token, appId: account.appId };
+  if (resolveIsGatewayMode(account)) {
+    return {
+      mode: "gateway",
+      baseUrl: resolveGeweTransportBaseUrl(account),
+      gatewayKey: account.config.gatewayKey?.trim(),
+    };
+  }
+  return {
+    mode: "direct",
+    baseUrl: resolveGeweTransportBaseUrl(account),
+    token: account.token,
+    appId: account.appId,
+  };
+}
+
+async function postSendJson<T>(params: {
+  ctx: GeweSendContext;
+  path: string;
+  body: Record<string, unknown>;
+}): Promise<{ ret: number; msg: string; data?: T }> {
+  if (params.ctx.mode === "gateway") {
+    return postGatewayJson<{ ret: number; msg: string; data?: T }>({
+      baseUrl: params.ctx.baseUrl,
+      gatewayKey: params.ctx.gatewayKey?.trim() ?? "",
+      path: params.path,
+      body: params.body,
+    });
+  }
+  return postGeweJson<T>({
+    baseUrl: params.ctx.baseUrl,
+    token: params.ctx.token?.trim() ?? "",
+    path: params.path,
+    body: {
+      appId: params.ctx.appId,
+      ...params.body,
+    },
+  });
 }
 
 function resolveSendResult(params: {
@@ -37,16 +75,14 @@ export async function sendTextGewe(params: {
   ats?: string;
 }): Promise<GeweSendResult> {
   const ctx = buildContext(params.account);
-  const resp = await postGeweJson<{
+  const resp = await postSendJson<{
     msgId?: number | string;
     newMsgId?: number | string;
     createTime?: number;
   }>({
-    baseUrl: ctx.baseUrl,
-    token: ctx.token,
+    ctx,
     path: "/gewe/v2/api/message/postText",
     body: {
-      appId: ctx.appId,
       toWxid: params.toWxid,
       content: params.content,
       ...(params.ats ? { ats: params.ats } : {}),
@@ -62,12 +98,10 @@ export async function sendImageGewe(params: {
   imgUrl: string;
 }): Promise<GeweSendResult> {
   const ctx = buildContext(params.account);
-  const resp = await postGeweJson({
-    baseUrl: ctx.baseUrl,
-    token: ctx.token,
+  const resp = await postSendJson({
+    ctx,
     path: "/gewe/v2/api/message/postImage",
     body: {
-      appId: ctx.appId,
       toWxid: params.toWxid,
       imgUrl: params.imgUrl,
     },
@@ -83,12 +117,10 @@ export async function sendVoiceGewe(params: {
   voiceDuration: number;
 }): Promise<GeweSendResult> {
   const ctx = buildContext(params.account);
-  const resp = await postGeweJson({
-    baseUrl: ctx.baseUrl,
-    token: ctx.token,
+  const resp = await postSendJson({
+    ctx,
     path: "/gewe/v2/api/message/postVoice",
     body: {
-      appId: ctx.appId,
       toWxid: params.toWxid,
       voiceUrl: params.voiceUrl,
       voiceDuration: params.voiceDuration,
@@ -106,12 +138,10 @@ export async function sendVideoGewe(params: {
   videoDuration: number;
 }): Promise<GeweSendResult> {
   const ctx = buildContext(params.account);
-  const resp = await postGeweJson({
-    baseUrl: ctx.baseUrl,
-    token: ctx.token,
+  const resp = await postSendJson({
+    ctx,
     path: "/gewe/v2/api/message/postVideo",
     body: {
-      appId: ctx.appId,
       toWxid: params.toWxid,
       videoUrl: params.videoUrl,
       thumbUrl: params.thumbUrl,
@@ -129,12 +159,10 @@ export async function sendFileGewe(params: {
   fileName: string;
 }): Promise<GeweSendResult> {
   const ctx = buildContext(params.account);
-  const resp = await postGeweJson({
-    baseUrl: ctx.baseUrl,
-    token: ctx.token,
+  const resp = await postSendJson({
+    ctx,
     path: "/gewe/v2/api/message/postFile",
     body: {
-      appId: ctx.appId,
       toWxid: params.toWxid,
       fileUrl: params.fileUrl,
       fileName: params.fileName,
@@ -153,12 +181,10 @@ export async function sendLinkGewe(params: {
   thumbUrl: string;
 }): Promise<GeweSendResult> {
   const ctx = buildContext(params.account);
-  const resp = await postGeweJson({
-    baseUrl: ctx.baseUrl,
-    token: ctx.token,
+  const resp = await postSendJson({
+    ctx,
     path: "/gewe/v2/api/message/postLink",
     body: {
-      appId: ctx.appId,
       toWxid: params.toWxid,
       title: params.title,
       desc: params.desc,

package/src/types.ts

@@ -19,6 +19,10 @@ export type GeweAccountConfig = {
   name?: string;
   enabled?: boolean;
   apiBaseUrl?: string;
+  gatewayUrl?: string;
+  gatewayKey?: string;
+  gatewayInstanceId?: string;
+  gatewayRegisterIntervalSec?: number;
   token?: string;
   tokenFile?: string;
   appId?: string;
@@ -99,6 +103,7 @@ export type ResolvedGeweAccount = {
   accountId: string;
   name?: string;
   enabled: boolean;
+  mode?: "direct" | "gateway";
   token: string;
   tokenSource: GeweTokenSource;
   appId: string;