@ystemsrx/cfshare

v0.1.6

Published

21 days ago

OpenClaw plugin to safely expose local ports/files via Cloudflare Quick Tunnel

0High
0Medium
0Low

ystemsrx

openclaw cloudflared cloudflare tunnel file-share

📖 这是什么？

CFShare 是 OpenClaw 的社区插件，让你的 AI 助手能够：

🔗 一键将本地端口暴露为临时公网 HTTPS 链接（https://*.trycloudflare.com）
📁 分享文件/目录——自动起本地静态服务器 + 隧道，对方打开链接即可浏览/下载/预览（支持加密）
🔒 内置安全策略——Token/Basic 认证、速率限制、端口黑名单、排除规则
⏱️ 自动过期清理——TTL 到期自动关闭隧道并删除临时文件

[!NOTE] 无需 Cloudflare 账号。CFShare 使用的是 Cloudflare Quick Tunnel（trycloudflare.com），完全免费、即开即用。

🏗️ 工作原理

flowchart LR
    subgraph LOCAL["你的电脑"]
        A["本地服务 / 文件"]
        B["[可选] 反向代理<br/>(认证 + 限流)"]
        C["cloudflared tunnel"]

        A --> B
        B --> C
    end

    C ==>|Cloudflare Quick Tunnel| D["https://xxx.trycloudflare.com"]
    E["对方浏览器"] --> D

CFShare 在内部完成：路径校验 → 文件复制到临时目录 → 启动只读静态服务器 → 挂载认证/限流反代 → 开启 cloudflared 隧道 → 设置过期回收。你只需告诉 AI “我要分享什么”，它会帮你完成剩下的工作。

🚀 安装步骤

第一步：确保已安装 OpenClaw

如果你还没有安装 OpenClaw，请先完成安装：

# 安装 OpenClaw（需要 Node.js ≥ 22）
npm install -g openclaw@latest

# 运行初始化向导
openclaw onboard --install-daemon

[!TIP] 如果你不确定 Node.js 版本，运行 node -v 检查。推荐使用 nvm 管理版本。

第二步：安装 `cloudflared`

CFShare 依赖 Cloudflare 的 cloudflared 命令行工具来创建隧道。

brew install cloudflare/cloudflare/cloudflared

curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt-get update && sudo apt-get install cloudflared

# 在 WSL2 中：
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

或在 Windows 原生 PowerShell / CMD 中使用 winget：

winget install --id Cloudflare.cloudflared

或者直接告诉 Agent 让他帮你安装

安装后验证：

cloudflared --version
# 输出类似: cloudflared version 2025.x.x

[!IMPORTANT] 只需安装 cloudflared，不需要运行 cloudflared tunnel login。Quick Tunnel 无需账号认证。

第三步：安装 CFShare 插件

方式 A — 从 npm 安装（推荐）：

openclaw plugins install @ystemsrx/cfshare
# 安装完成后，重启 Gateway：
openclaw gateway restart

方式 B — 从本地目录安装（适用于开发）：

如果你已经克隆了仓库：

# 先安装依赖
cd /path/to/cfshare
npm install

# 链接到 OpenClaw（开发模式，不复制文件）
openclaw plugins install -l .

第四步：启用插件并重启 Gateway

# 启用插件
openclaw plugins enable cfshare

# 重启 Gateway 使插件生效
openclaw gateway restart

[!NOTE] 如果你使用守护进程模式（--install-daemon），也可以通过 openclaw restart 重启。

🖥️ 直接命令行调用（无需 OpenClaw）

现在你也可以在安装后直接从终端调用 CFShare：

npm install -g @ystemsrx/cfshare
cfshare env_check

常用示例：

# 暴露已有本地服务
cfshare expose_port '{"port":3000,"opts":{"access":"token"}}'

# 分享文件/目录
cfshare expose_files '{"paths":["./dist"],"opts":{"access":"none"}}'

# 停止分享
cfshare exposure_stop '{"id":"all"}'

expose_port 与 expose_files 默认会打印结果并退出。如果你需要以前台方式保持生命周期管理（Ctrl+C 停止），可加 --keep-alive。

以 CLI 方式运行时，CFShare 默认使用 ~/.cfshare 保存状态、workspace、策略和审计文件。它与插件模式（~/.openclaw/cfshare）完全隔离，可同时存在、互不干扰。

⚙️ 配置（可选）

CFShare 开箱即用，以下默认配置适合绝大多数场景。如需调整，编辑 ~/.openclaw/openclaw.json：

{
  plugins: {
    entries: {
      cfshare: {
        enabled: true,
        config: {
          // 自定义配置（以下皆为可选项）
        },
      },
    },
  },
}

可配置项速查

[!TIP] 认证模式说明：
"token" — 访问链接需要带 Token（适合暴露端口）
"basic" — HTTP Basic 认证（用户名/密码）
"none" — 无认证，任何人都可访问（适合临时分享文件）

💬 使用示例

安装完成后，你可以直接对 AI 助手说自然语言，它会自动调用 CFShare 工具：

获取 AI 处理好的文件

按照 {index}_{name}.{ext} 的格式整理 /mnt/data/students/ 下所有文件名，最后打包发我下载链接

Agent 会自动执行 expose_files，返回一个公网链接和过期时间。

分享你的作品

"用 Vue3+Vite 框架完成3D交互式太阳系模型，然后用链接分享给我朋友"

"帮我运行这个项目，最后把链接发我访问"

Agent 会创建项目并运行，然后通过 expose_port 创建隧道，让任何人都能通过一个链接访问。

分享目录（带文件浏览器），可以在浏览器中预览图片/视频/文本等，也可以下载（支持加密）

"加密分享目录 ~/Pictures/vacation"

Agent 会用 expose_files 的 preview 模式创建带文件浏览器的分享页面，你需要拥有有效的 Token 才能访问。

查看活跃分享

"我现在有哪些正在分享的链接？"

停止分享

"关掉所有正在分享的链接"

🧰 工具一览

CFShare 为 AI 注册了以下工具：

🔐 安全设计

❓ 常见问题

不需要。CFShare 使用 Cloudflare Quick Tunnel（trycloudflare.com），完全免费，无需注册账号。

默认 1 小时，可通过配置或每次分享时指定（最长 7 天）。到期后自动销毁。

确认 cloudflared 已安装：cloudflared --version
如果安装位置不在 PATH 中，在配置里指定完整路径：

{
  plugins: {
    entries: {
      cfshare: {
        config: { cloudflaredPath: "/usr/local/bin/cloudflared" },
      },
    },
  },
}

OpenClaw 官方强烈推荐在 Windows 上使用 WSL2。CFShare 同样遵循此建议，请在 WSL2 环境中使用。

openclaw plugins list
# 应该能看到 cfshare 处于 enabled 状态

然后对 AI 说 "运行 cfshare 环境检查"，它会调用 env_check 并返回详细状态。