在多渠道 AI Agent 场景中（LINE、WeChat、WhatsApp、DingTalk 等），一个常见问题是：

❌ 很多聊天平台根本不支持发送任意文件附件
❌ 即使支持，也常出现 400 Bad Request 错误
❌ 直接暴露服务器文件路径存在安全风险

为了彻底解决这个问题，我构建了一套完整的：

OpenClaw + Download API + Caddy 反向代理 + 安全签名机制

架构，实现：

• 文件自动兜底分发

• 一天有效的临时下载链接

• 会话隔离

• 自动清理

• 不暴露服务器路径

• 不需要用户确认

本文完整总结部署方案。

🎯 一、设计目标

我们希望实现：

1. 当频道支持附件 → 直接发送

2. 当频道不支持或发送失败 → 自动生成下载链接

3. 下载链接：

   • 默认有效 24 小时

   • 用户看到的是友好文件名

   • 不暴露服务器真实路径

4. 每个会话文件隔离

5. 自动定期清理

6. 最小 root 权限运行

🏗 二、整体架构

公网用户
    ↓
Caddy (HTTPS)
    ↓
FastAPI Download API (azureuser)
    ↓
/---/---/.openclaw/workspace/public/sessions/{sessionId}
    ↑
OpenClaw Skill secure-download-link

🧩 三、核心组件说明

1️⃣ OpenClaw Skill：secure-download-link

功能：

• 复制生成文件到会话隔离目录

• 随机文件名

• 生成签名 token

• 返回下载 URL

• 默认 TTL = 86400 秒（1 天）

下载文件时：

• 使用 Content-Disposition

• 用户看到的是友好文件名

• 而不是长 token

2️⃣ Download API（FastAPI）

接口：

GET /dl/{token}

安全机制：

• 签名校验（itsdangerous）

• 过期时间校验

• 会话 ID 校验

• 路径穿越防护

• 不暴露真实 BASE_DIR

• 只监听 127.0.0.1

health 接口已修改为：

{
  "ok": true,
  "service": "download-api",
  "status": "running"
}

不泄露服务器路径。

3️⃣ Caddy 反向代理

Caddy 负责：

• 监听 80/443

• 自动申请 HTTPS（有域名时）

• 反代到 127.0.0.1:19090

示例配置：

files.example.com {
    encode gzip
    reverse_proxy 127.0.0.1:19090
}

如果只有 IP：

:80 {
    handle_path /dl/* {
        reverse_proxy 127.0.0.1:19090
    }

    handle {
        reverse_proxy 127.0.0.1:18789
    }
}

🔐 四、安全设计原则

1️⃣ 最小权限运行

Download API 使用：

User=azureuser
Group=azureuser

绝不使用 root。

原因：

• 防止路径穿越造成系统文件泄露

• 防止攻击扩大权限

2️⃣ 配置与代码分离

• 程序放在 /opt/download-api

• 配置放在 /etc/download-api.env

• 文件数据放在 workspace

遵循 Linux FHS 标准。

3️⃣ 会话隔离目录

文件发布路径：

public/sessions/{sessionId}/{random_uuid}.pdf

优点：

• 不可枚举

• 不冲突

• 多用户安全

4️⃣ 自动清理

系统级 cron：

0 3 * * * azureuser find /xxx/xxx/.openclaw/workspace/public/sessions -type f -mtime +3 -delete

防止磁盘堆积。

🤖 五、Agent 自动兜底规则

在 AGENTS.md 中加入：

If attachment sending fails or channel does not support file uploads:
→ Immediately use secure-download-link
→ Generate 24h valid link
→ Send file name + download link + expiry notice
→ Do not ask user for confirmation

实现：

• 无需用户参与

• 自动 fallback

• 体验平滑

🌐 六、IP-only 部署说明

可以只使用 IP 地址：

DL_DOMAIN=1.2.3.4
DL_SCHEME=http

但注意：

• 公网可信 HTTPS 证书通常需要域名

• IP 只能使用 HTTP 或自签 TLS

生产环境建议使用域名。

📦 七、完整一键安装包

我们制作了两个安装包：

1. secure-download-link-skill.zip

2. download-api-package.zip

安装后自动：

• 创建目录

• 创建 venv

• 写 systemd

• 写 Caddy 配置

• 写 cron 清理

• 启动服务

实现真正的“企业级文件分发模块”。

🧠 八、为什么这套方案值得做？

很多人用：

• S3 临时链接

• 临时网盘

• 直接暴露文件目录

但这种架构的优点是：

• 完全自建

• 可控

• 可审计

• 会话隔离

• 可扩展为 SaaS 文件服务

• 可做下载次数限制

• 可做一次性链接

它本质上是：

一个轻量级的私有文件分发系统

🚀 九、总结

这次部署不仅解决了：

“LINE 不能发附件怎么办？”

而是构建了：

• AI 文件生命周期管理

• 多渠道兼容策略

• 安全签名下载机制

• 最小权限服务架构

• 自动垃圾清理策略

这已经不是简单脚本，而是：

一套可长期运行的生产级文件分发架构。

如果有需求，欢迎评论留下联系方式，或者给我们留言，完整压缩包免费分享