gewe-openclaw 2026.2.4 → 2026.3.2

package/README.md

@@ -42,7 +42,7 @@ openclaw plugins install ./gewe-openclaw.tgz
 openclaw onboard
 ```
 
-在通道列表中选择 **GeWe**，按提示填写 `token`、`appId`、`webhook` 与 `mediaPublicUrl` 等信息。
+在通道列表中选择 **GeWe**，按提示填写 `token`、`appId`、`webhook`，以及可选的 `mediaPublicUrl`/`S3` 媒体配置。
 
 ### 方式 B：直接编辑配置文件
 
@@ -66,6 +66,15 @@ openclaw onboard
       "mediaPort": 4400,
       "mediaPath": "/gewe-media",
       "mediaPublicUrl": "https://your-public-domain/gewe-media",
+      "s3Enabled": true,
+      "s3Endpoint": "https://s3.amazonaws.com",
+      "s3Region": "us-east-1",
+      "s3Bucket": "your-bucket",
+      "s3AccessKeyId": "<access-key-id>",
+      "s3SecretAccessKey": "<secret-access-key>",
+      "s3UrlMode": "public",
+      "s3PublicBaseUrl": "https://cdn.example.com/gewe-media",
+      "s3KeyPrefix": "gewe-openclaw/outbound",
       "allowFrom": ["wxid_xxx"]
     }
   }
@@ -75,7 +84,15 @@ openclaw onboard
 完整参数说明：
 - `webhookHost/webhookPort/webhookPath`：GeWe 回调入口（需公网可达，常配合 FRP）。
 - `mediaPath`：本地媒体服务的路由前缀（默认 `/gewe-media`）。
-- `mediaPublicUrl`：公网访问地址的“基础前缀”，会自动拼接媒体 ID。通常应与 `mediaPath` 对齐，例如 `mediaPath="/gewe-media"` 时，`mediaPublicUrl` 也应包含 `/gewe-media`。
+- `mediaPublicUrl`：本地反代回退时的公网地址前缀（可选）。配置后会自动拼接媒体 ID；通常应与 `mediaPath` 对齐。
+- `s3Enabled`：是否启用 S3 兼容上传。
+- `s3Endpoint/s3Region/s3Bucket/s3AccessKeyId/s3SecretAccessKey`：S3 兼容服务连接参数。
+- `s3SessionToken`：临时凭证可选字段。
+- `s3ForcePathStyle`：是否启用 path-style（部分 S3 兼容服务需要）。
+- `s3UrlMode`：`public` 或 `presigned`（默认 `public`）。
+- `s3PublicBaseUrl`：`public` 模式下用于拼接可访问 URL（必填）。
+- `s3PresignExpiresSec`：`presigned` 模式签名有效期（默认 3600 秒）。
+- `s3KeyPrefix`：对象 key 前缀（默认 `gewe-openclaw/outbound`）。
 - `allowFrom`：允许私聊触发的微信 ID（或在群里走 allowlist 规则）。
 - `voiceAutoConvert`：自动将音频转为 silk（默认开启；设为 `false` 可关闭）。
 - `silkAutoDownload`：自动下载 `rust-silk`（默认开启；可关闭后自行配置 `voiceSilkPath` / `voiceDecodePath`）。
@@ -94,6 +111,10 @@ openclaw onboard
  - `mediaMaxMb`：上传媒体大小上限（默认 20MB）。
  - `downloadMinDelayMs`/`downloadMaxDelayMs`：入站媒体下载节流。
 
+发送媒体时的 URL 策略：
+- 本地文件：优先上传 S3，失败回退 `mediaPublicUrl` 本地反代。
+- 公网 URL：先尝试原 URL 发送，失败后再尝试上传 S3，仍失败回退本地反代。
+
 > 配置变更后需重启 Gateway。
 
 ## 高级用法：让未安装插件也出现在 onboarding 列表

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gewe-openclaw",
-  "version": "2026.2.4",
+  "version": "2026.3.2",
   "type": "module",
   "description": "OpenClaw GeWe channel plugin",
   "license": "MIT",
@@ -32,6 +32,8 @@
     }
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.922.0",
+    "@aws-sdk/s3-request-presigner": "^3.922.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {

package/src/config-schema.ts

@@ -40,6 +40,18 @@ export const GeweAccountSchemaBase = z
     mediaPath: z.string().optional(),
     mediaPublicUrl: z.string().optional(),
     mediaMaxMb: z.number().positive().optional(),
+    s3Enabled: z.boolean().optional(),
+    s3Endpoint: z.string().optional(),
+    s3Region: z.string().optional(),
+    s3Bucket: z.string().optional(),
+    s3AccessKeyId: z.string().optional(),
+    s3SecretAccessKey: z.string().optional(),
+    s3SessionToken: z.string().optional(),
+    s3ForcePathStyle: z.boolean().optional(),
+    s3PublicBaseUrl: z.string().optional(),
+    s3KeyPrefix: z.string().optional(),
+    s3UrlMode: z.enum(["public", "presigned"]).optional(),
+    s3PresignExpiresSec: z.number().int().positive().optional(),
     voiceAutoConvert: z.boolean().optional(),
     voiceFfmpegPath: z.string().optional(),
     voiceSilkPath: z.string().optional(),
@@ -85,6 +97,37 @@ export const GeweAccountSchemaBase = z
         message: "downloadMaxDelayMs must be >= downloadMinDelayMs",
       });
     }
+
+    if (value.s3Enabled === true) {
+      const required: Array<keyof typeof value> = [
+        "s3Endpoint",
+        "s3Region",
+        "s3Bucket",
+        "s3AccessKeyId",
+        "s3SecretAccessKey",
+      ];
+      for (const key of required) {
+        const raw = value[key];
+        if (typeof raw !== "string" || !raw.trim()) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [key],
+            message: `${String(key)} is required when s3Enabled=true`,
+          });
+        }
+      }
+      const mode = value.s3UrlMode ?? "public";
+      if (mode === "public") {
+        const base = value.s3PublicBaseUrl?.trim();
+        if (!base) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["s3PublicBaseUrl"],
+            message: "s3PublicBaseUrl is required when s3UrlMode=public",
+          });
+        }
+      }
+    }
   });
 
 export const GeweAccountSchema = GeweAccountSchemaBase.superRefine((value, ctx) => {

package/src/delivery.ts

@@ -9,6 +9,7 @@ import type { OpenClawConfig, ReplyPayload } from "openclaw/plugin-sdk";
 import { extractOriginalFilename, extensionForMime } from "openclaw/plugin-sdk";
 import { CHANNEL_ID } from "./constants.js";
 import { getGeweRuntime } from "./runtime.js";
+import { resolveS3Config, uploadToS3 } from "./s3.js";
 import { ensureRustSilkBinary } from "./silk.js";
 import {
   sendFileGewe,
@@ -43,6 +44,9 @@ type ResolvedMedia = {
   contentType?: string;
   fileName?: string;
   localPath?: string;
+  sourceKind: "remote" | "local";
+  sourceUrl: string;
+  provider: "direct" | "s3" | "proxy";
 };
 
 const LINK_THUMB_MAX_BYTES = 50 * 1024;
@@ -94,6 +98,21 @@ function buildPublicUrl(baseUrl: string, id: string): string {
   return `${trimmed}/${encodeURIComponent(id)}`;
 }
 
+function hasProxyBase(account: ResolvedGeweAccount): boolean {
+  return Boolean(account.config.mediaPublicUrl?.trim());
+}
+
+function hasS3(account: ResolvedGeweAccount): boolean {
+  return account.config.s3Enabled === true;
+}
+
+function resolveFallbackProviders(account: ResolvedGeweAccount): Array<"s3" | "proxy"> {
+  const providers: Array<"s3" | "proxy"> = [];
+  if (hasS3(account)) providers.push("s3");
+  if (hasProxyBase(account)) providers.push("proxy");
+  return providers;
+}
+
 function resolveMediaMaxBytes(account: ResolvedGeweAccount): number {
   const maxMb = account.config.mediaMaxMb;
   if (typeof maxMb === "number" && maxMb > 0) return Math.floor(maxMb * 1024 * 1024);
@@ -553,11 +572,6 @@ async function stageThumbBuffer(params: {
   fileName?: string;
 }): Promise<string> {
   const core = getGeweRuntime();
-  const publicBase = params.account.config.mediaPublicUrl?.trim();
-  if (!publicBase) {
-    throw new Error("mediaPublicUrl not configured (required for link thumbnails)");
-  }
-
   const normalized = await normalizeThumbBuffer({
     buffer: params.buffer,
     contentType: params.contentType,
@@ -566,6 +580,31 @@ async function stageThumbBuffer(params: {
     throw new Error("link thumbnail exceeds 50KB after resize");
   }
 
+  if (hasS3(params.account)) {
+    try {
+      const s3Config = resolveS3Config(params.account.config);
+      if (!s3Config) throw new Error("s3 not configured");
+      const uploaded = await uploadToS3({
+        config: s3Config,
+        accountId: params.account.accountId,
+        buffer: normalized.buffer,
+        contentType: normalized.contentType,
+        fileName: params.fileName,
+      });
+      return uploaded.url;
+    } catch (err) {
+      if (!hasProxyBase(params.account)) {
+        throw new Error(`s3 thumb upload failed and proxy fallback unavailable: ${String(err)}`);
+      }
+      const logger = core.logging.getChildLogger({ channel: CHANNEL_ID, module: "thumb" });
+      logger.warn?.(`gewe thumb s3 upload failed, fallback proxy: ${String(err)}`);
+    }
+  }
+
+  const publicBase = params.account.config.mediaPublicUrl?.trim();
+  if (!publicBase) {
+    throw new Error("mediaPublicUrl not configured (required for thumbnail fallback)");
+  }
   const saved = await core.channel.media.saveMediaBuffer(
     normalized.buffer,
     normalized.contentType,
@@ -638,26 +677,27 @@ async function stageMedia(params: {
   const core = getGeweRuntime();
   const rawUrl = normalizeMediaToken(params.mediaUrl);
   if (!rawUrl) throw new Error("mediaUrl is empty");
-
-  if (looksLikeHttpUrl(rawUrl) && params.allowRemote) {
+  const isRemote = looksLikeHttpUrl(rawUrl);
+  if (isRemote && params.allowRemote) {
     const contentType = await core.media.detectMime({ filePath: rawUrl });
     const fileName = path.basename(new URL(rawUrl).pathname || "");
-    return { publicUrl: rawUrl, contentType: contentType ?? undefined, fileName };
-  }
-
-  const publicBase = params.account.config.mediaPublicUrl?.trim();
-  if (!publicBase) {
-    throw new Error(
-      "mediaPublicUrl not configured (required for local media or forced proxy)",
-    );
+    return {
+      publicUrl: rawUrl,
+      contentType: contentType ?? undefined,
+      fileName,
+      sourceKind: "remote",
+      sourceUrl: rawUrl,
+      provider: "direct",
+    };
   }
 
   const maxBytes = resolveMediaMaxBytes(params.account);
   let buffer: Buffer;
   let contentType: string | undefined;
   let fileName: string | undefined;
+  let sourceLocalPath: string | undefined;
 
-  if (looksLikeHttpUrl(rawUrl)) {
+  if (isRemote) {
     const fetched = await core.channel.media.fetchRemoteMedia({
       url: rawUrl,
       maxBytes,
@@ -671,6 +711,41 @@ async function stageMedia(params: {
     buffer = await fs.readFile(localPath);
     contentType = await core.media.detectMime({ buffer, filePath: localPath });
     fileName = path.basename(localPath);
+    sourceLocalPath = localPath;
+  }
+
+  if (hasS3(params.account)) {
+    try {
+      const s3Config = resolveS3Config(params.account.config);
+      if (!s3Config) throw new Error("s3 not configured");
+      const uploaded = await uploadToS3({
+        config: s3Config,
+        accountId: params.account.accountId,
+        buffer,
+        contentType,
+        fileName,
+      });
+      return {
+        publicUrl: uploaded.url,
+        contentType,
+        fileName,
+        localPath: sourceLocalPath,
+        sourceKind: isRemote ? "remote" : "local",
+        sourceUrl: rawUrl,
+        provider: "s3",
+      };
+    } catch (err) {
+      if (!hasProxyBase(params.account)) {
+        throw new Error(`s3 upload failed and proxy fallback unavailable: ${String(err)}`);
+      }
+      const logger = core.logging.getChildLogger({ channel: CHANNEL_ID, module: "media" });
+      logger.warn?.(`gewe s3 upload failed, fallback to proxy: ${String(err)}`);
+    }
+  }
+
+  const publicBase = params.account.config.mediaPublicUrl?.trim();
+  if (!publicBase) {
+    throw new Error("mediaPublicUrl not configured (required for proxy fallback)");
   }
 
   const saved = await core.channel.media.saveMediaBuffer(
@@ -684,8 +759,7 @@ async function stageMedia(params: {
   let resolvedId = saved.id;
   let resolvedPath = saved.path;
   const desiredExt =
-    extensionForMime(contentType ?? saved.contentType) ||
-    path.extname(resolvedFileName);
+    extensionForMime(contentType ?? saved.contentType) || path.extname(resolvedFileName);
   if (desiredExt && !path.extname(resolvedId)) {
     const nextId = `${resolvedId}${desiredExt}`;
     const nextPath = path.join(path.dirname(saved.path), nextId);
@@ -697,7 +771,10 @@ async function stageMedia(params: {
     publicUrl: buildPublicUrl(publicBase, resolvedId),
     contentType: contentType ?? saved.contentType,
     fileName: resolvedFileName || resolvedId,
-    localPath: resolvedPath,
+    localPath: sourceLocalPath ?? resolvedPath,
+    sourceKind: isRemote ? "remote" : "local",
+    sourceUrl: rawUrl,
+    provider: "proxy",
   };
 }
 
@@ -716,6 +793,29 @@ async function resolvePublicUrl(params: {
   return staged.publicUrl;
 }
 
+function shouldRetryWithStagedFallback(params: {
+  originalUrl: string;
+  staged: ResolvedMedia;
+  account: ResolvedGeweAccount;
+}): boolean {
+  if (!looksLikeHttpUrl(params.originalUrl)) return false;
+  if (params.staged.provider !== "direct") return false;
+  return resolveFallbackProviders(params.account).length > 0;
+}
+
+async function stageFallbackFromRemote(params: {
+  account: ResolvedGeweAccount;
+  cfg: OpenClawConfig;
+  originalUrl: string;
+}): Promise<ResolvedMedia> {
+  return await stageMedia({
+    account: params.account,
+    cfg: params.cfg,
+    mediaUrl: params.originalUrl,
+    allowRemote: false,
+  });
+}
+
 export async function deliverGewePayload(params: {
   payload: ReplyPayload;
   account: ResolvedGeweAccount;
@@ -774,12 +874,34 @@ export async function deliverGewePayload(params: {
       const declaredDuration = resolveVoiceDurationMs(geweData);
       if (isSilkAudio({ contentType, fileName })) {
         if (declaredDuration) {
-          const result = await sendVoiceGewe({
-            account,
-            toWxid,
-            voiceUrl: staged.publicUrl,
-            voiceDuration: declaredDuration,
-          });
+          let result: GeweSendResult;
+          try {
+            result = await sendVoiceGewe({
+              account,
+              toWxid,
+              voiceUrl: staged.publicUrl,
+              voiceDuration: declaredDuration,
+            });
+          } catch (err) {
+            if (!shouldRetryWithStagedFallback({
+              originalUrl: normalizedMediaUrl,
+              staged,
+              account,
+            })) {
+              throw err;
+            }
+            const fallback = await stageFallbackFromRemote({
+              account,
+              cfg,
+              originalUrl: normalizedMediaUrl,
+            });
+            result = await sendVoiceGewe({
+              account,
+              toWxid,
+              voiceUrl: fallback.publicUrl,
+              voiceDuration: declaredDuration,
+            });
+          }
           core.channel.activity.record({
             channel: CHANNEL_ID,
             accountId: account.accountId,
@@ -795,21 +917,56 @@ export async function deliverGewePayload(params: {
         });
         if (converted) {
           const voiceDuration = declaredDuration ?? converted.durationMs;
-          const publicBase = account.config.mediaPublicUrl?.trim();
-          if (!publicBase) {
-            throw new Error("mediaPublicUrl not configured (required for silk voice)");
+          let voiceUrl: string;
+          if (hasS3(account)) {
+            try {
+              const s3Config = resolveS3Config(account.config);
+              if (!s3Config) throw new Error("s3 not configured");
+              const uploaded = await uploadToS3({
+                config: s3Config,
+                accountId: account.accountId,
+                buffer: converted.buffer,
+                contentType: "audio/silk",
+                fileName: "voice.silk",
+              });
+              voiceUrl = uploaded.url;
+            } catch (err) {
+              if (!hasProxyBase(account)) {
+                throw new Error(
+                  `s3 silk upload failed and proxy fallback unavailable: ${String(err)}`,
+                );
+              }
+              const publicBase = account.config.mediaPublicUrl?.trim();
+              if (!publicBase) {
+                throw new Error("mediaPublicUrl not configured (required for silk voice)");
+              }
+              const saved = await core.channel.media.saveMediaBuffer(
+                converted.buffer,
+                "audio/silk",
+                "outbound",
+                resolveMediaMaxBytes(account),
+                "voice.silk",
+              );
+              voiceUrl = buildPublicUrl(publicBase, saved.id);
+            }
+          } else {
+            const publicBase = account.config.mediaPublicUrl?.trim();
+            if (!publicBase) {
+              throw new Error("mediaPublicUrl not configured (required for silk voice)");
+            }
+            const saved = await core.channel.media.saveMediaBuffer(
+              converted.buffer,
+              "audio/silk",
+              "outbound",
+              resolveMediaMaxBytes(account),
+              "voice.silk",
+            );
+            voiceUrl = buildPublicUrl(publicBase, saved.id);
           }
-          const saved = await core.channel.media.saveMediaBuffer(
-            converted.buffer,
-            "audio/silk",
-            "outbound",
-            resolveMediaMaxBytes(account),
-            "voice.silk",
-          );
           const result = await sendVoiceGewe({
             account,
             toWxid,
-            voiceUrl: buildPublicUrl(publicBase, saved.id),
+            voiceUrl,
             voiceDuration,
           });
           core.channel.activity.record({
@@ -824,11 +981,32 @@ export async function deliverGewePayload(params: {
     }
 
     if (!forceFile && kind === "image") {
-      const result = await sendImageGewe({
-        account,
-        toWxid,
-        imgUrl: staged.publicUrl,
-      });
+      let result: GeweSendResult;
+      try {
+        result = await sendImageGewe({
+          account,
+          toWxid,
+          imgUrl: staged.publicUrl,
+        });
+      } catch (err) {
+        if (!shouldRetryWithStagedFallback({
+          originalUrl: normalizedMediaUrl,
+          staged,
+          account,
+        })) {
+          throw err;
+        }
+        const fallback = await stageFallbackFromRemote({
+          account,
+          cfg,
+          originalUrl: normalizedMediaUrl,
+        });
+        result = await sendImageGewe({
+          account,
+          toWxid,
+          imgUrl: fallback.publicUrl,
+        });
+      }
       core.channel.activity.record({
         channel: CHANNEL_ID,
         accountId: account.accountId,
@@ -902,6 +1080,11 @@ export async function deliverGewePayload(params: {
           url: thumbUrl,
           allowRemote: true,
         });
+        const canRetryMediaFallback = shouldRetryWithStagedFallback({
+          originalUrl: normalizedMediaUrl,
+          staged: stagedVideo,
+          account,
+        });
         try {
           const result = await sendVideoGewe({
             account,
@@ -918,6 +1101,33 @@ export async function deliverGewePayload(params: {
           statusSink?.({ lastOutboundAt: Date.now() });
           return result;
         } catch (err) {
+          if (canRetryMediaFallback) {
+            const fallbackVideo = await stageFallbackFromRemote({
+              account,
+              cfg,
+              originalUrl: normalizedMediaUrl,
+            });
+            const fallbackThumb = await resolvePublicUrl({
+              account,
+              cfg,
+              url: thumbUrl,
+              allowRemote: false,
+            });
+            const result = await sendVideoGewe({
+              account,
+              toWxid,
+              videoUrl: fallbackVideo.publicUrl,
+              thumbUrl: fallbackThumb,
+              videoDuration: Math.floor(videoDuration),
+            });
+            core.channel.activity.record({
+              channel: CHANNEL_ID,
+              accountId: account.accountId,
+              direction: "outbound",
+            });
+            statusSink?.({ lastOutboundAt: Date.now() });
+            return result;
+          }
           if (fallbackThumbUrl && fallbackThumbUrl !== thumbUrl) {
             logger.warn?.(
               `gewe video send failed with primary thumb, retrying fallback: ${String(err)}`,
@@ -952,12 +1162,34 @@ export async function deliverGewePayload(params: {
       geweData?.fileName ||
       fileName ||
       (contentType ? `file${contentType.includes("/") ? `.${contentType.split("/")[1]}` : ""}` : "file");
-    const result = await sendFileGewe({
-      account,
-      toWxid,
-      fileUrl: staged.publicUrl,
-      fileName: fallbackName,
-    });
+    let result: GeweSendResult;
+    try {
+      result = await sendFileGewe({
+        account,
+        toWxid,
+        fileUrl: staged.publicUrl,
+        fileName: fallbackName,
+      });
+    } catch (err) {
+      if (!shouldRetryWithStagedFallback({
+        originalUrl: normalizedMediaUrl,
+        staged,
+        account,
+      })) {
+        throw err;
+      }
+      const fallback = await stageFallbackFromRemote({
+        account,
+        cfg,
+        originalUrl: normalizedMediaUrl,
+      });
+      result = await sendFileGewe({
+        account,
+        toWxid,
+        fileUrl: fallback.publicUrl,
+        fileName: fallbackName,
+      });
+    }
     core.channel.activity.record({
       channel: CHANNEL_ID,
       accountId: account.accountId,

package/src/onboarding.ts

@@ -171,7 +171,7 @@ export const geweOnboarding: GeweOnboardingAdapter = {
         "You will need:",
         "- GeWe token + appId",
         "- Public webhook endpoint (FRP or reverse proxy)",
-        "- Public media base URL (for sending voice/media)",
+        "- Public media base URL (optional proxy fallback)",
       ].join("\n"),
       "GeWe setup",
     );
@@ -217,9 +217,109 @@ export const geweOnboarding: GeweOnboardingAdapter = {
       message: "Media public URL (prefix)",
       placeholder: "https://your-domain/gewe-media",
       initialValue: existing.mediaPublicUrl,
-      validate: (value) => (value.trim() ? undefined : "Required"),
     });
 
+    const enableS3 = await ctx.prompter.confirm({
+      message: "Enable S3-compatible media delivery?",
+      initialValue: existing.s3Enabled === true,
+    });
+    let s3Patch: Partial<GeweAccountConfig> = {};
+    if (enableS3) {
+      const s3Endpoint = await ctx.prompter.text({
+        message: "S3 endpoint",
+        placeholder: "https://s3.amazonaws.com",
+        initialValue: existing.s3Endpoint,
+        validate: (value) => (value.trim() ? undefined : "Required"),
+      });
+      const s3Region = await ctx.prompter.text({
+        message: "S3 region",
+        placeholder: "us-east-1",
+        initialValue: existing.s3Region,
+        validate: (value) => (value.trim() ? undefined : "Required"),
+      });
+      const s3Bucket = await ctx.prompter.text({
+        message: "S3 bucket",
+        initialValue: existing.s3Bucket,
+        validate: (value) => (value.trim() ? undefined : "Required"),
+      });
+      const s3AccessKeyId = await ctx.prompter.text({
+        message: "S3 access key id",
+        initialValue: existing.s3AccessKeyId,
+        validate: (value) => (value.trim() ? undefined : "Required"),
+      });
+      const s3SecretAccessKey = await ctx.prompter.text({
+        message: "S3 secret access key",
+        initialValue: existing.s3SecretAccessKey,
+        validate: (value) => (value.trim() ? undefined : "Required"),
+      });
+      const s3SessionToken = await ctx.prompter.text({
+        message: "S3 session token (optional)",
+        initialValue: existing.s3SessionToken,
+      });
+      const s3ForcePathStyle = await ctx.prompter.confirm({
+        message: "Use path-style for S3 endpoint?",
+        initialValue: existing.s3ForcePathStyle === true,
+      });
+      const s3KeyPrefix = await ctx.prompter.text({
+        message: "S3 key prefix (optional)",
+        placeholder: "gewe-openclaw/outbound",
+        initialValue: existing.s3KeyPrefix,
+      });
+      const s3UrlMode = await ctx.prompter.select({
+        message: "S3 URL mode",
+        options: [
+          { value: "public", label: "public (default)" },
+          { value: "presigned", label: "presigned" },
+        ],
+        initialValue: existing.s3UrlMode ?? "public",
+      });
+      const s3PublicBaseUrl =
+        s3UrlMode === "public"
+          ? await ctx.prompter.text({
+              message: "S3 public base URL",
+              placeholder: "https://cdn.example.com/gewe-media",
+              initialValue: existing.s3PublicBaseUrl,
+              validate: (value) => (value.trim() ? undefined : "Required"),
+            })
+          : await ctx.prompter.text({
+              message: "S3 public base URL (optional in presigned mode)",
+              initialValue: existing.s3PublicBaseUrl,
+            });
+      const s3PresignExpiresSecRaw =
+        s3UrlMode === "presigned"
+          ? await ctx.prompter.text({
+              message: "Presigned URL expire seconds",
+              initialValue: String(existing.s3PresignExpiresSec ?? 3600),
+              validate: (value) => {
+                const parsed = Number(value);
+                if (!Number.isInteger(parsed) || parsed <= 0) {
+                  return "Must be a positive integer";
+                }
+                return undefined;
+              },
+            })
+          : "";
+      s3Patch = {
+        s3Enabled: true,
+        s3Endpoint: s3Endpoint.trim(),
+        s3Region: s3Region.trim(),
+        s3Bucket: s3Bucket.trim(),
+        s3AccessKeyId: s3AccessKeyId.trim(),
+        s3SecretAccessKey: s3SecretAccessKey.trim(),
+        s3SessionToken: s3SessionToken.trim() || undefined,
+        s3ForcePathStyle,
+        s3KeyPrefix: s3KeyPrefix.trim() || undefined,
+        s3UrlMode,
+        s3PublicBaseUrl: s3PublicBaseUrl.trim() || undefined,
+        s3PresignExpiresSec:
+          s3UrlMode === "presigned" ? Number(s3PresignExpiresSecRaw) : undefined,
+      };
+    } else {
+      s3Patch = {
+        s3Enabled: false,
+      };
+    }
+
     let allowFrom = existing.allowFrom;
     let dmPolicy: GeweAccountConfig["dmPolicy"] | undefined;
     if (ctx.forceAllowFrom) {
@@ -255,7 +355,8 @@ export const geweOnboarding: GeweOnboardingAdapter = {
       mediaHost: existing.mediaHost ?? DEFAULT_MEDIA_HOST,
       mediaPort: existing.mediaPort ?? DEFAULT_MEDIA_PORT,
       mediaPath: existing.mediaPath ?? DEFAULT_MEDIA_PATH,
-      mediaPublicUrl: mediaPublicUrl.trim(),
+      mediaPublicUrl: mediaPublicUrl.trim() || undefined,
+      ...s3Patch,
       ...(allowFrom ? { allowFrom } : {}),
       ...(dmPolicy ? { dmPolicy } : {}),
     });

package/src/s3.ts

@@ -0,0 +1,149 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+
+import { GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { extensionForMime } from "openclaw/plugin-sdk";
+
+import type { GeweAccountConfig } from "./types.js";
+
+const DEFAULT_S3_KEY_PREFIX = "gewe-openclaw/outbound";
+const DEFAULT_PRESIGN_EXPIRES_SEC = 3600;
+
+export type ResolvedS3Config = {
+  endpoint: string;
+  region: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  forcePathStyle: boolean;
+  publicBaseUrl?: string;
+  keyPrefix: string;
+  urlMode: "public" | "presigned";
+  presignExpiresSec: number;
+};
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, "");
+}
+
+function normalizePrefix(value?: string): string {
+  const raw = value?.trim() || DEFAULT_S3_KEY_PREFIX;
+  return raw.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+export function resolveS3Config(config: GeweAccountConfig): ResolvedS3Config | null {
+  if (config.s3Enabled !== true) return null;
+  const endpoint = config.s3Endpoint?.trim();
+  const region = config.s3Region?.trim();
+  const bucket = config.s3Bucket?.trim();
+  const accessKeyId = config.s3AccessKeyId?.trim();
+  const secretAccessKey = config.s3SecretAccessKey?.trim();
+  if (!endpoint || !region || !bucket || !accessKeyId || !secretAccessKey) {
+    throw new Error("s3Enabled=true but S3 credentials or endpoint is incomplete");
+  }
+  const urlMode = config.s3UrlMode ?? "public";
+  const publicBaseUrl = config.s3PublicBaseUrl?.trim();
+  if (urlMode === "public" && !publicBaseUrl) {
+    throw new Error("s3PublicBaseUrl is required when s3UrlMode=public");
+  }
+  return {
+    endpoint: trimTrailingSlash(endpoint),
+    region,
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    sessionToken: config.s3SessionToken?.trim() || undefined,
+    forcePathStyle: config.s3ForcePathStyle === true,
+    publicBaseUrl: publicBaseUrl ? trimTrailingSlash(publicBaseUrl) : undefined,
+    keyPrefix: normalizePrefix(config.s3KeyPrefix),
+    urlMode,
+    presignExpiresSec:
+      config.s3PresignExpiresSec && config.s3PresignExpiresSec > 0
+        ? Math.floor(config.s3PresignExpiresSec)
+        : DEFAULT_PRESIGN_EXPIRES_SEC,
+  };
+}
+
+function createClient(config: ResolvedS3Config): S3Client {
+  return new S3Client({
+    endpoint: config.endpoint,
+    region: config.region,
+    forcePathStyle: config.forcePathStyle,
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      ...(config.sessionToken ? { sessionToken: config.sessionToken } : {}),
+    },
+  });
+}
+
+function inferExtension(fileName?: string, contentType?: string): string {
+  const byName = fileName ? path.extname(fileName).toLowerCase() : "";
+  if (byName) return byName;
+  const byMime = contentType ? extensionForMime(contentType) : "";
+  return byMime || "";
+}
+
+export function buildS3ObjectKey(params: {
+  accountId: string;
+  config: ResolvedS3Config;
+  fileName?: string;
+  contentType?: string;
+}): string {
+  const now = new Date();
+  const yyyy = String(now.getUTCFullYear());
+  const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(now.getUTCDate()).padStart(2, "0");
+  const ext = inferExtension(params.fileName, params.contentType);
+  return [
+    params.config.keyPrefix,
+    params.accountId,
+    yyyy,
+    mm,
+    dd,
+    `${randomUUID()}${ext}`,
+  ].join("/");
+}
+
+function buildPublicUrl(config: ResolvedS3Config, key: string): string {
+  if (!config.publicBaseUrl) {
+    throw new Error("s3PublicBaseUrl missing");
+  }
+  return `${config.publicBaseUrl}/${key.split("/").map(encodeURIComponent).join("/")}`;
+}
+
+export async function uploadToS3(params: {
+  config: ResolvedS3Config;
+  accountId: string;
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+}): Promise<{ key: string; url: string }> {
+  const key = buildS3ObjectKey({
+    accountId: params.accountId,
+    config: params.config,
+    fileName: params.fileName,
+    contentType: params.contentType,
+  });
+  const client = createClient(params.config);
+  const put = new PutObjectCommand({
+    Bucket: params.config.bucket,
+    Key: key,
+    Body: params.buffer,
+    ...(params.contentType ? { ContentType: params.contentType } : {}),
+  });
+  await client.send(put);
+  if (params.config.urlMode === "public") {
+    return { key, url: buildPublicUrl(params.config, key) };
+  }
+  const getCommand = new GetObjectCommand({
+    Bucket: params.config.bucket,
+    Key: key,
+  });
+  const url = await getSignedUrl(client, getCommand, {
+    expiresIn: params.config.presignExpiresSec,
+  });
+  return { key, url };
+}

package/src/types.ts

@@ -33,6 +33,18 @@ export type GeweAccountConfig = {
   mediaPath?: string;
   mediaPublicUrl?: string;
   mediaMaxMb?: number;
+  s3Enabled?: boolean;
+  s3Endpoint?: string;
+  s3Region?: string;
+  s3Bucket?: string;
+  s3AccessKeyId?: string;
+  s3SecretAccessKey?: string;
+  s3SessionToken?: string;
+  s3ForcePathStyle?: boolean;
+  s3PublicBaseUrl?: string;
+  s3KeyPrefix?: string;
+  s3UrlMode?: "public" | "presigned";
+  s3PresignExpiresSec?: number;
   voiceAutoConvert?: boolean;
   voiceFfmpegPath?: string;
   voiceSilkPath?: string;